@burglekitt/gmt/dist/plain/interval/intervalCountTime.d.ts

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

/**
 * Count how many `unit` boundaries a time interval crosses.
 *
 * - Counts clock boundaries touched by the half-open interval `[start, end)` — distinct from
 *   `diffTime`, which measures exact elapsed duration. An interval from 12:59 to 13:01 is two
 *   minutes long but touches 2 hour boundaries.
 * - The end boundary is excluded: `"12:00:00"` to `"14:00:00"` counts 2 hours.
 * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
 *   unit boundary.
 * - Accepts singular or plural units (`"hour"` and `"hours"` behave identically).
 * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
 *   or a unit that has no effect on `PlainTime`, e.g. `"days"`).
 *
 * @param start ISO PlainTime string for the interval start
 * @param end ISO PlainTime string for the interval end
 * @param unit unit string — `"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"` (calendar units return null)
 * @returns number of unit boundaries touched, or null on invalid input
 *
 * @example intervalCountTime("12:00:00", "14:00:00", "hour") // 2
 * @example intervalCountTime("12:30:00", "13:00:00", "hour") // 1
 * @example intervalCountTime("12:30:00", "12:30:00", "hour") // 1 (zero-length, mid-hour)
 * @example intervalCountTime("12:00:00", "12:00:00", "hour") // 0 (zero-length, on the boundary)
 * @example intervalCountTime("12:00:00", "14:00:00", "day") // null
 * @example intervalCountTime("invalid", "14:00:00", "hour") // null
 */
export declare function intervalCountTime(start: string, end: string, unit: string): number | null;