SUBTRACT_FROM_DATETIME

The function SUBTRACT_FROM_DATETIME subtracts a given number of years, months, weeks, days, hours, minutes, seconds, or milliseconds from a given DateTime.

This function takes three pieces of input: a DateTime, a Number, and a string. The string designates which value in the given DateTime will be modified: "year", "month", "week", "day", "hour", "minute", "second," or "millisecond". This function subtracts the given Number from the designated value, and returns the resulting DateTime. Calculation takes into account irregularities such as daylight savings time and leap years.

Declaration

SUBTRACT_FROM_DATETIME(datetime, number, unit_string) -> modified_datetime 

Parameters

datetime (required, type: DateTime)

Any valid DateTime.

number (required, type: Number)

The number of units to be subtracted from one of the values in the given DateTime. This number can be negative; if given a negative number, SUBTRACT_FROM_DATETIME will subtract the negative number from the specified value in the DateTime, ultimately increasing the original value.

unit_string (required, type: s_tring_)

The units in the given DateTime that will be modified: "year", "month", "week", "day", "hour", "minute", "second," or "millisecond". In order to be correctly parsed by SUBTRACT_FROM_DATETIME, the given string must exactly match one of the possible values given by this table.

Return Values

modified_datetime (type: DateTime)

The DateTime that results from subtracting given number of units from the given DateTime. Calculation takes into account irregularities such as daylight savings time and leap years.

Examples

Assume all examples have access to the following DateTime object:

example_date_and_time = {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example takes the date and time described in example_date_and_time and subtracts 33 minutes from it. Not that the returned DateTime is identical to example_date_and_time, save for the minute value:

SUBTRACT_FROM_DATETIME(example_date_and_time, 33, "minute") -> {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 0,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example takes the date and time described in example_date_and_time and subtracts 10 hours from it. Note how this results in a change not only in the hour value of the resulting DateTime, but also in the the day:

SUBTRACT_FROM_DATETIME(example_date_and_time, 10, "hour") -> {  
 "date": {  
  "day": 15,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 23,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example takes the date and time described in example_date_and_time and subtracts -1 day from it. Note how this effectively adds 1 to the given day value:

SUBTRACT_FROM_DATETIME(example_date_and_time, -1, "day") -> {  
 "date": {  
  "day": 17,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

If SUBTRACT_FROM_DATETIME is given a unit_string it cannot parse, it simply returns the given DateTime unmodified, such as in the following example:

SUBTRACT_FROM_DATETIME(example_date_and_time, 33, "This is a string") -> {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

Discussion

Subtracting negative values is the same as adding positive values, allowing SUBSTRACT_FROM_DATETIME to mimic the functionality of ADD_TO_DATETIME.