subtractIntervals

Signature

subtractIntervals(from: Interval, remove: Interval[]): Interval[]

Return the parts of from that no interval in remove covers, as sorted half-open intervals.

• A removal strictly inside from splits it in two; one covering an edge trims it; one covering all of it leaves [].
• Half-open: a removal that only touches from removes nothing, and pieces never include an instant any removal covers.
• remove may be unsorted and overlapping. Removing an empty interval changes nothing; subtracting from an empty from returns [].
• Endpoints are the caller’s own strings, and from’s spelling is kept wherever from and a removal name the same instant (GMT rule).
• [] is both a legitimate result (everything removed) and the invalid-input sentinel; check inputs with isValidInterval when the difference matters.
• The positional intervalDifferenceUtc (…) follow the same half-open rule for a single removal: pieces end exactly where the removal starts.
• For zone-aligned removals (non-working local days), build them with floorToZone first.
• Returns [] when from is not a valid Interval, remove is not an array, or any element of remove is not a valid Interval — even one outside from.

Parameters

Parameter	Type	Description
from	Interval	{ start, end } record of ISO 8601 instant strings to subtract from
remove	Interval[]	array of { start, end } records of ISO 8601 instant strings to remove

Returns

sorted, non-touching { start, end } records of what remains, or [] on invalid input

Related types

• Interval

Examples

import { subtractIntervals } from "@northguild/gmt/interval/calculate";

subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T12:00:00Z", end: "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" }]

from

remove

×

+ add

output

 

Source

interval/calculate/subtractIntervals.ts