number-formatter/README.md

Lightweight & Fast JavaScript Number Formatter

# Javascript Number Formatter

Lightweight & Fast JavaScript Number Formatter

[![Build Status](https://travis-ci.org/j-/number-formatter.png?branch=master)](https://travis-ci.org/j-/number-formatter)

## 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 as short as < 120 lines including license info, blank lines and comments. And production release is less than 1,200 bytes.

```js
numberFormatter( "#,##0.####", 1234567.890 );  // output: "1,234,567.89"
numberFormatter( "$ #,###.00", -1234567.890 ); // output: "$ -1,234,567.89"
```

## 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: `numberFormatter( "0.0000", 3.141592)`.
* Include a prefix &amp; suffix with the mask

## Limitations

* No scientific/engineering formatting.
* Not for date or phone formation.
* No color control.
* <del>No prefix or suffix is allowed except leading negation symbol. So `$#,##0.00` or `#,###.##USD` will not yield expected outcome. Use `'$'+numberFormatter('#,##0.00', 123.45)` or `numberFormatter('#,##0.00', 456.789) + 'USD'`</del>
* The prefix or suffix can not include any numbers (`0-9`), dashes (`-`), or plus signs (`+`).

## Installation

### npm

```sh
$ npm install --save number-formatter
```

### bower

```sh
$ bower install --save number-formatter
```

## Note

When there's only one symbol is supplied, system will always treat the single symbol as Decimal. For instance, `numberFormatter( '#,###', 1234567.890)` will output `1234567,890`. To force a single symbol as Separator, add a trailing dot to the end like this: `numberFormatter( '#,###.', 1234567.890)` which will then output `1,234,567`.

A demo/sample page with few examples is provided ([DEMO](http://mottie.github.io/javascript-number-formatter/)). The code is safe to be minimized using Google Compiler in Advanced mode.

## Version

### V1.1.5 (1/26/2015)

* Change name in bower.json & package.json to "number-format.js".
* Update readme with installation instructions.

### v1.1.4 (1/26/2015)

* Add AMD & NodeJS compatibility (UMD). Thanks [MadMG](https://github.com/MadMG)!
* Renamed variables & code cleanup to make it more readable.

### v1.1.3 (11/12/2014)

* Fix bower link to point to the production version. Thanks [marcelboettcher](https://github.com/marcelboettcher)!
* Minor code & demo cleanup.

### v1.1.2 (6/22/2014)

* Remove negative sign from results with a value of zero.
* Added more examples to demo page.