Introduction
Some powerful formatting features are available for formatting numerals by aligning them, specifying
the separator symbols number of digits, negation, etc. For this, a pattern string, called a formatting template needs
to be provided and is described in the following table.
The formatting template applies to following functions:
- str(), 2nd parameter
- table format numbers(), 3rd parameter
Formatting Templates
| Formatting Template | Description | |
|---|---|---|
| * | Only if used alone as single character: Generic output of number | |
| # | Placeholder for one digit. Meaningless zeros (i.e. leading zerosbefore decimal points, final ones after decimal points) are not shown. | |
| 0 | Placeholder for one digit. Meaningless zeros are shown | |
| ? | Placeholder for one digit. Meaningless zeros are shown with placeholder symbols (default: spaces) | |
| * | Asterisk is used as placeholder for entire number if: 1) no digit placeholders listed above are specified elsewhere, 2) it's the last asterisk in case more than one are encountered. Otherwise the asterisk will be treated as a given text. | |
| , | Thousand separator. Always use comma for this purpose. To use different symbols common in other countries, use the formatting option to specify the language, e.g. german for points. | |
| . | Decimal separator. Always use point for this purpose. To use different symbols common in other countries, use the formatting option to specify the language, e.g. german for commas. | |
| - | Minus signs will be displayed if the number is negative. The minus sign may be located anywhere, even after the number. | |
| ( ) | Parentheses will be displayed if the number is negative. | |
| [ ] | Bracket will be displayed if the number is negative. | |
| + | Displays a + if the number is positive and – (minus) if negative | |
| _ | Underscore prefix: If added in front of -, (, ), [, and ], blank or provided placeholder symbol is given out if number is positive in order to keep the other characters to the right aligned. | |
| ' ... ' | Contents inside quotation marks are treated as given text, including spaces | See 2 |
| " ... " | See above | See 3 |
| % | Number will be multipled by 100 before displaying together with percent symbol | |
| ‰ | Number will be multipled by 1,000 before displaying together with permille symbol | |
| ‱ | Number will be multipled by 10,000 before displaying together with the parts-per-10,000 symbol | |
| All other characters | Treated as given text, including digits 1..9 |
2 Applicable outside double quotation marks, otherwise symbols are treated as given text
3 Applicable outside single quotation marks, otherwise symbols are treated as given text
Attention: If the formatting template contains neiter # nor *, then the resulting string contains no number.
Locales
Specify a supported locale name, a country name or a language name. See locales for an overview of supported locales. Choices are not case sensitive.
Examples: en_US, DE_at, France, German, local, none
Program Examples
A few loop show the combination of different values.
numbers [] = { -1234, -0.29, 123456.78, 0 };
patterns[] = { '*', 'EUR_-*', '0', '+ 0.0', '0000.0000', '?', '?.?', '#.#', '####.####', '0.####', '_(0.00)' };
3rd p[] = { "", india, german, en_us, french, de_ch };
4th p[] = { "", "", "+", "", "", "" };
for all ( numbers[], number[] )
{
for all ( patterns[], pattern[] )
{
for all ( 3rd p[], para 3[], index[] )
{
para 4[] = 4th p[]{index[]};
if (para 3[] = '') l[] = str( number[], pattern[] );
else: if (para 4[] = '') l[] = str( number[], pattern[], para 3[] );
else: l[] = str( number[], pattern[], para 3[], para 4[] );
print( "'" + l[] + "', " );
}
echo;
}
echo;
}
echo( "Permille: ", str( 0.1234, '0.0 ‰') );
echo( "Directory assistance (USA): ", str( 5551212, '"Dial 1-"000"-"0000') );'-1234', '-1,234', '-1.234', '-1,234', '-1 234', '-1'234',
'EUR-1234', 'EUR-1,234', 'EUR-1.234', 'EUR-1,234', 'EUR-1 234', 'EUR-1'234',
'-1234', '-1,234', '-1.234', '-1,234', '-1 234', '-1'234',
'- 1234.0', '- 1,234.0', '- 1.234,0', '- 1,234.0', '- 1 234.0', '- 1'234.0',
'-1234.0000', '-1234.0000', '-1234,0000', '-1234.0000', '-1234.0000', '-1234.0000',
'-1234', '-1,234', '-1.234', '-1,234', '-1 234', '-1'234',
'-1234. ', '-1,234. ', '-1.234,+', '-1,234. ', '-1 234. ', '-1'234. ',
'-1234.', '-1,234.', '-1.234,', '-1,234.', '-1 234.', '-1'234.',
'-1234.', '-1234.', '-1234,', '-1234.', '-1234.', '-1234.',
'-1234.', '-1,234.', '-1.234,', '-1,234.', '-1 234.', '-1'234.',
'(1234.00)', '(1,234.00)', '(1.234,00)', '(1,234.00)', '(1 234.00)', '(1'234.00)',
'-0.29', '-0.29', '-0,29', '-0.29', '-0.29', '-0.29',
'EUR-0.29', 'EUR-0.29', 'EUR-0,29', 'EUR-0.29', 'EUR-0.29', 'EUR-0.29',
'-0', '-0', '-0', '-0', '-0', '-0',
'- 0.3', '- 0.3', '- 0,3', '- 0.3', '- 0.3', '- 0.3',
'-0000.2900', '-0000.2900', '-0000,2900', '-0000.2900', '-0000.2900', '-0000.2900',
'- ', '- ', '-+', '- ', '- ', '- ',
'- .3', '- .3', '-+,3', '- .3', '- .3', '- .3',
'-.3', '-.3', '-,3', '-.3', '-.3', '-.3',
'-.29', '-.29', '-,29', '-.29', '-.29', '-.29',
'-0.29', '-0.29', '-0,29', '-0.29', '-0.29', '-0.29',
'(0.29)', '(0.29)', '(0,29)', '(0.29)', '(0.29)', '(0.29)',
'123456.78', '1,23,456.78', '123.456,78', '123,456.78', '123 456.78', '123'456.78',
'EUR 123456.78', 'EUR 1,23,456.78', 'EUR+123.456,78', 'EUR 123,456.78', 'EUR 123 456.78', 'EUR 123'456.78',
'123457', '1,23,457', '123.457', '123,457', '123 457', '123'457',
'+ 123456.8', '+ 1,23,456.8', '+ 123.456,8', '+ 123,456.8', '+ 123 456.8', '+ 123'456.8',
'123456.7800', '1,23456.7800', '123456,7800', '123456.7800', '123456.7800', '123456.7800',
'123457', '1,23,457', '123.457', '123,457', '123 457', '123'457',
'123456.8', '1,23,456.8', '123.456,8', '123,456.8', '123 456.8', '123'456.8',
'123456.8', '1,23,456.8', '123.456,8', '123,456.8', '123 456.8', '123'456.8',
'123456.78', '1,23456.78', '123456,78', '123456.78', '123456.78', '123456.78',
'123456.78', '1,23,456.78', '123.456,78', '123,456.78', '123 456.78', '123'456.78',
' 123456.78', ' 1,23,456.78', '+123.456,78', ' 123,456.78', ' 123 456.78', ' 123'456.78',
'0', '0', '0', '0', '0', '0',
'EUR 0', 'EUR 0', 'EUR+0', 'EUR 0', 'EUR 0', 'EUR 0',
'0', '0', '0', '0', '0', '0',
'+ 0.0', '+ 0.0', '+ 0,0', '+ 0.0', '+ 0.0', '+ 0.0',
'0000.0000', '0000.0000', '0000,0000', '0000.0000', '0000.0000', '0000.0000',
' ', ' ', '+', ' ', ' ', ' ',
' . ', ' . ', '+,+', ' . ', ' . ', ' . ',
'.', '.', ',', '.', '.', '.',
'.', '.', ',', '.', '.', '.',
'0.', '0.', '0,', '0.', '0.', '0.',
' 0.00', ' 0.00', '+0,00', ' 0.00', ' 0.00', ' 0.00',
Permille: 123.4 ‰
Directory assistance (USA): Dial 1-555-1212