Elapsed-time macro
Learn how to calculate the elapsed time between two date-time values.
This macro calculates the elapsed time between two date-time values in terms of a specific unit, returning a whole number that represents the total number of complete units between the two dates. The result is positive if the start date is earlier than the end date and negative if it is the other way around.
For example, the number of months between June 15 and August 14 is one month because it is one day short of two complete months. In contrast, reversing the dates results in a negative interval of -1 month.
Mixing instants and local date times can lead to unexpected results because of time zone adjustments involved in converting local date times to instants.
Syntax
This macro has the following syntax:
number of /*<time-unit>*/ between /*<start>*/ and /*<end>*/
You can optionally prefix the macro with a definite article for readability:
the number of /*<time-unit>*/ between /*<start>*/ and /*<end>*/
The /*<time-unit>*/ is a literal word that represent a specific unit of time, and cannot be specified dynamically using expressions.
Here is a list of the supported time-unit specifiers:
Unit | Notes |
---|---|
days | The number of days may differ from the number of 24-hour periods due to daylight saving time adjustments. |
weeks | A week is defined as a period of seven days. |
weekdays | The number of weekdays depends on the locale configured at the application level. |
weekend days | The number of weekend days depends on the locale configured at the application level. |
months | The months can vary depending on the start and end dates, and may not necessarily align with 30-day periods. |
years | The number of years may differ from the number of 365-day periods due to leap years. |
hours | For local date times, a day is defined as a period of 24 hours. |
minutes | A minute is defined as 60 seconds. |
seconds | A second is defined as 1000 milliseconds. |
milliseconds millis | A millisecond is defined as 1000 microseconds. |
microseconds micros | A microsecond is defined as 1000 nanoseconds. |
nanoseconds nanos | The smallest supported unit of time. |
Parameters
The following list describes the supported parameters:
- start
The start of the interval (inclusive). This parameter is automatically converted to an instant in the configured time zone if necessary.
- end
The end of the interval (exclusive). This parameter is automatically converted to an instant in the configured time zone if necessary.
Examples
Here is an example of how to calculate the number of days between two dates:
number of days between "2025-08-01" and "2025-08-15" // 14
You can also calculate the amount of time between two date-time values in terms of months, weeks, or other units:
number of seconds between "2025-08-01T01:30" and "2025-08-01T02" // 1800