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: string)
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

``````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.