Skip to content
/ numfmt Public
forked from borgar/numfmt

Full ECMA-376 number and date formatting in JavaScript

Notifications You must be signed in to change notification settings

protobi/numfmt

 
 

Repository files navigation

numfmt – a spreadsheet number formatter

The numfmt library formats numbers according to a specifier string as defined in [ECMA-376][ecma]. The library tries its best to emulate the inns and outs of what the Excel spreadsheet software does.

The library is written in pure JavaScript and has no dependencies. It is comparable to the [SSF][ssf] with some minor interface exceptions.

Features

Why use this rather than the battle tested SSF? You may have no need to but numfmt is fully open source, has equivalent (if not better) formatting capabilities, built in international support, customizability, input parsing, and may run about twice as fast in most cases.

Adding locales is simple but those included are:

  • Arabic (ar)
  • Armenian (hy)
  • Azeri (az)
  • Belarusian (be)
  • Bengali (bn)
  • Bulgarian (bg)
  • Burmese (my)
  • Catalan (ca)
  • Chinese (zh_CN, zh_HK, zh_TW)
  • Croatian (hr)
  • Czech (cs)
  • Danish (da)
  • Dutch (nl)
  • English (en, en_AU, en_CA, en_GB, en_IE)
  • Filipino (fil)
  • Finnish (fi)
  • French (fr, fr_CA, fr_CH)
  • Georgian (ka)
  • German (de, de_CH)
  • Greek (el)
  • Gujarati (gu)
  • Hebrew (he)
  • Hindi (hi)
  • Hungarian (hu)
  • Icelandic (is)
  • Indonesian (id)
  • Italian (it, it_CH)
  • Japanese (ja)
  • Kannada (kn)
  • Kazakh (kk)
  • Korean (ko)
  • Latvian (lv)
  • Lithuanian (lt)
  • Malayalam (ml)
  • Marathi (mr)
  • Mongolian (mn)
  • Norwegian (nb, no)
  • Polish (pl)
  • Portuguese (pt, pt_BR)
  • Punjabi (pa)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es, es_AR, es_BO, es_CL, es_CO, es_EC, es_MX, es_PY, es_UY, es_VE)
  • Swedish (sv)
  • Tamil (ta)
  • Telugu (te)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Vietnamese (vi)
  • Welsh (cy)

The library is made to work with current generation spreadsheets and so it does not support the 1904 date system. It does not have built in tables for formats addressable by offsets, you are expected to maintain those yourself.

Installing

If you don't want to download and build numfmt yourself, the library is conveniently provided as an NPM package:

$ npm install numfmt

Using

import { format } from "numfmt";

const output = format("#,##0.00", 1234.56);
console.log(output);

The full API documentation is available under API.md.

Format syntax

Microsoft have excellent documentation on how the format works. Here are some quick basics:

A format pattern is divided into 4 sections: <POSITIVE>;<NEGATIVE>;<ZERO>;<TEXT>

Only the first section is mandatory, the others are filled in as needed. The sections consist of symbols to indicate what to emit. The symbols are case insensitive:

Symbol Result Description
0 Digit or Zero 7 formatted with 00 will emit "07"
# Digit if needed 7 formatted with ## will emit "7"
? Digit or Space 7 formatted with ?? will emit " 7"
. Decimal point
, Thousands separator 1234 formatted with #,##0 will emit "1,234". The emitted grouping character depends on the locale used.
% Percentage Number is multiplied by 100 before it is shown. .7 formatted with 0% will emit "70%"
E-, E+ Exponential format 12200000 formatted with 0.00E+00 will emit "1.22E+07"
$, -, +, /, (, ), Pass-through The symbol is printed as-is.
\ Escape Pass the the next character through as-is.
* Fill Repeat the next character in the format enough times to fill the column to its current width. By default numfmt emits nothing when this is used.
_ Skip width Skip the width of the next character. By default numfmt emits only a single space when this is used.
"text" Pass-through Pass through whatever text is inside the quotation marks as-is. 7 formatted with 0 "bells" will emit "7 bells"
@ Text value When value is a text, emit it as is: foo formatted with "bar"@"bar" will emit "barfoobar"
yy Years Two digit year
yyyy Years Four digit year
m Month 1–12
mm Month 01–12
mmm Short month Month name abbreviation (Jan–Dec). Names are locale dependent.
mmmm Month name Full month name (January–December). Names are locale dependent.
mmmmm Month name Single letter month abbreviation (J–D). Names are locale dependent.
d Days 1–31
dd Days 01–31
ddd Weekdays Sun–Sat
dddd Weekdays Sunday–Saturday
h Hours 0–23 or 1–12
hh Hours 00–23 or 01–12
m Minutes 0–59
mm Minutes 00–59
s Seconds 0–59
ss Seconds 00–59
AM/PM 12h clock Sets clock to 12h and emits AM or PM.
A/P 12h clock Sets clock to 12h and emits A or P.
[h] Hours Elapsed time in hours
[m] Minutes Elapsed time in minutes
[s] Seconds Elapsed time in seconds

The <POSITIVE> and <NEGATIVE> sections may optionally have conditionals. A condition is set by a comparison operator followed by a number, followed by the regular format symbols, surrounded by square brackets: [>=-2.5]#,##0.0. The supported set of operators is: = > < >= <= <>

  • There must not be more than 4 sections.
  • There must not be more than 2 conditional sections.
  • There must not be numerical or date emitting symbol in the (4th) text part.

About

Full ECMA-376 number and date formatting in JavaScript

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%