intervalSplitAtZoned

Signature

intervalSplitAtZoned(start: string, end: string, points: string[]): { start: string; end: string; }[]

Split a zoned interval at arbitrary points, producing consecutive sub-intervals.

• points need not be sorted — they are sorted internally (by instant) before splitting.
• Comparison and boundary placement use the instant each point represents, so points may carry a different time zone than start/end.
• Points before start or after end are dropped; they cannot introduce a boundary that isn’t inside the interval.
• Points on the same instant as start or end are dropped too — they would only produce a zero-length sub-interval at the edge.
• Duplicate points (same instant) collapse to a single boundary.
• Returns consecutive half-open [start, end) records, the same tiling as splitIntervalAt: each record’s end is the next record’s start and belongs only to that next record, so the pieces share no instant and together cover [start, end) exactly once.
• Returns [{ start, end }] (the whole interval, unsplit) when no valid in-range point remains.
• A piece’s end equals its start only when the interval itself is zero-length (start equal to end): the result is then that one empty piece, whatever the points.
• Returns [] when points is not an array, when any element is not a valid ISO ZonedDateTime string, or on invalid input (unparseable start/end, start > end, leap-second strings).
• Accepts RFC 9557 calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched set: start, end and every element of points must name the same calendar system (E7’s D4-zoned), since the returned sub-intervals are values the caller reads back as datetimes and an array of differently-tagged records would be unreadable as a set. A mismatch returns [].
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).

Parameters

Parameter	Type	Description
start	string	ISO 8601 zoned datetime string for the interval start
end	string	ISO 8601 zoned datetime string for the interval end
points	string[]	array of ISO 8601 zoned datetime strings to split at

Returns

array of { start, end } records, 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 can equal start, which makes the interval empty.

Examples

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

intervalSplitAtZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-10T00:00:00+00:00[UTC]", ["2024-01-05T00:00:00+00:00[UTC]"]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-05T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }]

startend

points

×

+ add

output

 

Source

zoned/interval/intervalSplitAtZoned.ts