Intl.NumberFormat - flyby fixes

files/en-us/web/javascript/reference/global_objects/intl/numberformat/format/index.md

@@ -14,9 +14,7 @@ browser-compat: javascript.builtins.Intl.NumberFormat.format
 ---
 {{JSRef}}
 
-The **`Intl.NumberFormat.prototype.format()`** method formats a
-number according to the locale and formatting options of this
-{{jsxref("Intl.NumberFormat")}} object.
+The **`Intl.NumberFormat.prototype.format()`** method formats a number according to the [locale and formatting options](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters) of this {{jsxref("Intl.NumberFormat")}} object.
 
 {{EmbedInteractiveExample("pages/js/intl-numberformat-prototype-format.html", "taller")}}
 
@@ -31,41 +29,61 @@ format(number)
 ### Parameters
 
 - `number`
-  - : A {{jsxref("Number")}} or {{jsxref("BigInt")}} to format.
+  - : A {{jsxref("Number")}}, {{jsxref("BigInt")}}, or string, to format.
+
+Strings are parsed as _**string** numeric literals_ (as defined by the ECMA-262 "[StringNumericLiteral](https://tc39.es/ecma262/#prod-StringNumericLiteral)" grammar).
+These support, among other things, the general syntax for decimal strings `#.#E#`, and non-base-10 numbers like hexadecimal and binary.
+String values passed to the `format()` function:
+
+- may have leading and/or trailing white space and/or line terminators.
+- may have any number of leading 0 digits.
+- may include a "+" or "-" character to indicate its sign.
+- may be empty or whitespace-only.
+  In this case the value is converted to +0.
+- may include `Infinity` or `-Infinity`.
+- cannot be suffixed with `n` (the suffix used to indicate that a numeric value is a `BigInt`)
+- cannot include a numeric literal separator (`_`).
+
+> **Note:** Older versions of the specification parsed strings as a {{jsxref("Number")}}.
+> Check the compatibility table for your browser.
 
 ## Description
 
-The `format` getter function formats a number into a string according to the
-locale and formatting options of this {{jsxref("Intl.NumberFormat")}} object.
+The `format()` method formats a number into a string according to the locale and formatting options of this {{jsxref("Intl.NumberFormat")}} object.
 
-> **Note:** Numbers in JavaScript suffer from loss of precision if they are too big or too small, making the text representation inaccurate. If you are formatting an integer larger than {{jsxref("Number.MAX_SAFE_INTEGER")}}, prefer using a {{jsxref("BigInt")}} instead.
->
-> ```js
-> new Intl.NumberFormat('en-US').format(1234567891234567891) // 1,234,567,891,234,568,000
-> new Intl.NumberFormat('en-US').format(1234567891234567891n) // 1,234,567,891,234,567,891
-> ```
+{{jsxref("Number")}} values in JavaScript suffer from loss of precision if they are too big or too small, making the text representation inaccurate.
+If you are performing calculations with integers larger than {{jsxref("Number.MAX_SAFE_INTEGER")}} you should use a {{jsxref("BigInt")}} instead, which will format correctly:
+
+```js
+new Intl.NumberFormat('en-US').format(1234567891234567891) // 1,234,567,891,234,568,000
+new Intl.NumberFormat('en-US').format(1234567891234567891n) // 1,234,567,891,234,567,891
+```
+
+You can also pass through very large strings to be formatted as an arbitrary-precision decimal string (if you're performing calculations on the data you will still need to work with `BigInt`):
+
+```js
+new Intl.NumberFormat('en-US').format("1234567891234567891") // 1,234,567,891,234,567,891
+```
 
 ## Examples
 
 ### Using format
 
-Use the `format` getter function for formatting a single currency value,
-here for Russia:
+Use the `format` getter function for formatting a single currency value.
+The code below shows how to format the roubles currency for a Russian locale:
 
 ```js
 const options = { style: 'currency', currency: 'RUB' };
 const numberFormat = new Intl.NumberFormat('ru-RU', options);
 console.log(numberFormat.format(654321.987));
-// → "654 321,99 руб."
+// → "654 321,99 ₽"
 ```
 
 ### Using format with map
 
 Use the `format` getter function for formatting all numbers in an array.
-Note that the function is bound to the {{jsxref("Intl.NumberFormat")}} from which it was
-obtained, so it can be passed directly to {{jsxref("Array.prototype.map")}}. This is
-considered a historical artefact, as part of a convention which is no longer followed
-for new features, but is preserved to maintain compatibility with existing programs.
+Note that the function is bound to the {{jsxref("Intl.NumberFormat")}} from which it was obtained, so it can be passed directly to {{jsxref("Array.prototype.map")}}.
+This is considered a historical artefact, as part of a convention which is no longer followed for new features, but is preserved to maintain compatibility with existing programs.
 
 ```js
 const a = [123456.789, 987654.321, 456789.123];
@@ -75,6 +93,36 @@ console.log(formatted.join('; '));
 // → "123.456,789; 987.654,321; 456.789,123"
 ```
 
+### Using format with a string
+
+Using a string we can specify very numbers that are larger than {{jsxref("Number.MAX_SAFE_INTEGER")}} without losing precision.
+
+```js
+const numberFormat = new Intl.NumberFormat("en-US");
+
+// Here the value is converted to a Number
+console.log(numberFormat.format(987654321987654321))
+// → 987,654,321,987,654,300
+
+// Here we use a string and don't lose precision
+console.log(numberFormat.format("987654321987654321"));
+// → 987,654,321,987,654,321
+```
+
+We can also use the general "E" exponent syntax for decimal strings: `#.#E#`.
+The code below creates a {{jsxref("BigInt")}},  coerces it to a string with the suffix `E-6`, and then formats it.
+
+```js
+const numberFormat = new Intl.NumberFormat("en-US");
+const bigNum = 1000000000000000110000n;
+console.log(numberFormat.format(bigNum));
+// → "1,000,000,000,000,000,110,000"
+
+// Format as a string using the `E` syntax:
+console.log(numberFormat.format(bigNum + "E-6"));
+// → "1,000,000,000,000,000.11"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrange/index.md

@@ -8,15 +8,14 @@ tags:
   - Localization
   - Method
   - NumberFormat
+  - Experimental
   - Prototype
   - Reference
 browser-compat: javascript.builtins.Intl.NumberFormat.formatRange
 ---
-{{JSRef}}
+{{JSRef}} {{SeeCompatTable}}
 
-The **`Intl.NumberFormat.prototype.formatRange()`** method formats a range of
-numbers according to the locale and formatting options of the
-{{jsxref("Intl.NumberFormat")}} object from which the method is called.
+The **`Intl.NumberFormat.prototype.formatRange()`** method formats a range of numbers according to the locale and formatting options of the {{jsxref("Intl.NumberFormat")}} object from which the method is called.
 
 ## Syntax
 
@@ -32,10 +31,16 @@ formatRange(startRange, endRange)
 - `endRange`
   - : A {{jsxref("Number")}} or {{jsxref("BigInt")}}.
 
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if `startRange` is less than `endRange`, or either value is `NaN`.
+- {{jsxref("TypeError")}}
+  - : Thrown if either `startRange` or `endRange` is undefined.
+
 ## Description
 
-The `formatRange` getter function formats a range of numbers into a string according to the
-locale and formatting options of this {{jsxref("Intl.NumberFormat")}} object from which it is called.
+The `formatRange` getter function formats a range of numbers into a string according to the locale and formatting options of this {{jsxref("Intl.NumberFormat")}} object from which it is called.
 
 ## Examples
 
@@ -51,6 +56,9 @@ const nf = new Intl.NumberFormat("en-US", {
 });
 
 console.log(nf.formatRange(3, 5)); // → "€3 – €5"
+
+// Note: the "approximately equals" symbol is added if 
+//   startRange and endRange round to the same values.
 console.log(nf.formatRange(2.9, 3.1)); // → "~€3"
 ```
 

files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrangetoparts/index.md

@@ -15,14 +15,14 @@ browser-compat: javascript.builtins.Intl.NumberFormat.formatRangeToParts
 ---
 {{JSRef}}
 
-The **`Intl.Numberformat.prototype.formatRangeToParts()`** method
-allows locale-aware formatting of strings produced by `NumberFormat`
-formatters.
+The **`Intl.Numberformat.prototype.formatRangeToParts()`** method enables locale-aware formatting of strings produced by `NumberFormat` formatters.
+
+It returns an {{jsxref("Array")}} of objects containing the locale-specific tokens from which it is possible to build custom strings while preserving the locale-specific parts.
+This makes it possible to provide locale-aware custom formatting ranges of number strings.
 
 ## Syntax
 
 ```js
-formatRangeToParts()
 formatRangeToParts(startRange, endRange)
 ```
 
@@ -38,12 +38,7 @@ formatRangeToParts(startRange, endRange)
 
 An {{jsxref("Array")}} of objects containing the formatted range of numbers in parts.
 
-## Description
-
-The `formatRangeToParts()` method is useful when custom formatting ranges of number
-strings. It returns an {{jsxref("Array")}} of objects containing the locale-specific
-tokens from which it is possible to build custom strings while preserving the
-locale-specific parts. The structure of the array the `formatRangeToParts()` method returns looks like this:
+The structure of the returned looks like this:
 
 ```js
 [
@@ -56,41 +51,54 @@ locale-specific parts. The structure of the array the `formatRangeToParts()` met
 
 ```
 
-Possible types are the following:
+Possible values for the `type` property include:
 
-- currency
-  - : The currency string, such as the symbols "$" and "€" or the name "Dollar", "Euro",
-    depending on how `currencyDisplay` is specified.
-- decimal
+- `currency`
+  - : The currency string, such as the symbols "$" and "€" or the name "Dollar", "Euro", depending on how `currencyDisplay` is specified.
+- `decimal`
   - : The decimal separator string (".").
-- fraction
+- `fraction`
   - : The fraction number.
-- group
+- `group`
   - : The group separator string (",").
-- infinity
+- `infinity`
   - : The {{jsxref("Infinity")}} string ("∞").
-- integer
+- `integer`
   - : The integer number.
-- literal
+- `literal`
   - : Any literal strings or whitespace in the formatted number.
-- minusSign
+- `minusSign`
   - : The minus sign string ("-").
-- nan
+- `nan`
   - : The {{jsxref("NaN")}} string ("NaN").
-- plusSign
+- `plusSign`
   - : The plus sign string ("+").
-- percentSign
+- `percentSign`
   - : The percent sign string ("%").
-- unit
-  - : The unit string, such as the "l" or "litres", depending on how
-    `unitDisplay` is specified.
+- `unit`
+  - : The unit string, such as the "l" or "litres", depending on how `unitDisplay` is specified.
+
+Possible values for the `source` property include:
+
+- `startRange`
+  - : The object is the start part of the range.
+- `endRange`
+  - : The object is the end part of the range.
+- `shared`
+  - : The object is a "shared" part of the range, such as a separator or currency.
+
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if `startRange` is less than `endRange`, or either value is `NaN`.
+- {{jsxref("TypeError")}}
+  - : Thrown if either `startRange` or `endRange` is undefined.
 
 ## Examples
 
 ### Comparing formatRange and formatRangeToParts
 
-`NumberFormat` outputs localized, opaque strings that cannot be manipulated
-directly:
+`NumberFormat` outputs localized, opaque strings that cannot be manipulated directly:
 
 ```js
 const startRange = 3500;
@@ -105,10 +113,8 @@ formatter.formatRange(startRange, endRange)
 // "3.500,00–9.500,00 €"
 ```
 
-However, for many user interfaces there is a need to customize the formatting of this
-string. The `formatRangeToParts` method enables locale-aware formatting of
-strings produced by `NumberFormat` formatters by providing you the string
-in parts:
+However, for many user interfaces there is a need to customize the formatting of this string.
+The `formatRangeToParts` method enables locale-aware formatting of strings produced by `NumberFormat` formatters by providing you the string in parts:
 
 ```js
 formatter.formatRangeToParts(startRange, endRange)

files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md

@@ -35,9 +35,9 @@ The **`Intl.NumberFormat`** object enables language-sensitive number formatting.
   - : Getter function that formats a number according to the locale and formatting options of this {{jsxref("Intl.NumberFormat")}} object.
 - {{jsxref("Intl/NumberFormat/formatToParts", "Intl.NumberFormat.prototype.formatToParts()")}}
   - : Returns an {{jsxref("Array")}} of objects representing the number string in parts that can be used for custom locale-aware formatting.
-- {{jsxref("Intl/NumberFormat/formatRange", "Intl.NumberFormat.prototype.formatRange()")}}
+- {{jsxref("Intl/NumberFormat/formatRange", "Intl.NumberFormat.prototype.formatRange()")}} {{experimental_inline}}
   - : Getter function that formats a range of numbers according to the locale and formatting options of the {{jsxref("Intl.NumberFormat")}} object from which the method is called.
-- {{jsxref("Intl/NumberFormat/formatRangeToParts", "Intl.NumberFormat.prototype.formatRangeToParts()")}}
+- {{jsxref("Intl/NumberFormat/formatRangeToParts", "Intl.NumberFormat.prototype.formatRangeToParts()")}} {{experimental_inline}}
   - : Returns an {{jsxref("Array")}} of objects representing the range of number strings in parts that can be used for custom locale-aware formatting.
 - {{jsxref("Intl/NumberFormat/resolvedOptions", "Intl.NumberFormat.prototype.resolvedOptions()")}}
   - : Returns a new object with properties reflecting the locale and collation options computed during initialization of the object.