parseDuration
Converts a duration string to a number representing the duration in seconds.
For example, [[parseDuration('3 days and 1 hour', 'dh')]] returns 262,800.
The function parses by matching numbers in the DURATION string (first parameter) to characters in the UNITS string (second parameter). By default, the function works left to right through the input strings, but you can reverse this by using the fifth parameter.
The third and fourth parameters specify start and end datetimes. These help to account for the fact that some time units vary in length (e.g. months can be 28, 29, 30, or 31 days).
Parameters
DURATION (number or string)
The input duration. This can be a whole number or a string containing whole numbers and non-numeric characters (e.g. '2 days, 3 weeks'). The numbers can represent years, months, weeks, days, hours, minutes, or seconds; their identity and order are determined by the UNITS parameter. The function treats non-numeric characters in the string as separators.
By default, the function matches the numbers in DURATION to the characters in UNITS, working left to right. If there are more duration numbers than unit characters, extra numbers are ignored.
UNITS (string)
Optional. A string for specifying the unit(s) for your duration. The string must contain characters from the set 'yMwdhms', where y = years, M = months, w = weeks, d = days, h = hours, m = minutes, and s = seconds. Any duplicate characters are ignored.
By default, the function matches the characters in UNITS to the numbers in DURATION, working left to right. If there are more unit characters than duration numbers, extra characters are ignored.
Default: yMdhms
START DATETIME (datetime or string)
Optional. The duration is parsed by counting forward from this datetime.
Input a datetime object or a string in an automatically recognized datetime pattern.
Default: 1970-01-01
END DATETIME (datetime 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.
RIGHT TO LEFT (Boolean)
Optional. By default, the function matches numbers in DURATION to characters in UNITS, working left to right. Set this parameter to true to make the function work right to left.
Default: false
Examples
ATL in Script | Result | Notes |
|---|---|---|
| 180 | 3 minutes |
| 86,400 | 0 years, 0 months and 1 day |
| 65 | 1 minute and 5 seconds |
| 65 | 1 minute and 5 seconds |
Important
The function ignores non-numeric characters — e.g. 'month' and 'days' — in the input string. It parses using the numbers only. Compare the third and fourth examples above.
Use the third parameter to calculate forward from a specific datetime.
ATL in Script | Result |
|---|---|
| 2,678,400 |
| 2,419,200 |
Note
January 2021 has 30 days, while February 2021 has 28 days.
Use the fourth parameter to calculate backward from a specific datetime.
ATL in Script | Result |
|---|---|
| 2,419,200 |
| 2,678,400 |
Note
The duration is calculated backward only when no start datetime (third parameter) is specified.
Set the fifth parameter to true to apply right-to-left matching. Left-to-right matching applies by default.
ATL in Script | Result | Notes |
|---|---|---|
| 36,892,800 | 1 year, 2 months and 3 days |
| 2,851,380 | 3 minutes, 2 days and 1 month |
These examples also show what happens when there are fewer duration numbers (first parameter) than unit characters (second parameter). Any numbers that can't be matched to a character are ignored.
