## Why
JS provides powerful number formatting with the standard built-in object `Intl.NumberFormat`, but we find its API a little verbose and hard to grasp its full potential. We took inspiration from older libraries like numbro.js and numeral.js and built a string based pattern for interacting with `Intl.NumberFormat`. Tiny footprint, no dependencies, works on the browser or nodejs.
## Usage
```typescript
import nf from '@tuplo/numberfmt';
// numeric
nf(123_456, '0,0.00'); // → 123,456.00
// currency
nf(123_456, '0,0GBP'); // → £123,456
// digital units
nf(123_456, '0b'); // → 120.56kb
// with locale
nf(123_456, '0,0.00', { locale: 'ar-EG' }); // → ١٢٣٬٤٥٦٫٧٩
// functional programming, partial application
const nfp = nf.partial('0,0.00');
nfp(123_456); // → 123,456.00
```
## Install
```bash
$ npm install @tuplo/numberfmt
# or with yarn
$ yarn add @tuplo/numberfmt
```
## Options
An optional set of options can be provided
```typescript
nf(123_456, '0,0.00', {
locale: 'ar-EG',
numberingSystem: 'arab'
}); // → ١٢٣٬٤٥٦٫٧٩
```
### locale
> `string` | optional | defaults to system locale
The BCP 47 language tag for the locale actually used.
### numberingSystem
> `string` | optional | derives from locale
Examples: `arab`, `fullwide`, `hant`, `latn`.
## Reference
| Character | Meaning | |
| --------- | -------------------------------- | ---------------- |
| 0 | digit | 1 |
| . | decimal separator | 1.2 |
| , | thousands group separator | 1,234 |
| [] | optional | |
| - | negative sign | -1 |
| () | negative sign (accounting) | (123) |
| % | percentage | 95% |
| o | ordinals | 1st |
| a | compact notation (short display) | 1K |
| A | compact notation (long display) | 1 thousand |
| e | exponential (scientific) | 1E4 |
| E | exponential (engineering) | 100E3 |
| b | bits | 1.23Mb |
| B | bytes | 1.23TB |
| m | length | 1.23km |
| k | mass | 1.23kg |
| USD | currency symbol | US$1,000 |
| s | currency narrow symbol | $1,000 |
| c | currency code | USD 1,000 |
| n | currency name | 1,000 US dollars |
### Numbers
| Value | Format | Result | |
| ------- | ------- | -------- | --------------------------------- |
| 123456 | 0,0 | 123,456 | thousands separator |
| 1234.5 | 0,0.0 | 1,234.5 | decimal separator |
| 1234.5 | 0,0.00 | 1,234.50 | fixed number of decimal digits |
| 123 | 0[.]0 | 123 | optional decimal separator |
| 123.4 | 0[.]0 | 123.4 | |
| 123.4 | 0[.]00 | 123.40 | |
| 123.45 | 0.00[0] | 123.45 | fixed and optional decimal digits |
| 123.456 | 0.00[0] | 123.456 | |
| -1 | -0 | -1 | negative sign |
| 1 | (0) | 1 | negative sign (accounting) |
| -1 | (0) | (1) | |
### Percentage
| Value | Format | Result |
| ------- | ------ | ------ |
| 1 | 0% | 100% |
| -0.12 | 0% | -12% |
| 0.12345 | 0.00% | 12.34% |
### Ordinals
| Value | Format | Result |
| ----- | ------ | ------- |
| 0 | 0o | 0th |
| 1 | 0o | 1st |
| 2 | 0o | 2nd |
| 3 | 0o | 3rd |
| 4 | 0o | 4th |
| 1234 | 0,0o | 1,234th |
### Compact notation
| Value | Format | Result | |
| ------------- | ------ | ----------- | ----------------------------- |
| 123 | 0a | 123 | short display |
| 1234 | 0a | 1K | |
| 12345 | 0a | 12K | |
| 123456 | 0a | 123K | |
| 1234567 | 0a | 1M | |
| 1234567890 | 0a | 1B | |
| 1234567890123 | 0a | 1T | |
| 1234 | 0A | 1 thousand | long display |
| 1234567 | 0A | 1 million | |
| 1234567890 | 0A | 1 billion | |
| 1234567890123 | 0A | 1 trillion | |
| 1234567 | 0.0a | 1.2M | combined with numeric formats |
| 1234567 | 0.0A | 1.2 million | |
### Exponential
| Value | Format | Result | |
| -------- | ------ | ------ | ----------------------------------------------------- |
| 1 | 0e | 1E0 | scientific (order-of-magnitude) |
| 10 | 0e | 1E1 | |
| 100 | 0e | 1E2 | |
| 1000 | 0e | 1E3 | |
| 10000 | 0e | 1E4 | |
| 1 | 0E | 1E0 | engineering (exponent of ten when divisible by three) |
| 10 | 0E | 10E0 | |
| 100 | 0E | 100E0 | |
| 1000 | 0E | 1E3 | |
| 10000 | 0E | 10E3 | |
| 100000 | 0E | 100E3 | |
| 12345678 | 0.0e | 1.2E7 | combined with numeric formats |
| 12345678 | 0.0E | 12.3E6 | |
### Digital
| Value | Format | Result | |
| ------------- | ------ | ------ | ----------------- |
| 1 | 0b | 1bit | bits (narrow) |
| 1024 | 0b | 1kb | |
| 1048576 | 0b | 1Mb | |
| 1073741824 | 0b | 1Gb | |
| 1099511627776 | 0b | 1Tb | |
| 1 | 0B | 1B | bytes (narrow) |
| 1024 | 0B | 1kB | |
| 1048576 | 0B | 1MB | |
| 1073741824 | 0B | 1GB | |
| 1099511627776 | 0B | 1TB | |
| 1 | 0 b | 1 bit | bits (short) |
| 1024 | 0 b | 1 kb | |
| 1 | 0 B | 1 byte | bytes (short) |
| 1024 | 0 B | 1 kB | |
| 1524 | 0b | 1.49kb | 2 fraction digits |
| 1524 | 0B | 1.49kB | |
### Length
| Value | Format | Result | |
| ----- | ------ | ------ | --------------------------------------------------- |
| 0.001 | 0m | 1mm | value in meters, formatted to closest unit (narrow) |
| 0.01 | 0m | 1cm | |
| 1 | 0m | 1m | |
| 1000 | 0m | 1km | |
| 1200 | 0m | 1.2km | |
| 0.001 | 0 m | 1 mm | (short) |
| 0.01 | 0 m | 1 cm | |
| 1 | 0 m | 1 m | |
| 1000 | 0 m | 1 km | |
| 1200 | 0 m | 1.2 km | |
### Mass
| Value | Format | Result | |
| ----- | ------ | ------- | ------ |
| 1 | 0k | 1kg | narrow |
| 0.001 | 0k | 1g | |
| 1.23 | 0k | 1.23kg | |
| 1 | 0 k | 1 kg | short |
| 0.001 | 0 k | 1 g | |
| 1.23 | 0 k | 1.23 kg | |
### Currency
| Value | Format | Result | |
| ----- | --------- | -------------------- | ----------------- |
| 123 | GBP | £123 | symbol |
| 1234 | 0,0GBP | £1,234 | |
| 1234 | 0,0.00GBP | £1,234.00 | |
| 123 | EUR | €123 | |
| 123 | JPY | JP¥123 | |
| 123 | USD | US$123 | |
| 123 | CAD | CA$123 | |
| 1000 | 0,0GBPs | £1,000 | narrow symbol |
| 1000 | 0,0EURs | €1,000 | |
| 1000 | 0,0USDs | $1,000 | |
| 1000 | 0,0CADs | $1,000 | |
| 1000 | 0,0JPYs | ¥1,000 | |
| 1000 | 0,0GBPc | GBP 1,000 | ISO currency code |
| 1000 | 0,0EURc | EUR 1,000 | |
| 1000 | 0,0USDc | USD 1,000 | |
| 1000 | 0,0JPYc | JPY 1,000 | |
| 1000 | 0,0GBPn | 1,000 British pounds | currency name |
| 1000 | 0,0EURn | 1,000 euros | |
| 1000 | 0,0USDn | 1,000 US dollars | |
| 1000 | 0,0JPYn | 1,000 Japanese yen | |
## License
MIT
