22 Dates and Temporal

opt

22.3.12 Operations for Reading Options

This section defines abstract operations for reading the properties of options Objects passed to Temporal functions. For example, GetTemporalOverflowOption accesses the "overflow" property of an Object, ensures that it is one of the allowed values "constrain" or "reject", and returns one of the corresponding Enum specification types "constrain" or "reject".

22.3.12.1 GetDifferenceSettings ( `operation`, `options`, `unitGroup`, `disallowedUnits`, `fallbackSmallestUnit`, `smallestLargestDefaultUnit` )

The abstract operation GetDifferenceSettings takes arguments operation (since or until), options (an Object), unitGroup (date, time, or datetime), disallowedUnits (a List of Temporal units), fallbackSmallestUnit (a Temporal unit), and smallestLargestDefaultUnit (a Temporal unit) and returns either a normal completion containing a Record with fields [[SmallestUnit]] (a Temporal unit), [[LargestUnit]] (a Temporal unit), [[RoundingMode]] (a rounding mode), and [[RoundingIncrement]] (an integer in the inclusive interval from 1 to 10⁹), or a throw completion. It reads unit and rounding options needed by difference operations. It performs the following steps when called:

Let largestUnit be ? GetTemporalUnitValuedOption(options, "largestUnit", optional).
Let roundingIncrement be ? GetRoundingIncrementOption(options).
Let roundingMode be ? GetRoundingModeOption(options, "trunc").
Let smallestUnit be ? GetTemporalUnitValuedOption(options, "smallestUnit", optional).
Perform ? ValidateTemporalUnitValue(largestUnit, unitGroup, « "auto" »).
If largestUnit is no-unit, then
1. Set largestUnit to "auto".
If disallowedUnits contains largestUnit, throw a RangeError exception.
Perform ? ValidateTemporalUnitValue(smallestUnit, unitGroup).
If smallestUnit is no-unit, then
1. Set smallestUnit to fallbackSmallestUnit.
If disallowedUnits contains smallestUnit, throw a RangeError exception.
Let defaultLargestUnit be LargerOfTwoTemporalUnits(smallestLargestDefaultUnit, smallestUnit).
If largestUnit is "auto", set largestUnit to defaultLargestUnit.
If LargerOfTwoTemporalUnits(largestUnit, smallestUnit) is not largestUnit, throw a RangeError exception.
Let maximum be MaximumTemporalDurationRoundingIncrement(smallestUnit).
If maximum is not no-maximum, perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, false).
If operation is since, then
1. Set roundingMode to NegateRoundingMode(roundingMode).
Return the Record { [[SmallestUnit]]: smallestUnit, [[LargestUnit]]: largestUnit, [[RoundingMode]]: roundingMode, [[RoundingIncrement]]: roundingIncrement, }.

22.3.12.2 GetDirectionOption ( `options` )

The abstract operation GetDirectionOption takes argument options (an Object) and returns either a normal completion containing either "next" or "previous", or a throw completion. It fetches and validates the "direction" property from options, throwing if absent. It performs the following steps when called:

Let value be ? Get(options, "direction").
If value is undefined, throw a RangeError exception.
Let stringValue be ? ToString(value).
If stringValue is not either "next"or "previous", throw a RangeError exception.
Return stringValue.

22.3.12.3 GetRoundingIncrementOption ( `options` )

The abstract operation GetRoundingIncrementOption takes argument options (an Object) and returns either a normal completion containing a positive integer in the inclusive interval from 1 to 10⁹, or a throw completion. It fetches and validates the "roundingIncrement" property from options, returning 1 if absent. It performs the following steps when called:

Let value be ? Get(options, "roundingIncrement").
If value is undefined, return 1.
Return ? SnapToInteger(value, truncate, 1, 10⁹).

22.3.12.4 GetRoundingModeOption ( `options`, `fallback` )

The abstract operation GetRoundingModeOption takes arguments options (an Object) and fallback (a rounding mode) and returns either a normal completion containing a rounding mode, or a throw completion. It fetches and validates the "roundingMode" property from options, returning fallback if absent. It performs the following steps when called:

Let value be ? Get(options, "roundingMode").
If value is undefined, return fallback.
Let stringValue be ? ToString(value).
If stringValue is not a rounding mode, throw a RangeError exception.
Return stringValue.

22.3.12.5 GetTemporalDisambiguationOption ( `options` )

The abstract operation GetTemporalDisambiguationOption takes argument options (an Object) and returns either a normal completion containing either "compatible", "earlier", "later", or "reject", or a throw completion. It fetches and validates the "disambiguation" property of options, returning "compatible" if absent. It performs the following steps when called:

Let value be ? Get(options, "disambiguation").
If value is undefined, return "compatible".
Let stringValue be ? ToString(value).
If stringValue is not one of "compatible", "earlier", "later", or "reject", throw a RangeError exception.
Return stringValue.

22.3.12.6 GetTemporalFractionalSecondDigitsOption ( `options` )

The abstract operation GetTemporalFractionalSecondDigitsOption takes argument options (an Object) and returns either a normal completion containing either auto or an integer in the inclusive interval from 0 to 9, or a throw completion. It fetches and validates the "fractionalSecondDigits" property from options, returning auto if absent. It performs the following steps when called:

Let digitsValue be ? Get(options, "fractionalSecondDigits").
If digitsValue is undefined, return auto.
If digitsValue is not a Number, then
1. If ? ToString(digitsValue) is not "auto", throw a RangeError exception.
2. Return auto.
If digitsValue is not finite, throw a RangeError exception.
Let digitCount be floor(ℝ(digitsValue)).
If digitCount is not in the inclusive interval from 0 to 9, throw a RangeError exception.
Return digitCount.

22.3.12.7 GetTemporalOffsetOption ( `options`, `fallback` )

The abstract operation GetTemporalOffsetOption takes arguments options (an Object) and fallback ("prefer", "use", "ignore", or "reject") and returns either a normal completion containing either "prefer", "use", "ignore", or "reject", or a throw completion. It fetches and validates the "offset" property of options, returning fallback if absent. It performs the following steps when called:

Let value be ? Get(options, "offset").
If value is undefined, return fallback.
Let stringValue be ? ToString(value).
If stringValue is not one of "prefer", "use", "ignore", or "reject", throw a RangeError exception.
Return stringValue.

22.3.12.8 GetTemporalOverflowOption ( `options` )

The abstract operation GetTemporalOverflowOption takes argument options (an Object) and returns either a normal completion containing either "constrain" or "reject", or a throw completion. It fetches and validates the "overflow" property of options, returning "constrain" if absent. It performs the following steps when called:

Let value be ? Get(options, "overflow").
If value is undefined, return "constrain".
Let stringValue be ? ToString(value).
If stringValue is not one of "constrain" or "reject", throw a RangeError exception.
Return stringValue.

22.3.12.9 GetTemporalRelativeToOption ( `options` )

The abstract operation GetTemporalRelativeToOption takes argument options (an Object) and returns either a normal completion containing a Record with fields [[PlainRelativeTo]] (a Temporal.PlainDate or empty) and [[ZonedRelativeTo]] (a Temporal.ZonedDateTime or empty), or a throw completion. It examines the value of the relativeTo property of its options argument. If the value is undefined, both the [[PlainRelativeTo]] and [[ZonedRelativeTo]] fields of the returned Record are empty. If the value is not a String or an Object, it throws a TypeError. Otherwise, it attempts to return a Temporal.ZonedDateTime instance in the [[ZonedRelativeTo]] field, or a Temporal.PlainDate instance in the [[PlainRelativeTo]] field, in order of preference, by converting the value. If neither of those are possible, it throws a RangeError. It performs the following steps when called:

Let value be ? Get(options, "relativeTo").
If value is undefined, return the Record { [[PlainRelativeTo]]: empty, [[ZonedRelativeTo]]: empty }.
Let offsetBehaviour be option.
Let matchBehaviour be match-exactly.
If value is an Object, then
1. If value has an [[InitializedTemporalZonedDateTime]] internal slot, then
  1. Return the Record { [[PlainRelativeTo]]: empty, [[ZonedRelativeTo]]: value }.
2. If value has an [[InitializedTemporalDate]] internal slot, then
  1. Return the Record { [[PlainRelativeTo]]: value, [[ZonedRelativeTo]]: empty }.
3. If value has an [[InitializedTemporalDateTime]] internal slot, then
  1. Let plainDate be ! CreateTemporalDate(value.[[ISODateTime]].[[ISODate]], value.[[Calendar]]).
  2. Return the Record { [[PlainRelativeTo]]: plainDate, [[ZonedRelativeTo]]: empty }.
4. Let calendar be ? GetTemporalCalendarIdentifierWithISODefault(value).
5. Let fields be ? PrepareCalendarFields(calendar, value, date-fields, time-fields-with-time-zone-and-offset, no-required-fields).
6. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, "constrain").
7. Let timeZone be fields.[[TimeZone]].
8. Let offsetString be fields.[[OffsetString]].
9. If offsetString is empty, then
  1. Set offsetBehaviour to wall.
10. Let isoDate be result.[[ISODate]].
11. Let time be result.[[Time]].
Else,
1. If value is not a String, throw a TypeError exception.
2. Let result be ? ParseISODateTime(value, any-date-time).
3. Let offsetString be result.[[TimeZone]].[[OffsetString]].
4. Let annotation be result.[[TimeZone]].[[TimeZoneAnnotation]].
5. If annotation is empty, then
  1. Let timeZone be empty.
6. Else,
  1. Let timeZone be ? ToTemporalTimeZoneIdentifier(annotation).
  2. If result.[[TimeZone]].[[Z]] is true, then
    1. Set offsetBehaviour to exact.
  3. Else if offsetString is empty, then
    1. Set offsetBehaviour to wall.
  4. Set matchBehaviour to match-minutes.
  5. If offsetString is not empty, then
    1. Let offsetParseResult be ParseText(offsetString, UTCOffset[+SubMinutePrecision]).
    2. Assert: offsetParseResult is a Parse Node.
    3. If offsetParseResult contains a Second Parse Node, set matchBehaviour to match-exactly.
7. Let calendar be result.[[Calendar]].
8. If calendar is empty, set calendar to "iso8601".
9. Set calendar to ? CanonicalizeCalendar(calendar).
10. Let isoDate be ! CreateISODateRecord(result.[[Year]], result.[[Month]], result.[[Day]]).
11. Let time be result.[[Time]].
If timeZone is empty, then
1. Let plainDate be ? CreateTemporalDate(isoDate, calendar).
2. Return the Record { [[PlainRelativeTo]]: plainDate, [[ZonedRelativeTo]]: empty }.
If offsetBehaviour is option, then
1. Assert: offsetString is a String.
2. Let offsetNanoseconds be ! ParseDateTimeUTCOffset(offsetString).
Else,
1. Let offsetNanoseconds be 0.
Let epochNanoseconds be ? InterpretISODateTimeOffset(isoDate, time, offsetBehaviour, offsetNanoseconds, timeZone, "compatible", "reject", matchBehaviour).
Let zonedRelativeTo be ! CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar).
Return the Record { [[PlainRelativeTo]]: empty, [[ZonedRelativeTo]]: zonedRelativeTo }.

22.3.12.10 GetTemporalShowCalendarNameOption ( `options` )

The abstract operation GetTemporalShowCalendarNameOption takes argument options (an Object) and returns either a normal completion containing either "auto", "always", "never", or "critical", or a throw completion. It fetches and validates the "calendarName" property from options, returning "auto" if absent. It performs the following steps when called:

Let value be ? Get(options, "calendarName").
If value is undefined, return "auto".
Let stringValue be ? ToString(value).
If stringValue is not one of "always", "never", "critical", or "auto", throw a RangeError exception.
Return stringValue.

22.3.12.11 GetTemporalShowOffsetOption ( `options` )

The abstract operation GetTemporalShowOffsetOption takes argument options (an Object) and returns either a normal completion containing either "auto" or "never", or a throw completion. It fetches and validates the "offset" property from options, returning "auto" if absent. It performs the following steps when called:

Let value be ? Get(options, "offset").
If value is undefined, return "auto".
Let stringValue be ? ToString(value).
If stringValue is not either "never" or "auto", throw a RangeError exception.
Return stringValue.

22.3.12.12 GetTemporalShowTimeZoneNameOption ( `options` )

The abstract operation GetTemporalShowTimeZoneNameOption takes argument options (an Object) and returns either a normal completion containing either "auto", "never", or "critical", or a throw completion. It fetches and validates the "timeZoneName" property from options, returning "auto" if absent. It performs the following steps when called:

Let value be ? Get(options, "timeZoneName").
If value is undefined, return "auto".
Let stringValue be ? ToString(value).
If stringValue is not one of "never", "critical", or "auto", throw a RangeError exception.
Return stringValue.

22.3.12.13 GetTemporalUnitValuedOption ( `options`, `key`, `default` )

The abstract operation GetTemporalUnitValuedOption takes arguments options (an Object), key (a property key), and default (optional or required) and returns either a normal completion containing either a Temporal unit, no-unit, or "auto", or a throw completion. It attempts to read a Temporal unit from the specified property of options.

Both singular and plural unit names are accepted, but only the singular form is used internally.

Let value be ? Get(options, key).
If value is undefined, then
1. If default is required, throw a RangeError exception.
2. Return no-unit.
Let stringValue be ? ToString(value).
If stringValue is "auto", return "auto".
If stringValue is either "year" or "years", return "year".
If stringValue is either "month" or "months", return "month".
If stringValue is either "week" or "weeks", return "week".
If stringValue is either "day" or "days", return "day".
If stringValue is either "hour" or "hours", return "hour".
If stringValue is either "minute" or "minutes", return "minute".
If stringValue is either "second" or "seconds", return "second".
If stringValue is either "milllisecond" or "millliseconds", return "milllisecond".
If stringValue is either "microsecond" or "microseconds", return "microsecond".
If stringValue is either "nanosecond" or "nanoseconds", return "nanosecond".
Throw a RangeError exception.

22.3.13 Rounding Modes and Increments

This section contains definitions pertaining to rounding increments and rounding modes. Several Temporal Objects provide the capability of rounding a quantity to a given increment, following different rounding rules.

A rounding mode is one of the values in the “Rounding Mode” column of Table 72. An unsigned rounding mode is one of infinity, zero, half-infinity, half-zero, or half-even.

Table 72: Rounding modes

Rounding Mode	Description	Examples: Round to 0 fraction digits
Rounding Mode	Description	-1.5	0.4	0.5	0.6	1.5
"ceil"	Toward positive infinity	⬆️ [-1]	⬆️ [1]	⬆️ [1]	⬆️ [1]	⬆️ [2]
"floor"	Toward negative infinity	⬇️ [-2]	⬇️ [0]	⬇️ [0]	⬇️ [0]	⬇️ [1]
"expand"	Away from zero	⬇️ [-2]	⬆️ [1]	⬆️ [1]	⬆️ [1]	⬆️ [2]
"trunc"	Toward zero	⬆️ [-1]	⬇️ [0]	⬇️ [0]	⬇️ [0]	⬇️ [1]
"halfCeil"	Ties toward positive infinity	⬆️ [-1]	⬇️ [0]	⬆️ [1]	⬆️ [1]	⬆️ [2]
"halfFloor"	Ties toward negative infinity	⬇️ [-2]	⬇️ [0]	⬇️ [0]	⬆️ [1]	⬇️ [1]
"halfExpand"	Ties away from zero	⬇️ [-2]	⬇️ [0]	⬆️ [1]	⬆️ [1]	⬆️ [2]
"halfTrunc"	Ties toward zero	⬆️ [-1]	⬇️ [0]	⬇️ [0]	⬆️ [1]	⬇️ [1]
"halfEven"	Ties toward an even rounding increment multiple	⬇️ [-2]	⬇️ [0]	⬇️ [0]	⬆️ [1]	⬆️ [2]

Note

The examples are illustrative of the unique behaviour of each option. ⬆️ means “resolves toward positive infinity”; ⬇️ means “resolves toward negative infinity”.

22.3.13.1 ApplyUnsignedRoundingMode ( `quantity`, `lowerBound`, `upperBound`, `unsignedRoundingMode` )

The abstract operation ApplyUnsignedRoundingMode takes arguments quantity (a mathematical value), lowerBound (a mathematical value), upperBound (a mathematical value), and unsignedRoundingMode (an unsigned rounding mode) and returns a mathematical value. It considers quantity, bounded below by lowerBound and above by upperBound, and returns either lowerBound or upperBound according to unsignedRoundingMode. It performs the following steps when called:

If quantity = lowerBound, return lowerBound.
Assert: lowerBound < quantity < upperBound.
If unsignedRoundingMode is zero, return lowerBound.
If unsignedRoundingMode is infinity, return upperBound.
Let distanceToLower be quantity – lowerBound.
Let distanceToUpper be upperBound – quantity.
If distanceToLower < distanceToUpper, return lowerBound.
If distanceToUpper < distanceToLower, return upperBound.
Assert: distanceToLower is equal to distanceToUpper.
If unsignedRoundingMode is half-zero, return lowerBound.
If unsignedRoundingMode is half-infinity, return upperBound.
Assert: unsignedRoundingMode is half-even.
Let cardinality be (lowerBound / (upperBound – lowerBound)) modulo 2.
If cardinality = 0, return lowerBound.
Return upperBound.

22.3.13.2 GetUnsignedRoundingMode ( `roundingMode`, `sign` )

The abstract operation GetUnsignedRoundingMode takes arguments roundingMode (a rounding mode) and sign (negative or positive) and returns an unsigned rounding mode. It returns the unsigned rounding mode that should be applied to the absolute value of a number to produce the same result as if roundingMode were applied to the signed value of the number (negative if sign is negative, or positive otherwise). It performs the following steps when called:

If roundingMode is "ceil", then
1. If sign is positive, return infinity.
2. Return zero.
If roundingMode is "floor", then
1. If sign is positive, return zero.
2. Return infinity.
If roundingMode is "expand", return infinity.
If roundingMode is "trunc", return zero.
If roundingMode is "halfCeil", then
1. If sign is positive, return half-infinity.
2. Return half-zero.
If roundingMode is "halfFloor", then
1. If sign is positive, return half-zero.
2. Return half-infinity.
If roundingMode is "halfExpand", return half-infinity.
If roundingMode is "halfTrunc", return half-zero.
Assert: roundingMode is "halfEven".
Return half-even.

22.3.13.3 MaximumTemporalDurationRoundingIncrement ( `unit` )

The abstract operation MaximumTemporalDurationRoundingIncrement takes argument unit (a Temporal unit) and returns 24, 60, 1000, or no-maximum. Given a Temporal unit passed as input to methods that perform duration rounding calculations such as Temporal.Duration.prototype.round (22.15.3.20) or Temporal.PlainDate.prototype.until (22.11.3.25), it returns the maximum rounding increment for that unit, or no-maximum if there is no maximum. It performs the following steps when called:

If unit is "hour", return 24.
If unit is either "minute" or "second", return 60.
If unit is one of "millisecond", "microsecond", or "nanosecond", return 1000.
Return no-maximum.

22.3.13.4 NegateRoundingMode ( `roundingMode` )

The abstract operation NegateRoundingMode takes argument roundingMode (a rounding mode) and returns a rounding mode. It returns the correct rounding mode to use when rounding the negative of a value that was originally given with roundingMode. It performs the following steps when called:

If roundingMode is "ceil", return "floor".
If roundingMode is "floor", return "ceil".
If roundingMode is "halfCeil", return "halfFloor".
If roundingMode is "halfFloor", return "halfCeil".
Return roundingMode.

22.3.13.5 RoundNumberToIncrement ( `quantity`, `increment`, `roundingMode` )

The abstract operation RoundNumberToIncrement takes arguments quantity (a mathematical value), increment (a positive integer), and roundingMode (a rounding mode) and returns an integer. It rounds quantity to the nearest multiple of increment, up or down according to roundingMode. It performs the following steps when called:

Let quotient be quantity / increment.
Let sign be positive.
If quotient < 0, then
1. Set sign to negative.
2. Set quotient to -quotient.
Let unsignedRoundingMode be GetUnsignedRoundingMode(roundingMode, sign).
Let lowerBound be floor(quotient).
Let upperBound be ceiling(quotient).
Let rounded be ApplyUnsignedRoundingMode(quotient, lowerBound, upperBound, unsignedRoundingMode).
If sign is negative, set rounded to -rounded.
Return rounded × increment.

22.3.13.6 RoundNumberToIncrementAsIfPositive ( `quantity`, `increment`, `roundingMode` )

The abstract operation RoundNumberToIncrementAsIfPositive takes arguments quantity (a mathematical value), increment (a positive integer), and roundingMode (a rounding mode) and returns an integer. It rounds quantity to the nearest multiple of increment, up or down according to roundingMode, but always as if quantity were positive. For example, "floor" and "trunc" behave identically. This is used when rounding exact times, where “rounding down” conceptually always means towards the beginning of time, even if the time is expressed as a negative amount of time relative to an epoch. It performs the following steps when called:

Let quotient be quantity / increment.
Let unsignedRoundingMode be GetUnsignedRoundingMode(roundingMode, positive).
Let lowerBound be floor(quotient).
Let upperBound be ceiling(quotient).
Let rounded be ApplyUnsignedRoundingMode(quotient, lowerBound, upperBound, unsignedRoundingMode).
Return rounded × increment.

22.3.13.7 ValidateTemporalRoundingIncrement ( `increment`, `dividend`, `inclusive` )

The abstract operation ValidateTemporalRoundingIncrement takes arguments increment (a positive integer), dividend (a positive integer), and inclusive (a Boolean) and returns either a normal completion containing unused or a throw completion. It checks whether increment evenly divides dividend, throwing a RangeError if it does not. dividend must be divided into more than one part unless inclusive is true. It performs the following steps when called:

If inclusive is true, then
1. Let maximum be dividend.
Else,
1. Assert: dividend > 1.
2. Let maximum be dividend - 1.
If increment > maximum, throw a RangeError exception.
If dividend modulo increment ≠ 0, throw a RangeError exception.
Return unused.

22.3.14 Time Durations

A time duration is an integer in the inclusive interval from -MaxTimeDuration to MaxTimeDuration, where MaxTimeDuration = 2⁵³ × NanosecondsPerSecond - 1 = 9,007,199,254,740,991,999,999,999 It represents the portion of a duration calculation that deals with time units, but as a combined value of total nanoseconds.

22.3.14.1 Add24HourDaysToTimeDuration ( `timeDuration`, `days` )

The abstract operation Add24HourDaysToTimeDuration takes arguments timeDuration (a time duration) and days (an integer) and returns either a normal completion containing a time duration or a throw completion. It returns a time duration that is the sum of timeDuration and the number of 24-hour days indicated by days, throwing an error if the result is not within the range of a time duration. This operation is not used in time zone arithmetic such as Temporal.Duration.prototype.round (22.15.3.20) with a Temporal.ZonedDateTime instance as the relativeTo parameter, since those days may not be 24 hours long. It performs the following steps when called:

Let result be timeDuration + days × NanosecondsPerDay.
If result is not a time duration, throw a RangeError exception.
Return result.

22.3.14.2 AddTimeDuration ( `xTimeDuration`, `yTimeDuration` )

The abstract operation AddTimeDuration takes arguments xTimeDuration (a time duration) and yTimeDuration (a time duration) and returns either a normal completion containing a time duration or a throw completion. It returns a time duration that is the sum of xTimeDuration and yTimeDuration, throwing an error if the result is not within the range of a time duration. It performs the following steps when called:

Let result be xTimeDuration + yTimeDuration.
If result is not a time duration, throw a RangeError exception.
Return result.

22.3.14.3 AddTimeDurationToEpochNanoseconds ( `timeDuration`, `epochNanoseconds` )

The abstract operation AddTimeDurationToEpochNanoseconds takes arguments timeDuration (a time duration) and epochNanoseconds (an epoch nanoseconds count) and returns an integer. It adds a time duration to an epoch nanoseconds count and returns a new exact time, which is not required to be within the inclusive interval from MinEpochNanoseconds to MaxEpochNanoseconds. It performs the following steps when called:

Return timeDuration + epochNanoseconds.

22.3.14.4 RoundTimeDuration ( `timeDuration`, `increment`, `unit`, `roundingMode` )

The abstract operation RoundTimeDuration takes arguments timeDuration (a time duration), increment (a positive integer), unit (a time unit), and roundingMode (a rounding mode) and returns either a normal completion containing a time duration, or a throw completion. It rounds a timeDuration according to the rounding parameters unit, increment, and roundingMode, and returns the time duration result. It performs the following steps when called:

Return ? RoundTimeDurationToIncrement(timeDuration, TemporalUnitLength(unit) × increment, roundingMode).

22.3.14.5 RoundTimeDurationToIncrement ( `timeDuration`, `increment`, `roundingMode` )

The abstract operation RoundTimeDurationToIncrement takes arguments timeDuration (a time duration), increment (a positive integer), and roundingMode (a rounding mode) and returns either a normal completion containing a time duration or a throw completion. It rounds the total number of nanoseconds in the time duration timeDuration to the nearest multiple of increment, up or down according to roundingMode. It performs the following steps when called:

Let rounded be RoundNumberToIncrement(timeDuration, increment, roundingMode).
If rounded is not a time duration, throw a RangeError exception.
Return rounded.

22.3.14.6 TimeDurationFromComponents ( `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`, `nanoseconds` )

The abstract operation TimeDurationFromComponents takes arguments hours (an integer), minutes (an integer), seconds (an integer), milliseconds (an integer), microseconds (an integer), and nanoseconds (an integer) and returns either a normal completion containing a time duration, or a throw completion. From the given units, it computes a time duration consisting of total nanoseconds. The time duration can be stored losslessly in two 64-bit floating point numbers consisting of truncate(nanoseconds / NanosecondsPerSecond) and remainder(nanoseconds, NanosecondsPerSecond). Alternatively, nanoseconds can be stored as a 96-bit integer. It performs the following steps when called:

Set minutes to minutes + hours × 60.
Set seconds to seconds + minutes × 60.
Set milliseconds to milliseconds + seconds × 1000.
Set microseconds to microseconds + milliseconds × 1000.
Set nanoseconds to nanoseconds + microseconds × 1000.
If nanoseconds is not a time duration, throw a RangeError exception.
Return nanoseconds.

22.3.14.7 TimeDurationFromEpochNanosecondsDifference ( `epochNanosecondsFrom`, `epochNanosecondsTo` )

The abstract operation TimeDurationFromEpochNanosecondsDifference takes arguments epochNanosecondsFrom (an epoch nanoseconds count) and epochNanosecondsTo (an epoch nanoseconds count) and returns a time duration. The returned time duration is the difference between two epoch nanoseconds counts, which must be within the range of a time duration. It performs the following steps when called:

Let result be epochNanosecondsTo - epochNanosecondsFrom.
Assert: result is a time duration.
Return result.

22.3.14.8 TimeDurationSign ( `timeDuration` )

The abstract operation TimeDurationSign takes argument timeDuration (a time duration) and returns -1, 0, or 1. It returns 0 if the duration is zero, or ±1 depending on the sign of the duration. It performs the following steps when called:

If timeDuration < 0, return -1.
If timeDuration > 0, return 1.
Return 0.

22.3.14.9 TotalTimeDuration ( `timeDuration`, `unit` )

The abstract operation TotalTimeDuration takes arguments timeDuration (a time duration) and unit (either a time unit or "day") and returns a mathematical value. It returns the total number of unit in duration. It performs the following steps when called:

Return timeDuration / TemporalUnitLength(unit).

Note

This operation cannot be implemented directly using floating-point arithmetic when 𝔽(timeDuration) is not a safe integer. The division can be implemented in C++ with the __float128 type if the compiler supports it, or with software emulation such as in the SoftFP library.

22.3.15 Time Records

A Time Record is a Record used to represent a valid clock time, together with a number of overflow days such as might occur in BalanceTime. For any Time Record t, IsValidTime(t.[[Hour]], t.[[Minute]], t.[[Second]], t.[[Millisecond]], t.[[Microsecond]], t.[[Nanosecond]]) must return true.

Most uses of Time Records ignore the [[Days]] field. The [[Days]] field is only used to indicate an overflow number of days when performing arithmetic in BalanceTime and RoundTime.

Time Records have the fields listed in Table 73.

Table 73: Time Record Fields

Field Name	Value	Meaning
`[[Days]]`	an integer	A number of days resulting from an overflow when the Time Record is the result of an arithmetic operation.
`[[Hour]]`	an integer in the inclusive interval from 0 to 23	The number of the hour.
`[[Minute]]`	an integer in the inclusive interval from 0 to 59	The number of the minute.
`[[Second]]`	an integer in the inclusive interval from 0 to 59	The number of the second.
`[[Millisecond]]`	an integer in the inclusive interval from 0 to 999	The number of the millisecond.
`[[Microsecond]]`	an integer in the inclusive interval from 0 to 999	The number of the microsecond.
`[[Nanosecond]]`	an integer in the inclusive interval from 0 to 999	The number of the nanosecond.

22.3.15.1 AddTime ( `time`, `timeDuration` )

The abstract operation AddTime takes arguments time (a Time Record) and timeDuration (a time duration) and returns a Time Record. It performs the following steps when called:

Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], time.[[Microsecond]], time.[[Nanosecond]] + timeDuration).

22.3.15.2 BalanceTime ( `hour`, `minute`, `second`, `millisecond`, `microsecond`, `nanosecond` )

The abstract operation BalanceTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and returns a Time Record. It performs the following steps when called:

Set microsecond to microsecond + floor(nanosecond / 1000).
Set nanosecond to nanosecond modulo 1000.
Set millisecond to millisecond + floor(microsecond / 1000).
Set microsecond to microsecond modulo 1000.
Set second to second + floor(millisecond / 1000).
Set millisecond to millisecond modulo 1000.
Set minute to minute + floor(second / 60).
Set second to second modulo 60.
Set hour to hour + floor(minute / 60).
Set minute to minute modulo 60.
Let deltaDays be floor(hour / 24).
Set hour to hour modulo 24.
Return ! CreateTimeRecord(hour, minute, second, millisecond, microsecond, nanosecond, deltaDays).

22.3.15.3 CompareTimeRecord ( `xTime`, `yTime` )

The abstract operation CompareTimeRecord takes arguments xTime (a Time Record) and yTime (a Time Record) and returns -1, 0, or 1. It compares the two given times, returning -1 if yTime comes later in the day than xTime, 1 if xTime comes later in the day than yTime, and 0 if they are the same. It performs the following steps when called:

If xTime.[[Hour]] > yTime.[[Hour]], return 1.
If xTime.[[Hour]] < yTime.[[Hour]], return -1.
If xTime.[[Minute]] > yTime.[[Minute]], return 1.
If xTime.[[Minute]] < yTime.[[Minute]], return -1.
If xTime.[[Second]] > yTime.[[Second]], return 1.
If xTime.[[Second]] < yTime.[[Second]], return -1.
If xTime.[[Millisecond]] > yTime.[[Millisecond]], return 1.
If xTime.[[Millisecond]] < yTime.[[Millisecond]], return -1.
If xTime.[[Microsecond]] > yTime.[[Microsecond]], return 1.
If xTime.[[Microsecond]] < yTime.[[Microsecond]], return -1.
If xTime.[[Nanosecond]] > yTime.[[Nanosecond]], return 1.
If xTime.[[Nanosecond]] < yTime.[[Nanosecond]], return -1.
Return 0.

22.3.15.4 CreateTimeRecord ( `hour`, `minute`, `second`, `millisecond`, `microsecond`, `nanosecond` [ , `deltaDays` ] )

The abstract operation CreateTimeRecord takes arguments hour (an integer in the inclusive interval from 0 to 23), minute (an integer in the inclusive interval from 0 to 59), second (an integer in the inclusive interval from 0 to 59), millisecond (an integer in the inclusive interval from 0 to 999), microsecond (an integer in the inclusive interval from 0 to 999), and nanosecond (an integer in the inclusive interval from 0 to 999) and optional argument deltaDays (an integer) and returns either a normal completion containing a Time Record or a throw completion. The deltaDays parameter indicates an overflow number of days when the Time Record represents the result of an arithmetic operation. In all other cases it is 0. It performs the following steps when called:

If deltaDays is not present, set deltaDays to 0.
If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
Return the Time Record { [[Days]]: deltaDays, [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond }.

22.3.15.5 DifferenceTime ( `timeFrom`, `timeTo` )

The abstract operation DifferenceTime takes arguments timeFrom (a Time Record) and timeTo (a Time Record) and returns a time duration. It returns the elapsed duration from a first wall-clock time, until a second wall-clock time. It performs the following steps when called:

Let hours be timeTo.[[Hour]] - timeFrom.[[Hour]].
Let minutes be timeTo.[[Minute]] - timeFrom.[[Minute]].
Let seconds be timeTo.[[Second]] - timeFrom.[[Second]].
Let milliseconds be timeTo.[[Millisecond]] - timeFrom.[[Millisecond]].
Let microseconds be timeTo.[[Microsecond]] - timeFrom.[[Microsecond]].
Let nanoseconds be timeTo.[[Nanosecond]] - timeFrom.[[Nanosecond]].
Let timeDuration be ! TimeDurationFromComponents(hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
Assert: timeDuration is in the interval from -NanosecondsPerDay (exclusive) to NanosecondsPerDay (exclusive).
Return timeDuration.

22.3.15.6 IsValidTime ( `hour`, `minute`, `second`, `millisecond`, `microsecond`, `nanosecond` )

The abstract operation IsValidTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and returns a Boolean. It returns true if its arguments form a valid time of day, and false otherwise. Leap seconds are not taken into account. It performs the following steps when called:

If hour is not in the inclusive interval from 0 to 23, return false.
If minute is not in the inclusive interval from 0 to 59, return false.
If second is not in the inclusive interval from 0 to 59, return false.
If millisecond is not in the inclusive interval from 0 to 999, return false.
If microsecond is not in the inclusive interval from 0 to 999, return false.
If nanosecond is not in the inclusive interval from 0 to 999, return false.
Return true.

22.3.15.7 MidnightTimeRecord ( )

The abstract operation MidnightTimeRecord takes no arguments and returns a Time Record. The returned Record denotes the wall-clock time of midnight. It performs the following steps when called:

Return the Time Record { [[Days]]: 0, [[Hour]]: 0, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0 }.

22.3.15.8 NoonTimeRecord ( )

The abstract operation NoonTimeRecord takes no arguments and returns a Time Record. The returned Record denotes the wall-clock time of noon. It performs the following steps when called:

Return the Time Record { [[Days]]: 0, [[Hour]]: 12, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0 }.

22.3.15.9 RegulateTime ( `hour`, `minute`, `second`, `millisecond`, `microsecond`, `nanosecond`, `overflow` )

The abstract operation RegulateTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), and overflow ("constrain" or "reject") and returns either a normal completion containing a Time Record or a throw completion. It applies the correction given by overflow to the given time. If overflow is "constrain", out-of-range values are clamped. If overflow is "reject", a RangeError is thrown if any values are out of range. It performs the following steps when called:

If overflow is "constrain", then
1. Set hour to the result of clamping hour between 0 and 23.
2. Set minute to the result of clamping minute between 0 and 59.
3. Set second to the result of clamping second between 0 and 59.
4. Set millisecond to the result of clamping millisecond between 0 and 999.
5. Set microsecond to the result of clamping microsecond between 0 and 999.
6. Set nanosecond to the result of clamping nanosecond between 0 and 999.
7. Return ! CreateTimeRecord(hour, minute, second, millisecond, microsecond,nanosecond).
Assert: overflow is "reject".
Return ? CreateTimeRecord(hour, minute, second, millisecond, microsecond,nanosecond).

22.3.15.10 RoundTime ( `time`, `increment`, `unit`, `roundingMode` )

The abstract operation RoundTime takes arguments time (a Time Record), increment (a positive integer), unit (either a time unit or "day"), and roundingMode (a rounding mode) and returns a Time Record. It rounds a time to the given increment. It performs the following steps when called:

Let quantity be 0.
If unit is either "day" or "hour", then
1. Set quantity to time.[[Hour]] × NanosecondsPerHour.
If unit is one of "day", "hour", or "minute", then
1. Set quantity to quantity + time.[[Minute]] × NanosecondsPerMinute.
If unit is one of "day", "hour", "minute", or "second", then
1. Set quantity to quantity + time.[[Second]] × NanosecondsPerSecond.
If unit is one of "day", "hour", "minute", "second", or "millisecond", then
1. Set quantity to quantity + time.[[Millisecond]] × NanosecondsPerMillisecond.
If unit is one of "day", "hour", "minute", "second", "millisecond", or "microsecond", then
1. Set quantity to quantity + time.[[Microsecond]] × NanosecondsPerMicrosecond.
Set quantity to quantity + time.[[Nanosecond]].
Let unitLength be TemporalUnitLength(unit).
Let result be RoundNumberToIncrement(quantity, increment × unitLength, roundingMode) / unitLength.
If unit is "day", return ! CreateTimeRecord(0, 0, 0, 0, 0, 0, result).
If unit is "hour", return BalanceTime(result, 0, 0, 0, 0, 0).
If unit is "minute", return BalanceTime(time.[[Hour]], result, 0, 0, 0, 0).
If unit is "second", return BalanceTime(time.[[Hour]], time.[[Minute]], result, 0, 0, 0).
If unit is "millisecond", return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], result, 0, 0).
If unit is "microsecond", return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], result, 0).
Assert: unit is "nanosecond".
Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], time.[[Microsecond]], result).

22.3.15.11 TimeRecordToString ( `time`, `precision` )

The abstract operation TimeRecordToString takes arguments time (a Time Record) and precision (either an integer in the inclusive interval from 0 to 9, minute, or auto) and returns a String. It formats the given time as an ISO 8601 string, to the precision specified by precision. It performs the following steps when called:

Let subSecondNanoseconds be time.[[Millisecond]] × NanosecondsPerMillisecond + time.[[Microsecond]] × NanosecondsPerMicrosecond + time.[[Nanosecond]].
Return FormatTimeString(time.[[Hour]], time.[[Minute]], time.[[Second]], subSecondNanoseconds, precision).

22.3.15.12 Partial Time Records

A partial Time Record is a Record used to represent input used for constructing a Temporal.PlainTime object (such as input passed to Temporal.PlainTime.prototype.with, 22.12.3.11), in which it is not required that all the fields be present or in the correct interval.

Partial Time Records have the fields listed in Table 74. Additionally, partial Time Records must have at least one field that is not empty.

Table 74: Partial Time Record Fields

Field Name	Value	Meaning
`[[Hour]]`	an integer or empty	The number of the hour, if present.
`[[Minute]]`	an integer or empty	The number of the minute, if present.
`[[Second]]`	an integer or empty	The number of the second, if present.
`[[Millisecond]]`	an integer or empty	The number of the millisecond, if present.
`[[Microsecond]]`	an integer or empty	The number of the microsecond, if present.
`[[Nanosecond]]`	an integer or empty	The number of the nanosecond, if present.

22.3.15.13 ToPartialTimeRecord ( `temporalTimeLike`, `completeness` )

The abstract operation ToPartialTimeRecord takes arguments temporalTimeLike (an Object) and completeness (partial or complete) and returns either a normal completion containing a partial Time Record or a throw completion. It performs the following steps when called:

If completeness is complete, then
1. Let result be the partial Time Record { [[Hour]]: 0, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0 }.
Else,
1. Let result be the partial Time Record { [[Hour]]: empty, [[Minute]]: empty, [[Second]]: empty, [[Millisecond]]: empty, [[Microsecond]]: empty, [[Nanosecond]]: empty }.
Let anyPresent be false.
Let hour be ? Get(temporalTimeLike, "hour").
If hour is not undefined, then
1. Set result.[[Hour]] to ? SnapToInteger(hour, truncate).
2. Set anyPresent to true.
Let microsecond be ? Get(temporalTimeLike, "microsecond").
If microsecond is not undefined, then
1. Set result.[[Microsecond]] to ? SnapToInteger(microsecond, truncate).
2. Set anyPresent to true.
Let millisecond be ? Get(temporalTimeLike, "millisecond").
If millisecond is not undefined, then
1. Set result.[[Millisecond]] to ? SnapToInteger(millisecond, truncate).
2. Set anyPresent to true.
Let minute be ? Get(temporalTimeLike, "minute").
If minute is not undefined, then
1. Set result.[[Minute]] to ? SnapToInteger(minute, truncate).
2. Set anyPresent to true.
Let nanosecond be ? Get(temporalTimeLike, "nanosecond").
If nanosecond is not undefined, then
1. Set result.[[Nanosecond]] to ? SnapToInteger(nanosecond, truncate).
2. Set anyPresent to true.
Let second be ? Get(temporalTimeLike, "second").
If second is not undefined, then
1. Set result.[[Second]] to ? SnapToInteger(second, truncate).
2. Set anyPresent to true.
If anyPresent is false, throw a TypeError exception.
Return result.

22.3.15.14 ToTimeRecordOrMidnight ( `item` )

The abstract operation ToTimeRecordOrMidnight takes argument item (an ECMAScript language value) and returns either a normal completion containing a Time Record or a throw completion. Converts item to a Time Record if possible, considering undefined to be the same as midnight, and throws otherwise. It performs the following steps when called:

If item is undefined, return MidnightTimeRecord().
Let plainTime be ? ToTemporalTime(item).
Return plainTime.[[Time]].

22.3.16 Units

Time is reckoned using multiple units. A Temporal unit is one of "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", or "nanosecond". A calendar unit is one of "year", "month", or "week". A date unit is either a calendar unit or "day", and a time unit is one of "hour", "minute", "second", "millisecond", "microsecond", or "nanosecond".

22.3.16.1 DefaultTemporalLargestUnit ( `duration` )

The abstract operation DefaultTemporalLargestUnit takes argument duration (a Temporal.Duration) and returns a Temporal unit. It implements the logic used in the Temporal.Duration.prototype.round method (22.15.3.20) and elsewhere, where the largestUnit option, if not given explicitly, is set to the largest-magnitude non-zero unit, or "nanosecond" for a zero-length duration. It performs the following steps when called:

If duration.[[Years]] ≠ 0, return "year".
If duration.[[Months]] ≠ 0, return "month".
If duration.[[Weeks]] ≠ 0, return "week".
If duration.[[Days]] ≠ 0, return "day".
If duration.[[Hours]] ≠ 0, return "hour".
If duration.[[Minutes]] ≠ 0, return "minute".
If duration.[[Seconds]] ≠ 0, return "second".
If duration.[[Milliseconds]] ≠ 0, return "millisecond".
If duration.[[Microseconds]] ≠ 0, return "microsecond".
Return "nanosecond".

22.3.16.2 LargerOfTwoTemporalUnits ( `xUnit`, `yUnit` )

The abstract operation LargerOfTwoTemporalUnits takes arguments xUnit (a Temporal unit) and yUnit (a Temporal unit) and returns a Temporal unit. Given two Temporal units, it returns the larger of the two units. It performs the following steps when called:

If xUnit is "year" or yUnit is "year", return "year".
If xUnit is "month" or yUnit is "month", return "month".
If xUnit is "week" or yUnit is "week", return "week".
If xUnit is "day" or yUnit is "day", return "day".
If xUnit is "hour" or yUnit is "hour", return "hour".
If xUnit is "minute" or yUnit is "minute", return "minute".
If xUnit is "second" or yUnit is "second", return "second".
If xUnit is "millisecond" or yUnit is "millisecond", return "millisecond".
If xUnit is "microsecond" or yUnit is "microsecond", return "microsecond".
Return "nanosecond".

22.3.16.3 TemporalUnitLength ( `unit` )

The abstract operation TemporalUnitLength takes argument unit (a time unit or "day") and returns a positive integer. It returns the length of unit in nanoseconds. It performs the following steps when called:

If unit is "day", return NanosecondsPerDay.
If unit is "hour", return NanosecondsPerHour.
If unit is "minute", return NanosecondsPerMinute.
If unit is "second", return NanosecondsPerSecond.
If unit is "millisecond", return NanosecondsPerMillisecond.
If unit is "microsecond", return NanosecondsPerMicrosecond.
Assert: unit is "nanosecond".
Return 1.

Note

The length of the "day" unit is considered to be NanosecondsPerDay. Note that changes in the UTC offset of a time zone may result in longer or shorter days, so care should be taken when using this value in the context of Temporal.ZonedDateTime arithmetic.

22.3.16.4 ValidateTemporalUnitValue ( `value`, `unitGroup` [ , `extraValues` ] )

The abstract operation ValidateTemporalUnitValue takes arguments value (either a Temporal unit, no-unit, or "auto") and unitGroup (date, time, or datetime) and optional argument extraValues (a List of either Temporal units or "auto") and returns either a normal completion containing unused or a throw completion. It validates that the result of GetTemporalUnitValuedOption is covered by the union of unitGroup, extraValues, and « no-unit ». It performs the following steps when called:

If value is no-unit, return unused.
If extraValues is present and extraValues contains value, return unused.
If value is a date unit and unitGroup is either date or datetime, return unused.
If value is a time unit and unitGroup is either time or datetime, return unused.
Throw a RangeError exception.

22.3.17 IsPartialTemporalObject ( `value` )

The abstract operation IsPartialTemporalObject takes argument value (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It determines whether value is a suitable input for one of the plain or zoned Temporal types' with() methods (22.11.3.23, 22.10.3.25, 22.14.3.6, 22.12.3.11, 22.13.3.13, 22.9.3.31): it must be an Object, it must not be an instance of one of those Temporal types, and it must not have a calendar or timeZone property. It performs the following steps when called:

If value is not an Object, return false.
NOTE: The following step accepts Temporal.Duration and Temporal.Instant, but rejects all other Temporal types.
If value has an [[InitializedTemporalDate]], [[InitializedTemporalDateTime]], [[InitializedTemporalMonthDay]], [[InitializedTemporalTime]], [[InitializedTemporalYearMonth]], or [[InitializedTemporalZonedDateTime]] internal slot, return false.
Let calendarProperty be ? Get(value, "calendar").
If calendarProperty is not undefined, return false.
Let timeZoneProperty be ? Get(value, "timeZone").
If timeZoneProperty is not undefined, return false.
Return true.

22.4 Parsing ISO 8601 / RFC 9557 Strings

Several operations in this section are intended to parse strings representing a date, a time, a duration, or a combined date and time. For the purposes of these operations, a valid ISO 8601 / RFC 9557 string is defined as a String that can be generated by one of the goal elements of the following grammar.

22.4.1 ISO 8601 / RFC 9557 Grammar

This grammar is adapted from the ABNF grammar of the ISO 8601 date-time format that is given in appendix A of RFC 3339, augmented with the grammar of annotations in section 4.1 of RFC 9557.

RFC 9557 and ISO 8601 are similar, but ISO 8601 defines a number of optional deviations that are allowed “by agreement between the communicating parties”. The following is a list of deviations supported by this grammar:

Only the calendar date format is supported, not the weekdate or ordinal date format.
Two-digit years are disallowed.
Expanded years of 6 digits are allowed.
Fractional parts may have 1 through 9 decimal places.
In time representations, only seconds are allowed to have a fractional part.
In duration representations, only hours, minutes, and seconds are allowed to have a fractional part.
A space may be used to separate the date and time in a combined date / time representation, but not in a duration (e.g., "1970-01-01 00:00Z" is valid but "P1D 1H" is not).
Alphabetic designators may be in lower or upper case (e.g., "1970-01-01t00:00Z" and "1970-01-01T00:00z" and "pT1m" are valid).
Period or comma may be used as the decimal separator (e.g., "PT1,00H" is a valid representation of a 1-hour duration).
UTC offsets of "-00:00" and "-0000" and "-00" are allowed, and all mean the same thing as "+00:00".
UTC offsets may have seconds and up to 9 sub-second fractional digits (e.g., "1970-01-01T00:00:00+00:00:00.123456789" is valid).
The constituent date, time, and UTC offset parts of a combined representation may each independently use basic format (with no separator symbols) or extended format (with mandatory - or : separators), as long as each such part is itself in either basic format or extended format (e.g., "1970-01-01T012345" and "19700101T01:23:45" are valid but "1970-0101T012345" and "1970-01-01T0123:45" are not).
When parsing a date representation for a Temporal.PlainMonthDay, the year may be omitted. The year may optionally be replaced by -- as in RFC 3339 Appendix A.
When parsing a date representation without a day for a Temporal.PlainYearMonth, the expression is allowed to be in basic format (with no separator symbols).
A duration specifier of "W" (weeks) can be combined with any of the other specifiers (e.g., "P1M1W1D" is valid).
Anything else described by ISO 8601 as requiring mutual agreement between communicating parties, is disallowed.

In addition to the above deviations, any number of conforming RFC 9557 suffixes in square brackets are allowed. However, the only recognized suffixes are time zone and BCP 47 calendar. Others are ignored, unless they are prefixed with !, in which case they are rejected. Note that the suffix keys, although they look similar, are not the same as keys in RFC 6067. In particular, keys are lowercase-only.

Alpha

:::

one of

LowercaseAlpha

:::

one of

DateSeparator

[Extended]

:::

[+Extended]

[~Extended]

[empty]

DaysDesignator

:::

one of

HoursDesignator

:::

one of

MinutesDesignator

:::

one of

MonthsDesignator

:::

one of

DurationDesignator

:::

one of

SecondsDesignator

:::

one of

DateTimeSeparator

:::

<SP>

TimeDesignator

:::

one of

WeeksDesignator

:::

one of

YearsDesignator

:::

one of

UTCDesignator

:::

one of

AnnotationCriticalFlag

:::

:::

Note the prohibition on negative zero in 22.4.1.3.

:::

:::

:::

[+Extended]

[~Extended]

:::

opt

[+Extended]

opt

[~Extended]

Note the prohibition on invalid combinations of month and day in 22.4.1.3.

[Extended]

:::

[?Extended]

[?Extended]

Note the prohibition on invalid combinations of month and day in 22.4.1.3.

:::

[+Extended]

[~Extended]

:::

[SubMinutePrecision]

:::

[?SubMinutePrecision, +Extended]

ASCIISign

Hour

HourSubcomponents

[?SubMinutePrecision, ~Extended]

ASCIISign

:::

one of

Hour

:::

HourSubcomponents

[SubMinutePrecision, Extended]

:::

TimeSeparator

[?Extended]

Minute

[+SubMinutePrecision]

[?Extended]

[?Extended]

opt

TimeSeparator

[Extended]

:::

[+Extended]

[~Extended]

[empty]

:::

:::

:::

:::

one of

DateTimeUTCOffset

[Z]

:::

[+Z]

UTCDesignator

UTCOffset

[+SubMinutePrecision]

:::

:::

:::

TZLeadingChar

TZChar

TimeZoneIANAName

:::

TimeZoneIANAName

TimeZoneIdentifier

:::

UTCOffset

[~SubMinutePrecision]

:::

[+Extended]

but not -00:00

:::

[

AnnotationCriticalFlag

opt

]

:::

:::

:::

:::

Alpha

opt

opt

AnnotationValue

:::

AnnotationValue

Annotation

:::

[

AnnotationCriticalFlag

opt

]

:::

opt

[Extended]

:::

[?Extended]

[?Extended]

[?Extended]

opt

:::

[+Extended]

[~Extended]

[Z, TimeRequired]

:::

[~TimeRequired]

[?Z]

opt

:::

[~Z]

opt

opt

opt

[~Z]

opt

TimeZoneAnnotation

opt

Annotations

opt

Note the disambiguation between the second alternative without TimeDesignator, and DateSpecMonthDay/DateSpecYearMonth in 22.4.1.3.

AnnotatedDateTime

[Zoned, TimeRequired]

:::

[~Zoned]

DateTime

[~Z, ?TimeRequired]

TimeZoneAnnotation

opt

Annotations

opt

[+Zoned]

[+Z, ?TimeRequired]

opt

:::

[~Sep]

opt

SecondsDesignator

DurationMinutesPart

:::

DecimalDigits

[~Sep]

[~Sep]

opt

:::

[~Sep]

[~Sep]

[~Sep]

opt

:::

:::

[~Sep]

:::

[~Sep]

opt

:::

[~Sep]

[~Sep]

opt

:::

[~Sep]

[~Sep]

[~Sep]

opt

:::

opt

opt

opt

opt

TemporalInstantString

:::

[+Z]

opt

opt

TemporalDateTimeString

[Zoned]

:::

AnnotatedDateTime

[?Zoned, ~TimeRequired]

TemporalDurationString

:::

opt

opt

TemporalMonthDayString

:::

opt

opt

[~Zoned, ~TimeRequired]

TemporalTimeString

:::

AnnotatedTime

AnnotatedDateTime

[~Zoned, +TimeRequired]

TemporalYearMonthString

:::

opt

opt

[~Zoned, ~TimeRequired]

Grammar symbols not explicitly defined above (NonZeroDigit, DecimalDigit, DecimalDigits) have the definitions used in the Lexical Grammar for numeric literals (12.9.3).

22.4.1.1 Static Semantics: IsValidMonthDay

The syntax-directed operation IsValidMonthDay takes no arguments and returns a Boolean. It is defined piecewise over the following productions:

[Extended]

:::

[?Extended]

[?Extended]

:::

opt

[+Extended]

opt

[~Extended]

If DateDay is "31" and DateMonth is "02", "04", "06", "09", "11", return false.
If DateMonth is "02" and DateDay is "30", return false.
Return true.

22.4.1.2 Static Semantics: IsValidDate

The syntax-directed operation IsValidDate takes no arguments and returns a Boolean. It is defined piecewise over the following productions:

[Extended]

:::

[?Extended]

[?Extended]

If IsValidMonthDay of DateSpec is false, return false.
Let year be ℝ(StringToNumber(CodePointsToString(DateYear))).
If DateMonth is "02" and DateDay is "29" and InLeapYear(TimeFromYear(year)) = 0, return false.
Return true.

22.4.1.3 Static Semantics: Early Errors

AnnotatedTime

:::

Time

DateTimeUTCOffset

[~Z]

opt

TimeZoneAnnotation

opt

Annotations

opt

It is a Syntax Error if ParseText(Time DateTimeUTCOffset[~Z], DateSpecMonthDay) is a Parse Node.
It is a Syntax Error if ParseText(Time DateTimeUTCOffset[~Z], DateSpecYearMonth) is a Parse Node.

[Extended]

:::

[?Extended]

[?Extended]

It is a Syntax Error if IsValidDate of DateSpec is false.

DateSpecMonthDay

:::

opt

[+Extended]

opt

[~Extended]

It is a Syntax Error if IsValidMonthDay of DateSpecMonthDay is false.

DateYear

:::

ASCIISign