intervalXorDate

Signature

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

Return the symmetric difference of two date intervals — time covered by exactly one interval.

• Half-open: an interval holds every t with start <= t < end. The result is every maximal run covered by exactly one of the two intervals, sorted by start — the same set as CORE-6’s mergeIntervals([...subtractIntervals(a, [b]), ...subtractIntervals(b, [a])]).
• Pieces end exactly where the other interval starts; no piece is stepped by one day.
• Touching intervals (aEnd === bStart) share nothing, so they return one combined run.
• Returns [] when the intervals are identical. An empty interval contributes nothing.
• Returns [] if either interval is invalid (start > end).
• Returns [] on invalid input (wrong type, malformed strings).
• Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is date values, all four arguments must carry the same calendar tag (or all be bare ISO); a mismatch returns [] (E5 decision of record D4). Each output piece’s tag is re-derived, never copied from an input.

Parameters

Parameter	Type	Description
aStart	string	ISO 8601 date string for the first interval start, optionally calendar-annotated
aEnd	string	ISO 8601 date string for the first interval end, optionally calendar-annotated
bStart	string	ISO 8601 date string for the second interval start, optionally calendar-annotated
bEnd	string	ISO 8601 date string for the second interval end, optionally calendar-annotated

Returns

array of { start, end } records representing the symmetric difference, or [] on invalid input / mismatched calendars

Members of each item

Member	Type	Description
start	string	The date the interval begins on, as an ISO 8601 date (YYYY-MM-DD). It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
end	string	The first date 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 { intervalXorDate } from "@northguild/gmt/plain/interval";

intervalXorDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-04-01" }, { start: "2024-06-30", end: "2024-12-31" }]

aStartaEndbStartbEnd

output

 

Source

plain/interval/intervalXorDate.ts