intervalDifferenceUtc

Signature

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

Return the portion(s) of interval A not covered by interval B.

• Half-open: an interval holds every t with start <= t < end. A returned piece ends exactly where B starts, or starts exactly where B ends, because B’s end is not in B (CORE-6’s subtractIntervals). No piece is stepped by one unit.
• B touching A (bStart === aEnd or bEnd === aStart), or empty, removes nothing.
• An empty A (aStart === aEnd) has nothing left: returns []. Every returned piece is non-empty.
• Delegates to CORE-6’s subtractIntervals once the arguments pass the UTC-string gate, and re-serialises the pieces to canonical Z strings.
• Returns [] when B fully covers A, which includes B equal to A.
• Returns [{ start, end }] when B overlaps exactly one edge of A, leaving one piece.
• 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.
• Returns [] if either interval is invalid (start > end).
• Returns [] on invalid input (wrong type, non-Z strings, malformed strings, leap seconds).

Parameters

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

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 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 is always later than start.

Examples

import { intervalDifferenceUtc } from "@northguild/gmt/utc/interval";

intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]

aStartaEndbStartbEnd

output

 

Source

utc/interval/intervalDifferenceUtc.ts