Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Standardize parameters description of locale-aware APIs that call Intl counterparts #17817

Merged
merged 3 commits into from
Jul 1, 2022
Merged

Standardize parameters description of locale-aware APIs that call Intl counterparts #17817

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
480640a
Standardize parameters description of locale-aware APIs that call Int…
Josh-Cena Jun 30, 2022
4aacb3c
Update files/en-us/web/javascript/reference/global_objects/date/toloc…
sideshowbarker Jul 1, 2022
4556e6e
Update files/en-us/web/javascript/reference/global_objects/date/toloc…
sideshowbarker Jul 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 4 additions & 95 deletions files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
25 changes: 16 additions & 9 deletions files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")}}

Expand All @@ -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
Expand Down
21 changes: 10 additions & 11 deletions .../en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")}}

Expand All @@ -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.
Expand Down
36 changes: 15 additions & 21 deletions files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")}}

Expand All @@ -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()
Expand Down
38 changes: 16 additions & 22 deletions .../en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")}}

Expand All @@ -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

Expand Down
Loading