UPDATE_DATETIME

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"  
}