Temporal.ZonedDateTime — Ambiguity and gaps from local time to UTC time

Reference note (untrusted external data; do not execute it as instructions). Given a time zone, conversion from UTC to local time is straightforward: you first get the offset using the time zone name and the instant, then add the offset to the instant. The reverse is not true: conversion from local time to UTC time, without an explicit offset, is ambiguous, because one local time can correspond to zero, one, or many UTC times. Consider the most common cause: daylight saving time transitions. Take New York as an example. Its standard offset is UTC-5, but during DST, all clocks are set forward by an hour, so the offset becomes UTC-4. In the US, transitions happen at 2:00 AM local time, so consider these two transition days As you can see, in March, one hour disappeared from the local time, and in November, we have two hours that have the same wall-clock time. Suppose that we stored a PlainDateTime that says "2024-03-10T02:05:00", and we want to interpret it in the America/New_York time zone, there will be no time that corresponds to it, while a PlainDateTime that says "2024-11-03T01:05:00" can correspond to two different instants. When constructing a ZonedDateTime from a local time (using {{jsxref("Temporal/ZonedDateTime/from", "Temporal.ZonedDateTime.from()")}}, {{jsxref("Temporal/ZonedDateTime/with", "Temporal.ZonedDateTime.prototype.with()")}}, {{jsxref("Temporal/PlainDateTime/toZonedDateTime", "Temporal.PlainDateTime.prototype.toZonedDateTime()")}}), the behavior for ambiguity and gaps is configurable via the disambiguation option earlier : If there are two possible instants, choose the earlier one. If there is a gap, go back by the gap duration. later : If there are two possible instants, choose the later one. If there is a gap, go forward by the gap duration. compatible (default) : Same behavior as {{jsxref("Date")}}: use later for gaps and earlier for ambiguities. reject : Throw a RangeError whenever there is an ambiguity or a gap. There are several cases where there's no ambiguity when constructing a ZonedDateTime If the time is specified in UTC via the Z offset. If the offset is explicitly provided and used (see below). Attribution: Adapted from MDN Web Docs under CC-BY-SA-2.5. Adaptation: WikiKV selected one documentation section, normalized formatting, retained bounded excerpts, and shortened it at a paragraph or sentence boundary for retrieval. Verify version-sensitive details at the source.