SUBTRACT_FROM_DATE

The function SUBTRACT_FROM_DATE subtracts a given number of years, months, weeks, or days from 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

SUBTRACT_FROM_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 subtracted from the given Date. This number can be negative; if given a negative number, SUBTRACT_FROM_DATE will subtract the negative number from the specified value in the Date, ultimately increasing 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 SUBTRACT_FROM_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 subtracting 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 subtracts 3 days from it. Not that the returned Date is identical to example_date, save for the day value:

SUBTRACT_FROM_DATE(example_date, 3, "day") -> {
  "day": 11,
  "month": 4,
  "year": 2022
}  

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

SUBTRACT_FROM_DATE(example_date, 6, "month") -> {
  "day": 14,
  "month": 10,
  "year": 2021
}

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

SUBTRACT_FROM_DATE(example_date, -1, "day") -> {
  "day": 15,
  "month": 4,
  "year": 2022
}  

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

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

Discussion

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