intervalXorZoned

Signature

intervalXorZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; }[]

import { intervalXorZoned } from "@northguild/gmt/zoned/interval";

Return the symmetric difference of two zoned intervals — time covered by exactly one interval.

• Uses Temporal.Instant.compare for comparison (via .toInstant()).
• Returns [] when intervals are identical or both invalid.
• Returns [{ start, end }] when one interval fully contains the other.
• Returns [{ start, end }, { start, end }] when intervals partially overlap.
• Returns [] if either interval is invalid (start > end).
• Returns [] on invalid input (wrong type, malformed strings, leap seconds).
• Accepts GMT calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched pair: every endpoint must name the same calendar system (E7’s D4-zoned). Unlike the ordering functions, this one returns a value the caller reads back as a datetime, and there is no principled way to pick one endpoint’s calendar as the answer’s. Rejection also keeps a uniform policy across all eight value-returning zoned set operations, four of which return arrays — a per-element “winner’s tag” would produce a result set whose members disagree about which calendar they are in. (intervalUnionZoned’s existing “winning endpoint’s time zone wins” is not precedent: the zone is a property of the surviving point, the calendar is a property of the answer.) A mismatch returns the sentinel.
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).
• Still rejects Temporal’s own [timeZone][u-ca=...] RFC 9557 ordering — see regex/calendar-zoned-date-time.ts.

Parameters

Parameter	Type	Description
aStart	string	ISO 8601 zoned datetime string for the first interval start
aEnd	string	ISO 8601 zoned datetime string for the first interval end
bStart	string	ISO 8601 zoned datetime string for the second interval start
bEnd	string	ISO 8601 zoned datetime string for the second interval end

Returns

array of { start, end } records representing the symmetric difference, or [] on invalid input

Examples

intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-04-01T11:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-03-31T17:00:00+00:00[UTC]" }, { start: "2024-06-30T12:00:01+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
intervalXorZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []

Source

zoned/interval/intervalXorZoned.ts