The function ADD_TO_DATE adds a given number of years, months, weeks, or days to a given Date.

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

### Declaration

``````ADD_TO_DATE(date, number, unit_string) -> modified_date
``````

### Parameters

`date` (required, type: `Date`)
Any valid Date.

`number` (required, type: `Number`)
The number of units to be added to the given Date.
This number can be negative; if given a negative number, ADD_TO_DATE will added the negative number from the specified value in the Date, ultimately decreasing the original value.

`unit_string` (required, type: `string`)
The units in the given Date that will be modified: "year", "month", "week", or"day". In order to be correctly parsed by ADD_TO_DATE, the given string must exactly match one of the relevant values given by this table.

### Return Values

`modified_date` (type: `Date`)
The Date that results from adding given number of units from the given Date.
Calculation takes into account irregularities such as daylight savings time and leap years.

### Examples

``````example_date = {
"day": 14,
"month": 4,
"year": 2022
}
``````

The following example takes the date described in `example_date` and adds 3 days to it. Not that the returned Date is identical to `example_date`, save for the day value:

``````ADD_TO_DATE(example_date, 3, "day") -> {
"day": 17,
"month": 4,
"year": 2022
}
``````

The following example takes the date described in `example_date` and adds 10 months to it. Note how this results in a change not only in the month value of the resulting Date, but also in the the year:

``````ADD_TO_DATE(example_date, 10, "month") -> {
"day": 14,
"month": 2,
"year": 2023
}
``````

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

``````ADD_TO_DATE(example_date, -1, "day") -> {
"day": 13,
"month": 4,
"year": 2022
}
``````

If ADD_TO_DATE is given a `unit_string` it cannot parse, it simply returns the given Date unmodified, such as in the following example:

``````ADD_TO_DATE(example_date, 33, "This is a string") -> {
"day": 14,
"month": 4,
"year": 2022
}
``````

### Discussion

Adding negative values is the same as subtracting positive values, allowing ADD_TO_DATE to mimic the functionality of SUBTRACT_FROM_DATE.