Modifies a date-time string by applying a specified amount of time to it.
This function is useful in tandem with GetDateTimeFormat, which produces a string containing a date, a time, or both.
Syntax
DateTimeAdd( ChangeUnit, ChangeValue, InitialDateTime, OutputFormat, Culture );
Parameters
| Parameter Name | Type | Description | Optional? | Default Value |
|---|---|---|---|---|
| ChangeUnit | String | The type of unit to be applied. This must be one of the following: "Year", "Month", "Day", "Hour", "Minutes", "Seconds", or "Milliseconds". | No | n/a |
| ChangeValue | Integer | The whole number of units to be applied. This can be either positive (for adding to the original) or negative (for subtracting from it). | No | n/a |
| InitialDateTime | String | The original date and time. If the date provided is not recognised, the function will use the current date and time instead. | No | n/a |
| OutputFormat | String | The format in which the modified date will appear. | Yes | "G" |
| Culture | String | The culture code of the initial date and time. This culture will also be applied to the function's result. | Yes | "en-GB" |
Output
If successful, the function will return a string consisting of the modified date and time. If an invalid Culture is provided, the function will return an error.
In cases where the date is incremented by months, any date whose day value is higher than the total days in the new month will be reduced to the last day of the new month. For example, if you add one month to the date “31/01/2014”, rather than returning “31/02/2014” (an invalid date) the expression returns “28/02/2014”, which is the closest available date in the correct month.
Use Case
A travel operator prides itself on a timely response to all customer enquiries, and makes a point to send a courtesy e-mail to customers two weeks after they make an initial booking.
To establish when a follow-up e-mail should be sent, it uses GetDateTimeFormat to add 14 days to the date of booking, as shown below:
CourtesyEmailDate = DateTimeAdd("Day", 14, BookingDate, "d");
Since the dates are already in the default en-GB culture, and the required date for the e-mail is also en-GB, the unnecessary Culture argument is omitted.