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.