intervalDifferenceDate

Signature

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

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

• Uses Temporal.PlainDate.compare for comparison.
• Half-open: an interval holds every date d with start <= d < 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 day.
• 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.
• end is the first day after the period: for a period whose last day is last, pass addDate(last, { days: 1 }).
• 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, 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 A minus B, 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 { intervalDifferenceDate } from "@northguild/gmt/plain/interval";

intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-06-01" }, { start: "2024-07-01", end: "2024-12-31" }]

aStartaEndbStartbEnd

output

 

Source

plain/interval/intervalDifferenceDate.ts