<p align="center"> <img alt="numerable" src="resources/numerable-logo-with-text-384-320.png"> </p> <p align="center"> <img alt="numerable-format-demo" width="400" src="resources/numerable-format-demo.gif"> </p> <p align="center"> <a href="https://travis-ci.com/gastonmesseri/numerable.svg?branch=master" alt="Build status"> <img src="https://travis-ci.com/gastonmesseri/numerable.svg?branch=master" /> </a> <a href="https://coveralls.io/repos/github/gastonmesseri/numerable/badge.svg?branch=master" alt="Build status"> <img src="https://coveralls.io/repos/github/gastonmesseri/numerable/badge.svg?branch=master" /> </a> <a href="https://img.shields.io/badge/license-MIT-blue.svg" alt="Build status"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" /> </a> <a href="https://img.shields.io/npm/dw/numerable?label=downloads" alt="Build status"> <img src="https://img.shields.io/npm/dw/numerable?label=downloads" /> </a> <a href="https://img.shields.io/npm/types/numerable" alt="Build status"> <img src="https://img.shields.io/npm/types/numerable" /> </a> <a href="https://img.shields.io/github/issues-raw/gastonmesseri/numerable" alt="Build status"> <img src="https://img.shields.io/github/issues-raw/gastonmesseri/numerable" /> </a> <a href="https://img.shields.io/npm/v/numerable?label=version" alt="Build status"> <img src="https://img.shields.io/npm/v/numerable?label=version" /> </a> </p>

numerable

numerable is a number formatting library for Javascript and Typescript apps.

---

:gear: Installation

Use npm or yarn to install numerable.

npm install --save numerable
# or
yarn add numerable

:book: Usage

import { format, parse } from 'numerable';

format(1500250.2, '0,0.00');
//=> '1,500,250.20'

format(0.25, '0.0 %');
//=> '25.0 %'

format(1200, '0.00 a');
//=> '1.20 K'

parse('80.5%');
//=> 0.805

---

:1234: Formatting numbers

Numbers formatting in numerable is done through a pattern-based syntax. With these patterns you can easily define common number formats, similar to date formatting.

The numeric pattern syntax defines:

• Amount of decimal places
• Thousands separator (grouping)
• Number sign type (+ - and ())
• Number sign position
• Positive sign visibility

Examples

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:-----------------:| | 10000 | "0,0.0000" | "10,000.0000" | en (English) | | 1.23 | "0.0" | "1.2" | en (English) | | 10000.23 | "0,0" | "10,000" | en (English) | | 1000.2345 | "0,0.X" | "1,000.2345" | en (English) | | 1000.2345 | "0,0.X" | "1 000,2345" | fr (French) | | 0 | "0.00" | "0,00" | fr (French) | | -10000 | "0,0.0" | "-10.000,0" | es (Spanish) | | 10000.1234 | "0.000" | "10000.123" | en (English) | | 10000.001 | "0[.]00" | "10000" | en (English) | | 10000 | "(0,0.0)" | "10,000.0" | en (English) | | -10000 | "(0,0.0)" | "(10,000.0)" | en (English) | | -12300 | "+0,0.00" | "-12,300.00" | en (English) | | 12300 | "+0,0.00" | "+1,2300.00" | ja (Japanese) | | 1230 | "0,0+" | "1,230+" | en (English) | | 1230 | "0,0-" | "1,230" | en (English) | | 0.67 | "0.0####" | "0.67" | en (English) | | 0.67 | "0.000##" | "0.670" | en (English) | | 3162.63 | "0.0####" | "3162.63" | en (English) | | 3162.6338 | "0.0####" | "3162.6338" | en (English) | | 0.23 | "000.##" | "000.23" | en (English) | | 1234.567 | "0,0.00" | "١‎٬٢‎٣‎٤‎٫٥‎٧‎" | arEG (Arabic) | | undefined | "0,0.00" | "" | en (English) | | null | "0.00" | "" | en (English) | | NaN | "0.0" | "" | en (English) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Percentages

By adding the % symbol to any of the previous patterns, the value is multiplied by 100 and the % symbol is added in the place indicated.

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:-----------------:| | 0.52 | "0.##%" | "52%" | en (English) | | 1 | "0.##%" | "100%" | en (English) | | 1 | "0,0.00 %" | "100.00 %" | en (English) | | -0.88 | "0 %" | "-88 %" | en (English) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Abbreviated numbers

If an abbreviation is specified in the pattern (a), numerable will look for the shortest abbreviation for your number, and it will display the number with a locale-specific abbreviation.

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:------------------:| | 2000000000 | "0.0a" | "2.0B" | en (English) | | 1230974 | "0.0a" | "1.2M" | en (English) | | 2460 | "0 a" | "2 mil" | es (Spanish) | | -104000 | "0 a" | "-104 K" | en (English) | | 999950 | "0.0a" | "1.0тыс." | ru (Russian) | | 999999999 | "0 a" | "1 Mio." | de (German) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Currency

numerable will format the currency symbol if the currency ISO code (ISO 4217) is passed as a format option (e.g. format(155, '$ 0.00', { currency: 'EUR' })) and the dollar symbol ($) is found in the pattern.

| Number | Pattern | Result | Currency | |---------------: |-------------: |-------------------: |:------------------: | | 1500.143 | "$0,0.00" | "$1,500.14" | USD (US Dollar) | | 1500.143 | "$0,0.00" | "€1,500.14" | EUR (Euro) | | -1500.143 | "0,0.00 $" | "-1,500.14 £" | GBP (Pound Sterling) | | 1500.143 | "0,0.00 $" | "1,500.14 ¥" | JPY (Yen) | | 1500.143 | "(0,0.00 $)" | "1,500.14 CN¥" | CNY (Yuan Renminbi) | | -1500.143 | "(0,0.00 $)" | "(1,500.14 A$)" | AUD (Australian dollar) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Bytes

numerable allows you to format bytes by adding the 'bd' or 'bb' characters to the pattern.

• 'bd' format bytes in a decimal scale (1000)
• 'bb' format bytes in a binary scale (1024)

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:-----------------:| | 3500 | "0.00bd" | "3.50KB" | en (English) | | 3500 | "0.00bb" | "3.42KiB" | en (English) | | -3500000 | "0.00bb" | "-3.34MiB" | en (English) | | 2444222000000 | "0.00bd" | "2.44TB" | en (English) | | 2444222000000 | "0.00bb" | "2.22TiB" | en (English) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Ordinal numbers

numerable allows you to format ordinal numbers based on the locale. The character 'o' in the mask will enable the ordinal numbers formatting.

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:-----------------:| | 1 | "0o" | "1st" | en (English) | | 2 | "0o" | "2nd" | en (English) | | 3 | "0o" | "3rd" | en (English) | | 4 | "0o" | "4th" | en (English) | | 1 | "0o" | "1er" | fr (French) | | 12 | "0o" | "12º" | es (Spanish) | | 8 | "0o" | "8." | de (German) | | <img width="200" height="1"> | <img width="200" height="1"> | <img width="200" height="1"> | <img width="150" height="1"> |

:small_orange_diamond: Time durations

Given an amount of seconds, it will display hours, minutes, and seconds.

| Number | Pattern | Result | Locale | |---------------: |-------------: |-------------------: |:------------------:| | 0 | "00:00:00" | "0