TIME_DELTA

The function TIME_DELTA returns returns the number of total hours, total minutes, total seconds, and total milliseconds between two Times.

This function takes two Times as input. It returns he number of total hours, total minutes, total seconds, and total milliseconds between the two Times. This output is a is formatted like another Time, but, unlike most Times, it does not express a valid time of day. Calculation takes into account irregularities such as daylight savings time and leap years.

Declaration

TIME_DELTA(time1, time2) -> delta

Parameters

time1 (required, type: Time) Any time.

time (required, type: Time) Any time.

Return Values

delta (type: Time) The number of total hours, total minutes, total seconds, and total milliseconds between time1 and time2. Calculation takes into account irregularities such as daylight savings time and leap years. Unlike most Times, delta does not express a valid time of day.

Examples

Assume the following examples have access to the following Time values:

example_time1 = {  
 "hour": 12  
 "minute": 38  
 "second": 24  
 "millisecond": 0  
}  
  
example_time2 = {  
 "hour": 2  
 "minute": 10  
 "second": 4  
 "millisecond": 500  
}

The following example returns the the number of hours, minutes, seconds, and milliseconds between example_time1 and example_time2. Note that the values associated with "minute", "second", and millisecond" are too large to be valid values describing a real Time; rather, the describe the total number of minutes, seconds and milliseconds (respectively) between the two given Times:

TIME_DELTA(example_time1, example_time2) = {  
 "hour": 10  
 "minute": 628  
 "second": 37699  
 "millisecond": 37699500  
}

TIME_DELTA returns the absolute difference between the given Times; it does not matter which is given first. The following example returns the the number of hours, minutes, seconds, and milliseconds between example_time2 and example_time1; note that the output is the same as the above example, even though the Time values are given in reverse order:

TIME_DELTA(example_time2, example_time1) = {  
 "hour": 10  
 "minute": 628  
 "second": 37699  
 "millisecond": 37699500  
}

Discussion

The Time returned by TIME_DELTA does not contain conventional TIME information; while it is technically possible to use it as TIME input in functions such as FORMAT_TIME, the output returned in such cases will not be meaningful. To avoid such confusion, it is best practice to use TIME_DELTA in tandem with the HOUR, MINUTE, or SECOND function. (There is no analogous MILLISECOND function; such small differences in time are effectively negligible in the context of real-world apps.) Examples can be found below:

HOUR(TIME_DELTA(time1, time2)) -> hour_delta

MINUTE(TIME_DELTA(time1, time2)) -> minute_delta

SECOND(TIME_DELTA(time1, time2)) -> second_delta

This returns a single Number: the hours, minutes, or seconds, respectively, between the two times.

Assume the following examples have access to example_time1 and example_time2 from the Examples section. The isolated difference between hours, minutes, or seconds (respectively) between them can be found as follows:

HOUR(TIME_DELTA(example_time1, example_time2)) -> 10

MINUTE(TIME_DELTA(example_time1, example_time2)) -> 628

SECOND(TIME_DELTA(example_time1, example_time2)) -> 37699