formatDuration
Formats the input duration as a text string — e.g. 115 seconds as '1 minute and 55 seconds'.
The first parameter takes a duration in seconds, and the second takes a format string. You pick from the set 'yMwdhms', where y = years, M = months, w = weeks, d = days, h = hours, m = minutes, and s = seconds. The default string is 'yMdhms' (weeks not selected by default). Non-selected units don't appear in the output.
The third parameter determines whether the output string includes zero values.
The fourth parameter determines whether the output strings includes a conjunction.
The fifth and sixth parameters set start and end datetimes — see the parameter descriptions for guidance.
Parameters
DURATION (number)
The duration in seconds.
UNITS (string)
Optional. A format string defining which time units to include in the output. Pick from the set 'yMwdhms', where y = years, M = months, w = weeks, d = days, h = hours, m = minutes, and s = seconds.
Default: yMdhms
EXPRESS ZEROS (Boolean)
Optional. Whether to include zero values (e.g. '0 months') in the output string.
Default: false
USE CONJUNCTION (Boolean)
Optional. Whether to include a conjunction ('and') in the output string.
Default: true
START DATETIME (datetime or string)
Optional. The duration is counted forward from this datetime.
Input a datetime object or a string in an automatically recognized datetime pattern.
Default: 1970-01-01.
END DATETIME (datetime or string)
Optional. The duration is counted backward from this datetime when no start datetime is specified.
Input a datetime object or a string in an automatically recognized datetime pattern.
Examples
These examples leave the optional parameters unspecified:
ATL in Script | Result |
|---|---|
| 1 minute |
| 1 minute and 1 second |
| 11 days, 13 hours, 46 minutes and 40 seconds |
| 3 years, 2 months, 2 days, 9 hours, 46 minutes and 40 seconds |
Use the second parameter to select time units.
ATL in Script | Result |
|---|---|
| 1 minute |
| 1 minute and 1 second |
| 11 days, 13 hours, 46 minutes and 40 seconds |
| 1 week, 4 days, 13 hours and 47 minutes |
Note
When a small unit is not selected, its value is rounded up or down to the nearest larger unit that is selected.
Set the third parameter to true to include zero values in the output.
ATL in Script | Result |
|---|---|
| 1 week |
| 1 week and 0 days. |
Set the fourth parameter to false to omit the conjunction from the output string.
ATL in Script | Result |
|---|---|
| 1 week and 0 days. |
| 1 week, 0 days. |
Use the fifth parameter to calculate forward from a specific datetime.
ATL in Script | Result |
|---|---|
| 30 days |
| 1 month and 2 days |
Use the sixth parameter to calculate backward from a specific datetime.
ATL in Script | Result |
|---|---|
| 1 month and 1 day |
| 30 days |
Note
The duration is calculated backward only when no start datetime (fifth parameter) is specified.
