Skip to main content

addToDateTime

Adds a duration to a datetime object.

When you add a duration to a datetime object that has no time component, Studio applies a default time of midnight — i.e. 00:00:00, which displays as 12:00:00 AM in Preview Mode.

Parameters

  • DATETIME (datetime or string)

    A datetime object, or a string in an automatically recognized datetime pattern.

  • DURATION (number or string)

    The duration to add. 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 only characters from the set 'yMwdhms', where y = years, M = months, w = weeks, d = days, h = hours, m = minutes, and s = seconds. 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: s

  • 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

Each example uses a string in an automatically recognized datetime pattern.

TIME-ONLY EXAMPLES

ATL in Script

Result

Notes

[[time = '10:30:00';
addToDateTime(time, 5)]]

10:30:05 AM

Adds the duration in seconds (default).

[[time = '10:30:00';
addToDateTime(time, 5, 'm')]]

10:35:00 AM

Adds the duration in minutes.

[[time = '10:30:00';
addToDateTime(time, 5, 'h')]]

3:30:00 PM

Adds the duration in hours.

[[time = '10:30:00';
addToDateTime(time, '5 hours', 'h')]]

3:30:00 PM

The duration value is given as a string.

[[time = '10:30:00';
addToDateTime(time, '5-10-7', 'smh')]]

5:40:05 PM

There are three duration numbers and three unit characters. The function matches these working left to right and adds 5 seconds, 10 minutes, and 7 hours.

[[time = '10:30:00';
addToDateTime(time, '5-10-7', 'h')]]

3:30:00 PM

There are three duration numbers but only one unit character. The function matches these working left to right, so adds a duration of 5 hours only. 

[[time = '10:30:00';
addToDateTime(time,'24 hours','h')]]

10:30:00 AM

In this example, 24 hours are added. The input value is time-only, so the time appears unchanged.

DATE-ONLY EXAMPLES

ATL in Script

Result

Notes

[[date = '2019-12-24';
addToDateTime(date, 5)]]

Dec 24, 2019 12:00:05 AM

The input value is date-only, so the function assumes a time of 00:00:00 and adds 5 seconds.

[[date = '2019-12-24';
addToDateTime(date, 5, 'd')]]

Dec 29, 2019 12:00:00 AM

The input value is date-only, so the function assumes a time of 00:00:00 and adds 5 days.

[[date = '2019-12-24';
addToDateTime(date, '5-10-7', 'dMy')]]

Oct 29, 2027 12:00:00 AM

The input value is date-only, so the function assumes a time of 00:00:00 and adds a duration of 5 days, 10 months, and 7 years. 

[[date = '2019-12-24';
addToDateTime(date, '5-10-7', 'wM')]]

Nov 28, 2020 12:00:00 AM

The input value is date-only, so the function assumes a time of 00:00:00 and adds 5 weeks and 10 months. The extra duration number (7) is ignored as it cannot be matched to a character.

DATETIME EXAMPLES

ATL in Script

Result

Notes

[[dateTime = '2019-12-24T10:30:00';
addToDateTime(dateTime, '5-7-10-15', 'smhd')]]

Jan 8, 2020 8:37:05 PM

Adds a duration of 5 seconds, 7 minutes, 10 hours, and 15 days.

[[dateTime = '2019-12-24T10:30:00';
addToDateTime(dateTime, '5-7-10-15', 'ssmhd')]]

Jan 8, 2020 8:37:05 PM

The function parses the duration using 'smhd' because duplicate characters are ignored.

[[dateTime = '2019-12-24T10:30:00';
addToDateTime(dateTime, 5, 'smhd')]]

Dec 24, 2019 10:30:05 AM

Adds a duration of 5 seconds only. The other unit characters (mdh) are ignored because they cannot be matched to a number.

[[dateTime = '2019-12-24T10:30:00';
addToDateTime(dateTime, 5, 'smhd', true)]]

Dec 29, 2019 10:30:00 AM

The RIGHT TO LEFT parameter is set to true. The function adds a duration of 5 days only. The other unit characters (smh) are ignored because they cannot be matched to a number.

© Arria Data2Text Limited