Skip to main content

subtractFromDateTime

Subtracts a duration from a datetime object.

When you subtract a duration from 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 subtract. 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 from 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';
subtractFromDateTime(time,5)]]

10:29:55 AM

Subtracts the duration in seconds (default).

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

10:25:00 AM

Subtracts the duration in minutes.

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

5:30:00 AM

Subtracts the duration in hours.

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

5:30:00 AM

The duration value is given as a string.

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

3:19:55 AM

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

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

5:30:00 AM

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

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

10:30:00 AM

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

DATE-ONLY EXAMPLES

ATL in Script

Result

Notes

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

Dec 23, 2019 11:59:55 PM

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

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

Dec 19, 2019 12:00:00 AM

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

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

Feb 19, 2012 12:00:00 AM

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

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

Jan 20, 2019 12:00:00 AM

The input value is date-only, so the function assumes a time of 00:00:00 and subtracts 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';
subtractFromDateTime(dateTime,'5-7-10-15','smhd')]]

Dec 9, 2019 12:22:55 AM

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

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

Dec 9, 2019 12:22:55 AM

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

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

Dec 24, 2019 10:29:55 AM

Subtracts 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';
subtractFromDateTime(dateTime,5,'smhd',true)]]

Dec 19, 2019 10:30:00 AM

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

© Arria Data2Text Limited