intervalLengthTime

Signature

intervalLengthTime(start: string, end: string, unit: string): number

import { intervalLengthTime } from "@northguild/gmt/plain/interval";

Return the exact length of a time interval in unit, as a real (possibly fractional) number.

• Distinct from intervalCountTime, which counts clock unit boundaries crossed rather than measuring exact duration — an interval from 12:59 to 13:01 touches 2 hour boundaries via intervalCountTime but has an exact length of ~0.033 hours via intervalLengthTime.
• Time units are fixed-length, so no relativeTo is needed for the total.
• Returns 0 for a zero-length interval (start === end).
• Returns null on invalid input (unparseable start/end, start > end, unsupported unit, or a unit that has no effect on PlainTime, e.g. "days").

Parameters

Parameter	Type	Description
start	string	ISO PlainTime string for the interval start
end	string	ISO PlainTime string for the interval end
unit	string	unit string — "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" (calendar units return null)

Returns

exact length of the interval expressed in unit, or null on invalid input

Examples

intervalLengthTime("12:00:00", "14:30:00", "hour") // 2.5
intervalLengthTime("12:59:00", "13:01:00", "hour") // 0.03333333333333333
intervalLengthTime("12:00:00", "12:00:00", "hour") // 0
intervalLengthTime("12:00:00", "14:00:00", "day") // null
intervalLengthTime("invalid", "14:00:00", "hour") // null

Source

plain/interval/intervalLengthTime.ts