diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/format/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/format/index.md index 8f1164a0d8376f5..3622a28477caef1 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/format/index.md +++ b/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}} diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrange/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrange/index.md index 8b4f525ba06bd0f..bc4cd42aa7ded63 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrange/index.md +++ b/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" ``` diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrangetoparts/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrangetoparts/index.md index caa13809d37fe73..82a7b0b22e3984f 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/formatrangetoparts/index.md +++ b/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) diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md index 7f2b6b3b2c6c68d..7dde2031f7c49b3 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/index.md +++ b/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. diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/numberformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/numberformat/index.md index 49f3029421e2aaf..8857e521218a218 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/numberformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/numberformat/index.md @@ -33,114 +33,82 @@ new Intl.NumberFormat(locales, options) - `locales` {{optional_inline}} - - : A string with a BCP 47 language tag, or an array of such strings. For the - general form and interpretation of the `locales` - argument, see the {{jsxref("Global_Objects/Intl", "Intl", "#Locale_identification_and_negotiation", 1)}} page. The following Unicode - extension key is allowed: + - : A string with a BCP 47 language tag, or an array of such strings. + For the general form and interpretation of the `locales` argument, see the {{jsxref("Global_Objects/Intl", "Intl", "#Locale_identification_and_negotiation", 1)}} page. + The following Unicode extension key is allowed: - `nu` - : The numbering system to be used. Possible values include: - "`adlm`", "`ahom`", "`arab`", - "`arabext`", "`bali`", "`beng`", - "`bhks`", "`brah`", "`cakm`", - "`cham`", "`deva`", "`diak`", - "`fullwide`", "`gong`", "`gonm`", - "`gujr`", "`guru`", "`hanidec`", - "`hmng`", "`hmnp`", "`java`", - "`kali`", "`khmr`", "`knda`", - "`lana`", "`lanatham`", "`laoo`", - "`latn`", "`lepc`", "`limb`", - "`mathbold`", "`mathdbl`", "`mathmono`", - "`mathsanb`", "`mathsans`", "`mlym`", - "`modi`", "`mong`", "`mroo`", - "`mtei`", "`mymr`", "`mymrshan`", - "`mymrtlng`", "`newa`", "`nkoo`", - "`olck`", "`orya`", "`osma`", - "`rohg`", "`saur`", "`segment`", - "`shrd`", "`sind`", "`sinh`", - "`sora`", "`sund`", "`takr`", - "`talu`", "`tamldec`", "`telu`", - "`thai`", "`tibt`", "`tirh`", - "`vaii`", "`wara`", "`wcho`". — see - the [standard Unicode numeral systems list](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numberingSystem). + `"adlm"`, `"ahom"`, `"arab"`, `"arabext"`, `"bali"`, `"beng"`, `"bhks"`, `"brah"`, `"cakm"`, + `"cham"`, `"deva"`, `"diak"`, `"fullwide"`, `"gong"`, `"gonm"`, + `"gujr"`, `"guru"`, `"hanidec"`, `"hmng"`, `"hmnp"`, `"java"`, + `"kali"`, `"khmr"`, `"knda"`, `"lana"`, `"lanatham"`, `"laoo"`, + `"latn"`, `"lepc"`, `"limb"`, `"mathbold"`, `"mathdbl"`, `"mathmono"`, + `"mathsanb"`, `mathsans"`, `"mlym"`, `"modi"`, `"mong"`, `"mroo"`, + `"mtei"`, `"mymr"`, `"mymrshan"`, `"mymrtlng"`, `"newa"`, `"nkoo"`, + `"olck"`, `"orya"`, `"osma"`, `"rohg"`, `"saur"`, `"segment"`, + `"shrd"`, `"sind"`, `"sinh"`, `"sora"`, `"sund"`, `"takr"`, `"talu"`, `"tamldec"`, `"telu"`, + `"thai"`, `"tibt"`, `"tirh"`, `"vaii"`, `"wara"`, `"wcho"`. + — see the [standard Unicode numeral systems list](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numberingSystem). - `options` {{optional_inline}} - : An object with some or all of the following properties: - `compactDisplay` - - : Only used when `notation` is "`compact`". Takes - either "`short`" (default) or "`long`". + - : Only used when `notation` is `"compact"`. Takes either `"short"` (default) or `"long"`. - `currency` - - : The currency to use in currency formatting. Possible values are the ISO - 4217 currency codes, such as "`USD`" for the US dollar, - "`EUR`" for the euro, or "`CNY`" for the Chinese RMB + - : The currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as `"USD"` for the US dollar, `"EUR"` for the euro, or `"CNY"` for the Chinese RMB — see the [Current currency & funds code list](https://www.six-group.com/en/products-services/financial-information/data-standards.html#scrollTo=currency-codes). - There is no default value; if the `style` is "`currency`", the `currency` - property must be provided. + There is no default value; if the `style` is `"currency"`, the `currency` property must be provided. - `currencyDisplay` - - : How to display the currency in currency formatting. Possible values are: + - : How to display the currency in currency formatting. + Possible values are: - - "`symbol`" to use a localized currency symbol such as - €, this is the default value, - - "`narrowSymbol`" to use a narrow format symbol ("$100" - rather than "US$100"), - - "`code`" to use the ISO currency code, - - "`name`" to use a localized currency name such as - "`dollar`", + - `"symbol"` to use a localized currency symbol such as €, this is the default value. + - `"narrowSymbol"` to use a narrow format symbol ("$100" rather than "US$100"). + - `"code"` to use the ISO currency code. + - `"name"` to use a localized currency name such as `"dollar"`. - `currencySign` - - : In many locales, accounting format means to wrap the number with - parentheses instead of appending a minus sign. You can enable this - formatting by setting the `currencySign` option to - "`accounting`". The default value is "`standard`". + - : In many locales, accounting format means to wrap the number with parentheses instead of appending a minus sign. + You can enable this formatting by setting the `currencySign` option to `"accounting"`. + The default value is `"standard"`. - `localeMatcher` - - : The locale matching algorithm to use. Possible values are - "`lookup`" and "`best fit`"; the default is - "`best fit`". For information about this option, see the - {{jsxref("Global_Objects/Intl", "Intl", "#Locale_negotiation", 1)}} page. + - : The locale matching algorithm to use. Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`. + For information about this option, see the {{jsxref("Global_Objects/Intl", "Intl", "#Locale_negotiation", 1)}} page. - `notation` - - : The formatting that should be displayed for the number, the defaults is - "`standard`" + - : The formatting that should be displayed for the number, the defaults is `"standard"` - - "`standard`" plain number formatting - - "`scientific`" return the order-of-magnitude for - formatted number. - - "`engineering`" return the exponent of ten when - divisible by three - - "`compact`" string representing exponent; defaults to using the "short" form. + - `"standard"` plain number formatting. + - `"scientific"` return the order-of-magnitude for formatted number. + - `"engineering"` return the exponent of ten when divisible by three. + - `"compact"` string representing exponent; defaults to using the "short" form. - `numberingSystem` - - : Numbering System. Possible values include: "`arab`", - "`arabext`", " `bali`", "`beng`", - "`deva`", "`fullwide`", " `gujr`", - "`guru`", "`hanidec`", "`khmr`", " - `knda`", "`laoo`", "`latn`", - "`limb`", "`mlym`", " `mong`", - "`mymr`", "`orya`", "`tamldec`", " - `telu`", "`thai`", "`tibt`". + - : Numbering System. + Possible values include: `"arab"`, `"arabext"`, `"bali"`, `"beng"`, `"deva"`, `"fullwide"`, `"gujr"`, `"guru"`, `"hanidec"`, `"khmr"`, `"knda"`, `"laoo"`, `"latn"`, `"limb"`, `"mlym"`, `"mong"`, `"mymr"`, `"orya"`, `"tamldec"`, `"telu"`, `"thai"`, `"tibt"`. - `signDisplay` - : When to display the sign for the number; defaults to "`auto`": - - "`always`" always display sign - - "`auto`" sign display for negative numbers only - - "`exceptZero`" sign display for positive and negative - numbers, but not zero - - "`negative`" sign display for negative numbers only, excluding negative zero. {{experimental_inline}} - - "`never`" never display sign + - `"always"` always display sign + - `"auto"` sign display for negative numbers only, including negative zero. + - `"exceptZero"` sign display for positive and negative numbers, but not zero + - `"negative"` sign display for negative numbers only, excluding negative zero. {{experimental_inline}} + - `"never"` never display sign - `style` - : The formatting style to use , the default is "`decimal`". - - "`decimal`" for plain number formatting. - - "`currency`" for currency formatting. - - "`percent`" for percent formatting - - "`unit`" for unit formatting + - `"decimal"` for plain number formatting. + - `"currency"` for currency formatting. + - `"percent"` for percent formatting. + - `"unit"` for unit formatting. - `unit` - : The unit to use in `unit` formatting, Possible values are core @@ -148,54 +116,55 @@ new Intl.NumberFormat(locales, options) A [subset](https://tc39.es/proposal-unified-intl-numberformat/section6/locales-currencies-tz_proposed_out.html#sec-issanctionedsimpleunitidentifier) of units from the [full list](https://github.com/unicode-org/cldr/blob/main/common/validity/unit.xml) was selected for use in ECMAScript. Pairs of simple units can - be concatenated with "`-per-`" to make a compound unit. There - is no default value; if the `style` is "`unit`", the - `unit` property must be provided. + be concatenated with "`-per-`" to make a compound unit. + There is no default value; if the `style` is `"unit"`, the `unit` property must be provided. - `unitDisplay` - : The unit formatting style to use in `unit` formatting, the - defaults is "`short`". + defaults is `"short"`. - - "`long`" (e.g., `16 litres`) - - "`short`" (e.g., `16 l`) - - "`narrow`" (e.g., `16l`) + - `"long"` (e.g., `16 litres`). + - `"short"` (e.g., `16 l`). + - `"narrow"` (e.g., `16l`). - `useGrouping` {{experimental_inline}} - : Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators. The default is `auto`. - - "`always`": display grouping separators even if the locale prefers otherwise - - "`auto`": display grouping separators based on the locale preference, which may also be dependent on the currency - - "`false`": do not display grouping separators - - "`min2`": display grouping separators when there are at least 2 digits in a group - - "`true`": alias for `always` + - `"always"`: display grouping separators even if the locale prefers otherwise. + - `"auto"`: display grouping separators based on the locale preference, which may also be dependent on the currency. + - `false`: do not display grouping separators. + - `"min2"`: display grouping separators when there are at least 2 digits in a group. + - `true`: alias for `always`. - `roundingMode` {{experimental_inline}} - : Options for rounding modes reflecting the [ICU user guide](https://unicode-org.github.io/icu/userguide/format_parse/numbers/rounding-modes.html). The default is `halfExpand`. - - "`ceil`": toward +∞ - - "`floor`": toward -∞ - - "`expand`": away from 0 - - "`trunc`": toward 0 - - "`halfCeil`": ties toward +∞ - - "`halfFloor`": ties toward -∞ - - "`halfExpand`": ties away from 0 - - "`halfTrunc`": ties toward 0 - - "`halfEven`": ties toward the value with even cardinality + - `"ceil"`: toward +∞. + - `"floor"`: toward -∞. + - `"expand"`: away from 0. + - `"trunc"`: toward 0. + - `"halfCeil"`: ties toward +∞. + - `"halfFloor"`: ties toward -∞. + - `"halfExpand"`: ties away from 0. + - `"halfTrunc"`: ties toward 0. + - `"halfEven"`: ties toward the value with even cardinality. - `roundingPriority` {{experimental_inline}} - : Options for control rounding behavior: - - "`auto`": the significant digits always win a conflict - - "`morePrecision`": the result with more precision wins a conflict - - "`lessPrecision`": the result with less precision wins a conflict + - `"auto"`: the significant digits always win a conflict. + - `"morePrecision"`: the result with more precision wins a conflict. + - `"lessPrecision"`: the result with less precision wins a conflict. - `roundingIncrement` {{experimental_inline}} - : Specifies the rounding-increment precision. Must be one of the following integers: "`1`", " `2`", "`5`", "`10`", "`20`", " `25`", "`50`", "`100`", "`200`", "`250`", "`500`", "`1000`", "`2000`", "`2500`", " `5000`". + > **Note:** The `roundingIncrement` option controls the rounding increment to be used when formatting numbers: - - It indicates the increment at which rounding should take place relative to the calculated rounding magnitude. - - It cannot be mixed with significant-digits rounding or any setting of `roundingPriority` other than `auto`. + > + > - It indicates the increment at which rounding should take place relative to the calculated rounding magnitude. + > - It cannot be mixed with significant-digits rounding or any setting of `roundingPriority` other than `auto`. > > For example, if `maximumFractionDigits` is 2 and `roundingIncrement` is 5, then the number is rounded to the nearest 0.05 ("nickel rounding"). > @@ -214,14 +183,13 @@ new Intl.NumberFormat(locales, options) > ``` > > If you set `minimumFractionDigits` and `maximumFractionDigits`, they must set them to the same value; otherwise a `RangeError` is thrown. - > - `trailingZeroDisplay` {{experimental_inline}} - : A string expressing the strategy for displaying trailing zeros on whole numbers. The default is "`auto`". - - "`auto`": keep trailing zeros according to minimumFractionDigits and minimumSignificantDigits - - "`stripIfInteger`": the result with more precision wins a conflict - - "`lessPrecision`": same as "auto", but remove the fraction digits if they are all zero + - `"auto"`: keep trailing zeros according to minimumFractionDigits and minimumSignificantDigits + - `"stripIfInteger"`: the result with more precision wins a conflict + - `"lessPrecision"`: same as "auto", but remove the fraction digits if they are all zero The following properties fall into two groups: `minimumIntegerDigits`, `minimumFractionDigits`, and @@ -240,26 +208,22 @@ new Intl.NumberFormat(locales, options) provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list_one.xml) (2 if the list doesn't provide that information). - `maximumFractionDigits` - - : The maximum number of fraction digits to use. Possible values are from 0 - to 20; the default for plain number formatting is the larger of - `minimumFractionDigits` and 3; the default for currency - formatting is the larger of `minimumFractionDigits` and the - number of minor unit digits provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list_one.xml) - (2 if the list doesn't provide that information); the default for percent formatting is the larger of - `minimumFractionDigits` and 0. + - : The maximum number of fraction digits to use. + Possible values are from 0 to 20; the default for plain number formatting is the larger of `minimumFractionDigits` and 3; + the default for currency formatting is the larger of `minimumFractionDigits` and the number of minor unit digits provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list_one.xml) (2 if the list doesn't provide that information); + the default for percent formatting is the larger of `minimumFractionDigits` and 0. - `minimumSignificantDigits` - - : The minimum number of significant digits to use. Possible values are from - 1 to 21; the default is 1. + - : The minimum number of significant digits to use. + Possible values are from 1 to 21; the default is 1. - `maximumSignificantDigits` - - : The maximum number of significant digits to use. Possible values are from - 1 to 21; the default is 21. + - : The maximum number of significant digits to use. + Possible values are from 1 to 21; the default is 21. ## Examples ### Basic usage -In basic use without specifying a locale, a formatted string in the default locale and -with default options is returned. +In basic use without specifying a locale, a formatted string in the default locale and with default options is returned. ```js let amount = 3500; @@ -281,8 +245,8 @@ new Intl.NumberFormat('en-US', {style: 'percent'}).format(amount); ### Unit formatting -If the `style` is `'unit'`, a `unit` property must be -provided. Optionally, `unitDisplay` controls the unit formatting. +If the `style` is `'unit'`, a `unit` property must be provided. +Optionally, `unitDisplay` controls the unit formatting. ```js let amount = 3500; @@ -322,8 +286,7 @@ new Intl.NumberFormat('bn', { ### Scientific, engineering or compact notations -Scientific and compact notation are represented by the `notation` option and -can be formatted like this: +Scientific and compact notation are represented by the `notation` option and can be formatted like this: ```js new Intl.NumberFormat('en-US', { notation: "scientific" }).format(987654321); @@ -366,8 +329,7 @@ new Intl.NumberFormat("en-US", { // → '+55%' ``` -Note that when the currency sign is "accounting", parentheses might be used instead of -a minus sign: +Note that when the currency sign is "accounting", parentheses might be used instead of a minus sign: ```js new Intl.NumberFormat('bn', { diff --git a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/resolvedoptions/index.md b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/resolvedoptions/index.md index 23402884f15bee1..7343fbca9158ed2 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/numberformat/resolvedoptions/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/numberformat/resolvedoptions/index.md @@ -14,9 +14,7 @@ browser-compat: javascript.builtins.Intl.NumberFormat.resolvedOptions --- {{JSRef}} -The **`Intl.NumberFormat.prototype.resolvedOptions()`** method -returns a new object with properties reflecting the locale and number formatting -options computed during initialization of this {{jsxref("Intl.NumberFormat")}} object. +The **`Intl.NumberFormat.prototype.resolvedOptions()`** method returns a new object with properties reflecting the [locale and number formatting options](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters) computed during initialization of this {{jsxref("Intl.NumberFormat")}} object. {{EmbedInteractiveExample("pages/js/intl-numberformat-prototype-resolvedoptions.html")}} @@ -30,51 +28,36 @@ resolvedOptions() ### Return value -A new object with properties reflecting the locale and number formatting options -computed during the initialization of the given {{jsxref("Intl.NumberFormat")}} object. - -## Description +A new object with properties reflecting the [locale and number formatting options](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters) computed during the construction of the given {{jsxref("Intl.NumberFormat")}} object. The resulting object has the following properties: - `locale` - - : The BCP 47 language tag for the locale actually used. If any Unicode extension - values were requested in the input BCP 47 language tag that led to this locale, - the key-value pairs that were requested and are supported for this locale are - included in `locale`. + - : The BCP 47 language tag for the locale actually used. + If any Unicode extension values were requested in the input BCP 47 language tag that led to this locale, the key-value pairs that were requested and are supported for this locale are included in `locale`. - `numberingSystem` - - : The value provided for this properties in the `options` argument, if - present, or the value requested using the Unicode extension key "`nu`" - or filled in as a default. + - : The value provided for this properties in the `options` argument, if present, or the value requested using the Unicode extension key `"nu"` or filled in as a default. - `notation` - - : The value provided for this property in the `options` argument, if - present, or "`standard`" filled in as a default. + - : The value provided for this property in the `options` argument, if present, or "`standard`" filled in as a default. - `compactDisplay` - - : The value provided for this property in the `options` argument, or - "`short`" filled in as a default. + - : The value provided for this property in the `options` argument, or "`short`" filled in as a default. This property is only present if the `notation` is set to "compact". - `signDisplay` - - : The value provided for this property in the `options` argument, or - "`auto`" filled in as a default. + - : The value provided for this property in the `options` argument, or "`auto`" filled in as a default. - `useGrouping` - - : The values provided for these properties in the `options` argument or - filled in as defaults. + - : The value provided for the [useGrouping](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#usegrouping) property in the constructor `options` argument or the default value (`"auto"`). - `currency`, `currencyDisplay` - - : The values provided for these properties in the `options` argument or - filled in as defaults. These properties are only present if `style` is - "`currency`". + - : The values provided for these properties in the `options` argument or filled in as defaults. + These properties are only present if `style` is "`currency`". Only one of the following two groups of properties is included: - `minimumIntegerDigits`, `minimumFractionDigits`, `maximumFractionDigits` - - : The values provided for these properties in the `options` argument or - filled in as defaults. These properties are present only if neither - `minimumSignificantDigits` nor `maximumSignificantDigits` - was provided in the `options` argument. + - : The values provided for these properties in the `options` argument or filled in as defaults. + These properties are present only if neither `minimumSignificantDigits` nor `maximumSignificantDigits` was provided in the `options` argument. - `minimumSignificantDigits`, `maximumSignificantDigits` - - : The values provided for these properties in the `options` argument or - filled in as defaults. These properties are present only if at least one of them - was provided in the `options` argument. + - : The values provided for these properties in the `options` argument or filled in as defaults. + These properties are present only if at least one of them was provided in the `options` argument. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md index 293088bc18b4412..b0d7dd3687444d7 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md @@ -31,7 +31,7 @@ The **`Intl.PluralRules`** object enables plural-sensitive formatting and plural - : Returns a new object with properties reflecting the locale and collation options computed during initialization of the object. - {{jsxref("Intl/PluralRules/select", "Intl.PluralRules.prototype.select()")}} - : Returns a string indicating which plural rule to use for locale-aware formatting. -- {{jsxref("Intl/PluralRules/selectRange", "Intl.PluralRules.prototype.selectRange()")}} +- {{jsxref("Intl/PluralRules/selectRange", "Intl.PluralRules.prototype.selectRange()")}} {{experimental_inline}} - : This method receives two values and returns a string indicating which plural rule to use for locale-aware formatting. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md index 224d63242147639..98d59bf8b9f8216 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md @@ -11,28 +11,27 @@ tags: - Prototype - Reference - selectRange + - Experimental browser-compat: javascript.builtins.Intl.PluralRules.selectRange --- -{{JSRef}} +{{JSRef}} {{SeeCompatTable}} The **`Intl.PluralRules.prototype.selectRange()`** method receives two values and returns a string indicating which plural rule to use for locale-aware formatting. ## Syntax ```js -formatRange(startRange, endRange) +selectRange(startRange, endRange) ``` ### Return value -A string representing the pluralization category of the `number`; can be one -of `zero`, `one`, `two`, `few`, -`many` or `other`, that are relevant for the locale whose localization is specified in [LDML Language Plural Rules](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/language_plural_rules.html#rules). +A string representing the pluralization category of the `number`. +This can be one of `zero`, `one`, `two`, `few`, `many` or `other`, that are relevant for the locale whose localization is specified in [LDML Language Plural Rules](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/language_plural_rules.html#rules). ## Description -This function selects a pluralization category according to the locale and formatting -options of an {{jsxref("Intl.PluralRules")}} object. +This function selects a pluralization category according to the locale and formatting options of an {{jsxref("Intl.PluralRules")}} object. ## Examples