Javascript Number Formatter
Lightweight & Fast JavaScript Number Formatter!Build Statusbuild-imagebuild-url !NPM Versionnpm-imagenpm-url !devDependency Statusdavid-dev-imagedavid-dev-url !MITlicense-imagelicense-url
Introduction
This standalone number formatter† is intended to be short and fast. As they are the main factors for a high performance JavaScript app. Development release is around 150 lines including license info, blank lines and comments. And production release is less than 2,000 bytes.format( "#,##0.####", 1234567.890 ); // output: "1,234,567.89"
format( "$ #,###.00", -1234567.890 ); // output: "$ -1,234,567.89"
// Added in v2.0.0
format( "$ #,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ 1,234,567.89"
format( "$ -#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", 1234567.890, {enforceMaskSign: true}); // output: "$ +1,234,567.89"
† Initial development release of this code was written by KPL and hosted at Google Code.
Features
- Short, fast, flexible yet standalone.
- Accept standard number formatting like
#,##0.00
or with negation-000.####
. - Accept any country format like
# ##0,00
,#,###.##
,#'###.##
or any type of non-numbering symbol. - Accept any numbers of digit grouping.
#,##,#0.000
or#,###0.##
are all valid. - Accept any redundant/fool-proof formatting.
##,###,##.#
or0#,#00#.###0#
are all OK. - Auto number rounding.
- Simple interface, just supply mask & value like this:
format( "0.0000", 3.141592)
. - Include a prefix & suffix with the mask.
Limitations
- No scientific/engineering formatting.
- Not for date or phone formation.
- No color control.
- No prefix or suffix is allowed except leading negation symbol. So
$#,##0.00
or#,###.##USD
will not yield expected outcome. Use'$'+format('#,##0.00', 123.45)
orformat('#,##0.00', 456.789) + 'USD'
- The prefix or suffix can not include any numbers (
0-9
), dashes (-
), or plus signs (+
).
Format Symbols
| Description | Symbol | Summary | |---------------|--------|---------| | Mask symbols | #0123456789+- | Mask symbols used for formatting the value. | | Placeholders | #123456789 | Un-forced digit; this optional digit will only show if it is required as a placeholder. | | Zero | 0 | Forced digit; the digit will be shown whether or not the digit is relevant to the value. | | Signs | +- | Indicates a positive or negative value; visible depending on the value sign and theenforceMaskSign
setting. |
| Leftmost | | Any non-mask symbol† inside the mask will be set to represent a thousands separator. |
| Rightmost | | Any non-mask symbol† inside the mask‡ will be set to represent the decimal separator. |
| Prefix/Suffix | | Any non-mask symbol† outside the mask. |\ Non-zero mask digits (
1
through 9
) behave the same as the #
.† Anything not a digit, and not a
+
, -
or #
.‡ In the case where there is a trailing decimal or comma, it will be included in the mask, e.g.
#.
or 0,
.Note
When only one symbol is supplied, the library will always treat that symbol as a decimal. For example,format( '#,###', 1234567.890)
will output 1234567,890
.To force a single symbol to be used as a separator, add a trailing symbol. In this example, a period is added to the end of the mask -
format( '#,###.', 1234567.890)
- resulting in it being used as a decimal and forcing the first symbol to be the separator and return this output: 1,234,567
.Installation
npm package
npm install --save number-format.js
Demos
A demo/sample page with few examples is provided (demo).And a jsFiddle was created to aid in testing: https://jsfiddle.net/Mottie/t2etyodx/
Recent Changes
View the complete change log here.v2.0.7 (2018-11-13)
- Update typescript binding. See issue #20.
- Fix improper placeholder behavior. Updated Readme with format symbols table. Closes issue #19.
- Add more tests.
- Meta:
v2.0.6 (2018-11-06)
- Trim trailing zeros in mask. Fixes issue #18.
v2.0.0 – 2.0.5 (2018-10-26)
- Add
ignoreSign
option (modified toenforeceMaskSign
!). - Switch to XO, AVA & rollup.
- Meta: Update dot files & remove bower support.
- Code cleanup & convert to ES2015.
ignoreSign
to enforceMaskSign
(default false
).
Reduce code complexity.
Export as node module.
Update TS with options.
Switch demo to use lib file & highlight valid results.- Switch from Grunt to rollup.
- Switch from IIFE to UMD output.