Stage 1 Draft / July 18, 2025

Measure

Introduction

This specification consists of two parts:

1 The Amount Object

Introduction

An Amount is an object that wraps mathematical value and a precision, together with a unit (e.g., mile, kilogram) or currency (e.g., EUR, JPY, USD). One can intuitively understand an Amount as a number that, so to speak, knows its own precision and what it is measuring.

The notation for mathematical values used by Amount are decimal digit string, which are Strings that adhere to the DecimalLiteral production, excepting "NaN", "Infinity", and *"-Infinity".

Rounding a mathematical value is an important part of this spec. When we say rounding mode in this specification we simply refer to ECMA-402's definition.

1.1 Abstract Operations

1.1.1 Operations for Reading Options

1.1.1.1 GetOption ( options, property, type, values, default )

The abstract operation GetOption takes arguments options (an Object), property (a property key), type (boolean, string or number), values (empty or a List of ECMAScript language values), and default (required or an ECMAScript language value) and returns either a normal completion containing an ECMAScript language value or a throw completion. It extracts the value of the specified property of options, converts it to the required type, checks whether it is allowed by values if values is not empty, and substitutes default if the value is undefined. It performs the following steps when called:

  1. Let value be ? Get(options, property).
  2. If value is undefined, then
    1. If default is required, throw a RangeError exception.
    2. Return default.
  3. If type is boolean, then
    1. Set value to ToBoolean(value).
  4. Else if type is number, then
    1. Set value to ? ToNumber(value).
  5. Else,
    1. Assert: type is string.
    2. Set value to ? ToString(value).
  6. If values is not empty and values does not contain value, throw a RangeError exception.
  7. Return value.

1.1.2 Operations on Decimal Digit Strings

1.1.2.1 CountSignificantDigits ( s )

The abstract operation CountSignificantDigits takes argument s (a decimal digit String) and returns a positive integer. It computes the number of significant digits in a given decimal digit String. It performs the following steps when called:

  1. Let digitsToCount be s.
  2. If digitsToCount contains an e character, set digitsToCount be the substring of s before the first occurence of "e".
  3. If digitsToCount contains a "." character, set digitsToCount to the result of replacing all occurrences of "." in digitsToCount by "".
  4. Let l be the length of digitsToCount.
  5. Return l.

1.1.2.2 CountFractionDigits ( s )

The abstract operation CountFractionDigits takes argument s (a decimal digit String) and returns a non-negative integer. It computes the number of fractional digits in a given decimal digit String. It performs the following steps when called:

  1. If s contains a "." character, then
    1. Let fractionDigits be the substring of s after the first "." character up to the first occurrence of "e" or "E" in s, if any.
    2. Let l be the length of fractionDigits.
    3. Return l.
  2. Otherwise:
    1. Return 0.

1.1.3 Abstract Operations

1.1.3.1 ApplyRoundingModeToPositive ( m, roundingMode )

The abstract operation ApplyRoundingModeToPositive takes arguments m (a positive mathematical value) and roundingMode (a rounding mode) and returns an integer. It computes the closest integer approximation to a given positive mathematical value, rounded according to the given rounding mode. It performs the following steps when called:

  1. Let mLow be floor(m).
  2. Let fraction be m – mLow.
  3. If fraction = 0, return mLow.
  4. Let mHigh be mLow + 1.
  5. If roundingMode is "floor" or "trunc", return mLow.
  6. If roundingMode is "ceil" or *"expand", return mHigh.
  7. If fraction < 0.5, return mLow.
  8. If fraction > 0.5, return mHigh.
  9. If roundingMode is "halfTrunc" or "halfFloor", return mLow.
  10. If roundingMode is "halfExpand" or *"halfCeil"*, return _mHigh_.
  11. If mLow is even, return mLow.
  12. Return mHigh.

1.1.3.2 RoundToFractionDigits ( v, n [ , roundingMode ] )

The abstract operation RoundToFractionDigits takes arguments v (a mathematical value) and n (a non-negative integer) and optional argument roundingMode (a rounding mode) and returns a mathematical value. It computes the closest approximation to a given mathematical value that has at most the given number of fractional digits, rounding (if necessary) according to the given rounding mode. It performs the following steps when called:

  1. If roundingMode is undefined, set roundingMode to "halfEven".
  2. If v = 0, return 0.
  3. If v < 0, then
    1. Let reverseRoundingMode be roundingMode.
    2. If roundingMode is "floor", set reverseRoundingMode to "ceil".
    3. If roundingMode is "ceil", set reverseRoundingMode to "floor".
    4. If roundingMode is "halfCeil", set reverseRoundingMode to "halfFloor".
    5. If roundingMode is "halfFloor", set reverseRoundingMode to "halfCeil".
    6. Let d be RoundToFractionDigits(–v, n, reverseRoundingMode).
    7. Return –d.
  4. Let e be the unique integer such that 10e ≤ v < 10e+1.
  5. Let pow be e + n.
  6. Let m be v × 10–pow.
  7. Let rounded be ApplyRoundingModeToPositive(m, roundingMode).
  8. Return rounded × 10e + n.

1.1.3.3 RoundToSignificantDigits ( v, n [ , roundingMode ] )

The abstract operation RoundToSignificantDigits takes arguments v (a mathematical value) and n (a non-negative integer) and optional argument roundingMode (a rounding mode) and returns a mathematical value. It computes the closest approximation to a given mathematical value that has at most the given number of significant digits, rounding (if necessary) according to the given rounding mode. It performs the following steps when called:

  1. If roundingMode is undefined, set roundingMode to "halfEven".
  2. If v = 0, return 0.
  3. If v < 0, then
    1. Let reverseRoundingMode be roundingMode.
    2. If roundingMode is "floor", set reverseRoundingMode to "ceil".
    3. If roundingMode is "ceil", set reverseRoundingMode to "floor".
    4. Let d be RoundToSignificantDigits(–v, n, reverseRoundingMode).
    5. Return –d.
  4. Let e be the unique integer such that 10e ≤ v < 10e+1.
  5. If n ≤ e, then
    1. Let pow be e - n.
    2. Let m be v × 10–pow.
    3. Let rounded be ApplyRoundingModeToPositive(m, roundingMode).
    4. Return rounded × 10n + e.
  6. Otherwise:
    1. todo.

1.1.3.4 RenderMVWithFractionDigits ( v, numDigits [ , roundingMode ] )

The abstract operation RenderMVWithFractionDigits takes arguments v (a mathematical value) and numDigits (a non-negative integer) and optional argument roundingMode (a rounding mode) and returns a String. It renders the given mathematical value with a given number of fractional digits, possibly rounding if necessary, using the given rounding mode, which, if missing, is "halfEven". It performs the following steps when called:

  1. If roundingMode is undefined, let mode be "halfEven", else let mode be roundingMode.
  2. If v < 0, let prefix be "-", else let prefix be "".
  3. If v < 0, set v to -v.
  4. Let rounded be ApplyRoundingModeToPositive(v × 10numDigits, mode).
  5. Set v to rounded × 10-numDigits.
  6. Let e be the smallest non-negative integer such that v × 10-numDigits is an integer.
  7. Let s be the unique decimal string representation of v without leading zeroes.
  8. If numDigits > e, then
    1. If v is an integer, return the string concatenation of _prefix, s, ".", and "0" repeated numDigits times.
    2. Otherwise, return the string concatenation of prefix, s and "0" repeated numDigits - e times.
  9. Otherwise:
    1. Return the string concatenation of _prefix, s and "0" repeated e - numDigits times.

1.1.3.5 GetAmountOptions ( opts )

The abstract operation GetAmountOptions takes argument opts (an Object) and returns either a normal completion containing a Record with fields [[Currency]] (a String or undefined), [[FractionDigits]] (a non-negative integer or undefined), [[RoundingMode]] (a rounding mode), [[SignificantDigits]] (a positive integer or undefined), and [[Unit]] (a String or undefined) or a throw completion. It validates the given options (an ECMAScript object) for creating an Amount and returns a Record with slots set to appropriate marthematical values (or undefined). It performs the following steps when called:

  1. Let opts be ? GetOptionsObject(opts).
  2. Let currency be ? GetOption(opts, "currency", string, empty, undefined).
  3. Let fractionDigits be ? GetOption(opts, "fractionDigits", number, empty, undefined).
  4. Let roundingMode be ? GetOption(opts, "roundingMode", string, « "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", "halfEven" », "halfEven").
  5. Let significantDigits be ? GetOption(opts, "significantDigits", number, empty, undefined).
  6. Let unit be ? GetOption(opts, "unit", string, empty, undefined).
  7. If currency is the empty String, throw a RangeError exception.
  8. If fractionDigits is not undefined, then
    1. If significantDigits is not undefined, throw a RangeError exception.
    2. If fractionDigits is not a non-negative integral number, throw a RangeError exception.
  9. Else if significantDigits is not undefined, then
    1. If significantDigits is not an integral number, throw a RangeError exception.
    2. If ℝ(significantDigits) < 1, throw a RangeError exception.
  10. If unit is the empty String, throw a RangeError exception.
  11. If unit is not undefined and currency is not undefined, throw a *RangeError exception.
  12. If currency is not undefined, set currency to the ASCII-uppercase of currency.
  13. If unit is not undefined, set unit to the ASCII-lowercase of unit.
  14. Return the Record { [[Currency]]: currency, [[FractionDigits]]: fractionDigits, [[RoundingMode]]: roundingMode, [[SignificantDigits]]: _significantDigits, [[Units]]: unit }.

1.2 The Amount Constructor

The Amount constructor:

  • is %Amount%.
  • is the initial value of the the "Amount" property of the global object.
  • creates and initializes a new Amount object when called as a constructor
  • may be used as the value of an extends clause of a class definition.

1.2.1 Amount ( x [ , opts ] )

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let toParse be undefined.
  3. If x is a BigInt, set toParse to BigInt::toString(x, 10).
  4. Else if x is a Number, set toParse to Number::toString(x, 10).
  5. Otherwise, if x is a String, set toParse to x.
  6. If toParse is not a String, throw a TypeError exception.
  7. If toParse is in « "NaN", "Infinity", "-Infinity" », throw a RangeError exception.
  8. Let parseResult be ParseText(toParse, StrDecimalLiteral).
  9. Let validatedOpts be ? GetAmountOptions(opts).
  10. If parseResult is a List of errors, throw a SyntaxError exception.
  11. Let amountValue be ? StringDecimalValue of parseResult.
  12. Let currency be validatedOpts.[[Currency]].
  13. Let fractionDigits be validatedOpts.[[FractionDigits]].
  14. Let roundingMode be validatedOpts.[[RoundingMode]].
  15. Let significantDigits be validatedOpts.[[SignificantDigits]].
  16. Let unit be validatedOpts.[[Unit]].
  17. Let roundedValue be amountValue.
  18. Assert: If fractionDigits is not undefined, then significantDigits is undefined.
  19. Assert: If significantDigits is not undefined, then fractionDigits is undefined.
  20. If both significantDigits and fractionDigits are undefined, then
    1. Set significantDigits to CountSignificantDigits(toParse).
    2. Set fractionDigits to CountFractionDigits(toParse).
  21. Else if significantDigits is undefined, then
    1. Set roundedValue be RoundToFractionDigits(amountValue, fractionDigits, roundingMode).
    2. Let digitStr be the unique decimal string representation of roundedValue without leading zeroes.
    3. Set significantDigits to CountSignificantDigits(digitStr).
  22. Otherwise:
    1. Set roundedValue be RoundToSignificantDigits(amountValue, significantDigits, roundingMode).
    2. Let digitStr be the unique decimal string representation of roundedValue without leading zeroes.
    3. Set fractionDigits to CountFractionDigits(digitStr).
  23. Let O be OrdinaryObjectCreate(%Amount.prototype%, « [[Currency]], [[FractionDigits]], [[SignificantDigits]], [[Unit]], [[Value]] »).
  24. Set O.[[Value]] to roundedValue.
  25. Set O.[[SignificantDigits]] to significantDigits.
  26. Set O.[[FractionDigits]] to fractionDigits.
  27. If unit is not undefined, set O.[[Unit]] to unit.
  28. If currency is not undefined, set O.[[Currency]] to currency.
  29. Return O.
 Note

Given a Number argument, the constructor converts it to a String using the toString method (with no arguments). In some cases, this may not be desired; consider passing in a String form of a Number using the toFixed or toPrecision methods.

1.2.1.1 Runtime Semantics: StringDecimalValue

The syntax-directed operation StringDecimalValue takes no arguments and returns either a normal completion containing a mathematical value or a throw completion. It is defined piecewise over the following productions:

StrDecimalLiteral ::: - StrUnsignedDecimalLiteral
  1. Let a be ? StringAmountValue of StrUnsignedDecimalLiteral.
  2. Assert: a is finite.
  3. Return −a.
 StrUnsignedDecimalLiteral ::: Infinity
  1. Throw a RangeError exception.
 StrUnsignedDecimalLiteral ::: DecimalDigits . DecimalDigitsopt ExponentPartopt
  1. Let a be MV of the first DecimalDigits.
  2. If the second DecimalDigits is present, then
    1. Let b be MV of the second DecimalDigits.
    2. Let n be the number of code points in the second DecimalDigits.
  3. Else,
    1. Let b be 0.
    2. Let n be 0.
  4. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  5. Return (a + (b × 10−n)) × 10e.
 StrUnsignedDecimalLiteral ::: . DecimalDigits ExponentPartopt
  1. Let b be MV of DecimalDigits.
  2. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  3. Let n be the number of code points in DecimalDigits.
  4. Let newValue be b × 10e − n.
  5. Return newValue.
 StrUnsignedDecimalLiteral ::: DecimalDigits ExponentPartopt
  1. Let a be MV of DecimalDigits.
  2. If ExponentPart is present, let e be MV of ExponentPart. Otherwise, let e be 0.
  3. Return a × 10e.

2 Properties of the Amount Prototype

2.1 Amount.prototype.toString ( [ options ] )

This method returns a String value that renders the underlying mathematical value according to its precision, as well as any unit or currency indicators, if present.

It performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[Value]]).
  3. Perform ? RequireInternalSlot(O, [[FractionDigits]]).
  4. Let options be ? GetOptionsObject(options).
  5. Let displayUnit be ? GetOption(options, "displayUnit", string, « "always", "auto", "never" », "auto").
  6. Let c be O.[[Currency]].
  7. Let u be O.[[Unit]].
  8. Let v be O.[[Value]].
  9. Let fractionDigits be O.[[FractionDigits]].
  10. Let s be RenderMVWithFractionDigits(v, fractionDigits).
  11. If u is undefined and c is undefined, then
    1. If displayUnit is "always", return the string concatenation of s, "[", "1", and "]".
    2. Else, return s.
  12. Else if u is undefined, then
    1. If displayUnit is "never", return s.
    2. Else, return the string concatenation of s, "[", c, and "]".
  13. Else,
    1. If displayUnit is "never", return s.
    2. Else, return the string concatenation of s, "[", u, and "]".

2.2 Amount.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used:

This method produces a String value that represents this Amount object formatted according to the conventions of the host environment’s current locale. This method is implementation-defined, and it is permissible, but not encouraged, for it to return the same thing as toString.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

2.3 Amount.prototype.with ( options )

This method returns a fresh Amount object whose underlying mathematical value is equal to the mathematical value of the current Amount, but possibly with different precision as specified in the options.

It performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[Currency]]).
  3. Perform ? RequireInternalSlot(O, [[Unit]]).
  4. Perform ? RequireInternalSlot(O, [[Value]]).
  5. Let options be ? GetAmountOptions(options).
  6. Let unit be options.[[Unit]].
  7. Let currency be options.[[Currency]].
  8. Let fractionDigits be options.[[FractionDigits]].
  9. Let significantDigits be options.[[SignificantDigits]].
  10. Let value be O.[[Value]].
  11. If fractionDigits is not undefined, set value to RoundToFractionDigits(value, fractionDigits).
  12. Else if significantDigits is not undefined, set value to RoundToSignificantDigits(value, significantDigits).
  13. Otherwise, throw a TypeError exception.
  14. Let N be OrdinaryObjectCreate("%Amount.prototype%", « [[Currency]], [[FractionDigits]], [[SignificantDigits]], [[Unit]], [[Value]] »).
  15. If unit is not undefined, then
    1. If O.[[Currency]] is not undefined, throw a TypeError exception.
    2. If O.[[Unit]] is undefined, throw a TypeError exception.
    3. If unit is not string equal to O.[[Unit]], throw a TypeError exception.
  16. If currency is not undefined, then
    1. If O.[[Unit]] is not undefined, throw a TypeError exception.
    2. If O.[[Currency]] is undefined, throw a TypeError exception.
    3. If currency is not string equal to O.[[Currency]], throw a TypeError exception.
  17. Set N.[[Value]] to value.
  18. Set N.[[Unit]] to unit.
  19. Set N.[[Currency]] to currency.
  20. Set N.[[FractionDigits]] to ℝ(fractionDigits).
  21. Set N.[[SignificantDigits]] to ℝ(significantDigits).
  22. Return N.

2.4 Amount.prototype [ %Symbol.toPrimitive% ] ( hint )

This method is called by ECMAScript language operators to convert an Amount to a primitive value. The allowed values are "default", "number", and "string". The default is "number."

It performs the following steps when called:

  1. Let O be the the this value.
  2. Perform ? RequireInternalSlot(O, [[Value]]).
  3. Perform ? RequireInternalSlot(O, [[FractionDigits]]).
  4. Perform ? RequireInternalSlot(O, [[Unit]]).
  5. Perform ? RequireInternalSlot(O, [[Currency]]).
  6. If hint is not in « "default", "number", "string" », throw a RangeError exception.
  7. If O.[[Unit]] is not undefined, throw a TypeError exception.
  8. If O.[[Currency]] is not undefined, throw a TypeError exception.
  9. Let mv be O.[[Value]].
  10. If hint is "string", then
    1. Let fractionDigits be O.[[FractionDigits]].
    2. Let str be RenderMVWithFractionDigits(mv, fractionDigits).
    3. Return str.
  11. Else,
    1. Return the Number value for mv.

3 Amendments to the ECMAScript® 2024 Internationalization API Specification

Editor's Note

This section lists amendments which must be made to ECMA-402, the ECMAScript® 2024 Internationalization API Specification. Text to be added is marked like this, and text to be deleted is marked like this. Blocks of unmodified text between modified sections are marked by [...].

3.1 Properties of the Amount Prototype Object

3.1.1 Amount.prototype.toLocaleString ( [ locales [ , options ] ] )

This definition supersedes the definition provided in es2025, 2.2.

This function performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[Decimal128Data]]).
  3. Let numberFormat be ? Construct(%Intl.NumberFormat%, « locales, options »).
  4. Return FormatNumeric(numberFormat, O.[[AmountData]]).

4 NumberFormat Objects

4.1 Abstract Operations for NumberFormat Objects

4.1.1 GetNumberFormatPattern ( numberFormat, x )

The abstract operation GetNumberFormatPattern takes arguments numberFormat (an Intl.NumberFormat) and x (an Intl mathematical value) and returns either a normal completion containing a String or a throw completion. It considers the resolved unit-related options in the number format object along with the final scaled and rounded number being formatted (an Intl mathematical value) and returns a pattern, a String value as described in 16.2.3. It performs the following steps when called:

  1. Let resolvedLocaleData be numberFormat.[[LocaleData]].
  2. Let patterns be resolvedLocaleData.[[patterns]].
  3. Assert: patterns is a Record (see 16.2.3).
  4. Let style be numberFormat.[[Style]].
  5. If style is "percent", then
    1. Set patterns to patterns.[[percent]].
  6. Else if style is "unit", then
    1. Let unit be numberFormat.[[Unit]].
    2. Let fmtUnit be x.[[Unit]].
    3. If fmtUnit is not undefined and SameValueNonNumber(unit, fmtUnit) is false, then
      1. If unit is not undefined, throw a TypeError exception.
      2. Set unit to fmtUnit.
    4. Else if unit is undefined, then
      1. Throw a TypeError exception.
    5. Let unitDisplay be numberFormat.[[UnitDisplay]].
    6. Set patterns to patterns.[[unit]].
    7. If patterns doesn't have a field [[<unit>]], then
      1. Set unit to "fallback".
    8. Set patterns to patterns.[[<unit>]].
    9. Set patterns to patterns.[[<unitDisplay>]].
  7. Else if style is "currency", then
    1. Let currency be numberFormat.[[Currency]].
    2. Let fmtCurrency be x.[[Currency]].
    3. If fmtCurrency is not undefined and SameValueNonNumber(currency, fmtCurrency) is false, then
      1. If currency is not undefined, throw a TypeError exception.
      2. Set currency to fmtCurrency.
    4. Else if currency is undefined, then
      1. Throw a TypeError exception.
    5. Let currencyDisplay be numberFormat.[[CurrencyDisplay]].
    6. Let currencySign be numberFormat.[[CurrencySign]].
    7. Set patterns to patterns.[[currency]].
    8. If patterns doesn't have a field [[<currency>]], then
      1. Set currency to "fallback".
    9. Set patterns to patterns.[[<currency>]].
    10. Set patterns to patterns.[[<currencyDisplay>]].
    11. Set patterns to patterns.[[<currencySign>]].
  8. Else,
    1. Assert: style is "decimal".
    2. Set patterns to patterns.[[decimal]].
  9. If x is negative-infinity, then
    1. Let category be negative-non-zero.
  10. Else if x is negative-zero, then
    1. Let category be negative-zero.
  11. Else if x is not-a-number, then
    1. Let category be positive-zero.
  12. Else if x is positive-infinity, then
    1. Let category be positive-non-zero.
  13. Else,
    1. Assert: x is a mathematical value.
    2. If x < 0, then
      1. Let category be negative-non-zero.
    3. Else if x > 0, then
      1. Let category be positive-non-zero.
    4. Else,
      1. Let category be positive-zero.
  14. Let signDisplay be numberFormat.[[SignDisplay]].
  15. If signDisplay is "never", then
    1. Let pattern be patterns.[[zeroPattern]].
  16. Else if signDisplay is "auto", then
    1. If category is positive-non-zero or positive-zero, then
      1. Let pattern be patterns.[[zeroPattern]].
    2. Else,
      1. Let pattern be patterns.[[negativePattern]].
  17. Else if signDisplay is "always", then
    1. If category is positive-non-zero or positive-zero, then
      1. Let pattern be patterns.[[positivePattern]].
    2. Else,
      1. Let pattern be patterns.[[negativePattern]].
  18. Else if signDisplay is "exceptZero", then
    1. If category is positive-zero or negative-zero, then
      1. Let pattern be patterns.[[zeroPattern]].
    2. Else if category is positive-non-zero, then
      1. Let pattern be patterns.[[positivePattern]].
    3. Else,
      1. Let pattern be patterns.[[negativePattern]].
  19. Else,
    1. Assert: signDisplay is "negative".
    2. If category is negative-non-zero, then
      1. Let pattern be patterns.[[negativePattern]].
    3. Else,
      1. Let pattern be patterns.[[zeroPattern]].
  20. Return pattern.

4.1.2 ToIntlMathematicalValue ( value )

The abstract operation ToIntlMathematicalValue takes argument value (an ECMAScript language value) and returns either a normal completion containing an Intl mathematical value or a throw completion. It returns value converted to an Intl mathematical value, which is a mathematical value together with positive-infinity, negative-infinity, not-a-number, and negative-zero. This abstract operation is similar to 7.1.3, but a mathematical value can be returned instead of a Number or BigInt, so that exact decimal values can be represented. It performs the following steps when called:

  1. If value has the [[Value]] and [[FractionDigits]] internal slots, let primValue be RenderMVWithFractionDigits(value.[[Value]], value.[[FractionDigits]]) elseLet letprimValue be ? ToPrimitive(value, number).
  2. If primValue is a BigInt, return ℝ(primValue).
  3. If primValue is a String, then
    1. Let str be primValue.
  4. Else,
    1. Let x be ? ToNumber(primValue).
    2. If x is -0𝔽, return negative-zero.
    3. Let str be Number::toString(x, 10).
  5. Let text be StringToCodePoints(str).
  6. Let literal be ParseText(text, StringNumericLiteral).
  7. If literal is a List of errors, return not-a-number.
  8. Let intlMV be the StringIntlMV of literal.
  9. If intlMV is a mathematical value, then
    1. Let rounded be RoundMVResult(abs(intlMV)).
    2. If rounded is +∞𝔽 and intlMV < 0, return negative-infinity.
    3. If rounded is +∞𝔽, return positive-infinity.
    4. If rounded is +0𝔽 and intlMV < 0, return negative-zero.
    5. If rounded is +0𝔽, return 0.
  10. Return intlMV.

4.1.3 SetNumberFormatUnitOptions ( intlObj, options )

The abstract operation SetNumberFormatUnitOptions takes arguments intlObj (an Intl.NumberFormat) and options (an Object) and returns either a normal completion containing unused or a throw completion. It resolves the user-specified options relating to units onto intlObj. It performs the following steps when called:

  1. Let style be ? GetOption(options, "style", string, « "decimal", "percent", "currency", "unit" », "decimal").
  2. Set intlObj.[[Style]] to style.
  3. Let currency be ? GetOption(options, "currency", string, empty, undefined).
  4. If currency is undefined, then
    1. If style is "currency", throw a TypeError exception.
  5. Else,
    1. If IsWellFormedCurrencyCode(currency) is false, throw a RangeError exception.
  6. If currency is not undefined and IsWellFormedCurrencyCode(currency) is false, throw a RangeError exception.
  7. Let currencyDisplay be ? GetOption(options, "currencyDisplay", string, « "code", "symbol", "narrowSymbol", "name" », "symbol").
  8. Let currencySign be ? GetOption(options, "currencySign", string, « "standard", "accounting" », "standard").
  9. Let unit be ? GetOption(options, "unit", string, empty, undefined).
  10. If unit is undefined, then
    1. If style is "unit", throw a TypeError exception.
  11. Else,
    1. If IsWellFormedUnitIdentifier(unit) is false, throw a RangeError exception.
  12. If unit is not undefined and IsWellFormedUnitIdentifier(unit) is false, throw a RangeError exception.
  13. Let unitDisplay be ? GetOption(options, "unitDisplay", string, « "short", "narrow", "long" », "short").
  14. If style is "currency", then
    1. If currency is not undefined, set Set intlObj.[[Currency]] to the ASCII-uppercase of currency.
    2. Set intlObj.[[CurrencyDisplay]] to currencyDisplay.
    3. Set intlObj.[[CurrencySign]] to currencySign.
  15. If style is "unit", then
    1. If unit is not undefined, Set set intlObj.[[Unit]] to unit.
    2. Set intlObj.[[UnitDisplay]] to unitDisplay.
  16. Return unused.

A Copyright & Software License

Copyright Notice

© 2025 Ben Allen, Jesse Alama

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.