ADD_TO_DATETIME

The function ADD_TO_DATETIME adds 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 adds the given Number from the designated value, and returns the resulting DateTime.

Declaration

ADD_TO_DATETIME(datetime, number, unit_string) -> datetime

Parameters

datetime (required, type: DateTime)
Any valid DateTime.

number (required, type: Number)
The number of units to be added to one of the values in the given DateTime.
This number can be negative; if given a negative number, ADD_FROM_DATETIME will add the negative number to the specified value in the DateTime, effectively performing a subtraction operation.

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 ADD_TO_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 adding the given number of units to the given DateTime.

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 adds 5 minutes to it. Not that the returned DateTime is identical to example_date_and_time, save for the minute value:

ADD_TO_DATETIME(example_date_and_time, 5, "minute") -> {  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 38,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example takes the date and time described in example_date_and_time and adds 20 hours to it. Note how this results in a change not only in the hour value of the resulting DateTime, but also in the the day:

ADD_TO_DATETIME(example_date_and_time, 10, "hour") -> {  
 "date": {  
  "day": 17,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 5,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

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

ADD_TO_DATETIME(example_date_and_time, -1, "day") -> {  
 "date": {  
  "day": 15,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

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

ADD_TO_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

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

ADD_TO_DATETIME can be used in tandem with the NOW function in order to create a DateTime specifying a future date and time, which is particularly valuable in the context of timers. For instance, to set an action to occur five minutes in the future, you can define the DateTime at which the action will occur as follows:

ADD_TO_DATETIME(  
  NOW(),  
  5,  
  "minute"  
)