 DownloadDocumentation for the "NumberFormatter" class.
Used by CIDRAM and phpMussel to format numbers generated by their front-end pages, the class provides a more controllable, customisable mechanism for number formatting than PHP's internal number_format() function.
How to use:
NumberFormatter constructor.
public function __construct(string $Format = '');
To use the number formatter, you'll firstly need to instantiate it. You don't need to parse any parameters to the constructor, but it optionally accepts one parameter, $Format. The $Format parameter can be used to immediately set various commonly used values to the object's members during object instantiation (so that you won't need to set each definition manually). You can set these later though. More information about these members will be explained later in this document. The currently supported values for $Format are listed in the table below.
Value | ConversionSet | GroupSeparator | GroupSize | GroupOffset | DecimalSeparator | Base
---|---|---|---|---|---|---
Default values (e.g., when the parameter is omitted) and Latin-1. | Western | ,<br />(comma) | 3 | 0 | .<br />(decimal) | 10
NoSep-1 | Western | (empty) | (n/a) | (n/a) | .<br />(decimal) | 10
NoSep-2 | Western | (empty) | (n/a) | (n/a) | ,<br />(comma) | 10
Latin-2 | Western | ?<br />(non-breaking space) | 3 | 0 | .<br />(decimal) | 10
Latin-3 | Western | .<br />(decimal) | 3 | 0 | ,<br />(comma) | 10
Latin-4 | Western | ?<br />(non-breaking space) | 3 | 0 | ,<br />(comma) | 10
Latin-5 | Western | ,<br />(comma) | 3 | 0 | ·<br />(middle dot) | 10
China-1 | Western | ,<br />(comma) | 4 | 0 | .<br />(decimal) | 10
India-1 | Western | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
India-2 or Devanagari | Devanagari | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
India-3 or Gujarati | Gujarati | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
India-4 or Gurmukhi | Gurmukhi | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
India-5 or Kannada | Kannada | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
India-6 or Telugu | Telugu | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
Arabic-1 | Eastern | (empty) | (n/a) | (n/a) | ?<br />(arabic decimal separator) | 10
Arabic-2 | Eastern | ?<br />(arabic thousands separator) | 3 | 0 | ?<br />(arabic decimal separator) | 10
Arabic-3 or Persian | Persian | ?<br />(arabic thousands separator) | 3 | 0 | ?<br />(arabic decimal separator) | 10
Arabic-4 or Urdu | Persian | ?<br />(arabic thousands separator) | 2 | -1 | ?<br />(arabic decimal separator) | 10
Bengali-1 or Nagari | Nagari | ,<br />(comma) | 2 | -1 | .<br />(decimal) | 10
Burmese-1 | Burmese | (empty) | (n/a) | (n/a) | .<br />(decimal) | 10
Khmer-1 | Burmese | .<br />(decimal) | 3 | 0 | ,<br />(comma) | 10
Lao-1 | Lao | (empty) | (n/a) | (n/a) | .<br />(decimal) | 10
Thai-1 | Thai | ,<br />(comma) | 3 | 0 | .<br />(decimal) | 10
Thai-2 | Thai | (empty) | (n/a) | (n/a) | .<br />(decimal) | 10
Base-12 [?2] | Western | (empty) | (n/a) | (n/a) | .<br />(decimal) | 12
Base-16 [?2] | Western | (empty) | (n/a) | (n/a) | .<br />(decimal) | 16
Mayan [?1] [?2] | Mayan | (empty) | (n/a) | (n/a) | .<br />(decimal) | 20
[?1]: Not actually "commonly used" at all, seeing as it hasn't actually been actively used since the 17th century, so, unlikely to be practical, but included anyway as a means of demonstratrating some of what the class can do (think of it as an "easter egg").
[?2]: The class fully supports fractions, including the ability to convert between arbitrary bases for both decimals and fractions alike, and including for numeral systems, that the class supports, that mightn't necessarily themselves support fractions natively, or in the contexts where those numeral systems would normally be used. It's not my intention to imply that they should. However, the support already exists, removing it for specific numeral systems would require additional code complexity, and doing so would be generally pointless, I think. Alternatively, any users concerned about this can easily just omit the $Decimals parameter when calling format() to avoid fractions.
(n/a): Means "not applicable".
format method.
After instantiating the number formatter, after setting any necessary values for the instance's members, the format method is used to format numbers.
public function format($Number, int $Decimals = 0): string;
The method accepts two parameters.
The first parameter, $Number, is the number you want to format (mandatory). The method uses this parameter in a way consistent with strings, but any scalar value (e.g., string, int, float) can be used.
The second parameter, $Decimals, is an optional integer (defaults to 0), and tells the method how many decimal places you expect the formatted number to have.
Example:
<?php
$Formats = [
'NoSep-1',
'NoSep-2',
'Latin-1',
'Latin-2',
'Latin-3',
'Latin-4',
'Latin-5',
'China-1',
'India-1',
'India-2',
'India-3',
'India-4',
'India-5',
'India-6',
'Arabic-1',
'Arabic-2',
'Arabic-3',
'Arabic-4',
'Bengali-1',
'Burmese-1',
'Khmer-1',
'Lao-1',
'Thai-1',
'Thai-2',
'Base-12',
'Base-16',
'Mayan'
];
echo "Format | `\$Obj->format('1234567.89', 2)` | `\$Obj->format('10203040.50607080', 5)`\n---|---|---\n";
foreach ($Formats as $Format) {
$Obj = new \Maikuolan\Common\NumberFormatter($Format);
echo '`' . $Format . '` | `' . $Obj->format('1234567.89', 2) . '` | `' . $Obj->format('10203040.50607080', 5) . "`\n";
}
Output:
Format | $Obj->format('1234567.89', 2) | $Obj->format('10203040.50607080', 5)
---|---|---
NoSep-1 | 1234567.89 | 10203040.50607
NoSep-2 | 1234567,89 | 10203040,50607
Latin-1 | 1,234,567.89 | 10,203,040.50607
Latin-2 | 1?234?567.89 | 10?203?040.50607
Latin-3 | 1.234.567,89 | 10.203.040,50607
Latin-4 | 1?234?567,89 | 10?203?040,50607
Latin-5 | 1,234,567·89 | 10,203,040·50607
China-1 | 123,4567.89 | 1020,3040.50607
India-1 | 12,34,567.89 | 1,02,03,040.50607
India-2 | ??,??,???.?? | ?,??,??,???.?????
India-3 | ??,??,???.?? | ?,??,??,???.?????
India-4 | ??,??,???.?? | ?,??,??,???.?????
India-5 | ??,??,???.?? | ?,??,??,???.?????
India-6 | ??,??,???.?? | ?,??,??,???.?????
Arabic-1 | ?????????? | ??????????????
Arabic-2 | ???????????? | ????????????????
Arabic-3 | ???????????? | ????????????????
Arabic-4 | ???????????? | ?????????????????
Bengali-1 | ??,??,???.?? | ?,??,??,???.?????
Burmese-1 | ???????.?? | ????????.?????
Khmer-1 | ?.???.???,?? | ??.???.???,?????
Lao-1 | ???????.?? | ????????.?????
Thai-1 | ?,???,???.?? | ??,???,???.?????
Thai-2 | ???????.?? | ????????.?????
Base-12 | 4b6547.a6 | 3500654.60728
Base-16 | 12d687.e2 | 9bafa0.80971
Mayan | ?????.?? | ??????.?????
ConversionSet member.
public $ConversionSet = 'Western';
The ConversionSet member tells the number formatter which characters it should to use to represent which numbers.
Currently supported values:
Value | Description
---|---
Western | Standard numerals (0-9), alternatively known as Western Arabic numerals, Arabic numerals, Hindu-Arabic numerals, etc.
Eastern | Eastern Arabic numerals.
Persian | Persian/Urdu numerals (Eastern Arabic variant).
Nagari | Nagari/Bengali/Bangla numerals.
Devanagari | Devanagari numerals.
Gujarati | Gujarati numerals.
Gurmukhi | Gurmukhi numerals.
Kannada | Kannada numerals.
Telugu | Telugu numerals.
Burmese | Burmese numerals.
Khmer | Khmer numerals.
Thai | Thai numerals.
Lao | Lao numerals.
Mayan | Mayan numerals.
(If needed, the class can easily be extended to add support for additional conversion sets).
Example usage:
$Obj = new \Maikuolan\Common\NumberFormatter();
$Obj->ConversionSet = 'Devanagari';
echo $Obj->format('123.45', 2) . PHP_EOL;
$Obj->ConversionSet = 'Kannada';
echo $Obj->format('123.45', 2) . PHP_EOL;
$Obj->ConversionSet = 'Western';
echo $Obj->format('123.45', 2) . PHP_EOL;
Output:
???.??
???.??
123.45
GroupSeparator member.
public $GroupSeparator = ',';
The GroupSeparator member tells the number formatter which character to use to separate groups of numbers (e.g., the comma in 1,234.56).
Example usage:
$Obj = new \Maikuolan\Common\NumberFormatter();
$Obj->GroupSeparator = "'";
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->GroupSeparator = ',';
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->GroupSeparator = '.';
$Obj->DecimalSeparator = ',';
echo $Obj->format('1234567.89', 2) . PHP_EOL;
Output:
1'234'567.89
1,234,567.89
1.234.567,89
GroupSize member.
public $GroupSize = 3;
The GroupSize member tells the number formatter how many numbers should from a number group (typically this is three, but sometimes other sizes may be needed).
Example usage:
$Obj = new \Maikuolan\Common\NumberFormatter();
$Obj->GroupSize = 4;
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->GroupSize = 3;
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->GroupSize = 2;
echo $Obj->format('1234567.89', 2) . PHP_EOL;
Output:
123,4567.89
1,234,567.89
1,23,45,67.89
GroupOffset member.
public $GroupOffset = 0;
The GroupOffset member provides a mechanism by which the first number group in a number can be a different size to any subsequent number groups in the number. This can be particularly important when expressing numbers that deal with lakhs and crores, typically requiring that the first number group contain three numbers, with any subsequent number groups containing two numbers.
Example usage:
$Obj = new \Maikuolan\Common\NumberFormatter();
$Obj->GroupOffset = -2;
echo $Obj->format('1000000000000000') . PHP_EOL;
$Obj->GroupOffset = -1;
echo $Obj->format('1000000000000000') . PHP_EOL;
$Obj->GroupOffset = 0;
echo $Obj->format('1000000000000000') . PHP_EOL;
$Obj->GroupOffset = 1;
echo $Obj->format('1000000000000000') . PHP_EOL;
$Obj->GroupOffset = 2;
echo $Obj->format('1000000000000000') . PHP_EOL;
$Obj->GroupSize = 2;
$Obj->GroupOffset = -1;
echo $Obj->format('1000000000000000') . PHP_EOL;
Output:
10,000,000,000,00000
100,000,000,000,0000
1,000,000,000,000,000
10,000,000,000,000,00
100,000,000,000,000,0
1,00,00,00,00,00,00,000
DecimalSeparator member.
public $DecimalSeparator = '.';
The DecimalSeparator member tells the number formatter which character to use to separate whole numbers from fractions (e.g., the period in 1,234.56).
Example usage:
$Obj = new \Maikuolan\Common\NumberFormatter();
$Obj->DecimalSeparator = "?";
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->DecimalSeparator = "?";
echo $Obj->format('1234567.89', 2) . PHP_EOL;
$Obj->GroupSeparator = '.';
$Obj->DecimalSeparator = ',';
echo $Obj->format('1234567.89', 2) . PHP_EOL;
Output:
1,234,567?89
1,234,567?89
1.234.567,89
Base member.
public $Base = 10;
The Base member tells the number formatter which base to use to express numbers. This will typically be 10, but sometimes other bases may be needed. The mechanism for switching between bases relies upon PHP's internal base_convert() function, which requires that bases be between 2 and 36 inclusive. The Base member must therefore be set to a value between 2 and 36 inclusive (otherwise it won't work properly).
An example that uses 1e+9 (1,000,000,000):
$Obj = new \Maikuolan\Common\NumberFormatter();
for ($Obj->Base = 2; $Obj->Base < 37; $Obj->Base++) {
echo 'Base ' . $Obj->Base . ': ' . $Obj->format(1e+9) . PHP_EOL;
}
Output:
Base 2: 111,011,100,110,101,100,101,000,000,000
Base 3: 2,120,200,200,021,010,001
Base 4: 323,212,230,220,000
Base 5: 4,022,000,000,000
Base 6: 243,121,245,344
Base 7: 33,531,600,616
Base 8: 7,346,545,000
Base 9: 2,520,607,101
Base 10: 1,000,000,000
Base 11: 473,523,88a
Base 12: 23a,a93,854
Base 13: 12c,23a,19c
Base 14: 96,b4b,6b6
Base 15: 5c,bd1,46a
Base 16: 3b,9ac,a00
Base 17: 27,750,aa7
Base 18: 1b,73h,dda
Base 19: 12,4g6,g1i
Base 20: f,ca0,000
Base 21: b,dhi,eed
Base 22: 8,i0i,7fa
Base 23: 6,h8a,c3k
Base 24: 5,5e1,n2g
Base 25: 4,2a0,000
Base 26: 3,647,joc
Base 27: 2,fii,731
Base 28: 2,22p,q5k
Base 29: 1,jlp,2ii
Base 30: 1,b4h,13a
Base 31: 1,3sp,5mg
Base 32: tpl,ig0
Base 33: pi7,fla
Base 34: m0a,nuo
Base 35: j1d,lik
Base 36: gjd,gxs
Now, as an example to demonstrate working with fractions:
$Obj = new \Maikuolan\Common\NumberFormatter();
for ($Obj->Base = 2; $Obj->Base < 37; $Obj->Base++) {
echo 'Base ' . $Obj->Base . ': ' . $Obj->format('10.5', 4) . ' ~ ' . $Obj->format('256.25', 4) . PHP_EOL;
}
Output:
Base 2: 1,010.1000 ~ 100,000,000.0101
Base 3: 101.1111 ~ 100,111.0211
Base 4: 22.2000 ~ 10,000.1000
Base 5: 20.2100 ~ 2,011.1210
Base 6: 14.3000 ~ 1,104.1413
Base 7: 13.3500 ~ 514.1104
Base 8: 12.4000 ~ 400.2000
Base 9: 11.4410 ~ 314.2241
Base 10: 10.5000 ~ 256.2500
Base 11: a.5500 ~ 213.2749
Base 12: a.6000 ~ 194.3000
Base 13: a.6499 ~ 169.3249
Base 14: a.7000 ~ 144.3500
Base 15: a.7499 ~ 121.3749
Base 16: a.8000 ~ 100.4000
Base 17: a.8499 ~ f1.4249
Base 18: a.9000 ~ e4.4499
Base 19: a.9500 ~ d9.4750
Base 20: a.a000 ~ cg.5000
Base 21: a.a500 ~ c4.5250
Base 22: a.b000 ~ be.5500
Base 23: a.b500 ~ b3.5749
Base 24: a.c000 ~ ag.6000
Base 25: a.c500 ~ a6.6250
Base 26: a.d000 ~ 9m.6499
Base 27: a.d500 ~ 9d.6749
Base 28: a.e000 ~ 94.7000
Base 29: a.e500 ~ 8o.7250
Base 30: a.f000 ~ 8g.7499
Base 31: a.f500 ~ 88.7750
Base 32: a.g000 ~ 80.8000
Base 33: a.g499 ~ 7p.8249
Base 34: a.h000 ~ 7i.8499
Base 35: a.h499 ~ 7b.8750
Base 36: a.i000 ~ 74.9000
Important: Please be aware that switching bases may result in a loss of precision (meaning that the resulting formatted numbers may sometimes be subject to some degree of inaccuracy).
Last Updated: 27 June 2019 (2019.06.27).
|
