intervalUnionUtc

Signature

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

Return the combined span of two UTC intervals, or null when they are disjoint.

• Half-open: an interval holds every t with start <= t < end. The union is returned only when it is one non-empty interval — the single run CORE-6’s mergeIntervals would give.
• Overlapping intervals, and touching intervals (aEnd === bStart), return their combined span.
• Two non-empty intervals with any gap between them return null, even a one-unit gap. The caveat matters: an empty interval is the empty set, so it is never “separated” from anything. A non-empty interval unioned with an empty one far away is still that non-empty interval — see the next bullet — not null.
• An empty interval (start === end) is the empty set: it adds nothing, so the union is the other interval. Two empty intervals have no non-empty union and return null.
• Delegates to CORE-6’s mergeIntervals once the arguments pass the UTC-string gate, and re-serialises the run to canonical Z strings.
• Returns null if either interval is invalid (start > end).
• Returns null 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

{ start, end } with the merged span, or null on invalid input / disjoint intervals

Members

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 { intervalUnionUtc } from "@northguild/gmt/utc/interval";

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

aStartaEndbStartbEnd

output

 

Source

utc/interval/intervalUnionUtc.ts