intervalDivideEquallyUtc

Signature

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

Split a UTC 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 epoch nanoseconds, so the split is exact whenever the span divides evenly by n and within half a nanosecond of the exact cut otherwise, at any span length (no double arithmetic) — no DST is involved, since UTC has no time zone offset.
• 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, leap-second strings).
• Returns [] before building any piece when n exceeds the longest possible array (2^32 - 1).

Parameters

Parameter	Type	Description
start	string	ISO UTC datetime string for the interval start
end	string	ISO UTC datetime string for the interval end
n	number	number of equal sub-intervals to produce (positive integer)

Options

options

A 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 instant the interval begins at, as an ISO 8601 UTC string ending in Z.
end	string	The first instant 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 { intervalDivideEquallyUtc } from "@northguild/gmt/utc/interval";

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

startendn

output

 

Source

utc/interval/intervalDivideEquallyUtc.ts