intervalDifferenceZoned
Signature
Section titled “Signature”intervalDifferenceZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; }[]Return the portion(s) of the half-open interval A [aStart, aEnd) not covered by the half-open interval B [bStart, bEnd).
- Compares instants, with the same rule as
subtractIntervals. - Every cut lands exactly on B’s own
startorend: the piece before B ends atbStart, which it excludes, and the piece after B starts atbEnd, which B excludes. No boundary is stepped by a nanosecond. A boundary A supplies keeps A’s time zone; a cut keeps B’s. - Returns
[]when B fully covers A (this includes B being identical to A), and when A is empty (aStartandaEndthe same instant). - Returns
[{ start, end }]when B overlaps exactly one edge of A. - Returns
[{ start, end }, { start, end }]when B is fully inside A with gaps on both sides. - Returns A unchanged when B lies entirely before or after it, touches it, or is empty.
- Returns
[]if either interval is invalid (start > end). - Returns
[]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
Section titled “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
Section titled “Returns”array of { start, end } records representing A minus B, or [] on invalid input
Members of each item
| 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 is always later than start. |
Examples
Section titled “Examples”import { intervalDifferenceZoned } from "@northguild/gmt/zoned/interval";
intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-06-01T12:00:00+00:00[UTC]" }, { start: "2024-07-01T13:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]