intervalDivideEquallyDate

Signature

intervalDivideEquallyDate(start: string, end: string, n: number, options?: { maxPieces?: number; }): { start: string; end: string; }[]

Split a date interval into n equal-length sub-intervals.

• Returns an array of n { start, end } records that tile the original interval, each record’s end equal to the next record’s start.
• Every piece is half-open [start, end): a boundary belongs only to the piece that starts there, so the pieces share no value and together cover the interval exactly once (the rule CORE-6’s splitIntervalAt uses).
• PlainDate has no fractional-day representation, so each internal boundary is rounded to the nearest whole day (round(totalDays · i / n), computed exactly in bigint, an exact half rounding up) — when totalDays isn’t evenly divisible by n, the resulting sub-intervals differ by at most one day rather than being mathematically exact.
• When n is larger than the number of whole days in the interval, some pieces are empty (their start equals their end): the result always has exactly n pieces.
• n === 1 returns the original interval unchanged, as a single-element array.
• A zero-length interval (start === end) returns n identical zero-length sub-intervals.
• Returns [] when n is not a positive integer, or on invalid input (unparseable start/end, start > end).
• Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). start and end must carry the same calendar tag (or both be bare ISO); a mismatch returns [] (E5 decision of record D4). Internal boundaries are computed in whole days (calendar-independent), then re-formatted in the shared calendar.

Parameters

Parameter	Type	Description
start	string	ISO PlainDate string for the interval start, optionally calendar-annotated
end	string	ISO PlainDate string for the interval end, optionally calendar-annotated
n	number	number of equal sub-intervals to produce (positive integer)

Options

options

The limit on the size of the result

Option	Type	Default	Description
maxPieces?	number	1_000_000	The most records the result may hold. A result that would hold more, or more than the longest possible array (2^32 - 1 elements), returns [] and none is built. A value that is not a positive safe integer also returns [].

Returns

array of n { start, end } records, 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 can equal start, which makes the interval empty.

Examples

import { intervalDivideEquallyDate } from "@northguild/gmt/plain/interval";

intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4) // [{ start: "2024-01-01", end: "2024-01-02" }, { start: "2024-01-02", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-05" }]

startendn

output

 

Source

plain/interval/intervalDivideEquallyDate.ts