/javascript-number-formatter

Lightweight & Fast JavaScript Number Formatter

Primary LanguageJavaScriptMIT LicenseMIT

Javascript Number Formatter

Lightweight & Fast JavaScript Number Formatter

Build Status NPM Version devDependency Status MIT

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. ##,###,##.# or 0#,#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) or format('#,##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 the enforceMaskSign 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:
    • Update dependencies.
    • Improve code readability.
    • Include version in min.js.

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 to enforeceMaskSign!).
  • Switch to XO, AVA & rollup.
  • Meta: Update dot files & remove bower support.
  • Code cleanup & convert to ES2015.
    • Rename 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.