From 480640a2f75c081c34b44e77629eba25db990b0a Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 30 Jun 2022 23:13:54 +0800 Subject: [PATCH 1/3] Standardize parameters description of locale-aware APIs that call Intl counterparts --- .../array/tolocalestring/index.md | 99 +------------------ .../bigint/tolocalestring/index.md | 25 +++-- .../date/tolocaledatestring/index.md | 21 ++-- .../date/tolocalestring/index.md | 36 +++---- .../date/tolocaletimestring/index.md | 38 +++---- .../number/tolocalestring/index.md | 89 +++-------------- .../string/localecompare/index.md | 37 +++---- 7 files changed, 89 insertions(+), 256 deletions(-) diff --git a/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md index 4139f2a28a3d1cd..8c776c153303579 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md @@ -29,108 +29,17 @@ toLocaleString(locales, options); ### Parameters - `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("Intl")}} page. + - : 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("Intl")}} page. - `options` {{optional_inline}} - - : An object with configuration properties, for numbers see - {{jsxref("Number.prototype.toLocaleString()")}}, and for dates see - {{jsxref("Date.prototype.toLocaleString()")}}. + - : An object with configuration properties. For numbers, see {{jsxref("Number.prototype.toLocaleString()")}}; for dates, see {{jsxref("Date.prototype.toLocaleString()")}}. ### Return value A string representing the elements of the array. -## Polyfill +## Description -```js -// https://tc39.github.io/ecma402/#sup-array.prototype.tolocalestring -if (!Array.prototype.toLocaleString) { - Object.defineProperty(Array.prototype, 'toLocaleString', { - value: function(locales, options) { - // 1. Let O be ? ToObject(this value). - if (this === null) { - throw new TypeError('"this" is null or not defined'); - } - - const a = Object(this); - - // 2. Let len be ? ToLength(? Get(A, "length")). - const len = a.length >>> 0; - - // 3. Let separator be the String value for the - // list-separator String appropriate for the - // host environment's current locale (this is - // derived in an implementation-defined way). - // NOTE: In this case, we will use a comma - const separator = ','; - - // 4. If len is zero, return the empty String. - if (len === 0) { - return ''; - } - - // 5. Let firstElement be ? Get(A, "0"). - const firstElement = a[0]; - // 6. If firstElement is undefined or null, then - // a. Let R be the empty String. - // 7. Else, - // a. Let R be ? - // ToString(? - // Invoke( - // firstElement, - // "toLocaleString", - // « locales, options » - // ) - // ) - let r = firstElement === null ? - '' : firstElement.toLocaleString(locales, options); - - // 8. Let k be 1. - let k = 1; - - // 9. Repeat, while k < len - while (k < len) { - // a. Let S be a String value produced by - // concatenating R and separator. - const s = r + separator; - - // b. Let nextElement be ? Get(A, ToString(k)). - const nextElement = a[k]; - - // c. If nextElement is undefined or null, then - // i. Let R be the empty String. - // d. Else, - // i. Let R be ? - // ToString(? - // Invoke( - // nextElement, - // "toLocaleString", - // « locales, options » - // ) - // ) - r = nextElement === null ? - '' : nextElement.toLocaleString(locales, options); - - // e. Let R be a String value produced by - // concatenating S and R. - r = s + r; - - // f. Increase k by 1. - k++; - } - - // 10. Return R. - return r; - } - }); -} -``` - -If you need to support truly obsolete JavaScript engines that don't support -[`Object.defineProperty`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty), -it's best not to polyfill `Array.prototype` methods at all, as you can't make -them non-enumerable. +The `Array.prototype.toLocaleString` method traverses its content, calling the `toLocaleString` method of every element with the `locales` and `options` parameters provided, and concatenates them with a implementation-defined separator (such as a comma ","). Note that the method itself does not consume the two parameters — it only passes them to the `toLocaleString()` of each element. The choice of the separator string depends on the host's current locale, not the `locales` parameter. ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md index d6cf14d2928b44f..9552e41b076e0b2 100644 --- a/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md @@ -12,8 +12,7 @@ browser-compat: javascript.builtins.BigInt.toLocaleString --- {{JSRef}} -The **`toLocaleString()`** method returns a string with a -language-sensitive representation of this BigInt. +The **`toLocaleString()`** method returns a string with a language-sensitive representation of this BigInt. In implementations with [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) support, this method simply calls `Intl.NumberFormat`. {{EmbedInteractiveExample("pages/js/bigint-tolocalestring.html")}} @@ -27,19 +26,27 @@ toLocaleString(locales, options) ### Parameters -The `locales` and `options` arguments customize the behavior of -the function and let applications specify the language whose formatting conventions -should be used. In implementations that ignore the `locales` and -`options` arguments, the locale used and the form of the string returned are -entirely implementation-dependent. +The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. -See the [`Intl.NumberFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) -for details on these parameters and how to use them. +In implementations that support the [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), these parameters correspond exactly to the [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) constructor's parameters. Implementations without `Intl.NumberFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. + +- `locales` {{optional_inline}} + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#locales) parameter of the `Intl.NumberFormat()` constructor. + + In implementations without `Intl.NumberFormat` support, this parameter is ignored and the host's locale is usually used. +- `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) parameter of the `Intl.NumberFormat()` constructor. + + In implementations without `Intl.NumberFormat` support, this parameter is ignored. + +See the [`Intl.NumberFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) for details on these parameters and how to use them. ### Return value A string with a language-sensitive representation of the given BigInt. +In implementations with `Intl.NumberFormat`, this is equivalent to `new Intl.NumberFormat(locales, options).format(number)`. + ## Performance When formatting large numbers of numbers, it is better to create a diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md index f94b8ef59542c88..7f28a9fdb20881d 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md @@ -13,10 +13,7 @@ browser-compat: javascript.builtins.Date.toLocaleDateString --- {{JSRef}} -The **`toLocaleDateString()`** method returns a string with a language sensitive representation of the date portion of the specified date in the user agent's timezone. - -The `locales` and `options` arguments let applications specify the language whose formatting conventions should be used and allow to customize the behavior of the function. -In older implementations, which ignore the `locales` and `options` arguments, the locale used and the form of the string returned are entirely implementation dependent. +The **`toLocaleDateString()`** method returns a string with a language sensitive representation of the date portion of the specified date in the user agent's timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. {{EmbedInteractiveExample("pages/js/date-tolocaledatestring.html")}} @@ -31,24 +28,26 @@ toLocaleDateString(locales, options) ### Parameters The `locales` and `options` arguments customize the behavior of the function and let applications specify the language whose formatting conventions should be used. -In implementations, which ignore the `locales` and `options` arguments, the locale used and the form of the string returned are entirely implementation dependent. -- `locales` {{optional_inline}} +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. - - : These are the same locales as documented in the {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat()")}} constructor. - They include (non-exhaustively): `nu`, `ca`, `hc`. +- `locales` {{optional_inline}} + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used. - `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. The `timeStyle` option must be undefined, or a {{jsxref("TypeError")}} would be thrown. If `weekday`, `year`, `month`, and `day` are all undefined, then `year`, `month`, and `day` will be set to `"numeric"`. - - : These are the same options as documented in the {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat()")}} constructor. They include (non-exhaustively) the following properties: - `dateStyle`, `timeStyle`, `calendar`, `dayPeriod`, `numberingSystem`, `localeMatcher`, `weekday`, `era`, `year`, `month`, `day`, `hour`, `minute`, `second`, `fractionalSecondDigits`, `timeZoneName`. + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored. -The default value for each date-time component property is {{jsxref("undefined")}}, but if the `weekday`, `year`, `month`, `day` properties are all {{jsxref("undefined")}}, then `year`, `month`, and `day` are assumed to be `"numeric"`. +See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value A string representing the date portion of the given {{jsxref("Global_Objects/Date", "Date")}} instance according to language-specific conventions. +In implementations with `Intl.DateTimeFormat`, this is equivalent to `new Intl.DateTimeFormat(locales, options).format(date)`, where `options` has been normalized as described above. + ## Performance When formatting large numbers of dates, it is better to create an {{jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")}} object and use the function provided by its {{jsxref("DateTimeFormat.prototype.format", "format")}} property. diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md index 2e61b21d380eecf..beac5b82d594ea7 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md @@ -12,16 +12,7 @@ browser-compat: javascript.builtins.Date.toLocaleString --- {{JSRef}} -The **`toLocaleString()`** method returns a string with a -language sensitive representation of this date. - -The new `locales` and `options` arguments -let applications specify the language whose formatting conventions should be used and -customize the behavior of the function. - -In older implementations, which ignore the `locales` and -`options` arguments, the locale used and the form of the string -returned are entirely implementation-dependent. +The **`toLocaleString()`** method returns a string with a language sensitive representation of this date. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. {{EmbedInteractiveExample("pages/js/date-tolocalestring.html")}} @@ -35,24 +26,27 @@ toLocaleString(locales, options) ### Parameters -The `locales` and `options` arguments -customize the behavior of the function and let applications specify the language whose -formatting conventions should be used. In implementations which ignore the -`locales` and `options` arguments, the -locale used and the form of the string returned are entirely implementation-dependent. +The `locales` and `options` arguments customize the behavior of the function and let applications specify the language whose formatting conventions should be used. + +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. -See the {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat()")}} -constructor for details on these parameters and how to use them. +- `locales` {{optional_inline}} + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. -The default value for each date-time component property is {{jsxref("undefined")}}. -But if the `weekday`, `year`, `month`, and -`day` properties are all {{jsxref("undefined")}}, then `year`, -`month`, and `day` are assumed to be `"numeric"`. + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used. +- `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. If `weekday`, `year`, `month`, `day`, `dayPeriod`, `hour`, `minute`, `second`, and `fractionalSecondDigits` are all undefined, then `year`, `month`, `day`, `hour`, `minute`, `second` will be set to `"numeric"`. + + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored. + +See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value A string representing the given date according to language-specific conventions. +In implementations with `Intl.DateTimeFormat`, this is equivalent to `new Intl.DateTimeFormat(locales, options).format(date)`. + ## Examples ### Using toLocaleString() diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md index 296b58aec15bad5..e20c542b595e2f8 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md @@ -12,15 +12,7 @@ browser-compat: javascript.builtins.Date.toLocaleTimeString --- {{JSRef}} -The **`toLocaleTimeString()`** method returns a string with a -language-sensitive representation of the time portion of the date. The newer -`locales` and `options` arguments let applications specify the -language formatting conventions to use. These arguments can also customize the behavior of the -function. - -More dated implementations ignore the `locales` and -`options` arguments. In these circumstances, the form of the string returned is -entirely implementation-dependent. +The **`toLocaleTimeString()`** method returns a string with a language-sensitive representation of the time portion of the date. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. {{EmbedInteractiveExample("pages/js/date-tolocaletimestring.html")}} @@ -34,24 +26,26 @@ toLocaleTimeString(locales, options) ### Parameters -The `locales` and `options` arguments customize the behavior of -the function and let applications specify which language formatting conventions -should be used. In older implementations that ignore the `locales` and -`options` arguments, the `locales` and the form of the string returned will be -entirely implementation-dependent. +The `locales` and `options` arguments customize the behavior of the function and let applications specify the language whose formatting conventions should be used. + +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. + +- `locales` {{optional_inline}} + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. -See the {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat()")}} -constructor for details on these parameters and how to use them. + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used. +- `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. If `dayPeriod`, `hour`, `minute`, `second`, and `fractionalSecondDigits` are all undefined, then `hour`, `minute`, `second` will be set to `"numeric"`. -The default value for each date-time component property is {{jsxref("undefined")}}, but -if the `hour`, `minute`, `second` properties are all -{{jsxref("undefined")}}, then `hour`, `minute`, and -`second` are assumed to be `"numeric"`. + In implementations without `Intl.DateTimeFormat` support, this parameter is ignored. + +See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value -A string representing the time portion of the given {{jsxref("Global_Objects/Date", - "Date")}} instance according to language-specific conventions. +A string representing the time portion of the given {{jsxref("Global_Objects/Date", "Date")}} instance according to language-specific conventions. + +In implementations with `Intl.DateTimeFormat`, this is equivalent to `new Intl.DateTimeFormat(locales, options).format(date)`, where `options` has been normalized as described above. ## Performance diff --git a/files/en-us/web/javascript/reference/global_objects/number/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/number/tolocalestring/index.md index 97c5d9a2f3dca77..35e9cc0bb2bce1a 100644 --- a/files/en-us/web/javascript/reference/global_objects/number/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/number/tolocalestring/index.md @@ -11,8 +11,7 @@ browser-compat: javascript.builtins.Number.toLocaleString --- {{JSRef}} -The **`toLocaleString()`** method returns a string with a -language-sensitive representation of this number. +The **`toLocaleString()`** method returns a string with a language-sensitive representation of this number. In implementations with [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) support, this method simply calls `Intl.NumberFormat`. {{EmbedInteractiveExample("pages/js/number-tolocalestring.html")}} @@ -26,91 +25,27 @@ toLocaleString(locales, options) ### Parameters -The `locales` and `options` parameters customize the behavior of -the function and let applications specify the language whose formatting conventions -should be used. In implementations, which ignore the `locales` and -`options` arguments, the locale used and the form of the string returned are -entirely implementation-dependent. +The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. + +In implementations that support the [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), these parameters correspond exactly to the [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) constructor's parameters. Implementations without `Intl.NumberFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. - `locales` {{optional_inline}} - - : A string containing the {{Glossary("locale")}} to convert to. + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#locales) parameter of the `Intl.NumberFormat()` constructor. + In implementations without `Intl.NumberFormat` support, this parameter is ignored and the host's locale is usually used. - `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) parameter of the `Intl.NumberFormat()` constructor. + + In implementations without `Intl.NumberFormat` support, this parameter is ignored. - - : An object with some or all of the following properties: - - `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 - — 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. - - `currencyDisplay` - - - : 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, - - "`code`" to use the ISO currency code, - - "`name`" to use a localized currency name such as - "`dollar`", - - - `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. - - - `style` - - : The formatting style to use , the default is "`decimal`". - - - "`decimal`" for plain number formatting. - - "`currency`" for currency formatting. - - "`percent`" for percent formatting - - - `useGrouping` - - : Whether to use grouping separators. The default is `true`. - - - "`true`": display grouping separators even if the locale prefers otherwise - - "`false`": do not display grouping separators - - The following properties fall into two groups: - `minimumIntegerDigits`, `minimumFractionDigits`, and - `maximumFractionDigits` in one group, - `minimumSignificantDigits` and - `maximumSignificantDigits` in the other. If at least one property - from the second group is defined, then the first group is ignored. - - `minimumIntegerDigits` - - : The minimum number of integer digits to use. Possible values are from 1 to - 21; the default is 1. - - `minimumFractionDigits` - - : The minimum number of fraction digits to use. Possible values are from 0 - to 20; the default for plain number and percent formatting is 0; the - default for currency formatting is 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). - - `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. - - `minimumSignificantDigits` - - : 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. - -See the [`Intl.NumberFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) -for details on these parameters and how to use them. +See the [`Intl.NumberFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) for details on these parameters and how to use them. ### Return value A string with a language-sensitive representation of the given number. +In implementations with `Intl.NumberFormat`, this is equivalent to `new Intl.NumberFormat(locales, options).format(number)`. + ## Performance When formatting large numbers of numbers, it is better to create a diff --git a/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.md b/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.md index ad08349a1359864..3956f9fe1beb97b 100644 --- a/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.md +++ b/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.md @@ -12,18 +12,10 @@ browser-compat: javascript.builtins.String.localeCompare --- {{JSRef}} -The **`localeCompare()`** method returns a number indicating -whether a reference string comes before, or after, or is the same as the given string in -sort order. +The **`localeCompare()`** method returns a number indicating whether a reference string comes before, or after, or is the same as the given string in sort order. In implementations with [`Intl.Collator` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator) support, this method simply calls `Intl.Collator`. {{EmbedInteractiveExample("pages/js/string-localecompare.html")}} -The new `locales` and `options` arguments -let applications specify the language whose sort order should be used and customize the -behavior of the function. In older implementations, which ignore the -`locales` and `options` arguments, the -locale and sort order used are entirely implementation-dependent. - ## Syntax ```js @@ -34,25 +26,28 @@ localeCompare(compareString, locales, options) ### Parameters +The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. + +In implementations that support the [`Intl.Collator` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator), these parameters correspond exactly to the [`Intl.Collator()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) constructor's parameters. Implementations without `Intl.Collator` support are asked to ignore both parameters, making the comparison result returned entirely implementation-dependent — it's only required to be _consistent_. + - `compareString` - : The string against which the `referenceStr` is compared. -- `locales` and `options` +- `locales` {{optional_inline}} + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#locales) parameter of the `Intl.Collator()` constructor. - - : These arguments customize the behavior of the function and let applications specify - the language whose formatting conventions should be used. In implementations which - ignore the `locales` and - `options` arguments, the locale used and the form of the - string returned are entirely implementation-dependent. + In implementations without `Intl.Collator` support, this parameter is ignored and the host's locale is usually used. +- `options` {{optional_inline}} + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options) parameter of the `Intl.Collator()` constructor. - See the [`Intl.Collator()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) - for details on these parameters and how to use them. + In implementations without `Intl.Collator` support, this parameter is ignored. + +See the [`Intl.Collator()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) for details on the `locales` and `options` parameters and how to use them. ### Return value -A **negative** number if `referenceStr` occurs -before `compareString`; **positive** if the -`referenceStr` occurs after `compareString`; -`0` if they are equivalent. +A **negative** number if `referenceStr` occurs before `compareString`; **positive** if the `referenceStr` occurs after `compareString`; `0` if they are equivalent. + +In implementations with `Intl.Collator`, this is equivalent to `new Intl.Collator(locales, options).compare(referenceStr, compareString)`. ## Description From 4aacb3c63afb8eb1765a403da08315d087d1b3c5 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Fri, 1 Jul 2022 18:20:17 +0900 Subject: [PATCH 2/3] Update files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md --- .../reference/global_objects/date/tolocaledatestring/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md index 7f28a9fdb20881d..f70e77795c34c30 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md @@ -13,7 +13,7 @@ browser-compat: javascript.builtins.Date.toLocaleDateString --- {{JSRef}} -The **`toLocaleDateString()`** method returns a string with a language sensitive representation of the date portion of the specified date in the user agent's timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. +The **`toLocaleDateString()`** method returns a string with a language-sensitive representation of the date portion of the specified date in the user agent's timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. {{EmbedInteractiveExample("pages/js/date-tolocaledatestring.html")}} From 4556e6eff75f2de1c07a06bed01bb2193b5d58eb Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Fri, 1 Jul 2022 18:21:10 +0900 Subject: [PATCH 3/3] Update files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md --- .../reference/global_objects/date/tolocalestring/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md index beac5b82d594ea7..598aca74878500a 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md @@ -12,7 +12,7 @@ browser-compat: javascript.builtins.Date.toLocaleString --- {{JSRef}} -The **`toLocaleString()`** method returns a string with a language sensitive representation of this date. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. +The **`toLocaleString()`** method returns a string with a language-sensitive representation of this date. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. {{EmbedInteractiveExample("pages/js/date-tolocalestring.html")}}