durationAsList
Converts a duration to a list of values for years, months, weeks, days, hours, minutes, and seconds.
The first parameter takes a duration in seconds, and the second takes a string specifying the selected time units. You select from the set 'yMwdhms', where y = years, M = months, w = weeks, d = days, h = hours, m = minutes, and s = seconds. The default units string is 'yMdhms' (weeks not selected by default).
The output is a list of seven values. The value for any non-selected unit is null. Studio does not print nulls, so the printed output may show fewer than seven values, even though seven values are there. For example, [[durationAsList(1000000,'dh')]] returns the list (null, null, null, 11, 14, null, null), but this prints as "11 and 14".
Zero-based indexing applies, and there are always seven values. Therefore:
Index 0 = years Index 1 = months Index 2 = weeks Index 3 = days | Index 4 = hours Index 5 = minutes Index 6 = seconds Index 7 = null |
The optional third and fourth parameters specify start and end datetimes. These 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)
The duration in seconds.
UNITS (string)
Optional. A string for selecting time units. 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.
Default: yMdhms.
START DATETIME (datetime or string)
Optional. The duration is calculated 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 calculated backward from this datetime when no start datetime is specified.
Input a datetime object or a string in an automatically recognized datetime pattern.
Examples
The default UNITS string is 'yMdhms' (weeks not selected).
ATL in Script | Output List (y, M, w, d, h, m, s) | Printed Output |
|---|---|---|
| (0, 0, null, 11, 13, 46, 40) | 0, 0, 11, 13, 46 and 40 |
Important
The third value is null because weeks is not selected by default. Note that this third value does not appear in the printed result because Studio does not print nulls.
To get a numerical value for weeks, use the second parameter.
ATL in Script | Output List (y,M,w,d,h,m,s) | Printed Output |
|---|---|---|
| (0, 0, 1, 4, 13, 46, 40) | 0, 0, 1, 4, 13, 46 and 40 |
When a small unit is not selected, its value is rounded up or down to the nearest larger unit that is selected.
ATL in Script | Output List (y,M,w,d,h,m,s) | Printed Output |
|---|---|---|
| (null, null, null, null, 1, 46, 40) | 1, 46 and 40 |
| (null, null, null, null, 1, 47, null) | 1 and 47 |
Use the third parameter to calculate forward from a specific datetime.
ATL in Script | Output List (y,M,w,d,h,m,s) | Printed Output |
|---|---|---|
| (0, 0, null, 28, 0, 0, 0) | 0, 0, 28, 0, 0 and 0 |
| (0, 1, null, 0, 0, 0, 0) | 0, 1, 0, 0, 0 and 0 |
Note
2419200 seconds = 28 days, which is 1 month counting forward from Feb 1, 2021.
Use the fourth parameter to calculate backward from a specific datetime.
ATL in Script | Output List (y,M,w,d,h,m,s) | Printed Output |
|---|---|---|
| (0, 1, null, 0, 0, 0, 0) | 0, 1, 0, 0, 0 and 0 |
| (0, 0, null, 28, 0, 0, 0) | 0, 0, 28, 0, 0 and 0 |
Note
The duration is calculated backward only when no start datetime (third parameter) is specified.
durationAsList vs. formatDuration
To convert a duration (in seconds) to a string — e.g. "1 year, 2 months and 3 days" — formatDuration is often the better choice as it returns a string, not a list that requires further conversion to a string.
However, formatDuration always prints time values as digits. There is no option to convert numbers to words — e.g. "one year, two months and three days." For this, you could use durationAsList.
For example, this function script calculates a duration and returns a string:
#value getDuration(startDate, endDate) [[ duration = dateTimeDifference(startDate, endDate) unitsList = durationAsList(duration, 'yMd') yearsPart = countable(unitsList[0], '', 'year', 'wordsOnly') monthsPart = countable(unitsList[1], '', 'month', 'wordsOnly') daysPart = countable(unitsList[3], '', 'day', 'wordsOnly') joinStrings(yearsPart, ', ', monthsPart, ' and ', daysPart) ]]
This is a user-defined function, so you must call it in another script. For example:
ATL in Script | Printed Output |
|---|---|
| One year, two months and three days |
