intervalIntersectionZoned

Signature

intervalIntersectionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; } | null

Return the overlapping span of two half-open zoned intervals [start, end), or null when they do not overlap.

• Uses Temporal.ZonedDateTime.compare for comparison (same instant semantics).
• The result is [max(aStart, bStart), min(aEnd, bEnd)), and it exists only when intervalsOverlapZoned is true — the same rule as intersectIntervals. On a tie the first interval’s boundary wins, so its time zone is the one kept.
• Touching intervals (e.g. aEnd the same instant as bStart) share no instant, because each end is excluded, and return null.
• An empty interval (start and end the same instant) strictly inside the other returns itself; at either edge, or against another empty interval, it returns null.
• Returns null if either interval is invalid (start > end).
• Returns null on invalid input (wrong type, malformed strings, leap seconds).
• Accepts RFC 9557 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).
• Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.

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

{ start, end } with the overlapping span, or null on invalid input / no overlap

Members

Member	Type	Description
start	string	The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time zone. It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
end	string	The first instant after the interval, in the same format as start. It is exclusive: the interval holds everything from start up to but not including this value. It can equal start, which makes the interval empty.

Examples

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

intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-04-01T00:00:00+00:00[UTC]", end: "2024-06-30T23:59:59+00:00[UTC]" }

aStartaEndbStartbEnd

output

 

Interval algebra visualizer

1. Place two intervals

A

B

Intersection

Union

Difference (A − B)

Symmetric difference (XOR)

Jan 2024JulDec

A startA end

B startB end

2. Compare the four operations

Intersection

 

Union

 

Difference (A − B)

 

Symmetric difference (XOR)

 

Source

zoned/interval/intervalIntersectionZoned.ts