diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md index 0cb06fef1df4f16..0e89b03eecb30f4 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md @@ -20,7 +20,7 @@ You can convert from `Date` to `Temporal.Instant` using the {{jsxref("Date.proto `Instant` objects can be serialized and parsed using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (with some extensions specified by ECMAScript). The string has the following form (spaces are only for readability and should not be present in the actual string): ```plain -YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM +YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM:SS.sssssssss ``` - `YYYY` @@ -37,8 +37,8 @@ YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM - : A two-digit number from `00` to `59`. Defaults to `00`. - `SS.sssssssss` {{optional_inline}} - : A two-digit number from `00` to `59`. May optionally be followed by a `.` or `,` and one to nine digits. Defaults to `00`. The `HH`, `MM`, and `SS` components can be separated by `:` or nothing. You can omit either just `SS` or both `SS` and `MM`, so the time can be one of three forms: `HH`, `HH:MM`, or `HH:MM:SS.sssssssss`. -- `Z/±HH:MM` - - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the previous `HH:MM`: a two-digit number from `00` to `23`, and a two-digit number from `00` to `59`, separated by `:` or nothing. +- `Z/±HH:MM:SS.sssssssss` + - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the time component. Note that subminute precision may be unsupported by other systems. As an input, you may optionally include the time zone identifier and calendar, in the same format as [`ZonedDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#iso_8601_format), but they will be ignored. Other annotations in the `[key=value]` format are also ignored, and they must not have the critical flag. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md index 54a260875df48ad..9b26073bd39f163 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md @@ -18,6 +18,8 @@ new Temporal.PlainDate(year, month, day) new Temporal.PlainDate(year, month, day, calendar) ``` +> **Note:** `Temporal.PlainDate()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `year` diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md index 6371118e885ad82..995192e19743d83 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md @@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.PlainDateTime The **`Temporal.PlainDateTime()`** constructor creates {{jsxref("Temporal.PlainDateTime")}} objects. +Like all other `Temporal` classes, you should usually construct `Temporal.PlainDateTime` objects using the {{jsxref("Temporal/PlainDateTime/from", "Temporal.PlainDateTime.from()")}} static method, which can handle a variety of input types. + ## Syntax ```js-nolint @@ -22,6 +24,8 @@ new Temporal.PlainDateTime(year, month, day, hour, minute, second, millisecond, new Temporal.PlainDateTime(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, calendar) ``` +> **Note:** `Temporal.PlainDateTime()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `year` diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md index 4e5bbee0b40de01..bc7de4e6da4a688 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md @@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.PlainMonthDay The **`Temporal.PlainMonthDay()`** constructor creates {{jsxref("Temporal.PlainMonthDay")}} objects. +Like all other `Temporal` classes, you should usually construct `Temporal.PlainMonthDay` objects using the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} static method, which can handle a variety of input types. + ## Syntax ```js-nolint @@ -17,6 +19,8 @@ new Temporal.PlainMonthDay(month, day, calendar) new Temporal.PlainMonthDay(month, day, calendar, referenceYear) ``` +> **Note:** `Temporal.PlainMonthDay()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `month` diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md index 0f0334c3133e475..005f568af836a62 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md @@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Temporal.PlainTime.PlainTime The **`Temporal.PlainTime()`** constructor creates {{jsxref("Temporal.PlainTime")}} objects. +Like all other `Temporal` classes, you should usually construct `Temporal.PlainTime` objects using the {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} static method, which can handle a variety of input types. + ## Syntax ```js-nolint @@ -21,6 +23,8 @@ new Temporal.PlainTime(hour, minute, second, millisecond, microsecond) new Temporal.PlainTime(hour, minute, second, millisecond, microsecond, nanosecond) ``` +> **Note:** `Temporal.PlainTime()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `hour` {{optional_inline}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md index 90bd1d83d4f7421..f9a41154b273b74 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md @@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Temporal.PlainYearMonth.PlainYearMonth The **`Temporal.PlainYearMonth()`** constructor creates {{jsxref("Temporal.PlainYearMonth")}} objects. +Like all other `Temporal` classes, you should usually construct `Temporal.PlainYearMonth` objects using the {{jsxref("Temporal/PlainYearMonth/from", "Temporal.PlainYearMonth.from()")}} static method, which can handle a variety of input types. + ## Syntax ```js-nolint @@ -17,6 +19,8 @@ new Temporal.PlainYearMonth(year, month, calendar) new Temporal.PlainYearMonth(year, month, calendar, referenceDay) ``` +> **Note:** `Temporal.PlainYearMonth()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `year` diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/gettimezonetransition/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/gettimezonetransition/index.md index 5ddb576d00602ba..95836766b7dbe48 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/gettimezonetransition/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/gettimezonetransition/index.md @@ -7,34 +7,54 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.getTimeZoneTransition {{JSRef}} -The **`getTimeZoneTransition()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`getTimeZoneTransition()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances returns a {{jsxref("Temporal.ZonedDateTime")}} object representing the closest instant after or before this instant at which the time zone's UTC offset changes (the returned instant is the first instant after the change), or `null` if there is no such transition. This is useful for finding out the offset rules of a time zone, such as its daylight saving time pattern. + +Note that instants returned about the future may be unreliable, for example due to changes to the time zone definitions. ## Syntax ```js-nolint getTimeZoneTransition(direction) +getTimeZoneTransition(options) ``` ### Parameters - `direction` - - : TODO + - : A string representing the [`direction`](#direction_2) option. This is a convenience overload, so `getTimeZoneTransition(direction)` is equivalent to `round({ direction })`, where `direction` is a string. +- `options` + - : An object containing the following property: + - `direction` + - : Whether to search before or after the current instant. Must be one of `"next"` or `"previous"`. ### Return value -TODO +A {{jsxref("Temporal.ZonedDateTime")}} object with instant `t`, such that: -### Exceptions +- The time zone offset at `t` is different from the offset one nanosecond before `t`. +- `t < this.epochNanoseconds` if `direction` is `"previous"`, or `t > this.epochNanoseconds` if `direction` is `"next"`. +- For all instants between `this.epochNanoseconds` and `t`, exclusive, the offset is constant. -TODO +If there is no such transition, `null` is returned. -## Description +## Examples -TODO +### Finding the next time zone transition -## Examples +```js +const dt = Temporal.ZonedDateTime.from("2024-01-01T00-05:00[America/New_York]"); +const transition = dt.getTimeZoneTransition("next"); +console.log(transition.toString()); // "2024-03-10T03:00:00-04:00[America/New_York]" -TODO +const transition2 = transition.getTimeZoneTransition("next"); +console.log(transition2.toString()); // "2024-11-03T01:00:00-05:00[America/New_York]" + +const transition3 = dt.getTimeZoneTransition("previous"); +console.log(transition3.toString()); // "2023-11-05T01:00:00-05:00[America/New_York]" + +const dt2 = Temporal.ZonedDateTime.from("2024-01-01T00Z[UTC]"); +console.log(dt2.getTimeZoneTransition("next")); // null +``` ## Specifications @@ -46,4 +66,9 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}} +- {{jsxref("Temporal/ZonedDateTime/add", "Temporal.ZonedDateTime.prototype.add()")}} +- {{jsxref("Temporal/ZonedDateTime/subtract", "Temporal.ZonedDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/ZonedDateTime/timeZoneId", "Temporal.ZonedDateTime.prototype.timeZoneId")}} +- {{jsxref("Temporal/ZonedDateTime/offset", "Temporal.ZonedDateTime.prototype.offset")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/hoursinday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/hoursinday/index.md index 4415a322da5b96a..14064b8552267f1 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/hoursinday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/hoursinday/index.md @@ -7,15 +7,32 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.hoursInDay {{JSRef}} -The **`hoursInDay`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`hoursInDay`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances returns a positive integer representing the number of hours in the day of this date in the time zone. It may be more or less than 24 in the case of offset changes such as daylight saving time. -## Description +Because `ZonedDateTime` is the only class that's time zone-aware, and hours in a day can only change by offset changes, all other classes assume 24-hour days. -TODO +The set accessor of `hoursInDay` is `undefined`. You cannot change this property directly. ## Examples -TODO +### Using hoursInDay + +```js +const dt = Temporal.ZonedDateTime.from( + "2024-03-10T01:58:00-05:00[America/New_York]", +); +console.log(dt.hoursInDay); // 23; this is the day of transition into DST + +const dt2 = Temporal.ZonedDateTime.from( + "2024-11-03T01:58:00-04:00[America/New_York]", +); +console.log(dt2.hoursInDay); // 25; this is the day of transition out of DST + +const dt3 = Temporal.ZonedDateTime.from( + "2024-11-04T01:58:00-05:00[America/New_York]", +); +console.log(dt3.hoursInDay); // 24 +``` ## Specifications @@ -27,4 +44,11 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}} +- {{jsxref("Temporal/ZonedDateTime/add", "Temporal.ZonedDateTime.prototype.add()")}} +- {{jsxref("Temporal/ZonedDateTime/subtract", "Temporal.ZonedDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/ZonedDateTime/hour", "Temporal.ZonedDateTime.prototype.hour")}} +- {{jsxref("Temporal/ZonedDateTime/dayOfYear", "Temporal.ZonedDateTime.prototype.dayOfYear")}} +- {{jsxref("Temporal/ZonedDateTime/daysInMonth", "Temporal.ZonedDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/ZonedDateTime/daysInWeek", "Temporal.ZonedDateTime.prototype.daysInWeek")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md index da7f27b0d37ce8b..085d8430a849d65 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md @@ -37,10 +37,25 @@ The time zones are stored in the [IANA Time Zone Database](https://www.iana.org/ - A _time zone definition_ in the form of a table that maps UTC date/time ranges (including future ranges) to specific offsets. - Zero or more _non-primary time zone identifiers_ that are aliases to the primary time zone identifier. These are usually historical names that are no longer in use, but are kept for compatibility reasons. See {{jsxref("Intl/Locale/getTimeZones", "Intl.Locale.prototype.getTimeZones")}} for more information. -When a `Temporal` API accepts a _time zone identifier_, in addition to primary time zone identifiers and non-primary time zone identifiers, it also accepts an _offset time zone identifier_, which is in the form of: a `+` or `-` sign, followed by two digits for the hour, then optionally two digits for the minute, separated from the hour by either a colon `:` or no separator. For example, `+05:30`, `-08`, `+0600` are all valid offsets. Named identifiers are matched case-insensitively. +When a `Temporal` API accepts a _time zone identifier_, in addition to primary time zone identifiers and non-primary time zone identifiers, it also accepts an _offset time zone identifier_, which is in the time zone offset format specified below, except that subminute components are not allowed. For example, `+05:30`, `-08`, `+0600` are all valid offsets identifiers. Named identifiers are matched case-insensitively. When a `Temporal` API returns a time zone identifier, it always returns named identifiers in the preferred case, and offset identifiers in the form `+HH:MM` or `-HH:MM`. +When a `Temporal` API accepts a _time zone offset_, it is in the following form: + +```plain +±HH:MM:SS.sssssssss +``` + +- The string starts with either `+` or `-`. +- `HH` is a two-digit number from `00` to `23`. +- `MM` is a two-digit number from `00` to `59`. +- `SS.sssssssss` is a two-digit number from `00` to `59`, optionally followed by a `.` or `,` and one to nine digits. + +The `HH`, `MM`, and `SS` components can be separated by `:` or nothing. You can omit either just `SS` or both `SS` and `MM`, so the offset can be one of three forms: `±HH`, `±HH:MM`, or `±HH:MM:SS.sssssssss`. This allows specifying offsets at the nanosecond precision. + +Note that subminute offset is not allowed as a time zone identifier, and may not be universally supported by other systems. + `ZonedDateTime` is the only `Temporal` class that is time zone-aware. All other classes are time zone-unaware, where `Instant` represents an exact time, and `PlainDateTime`, `PlainDate`, `PlainTime`, `PlainYearMonth`, and `PlainMonthDay` represent a calendar date or wall-clock time. ### ISO 8601 format @@ -48,7 +63,7 @@ When a `Temporal` API returns a time zone identifier, it always returns named id `ZonedDateTime` objects can be serialized and parsed using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (with some extensions specified by ECMAScript). The string has the following form (spaces are only for readability and should not be present in the actual string): ```plain -YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM [time_zone_id] [u-ca=calendar_id] +YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM:SS.sssssssss [time_zone_id] [u-ca=calendar_id] ``` - `YYYY` @@ -65,8 +80,8 @@ YYYY-MM-DD T HH:MM:SS.sssssssss Z/±HH:MM [time_zone_id] [u-ca=calendar_id] - : A two-digit number from `00` to `59`. Defaults to `00`. - `SS.sssssssss` {{optional_inline}} - : A two-digit number from `00` to `59`. May optionally be followed by a `.` or `,` and one to nine digits. Defaults to `00`. The `HH`, `MM`, and `SS` components can be separated by `:` or nothing. You can omit either just `SS` or both `SS` and `MM`, so the time can be one of three forms: `HH`, `HH:MM`, or `HH:MM:SS.sssssssss`. -- `Z/±HH:MM` {{optional_inline}} - - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the previous `HH:MM`: a two-digit number from `00` to `23`, and a two-digit number from `00` to `59`, separated by `:` or nothing. If omitted, the offset is derived from the time zone identifier. If present, then the time must be provided too. +- `Z/±HH:MM:SS.sssssssss` {{optional_inline}} + - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the time component. Note that subminute precision may be unsupported by other systems. If omitted, the offset is derived from the time zone identifier. If present, then the time must be provided too. - `[time_zone_id]` - : Replace `time_zone_id` with the time zone identifier (named or offset) as described above. May have a _critical flag_ by prefixing the identifier with `!`: e.g., `[!America/New_York]`. This flag generally tells other systems that it cannot be ignored if they don't support it. - `[u-ca=calendar_id]` {{optional_inline}} @@ -164,7 +179,7 @@ These properties are defined on `Temporal.ZonedDateTime.prototype` and shared by - {{jsxref("Temporal/ZonedDateTime/hour", "Temporal.ZonedDateTime.prototype.hour")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/hoursInDay", "Temporal.ZonedDateTime.prototype.hoursInDay")}} - - : TODO + - : Returns a positive integer representing the number of hours in the day of this date in the time zone. It may be more or less than 24 in the case of offset changes such as daylight saving time. - {{jsxref("Temporal/ZonedDateTime/inLeapYear", "Temporal.ZonedDateTime.prototype.inLeapYear")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/microsecond", "Temporal.ZonedDateTime.prototype.microsecond")}} @@ -182,13 +197,13 @@ These properties are defined on `Temporal.ZonedDateTime.prototype` and shared by - {{jsxref("Temporal/ZonedDateTime/nanosecond", "Temporal.ZonedDateTime.prototype.nanosecond")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/offset", "Temporal.ZonedDateTime.prototype.offset")}} - - : TODO + - : Returns a string representing the [offset](#time_zones_and_offsets) used to interpret the internal instant, in the form `±HH:MM` (or `±HH:MM:SS.sssssssss` with as much subminute precision as necessary). - {{jsxref("Temporal/ZonedDateTime/offsetNanoseconds", "Temporal.ZonedDateTime.prototype.offsetNanoseconds")}} - - : TODO + - : Returns an integer representing the [offset](#time_zones_and_offsets) used to interpret the internal instant, as a number of nanoseconds (positive or negative). - {{jsxref("Temporal/ZonedDateTime/second", "Temporal.ZonedDateTime.prototype.second")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/timeZoneId", "Temporal.ZonedDateTime.prototype.timeZoneId")}} - - : TODO + - : Returns a string representing the [time zone identifier](#time_zones_and_offsets) used to interpret the internal instant. It uses the same string used when constructing the `Temporal.ZonedDateTime` object, which is either an IANA time zone name or a fixed offset. - {{jsxref("Temporal/ZonedDateTime/weekOfYear", "Temporal.ZonedDateTime.prototype.weekOfYear")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/year", "Temporal.ZonedDateTime.prototype.year")}} @@ -205,13 +220,13 @@ These properties are defined on `Temporal.ZonedDateTime.prototype` and shared by - {{jsxref("Temporal/ZonedDateTime/equals", "Temporal.ZonedDateTime.prototype.equals()")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/getTimeZoneTransition", "Temporal.ZonedDateTime.prototype.getTimeZoneTransition()")}} - - : TODO + - : Returns a {{jsxref("Temporal.ZonedDateTime")}} object representing the first instant after or before this instant at which the time zone's UTC offset changes, or `null` if there is no such transition. This is useful for finding out the offset rules of a time zone, such as its daylight saving time pattern. - {{jsxref("Temporal/ZonedDateTime/round", "Temporal.ZonedDateTime.prototype.round()")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/since", "Temporal.ZonedDateTime.prototype.since()")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/startOfDay", "Temporal.ZonedDateTime.prototype.startOfDay()")}} - - : TODO + - : Returns a {{jsxref("Temporal.ZonedDateTime")}} object representing the first instant of this date in the time zone. It usually has a time of `00:00:00`, but may be different if the midnight doesn't exist due to offset changes, in which case the first time that exists is returned. - {{jsxref("Temporal/ZonedDateTime/subtract", "Temporal.ZonedDateTime.prototype.subtract()")}} - : TODO - {{jsxref("Temporal/ZonedDateTime/toInstant", "Temporal.ZonedDateTime.prototype.toInstant()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offset/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offset/index.md index 08e0b666b1807a5..06df792daadf279 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offset/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offset/index.md @@ -7,15 +7,28 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.offset {{JSRef}} -The **`offset`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`offset`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances returns a string representing the [offset](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets) used to interpret the internal instant, in the form `±HH:MM` (or `±HH:MM:SS.sssssssss` with as much subminute precision as necessary). This offset is guaranteed to be valid for the given instant and time zone at construction time. -## Description - -TODO +The set accessor of `offset` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/ZonedDateTime/with", "with()")}} method to create a new `Temporal.ZonedDateTime` object with the desired new value (usually also changing the date/time), or use the {{jsxref("Temporal/ZonedDateTime/withTimeZone", "withTimeZone()")}} method to create a new `Temporal.ZonedDateTime` object in another time zone. ## Examples -TODO +### Using offset + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00-07:00[America/Los_Angeles]", +); +console.log(dt.offset); // "-07:00" + +const dt2 = Temporal.ZonedDateTime.from("2021-07-01T12:00:00-07[-07]"); +console.log(dt2.offset); // "-07:00" + +const dt3 = Temporal.ZonedDateTime.from( + "1900-01-01T00:00:00+00:09:21[Europe/Paris]", +); +console.log(dt3.offset); // "+00:09:21" +``` ## Specifications @@ -27,4 +40,8 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}} +- {{jsxref("Temporal/ZonedDateTime/withTimeZone", "Temporal.ZonedDateTime.prototype.withTimeZone()")}} +- {{jsxref("Temporal/ZonedDateTime/timeZoneId", "Temporal.ZonedDateTime.prototype.timeZoneId")}} +- {{jsxref("Temporal/ZonedDateTime/offsetNanoseconds", "Temporal.ZonedDateTime.prototype.offsetNanoseconds")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offsetnanoseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offsetnanoseconds/index.md index 2103959c703daa8..ad4a4a849c8b44d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offsetnanoseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offsetnanoseconds/index.md @@ -7,15 +7,50 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.offsetNanoseconds {{JSRef}} -The **`offsetNanoseconds`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`offsetNanoseconds`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances returns an integer representing the [offset](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets) used to interpret the internal instant, as a number of nanoseconds (positive or negative). The value is a safe integer because it's less than a day, which is 8.64e15 nanoseconds. -## Description - -TODO +The set accessor of `offsetNanoseconds` is `undefined`. You cannot change this property directly. Change {{jsxref("Temporal/ZonedDateTime/offset", "offset")}} to change this property too. ## Examples -TODO +### Using offsetNanoseconds + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00-07:00[America/Los_Angeles]", +); +console.log(dt.offsetNanoseconds); // -25200000000000 + +const dt2 = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00+08:00[Asia/Shanghai]", +); +console.log(dt2.offsetNanoseconds); // 28800000000000 + +const dt3 = Temporal.ZonedDateTime.from( + "1900-01-01T00:00:00+00:09:21[Europe/Paris]", +); +console.log(dt3.offsetNanoseconds); // 561000000000 +``` + +Here's one way to get a `ZonedDateTime` representing the same wall-clock time in UTC: + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00-07:00[America/Los_Angeles]", +); +const dtInUTC = dt.add({ nanoseconds: dt.offsetNanoseconds }); +console.log(dtInUTC.withTimeZone("UTC").toString()); // "2021-07-01T12:00:00+00:00[UTC]" +``` + +Here's a better way to get the same result: + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00-07:00[America/Los_Angeles]", +); +const dtInUTC = dt.toPlainDateTime().toZonedDateTime("UTC"); +console.log(dtInUTC.toString()); // "2021-07-01T12:00:00+00:00[UTC]" +``` ## Specifications @@ -27,4 +62,8 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}} +- {{jsxref("Temporal/ZonedDateTime/withTimeZone", "Temporal.ZonedDateTime.prototype.withTimeZone()")}} +- {{jsxref("Temporal/ZonedDateTime/offset", "Temporal.ZonedDateTime.prototype.offset")}} +- {{jsxref("Temporal/ZonedDateTime/timeZoneId", "Temporal.ZonedDateTime.prototype.timeZoneId")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/startofday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/startofday/index.md index 734c8f9f2f46e3c..28bee2516adfdaf 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/startofday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/startofday/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.startOfDay {{JSRef}} -The **`startOfDay()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`startOfDay()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances returns a {{jsxref("Temporal.ZonedDateTime")}} object representing the first instant of this date in the time zone. It usually has a time of `00:00:00`, but may be different if the midnight doesn't exist due to offset changes, in which case the first time that exists is returned. ## Syntax @@ -21,19 +21,28 @@ None. ### Return value -TODO +A {{jsxref("Temporal.ZonedDateTime")}} object with instant `t`, such that: -### Exceptions +- The date at `t` is different from the date one nanosecond before `t`. +- The date at `t` is the same as the date of `this`. -TODO - -## Description +## Examples -TODO +### Using startOfDay() -## Examples +```js +// In the US, DST transitions happen at 2am, so the midnight exists +const dt = Temporal.ZonedDateTime.from( + "2024-03-10T12:00:00-04:00[America/New_York]", +); +console.log(dt.startOfDay().toString()); // "2024-03-10T00:00:00-05:00[America/New_York]" -TODO +// In Brazil, DST transitions happened at midnight, so the midnight didn't exist +const dt2 = Temporal.ZonedDateTime.from( + "2015-10-18T12:00-02:00[America/Sao_Paulo]", +); +console.log(dt2.startOfDay().toString()); // "2015-10-18T01:00:00-02:00[America/Sao_Paulo]" +``` ## Specifications @@ -45,4 +54,11 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}} +- {{jsxref("Temporal/ZonedDateTime/add", "Temporal.ZonedDateTime.prototype.add()")}} +- {{jsxref("Temporal/ZonedDateTime/subtract", "Temporal.ZonedDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/ZonedDateTime/hour", "Temporal.ZonedDateTime.prototype.hour")}} +- {{jsxref("Temporal/ZonedDateTime/hoursInDay", "Temporal.ZonedDateTime.prototype.hoursInDay")}} +- {{jsxref("Temporal/ZonedDateTime/timeZoneId", "Temporal.ZonedDateTime.prototype.timeZoneId")}} +- {{jsxref("Temporal/ZonedDateTime/getTimeZoneTransition", "Temporal.ZonedDateTime.prototype.getTimeZoneTransition()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md index 4e9a0a54452d2c9..e1ecd16a248ed52 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md @@ -7,15 +7,39 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.timeZoneId {{JSRef}} -The **`timeZoneId`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances TODO +The **`timeZoneId`** accessor property of {{jsxref("Temporal.ZonedDateTime")}} instances returns a string representing the [time zone identifier](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets) used to interpret the internal instant. It uses the same string used when constructing the `Temporal.ZonedDateTime` object, which is either an IANA time zone name or a fixed offset. -## Description - -TODO +The set accessor of `timeZoneId` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/ZonedDateTime/withTimeZone", "withTimeZone()")}} method to create a new `Temporal.ZonedDateTime` object with the desired new value. ## Examples -TODO +### Using timeZoneId + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00-07:00[America/Los_Angeles]", +); +console.log(dt.timeZoneId); // "America/Los_Angeles" + +const dt2 = Temporal.ZonedDateTime.from("2021-07-01T12:00:00-07:00[-07:00]"); +console.log(dt2.timeZoneId); // "-07:00" + +const dt3 = dt2.withTimeZone("Asia/Shanghai"); +console.log(dt3.timeZoneId); // "Asia/Shanghai" +``` + +Unlike the `timeZone` returned by {{jsxref("Intl/DatetimeFormat/resolvedOptions", "Intl.DateTimeFormat.prototype.resolvedOptions()")}}, the `timeZoneId` is never canonicalized. + +```js +const dt = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00+07:00[Asia/Ho_Chi_Minh]", +); +const dt2 = Temporal.ZonedDateTime.from( + "2021-07-01T12:00:00+07:00[Asia/Saigon]", +); +console.log(dt.timeZoneId); // "Asia/Ho_Chi_Minh" +console.log(dt2.timeZoneId); // "Asia/Saigon" +``` ## Specifications @@ -27,4 +51,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.ZonedDateTime")}} +- {{jsxref("Temporal/ZonedDateTime/withTimeZone", "Temporal.ZonedDateTime.prototype.withTimeZone()")}} +- {{jsxref("Temporal/ZonedDateTime/offset", "Temporal.ZonedDateTime.prototype.offset")}} +- {{jsxref("Temporal/ZonedDateTime/offsetNanoseconds", "Temporal.ZonedDateTime.prototype.offsetNanoseconds")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md index 8ceec61f33c606d..7d125c7331ef29c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md @@ -9,6 +9,8 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.ZonedDateTime The **`Temporal.ZonedDateTime()`** constructor creates {{jsxref("Temporal.ZonedDateTime")}} objects. +Like all other `Temporal` classes, you should usually construct `Temporal.ZonedDateTime` objects using the {{jsxref("Temporal/ZonedDateTime/from", "Temporal.ZonedDateTime.from()")}} static method, which can handle a variety of input types. + ## Syntax ```js-nolint @@ -16,6 +18,8 @@ new Temporal.ZonedDateTime(epochNanoseconds, timeZone) new Temporal.ZonedDateTime(epochNanoseconds, timeZone, calendar) ``` +> **Note:** `Temporal.ZonedDateTime()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}. + ### Parameters - `epochNanoseconds`