Proposed abbreviation API for Intl.NumberFormat

gistfile1.md

Intl.NumberFormat

Syntax

new Intl.NumberFormat([locales[, options]])
Intl.NumberFormat.call(this[, locales[, options]])

Parameters

…

options

Optional. An object with some or all of the following properties:

…

abbreviationThreshold

Numbers whose absolute value is greater than this number will be abbreviated. Possible values are from 0 to Infinity; the default is Infinity, which effectively disables abbreviation.

  <dt>abbreviationRoundingMethod</dt>
  <dd>The rounding behavior to exhibit when abbreviating a number. Possible values are <code>Intl.NumberFormat.ROUND_CEILING</code>, <code>Intl.NumberFormat.ROUND_FLOOR</code>, <code>Intl.NumberFormat.ROUND_UP</code>, <code>Intl.NumberFormat.ROUND_DOWN</code>, <code>Intl.NumberFormat.ROUND_HALF_DOWN</code>, <code>Intl.NumberFormat.ROUND_HALF_EVEN</code>, and <code>Intl.NumberFormat.ROUND_HALF_UP</code>; the default is <code>Intl.NumberFormat.ROUND_HALF_CEILING</code>. For more information about rounding modes, see <a href="#roundingmodes">rounding modes</a>.</dd>
  …
</dl>

…

Examples

…

Example: Using options

The results can be customized using the options argument:

var number = 1234567.89;
…

// abbreviate a number
console.log(new Intl.NumberFormat('en-US', { abbreviationThreshold: 1e6, maximumSignificantDigits: 3 }).format(number));
// → 1.23M
console.log(new Intl.NumberFormat('en-US', { abbreviationThreshold: 1e6, style: 'currency', maximumSignificantDigits: 3 }).format(number));
// → $1.23M
console.log(new Intl.NumberFormat('ja-JP', { abbreviationThreshold: 1e6, maximumSignificantDigits: 3 }).format(number));
// → 123万
…

Addendum

Rounding modes

Intl.NumberFormat.ROUND_CEILING

Rounding mode to round towards positive infinity.

Intl.NumberFormat.ROUND_FLOOR

Rounding mode to round towards negative infinity.

Intl.NumberFormat.ROUND_DOWN

Rounding mode to round towards zero.

Intl.NumberFormat.ROUND_UP

Rounding mode to round away from zero.

Intl.NumberFormat.ROUND_HALF_CEILING

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards positive infinity.

Intl.NumberFormat.ROUND_HALF_UP

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.

Intl.NumberFormat.ROUND_HALF_EVEN

Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.

Intl.NumberFormat.ROUND_HALF_FLOOR

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards negative infinity.

Intl.NumberFormat.ROUND_HALF_DOWN

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.

(Prior art: http://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html)

Oh yay!

Intl.NumberFormat('en-CA', {notation: 'compact'}).format(7654321)
"7.7M"
Intl.NumberFormat('ja-JP', {notation: 'compact'}).format(7654321)
"765万"

I'm a little concerned that the en-CA implementation rounded up instead of down. Sometimes products don't want to overstate values (eg. follower counts). Is the ability to configure the rounding behavior still on the table?

I have no idea and I'm the wrong person to ask. I just found this gist when I searched for the funcationality before I found the answer on MDN and figured I'd leave a note.