intervalDivideEquallyDateTime

Signature

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

Split a datetime 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).
• Each boundary is start + round((end - start) · i / n) in integer nanoseconds, computed in bigint: the split is exact whenever the total divides evenly by n, and within half a nanosecond of the exact cut otherwise (an exact half rounds up), at any span length — the whole PlainDateTime range included.
• When n is larger than the number of nanoseconds 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).

Parameters

Parameter	Type	Description
start	string	ISO PlainDateTime string for the interval start
end	string	ISO PlainDateTime string for the interval end
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

Members of each item

Member	Type	Description
start	string	The date-time the interval begins at, as an ISO 8601 date-time string with no offset or time zone.
end	string	The first date-time 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 { intervalDivideEquallyDateTime } from "@northguild/gmt/plain/interval";

intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 3) // [{ start: "2024-01-01T00:00:00", end: "2024-01-02T00:00:00" }, { start: "2024-01-02T00:00:00", end: "2024-01-03T00:00:00" }, { start: "2024-01-03T00:00:00", end: "2024-01-04T00:00:00" }]

startendn

output

 

Source

plain/interval/intervalDivideEquallyDateTime.ts