@burglekitt/gmt/dist/utc/interval/intervalCountUtc.d.ts

Temporal-based date and time utilities with timezone support and polyfill integration

/**
 * Count how many `unit` boundaries a UTC interval crosses.
 *
 * - Counts calendar boundaries touched by the half-open interval `[start, end)` — distinct
 *   from `diffUtc`, which measures exact elapsed duration. An interval from 23:59 to 00:01 is
 *   two minutes long but touches 2 day boundaries.
 * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
 * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
 *   unit boundary.
 * - Boundaries are UTC boundaries — no DST is involved.
 * - Weeks start on Monday (ISO 8601).
 * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
 * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
 *   leap-second strings).
 *
 * @param start ISO UTC datetime string for the interval start
 * @param end ISO UTC datetime string for the interval end
 * @param unit unit string — any `DateTimeUnit`
 * @returns number of unit boundaries touched, or null on invalid input
 *
 * @example intervalCountUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 2
 * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-03T00:00:00Z", "day") // 2
 * @example intervalCountUtc("2024-01-15T00:00:00Z", "2024-03-10T00:00:00Z", "month") // 3
 * @example intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 1 (zero-length, mid-day)
 * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0 (zero-length, on the boundary)
 * @example intervalCountUtc("invalid", "2024-01-02T00:00:00Z", "day") // null
 */
export declare function intervalCountUtc(start: string, end: string, unit: string): number | null;