NumbertoFormat Method
Syntax
Arguments
- formatstring
The format to return the number in.
Returns
- valuestring
A string with the result of the format when applied to the number.
Description
Extension to the native number variable to convert a number into a formatted string.
Discussion
The Number.toFormat method can be used on numbers to convert them to formatted strings. The passed in format allows for complex operations to be preformed on the number during the conversion to a string.
"#" is used to represent an optional digit. If there is an explicit digit at the corresponding location in the number then that digit will be output - otherwise no character will be output.
"0" is used to represent a required digit. Unlike "#" if there is no explicit digit then a "0" will be output.
"_" is used to represent an optional digit. Unlike "#" a " " will be output if there is no explicit value.
"*" is used to represent no rounding. This will allow the number to be formatted to show all decimals. "=" at the beginning of a format means the following format is a mask, and each digit of the number will be sequentially output in the mask. For example to store a phone number as a number, but present it in the standard format.
"]" at the end of a format (or before a "<" or ">") means round to zero.
"[" when used in conjunction with "]" means force "0" (e.g. 123 with a format of "#[00]" would output "100").
"<" at the end of a format will round the decimal up. If it occurs before a "]" it will behave like the "[", only rounding the integer up.
">" behaves exactly like "<" only rounding down instead of up.
";" can be used to allow for multiple formats. It can be used with an if statement (see below), or without. When used without, the first format will be used for a positive number, the second for a negative number, and optionally the third will be output when the number is equal to zero.
"if(expr)" at beginning of a format will use the expression expression ("expr" to be replaced with an expression where "n" is equal to the value of the number) for choosing one of the two formats (separated be a ";") to use.
"=(expr)" at the end of a format will allow for a custom expression ("expr" to be replaced with an expression where "n" is equal to the value of the number) to be preformed on the number before it is formatted.
"-/-" will force the decimal to be output as a fraction. To specify the denominator, a value can be put in its place. For example "-/100" will result in the fractional value of the number being rounded to the nearest hundredth.
"\" can be used to escape format characters.
The format will automatically detect the character used as the (optional) thousands separator, and the decimal.
Example
var num = 1020.5893;
var numStr = '';
// currency format
numStr = num.toFormat('$#,##0.00'); // numStr = '$1,020.59'
// comma for decimal and space for thousands separator format
numStr = num.toFormat('# ##0,00'); // numStr = '1 020,59'
// round down to two decimal places
numStr = num.toFormat('0.00>'); // numStr = '1020.58'
// show decimal as a fraction
num = 20.25;
numStr = num.toFormat('#,##0.* and -/-'); // numStr = '20 and 1/4'
// positive, negative and zero formats in single format
numStr = num.toFormat('$#,##0.00;$ (#,##0.00);------'); // numStr = '$1,020.25'
num = -10.34;
numStr = num.toFormat('$#,##0.00;$ (#,##0.00);------'); // numStr = '$ (10.34)'
num = 0;
numStr = num.toFormat('$#,##0.00;$ (#,##0.00);------'); // numStr = '------'
// mask format
num = 1234567890;