intervalSplitAtUtc

Signature

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

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

• points need not be sorted — they are sorted internally before splitting.
• Points before start or after end are dropped; they cannot introduce a boundary that isn’t inside the interval.
• Points exactly on start or end are dropped too — they would only produce a zero-length sub-interval at the edge.
• Duplicate points collapse to a single boundary.
• Returns consecutive { start, end } records, each record’s end equal to the next record’s start.
• Every piece is half-open [start, end): a boundary belongs only to the piece that starts there, so the pieces share no value and together cover the interval exactly once (the rule CORE-6’s splitIntervalAt uses).
• 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 UTC datetime string, or on invalid input (unparseable start/end, start > end, leap-second strings).

Parameters

Parameter	Type	Description
start	string	ISO UTC datetime string for the interval start
end	string	ISO UTC datetime string for the interval end
points	string[]	array of ISO UTC 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 an ISO 8601 UTC string ending in Z.
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 { intervalSplitAtUtc } from "@northguild/gmt/utc/interval";

intervalSplitAtUtc("2024-01-01T00:00:00Z", "2024-01-10T00:00:00Z", ["2024-01-05T00:00:00Z"]) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-05T00:00:00Z" }, { start: "2024-01-05T00:00:00Z", end: "2024-01-10T00:00:00Z" }]

startend

points

×

+ add

output

 

Source

utc/interval/intervalSplitAtUtc.ts