UPDATE_DATETIME

Chandra Bergmann

The function UPDATE_DATETIME replaces the date and time described by a DateTime with another specified Date and Time.

This function takes three pieces of input: a base DateTime, a Date and a Time. It outputs a DateTime with the date and time information replaced by the information given in the given Date and Time. This function also provides the option to declare a change in timezone in the form of a string.

Declaration

UPDATE_DATETIME(base_datetime, new_date, new_time, new_time_zone) -> datetime

Parameters

base_datetime (required, type: Datetime)
Any datetime.
new_date (required, type: Date)
The new date.
new_time (required, type: Time)
The new time.
new_time_zone (optional, type: string)
The new timezone. Timezones must be described by their TZ database names, or UPDATE_DATETIME will not parse them as meaningful timezones.

Return Values

datetime (type: DateTime)
The DateTime that results from replacing the date and time information in the given DateTime with given Date and Time. If a new timezone is given, this will also be taken into account.

Examples

Assume the example has access to the following DateTime, Date, and Time values:

example_date_and_time = { "date": {  "day": 1,  "month": 4,  "year": 2021 }, "time": {  "hour": 16,  "minute": 14,  "second": 38,  "millisecond": 0 }, "timeZone": "UTC"}example_date = { "day": 2 "month": 1 "year" : 2022}example_time = { "hour": 5 "minute": 11 "second" : 55 "millisecond": 45}

The following example takes the date and time information given by example_date_and_time, and replaces them it with the information given by example_date and example_time:

UPDATE_DATETIME(example_date_and_time, example_date, example_time) = { "date": {  "day": 2,  "month": 1,  "year": 2022 }, "time": {  "hour": 5,  "minute": 11,  "second": 55,  "millisecond": 45 }, "timeZone": "UTC"}

UPDATE_DATETIME also provides the option to specify a timezone change by entering a string representing TZ database name. The following example takes the same DateTime, Date, and Time input as the example above, but it also specifies a value for new_time_zone. The timezone specified, "Africa/Addis_Ababa", is three hours ahead of UTC. Note how this changes the hour value as compared to the above example:

UPDATE_DATETIME(example_date_and_time, example_date, example_time, "Africa/Addis_Ababa") = { "date": {  "day": 2,  "month": 1,  "year": 2022 }, "time": {  "hour": 8,  "minute": 11,  "second": 55,  "millisecond": 45 }, "timeZone": "UTC"}