diff

function diff(
  left: Date,
  right: Date,
  unit: TimeUnit = "millisecond",
  float: boolean = false
): number;

The result is the first date minus the second, so it is negative when the second is later. Whole units are reported by default; pass float to get the fraction as well.

Milliseconds, seconds, minutes and hours are fixed lengths and are divided out exactly. Days, months and years are counted as whole elapsed units, which is why two hours across midnight is 0 days and not 1.

Parameters

Parameter	Type	Description
`left`	`Date`	The date the interval is measured from.
`right`	`Date`	The date subtracted from it.
`unit` (optional) `= "millisecond"`	`TimeUnit`	`"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"month"` or `"year"`.
`float` (optional) `= false`	`boolean`	Keep the fractional part instead of truncating. Fixed-length units only.

Returns

number — the interval, negative when the second date is later.

Throws

Exception	Condition
`IllegalArgumentException`	an argument is not a valid `Date`, or the unit is unknown.

Examples

Measuring an interval

diff(new Date(2026, 0, 31), new Date(2026, 0, 1), "day"); // => 30
diff(new Date(2026, 0, 1), new Date(2026, 0, 1, 12), "hour"); // => -12
diff(new Date(2026, 0, 2, 1), new Date(2026, 0, 1, 23), "day"); // => 0

Source

src/time/diff.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help