intervalDivideEquallyZoned

Signature

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

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

• Returns an array of n half-open [start, end) records that tile the original interval: each record’s end is the next record’s start and belongs only to that next record, so the pieces share no instant and together cover [start, end) exactly once.
• Each boundary is start + round((end - start) · i / n) in integer epoch nanoseconds (real elapsed time, exact at any span length), so a spring-forward day split in half lands exactly on the DST transition’s real midpoint rather than the local-clock midpoint.
• 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, each an empty [start, start) that holds no instant.
• start and end may name different time zones. The first start and every inner boundary are written in start’s zone; the last end is the end argument, in its own zone.
• Returns [] when n is not a positive integer, or on invalid input (unparseable start/end, start > end, leap-second strings).
• Accepts RFC 9557 calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched pair: start and end must name the same calendar system (E7’s D4-zoned), since the synthesized boundaries are values the caller reads back as datetimes and an array of differently-tagged records would be unreadable as a set. A mismatch returns [].
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).
• An n over options.maxPieces returns [] before any piece is built.

Parameters

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

Options

options

optional limit on the size of the output

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 a zoned ISO 8601 string with offset and bracketed time zone. It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
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 { intervalDivideEquallyZoned } from "@northguild/gmt/zoned/interval";

intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)

startendn

output

 

Source

zoned/interval/intervalDivideEquallyZoned.ts