ADD_TO_DATE

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

Assume all examples have access to the following Date:

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.