diffTime

Signature

diffTime(time1: string, time2: string, units: "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | TimeUnit | ("hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | TimeUnit)[], options?: RoundingOptions<TimeUnit>): number | Record<"hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", number> | null

Return the difference between two PlainTime values in the requested unit.

• Returns null for invalid inputs.
• Uses Temporal.PlainTime.until with largestUnit and extracts the requested unit. smallestUnit, roundingIncrement, and roundingMode control optional rounding of the result, per Temporal’s DifferenceOptions — e.g. { smallestUnit: "minute", roundingMode: "halfExpand" } rounds the difference to the nearest minute before extracting the requested unit.
• When units is an array, smallestUnit must not be coarser than the largest unit in the array (e.g. ["minutes", "seconds"] with smallestUnit: "hour") — this combination is rejected by Temporal and returns null, same as other invalid input.
• With an array of units, the record is the whole difference: the largest listed unit is Temporal’s largestUnit, and the amount of each unlisted unit between two listed units is carried into the next smaller listed unit, measured from the start moved by the larger listed amounts (so adding the record to the start reaches the end). Units smaller than the smallest listed unit are truncated, as for a single unit. For example, ["hours", "seconds"] over 1 hour 30 minutes 15 seconds returns { hours: 1, seconds: 1815 }.
• Nanosecond precision is always exact here, unlike diffDateTime/diffUtc/diffUnix: two plain times are less than a day apart, so the widest possible result, diffTime("00:00:00.000000000", "23:59:59.999999999", "nanoseconds") = 86399999999999, is well inside Number.MAX_SAFE_INTEGER. Those three can span more than about 104 days, at which point a nanosecond count stops being a safe integer and the bigint APIs (spanNs in span/, toNanoseconds in precision/) are the exact ones.

Parameters

Parameter	Type	Description
time1	string	ISO PlainTime string for the start
time2	string	ISO PlainTime string for the end
units	"hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | TimeUnit | ("hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | TimeUnit)[]	TimeDurationUnit | TimeDurationUnit[] to measure the difference

Options

options

optional: how the difference is rounded; a non-object value (such as null) is invalid

Type: RoundingOptions.

Option	Type	Default	Description
smallestUnit?	TimeUnit | PluralUnit<TimeUnit>	None. The difference is not rounded: Temporal uses the smallest unit the values have, "day" for dates and "nanosecond" otherwise.	The smallest unit kept in the difference; anything smaller is rounded into it. It may not be larger than the largest unit asked for.
roundingIncrement?	number	1, Temporal’s default.	The step the smallest unit is rounded to, so 15 with "minute" rounds to a quarter of an hour. For a time unit it must divide the next larger unit evenly and be smaller than it (15 or 30 minutes, not 7 or 60); a date unit takes any whole number from 1 up. A non-integer is truncated first, as Temporal does, and any other value is invalid input.
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"trunc", Temporal’s default for a difference.	Which way a value between two steps goes. "trunc" rounds toward zero and "halfExpand" to the nearest step, a half going away from zero; the other modes are those of Temporal’s roundingMode option.

Returns

numeric difference in the requested unit, or null on invalid input

Related types

• TimeDurationUnit
• RoundingOptions

Examples

import { diffTime } from "@northguild/gmt/plain/calculate";

diffTime("12:00:00", "14:30:00", "hours") // 2

time1time2

output

 

Source

plain/calculate/diffTime.ts