UPDATE_TIMEZONE

The function UPDATE_TIMEZONE changes the timezone described by a DateTime into another specified timezone.

This function takes two pieces of input: a DateTime, and a string. It outputs the given DateTime in the timezone described by the given string.

Declaration

UPDATE_TIMEZONE(datetime, new_time_zone) -> new_datetime

Parameters

datetime (required, type: DateTime)
Any DateTime.

new_time_zone (required, type: string)
The new timezone; this is what specifies the timezone of the returned DateTime. Timezones must be described by their TZ database names, or UPDATE_TIMEZONE will not parse them as meaningful timezones.

Return Values

new_datetime (type: DateTime)
The DateTime describing the given date and time in the new timezone.

Examples

Assume the following examples have access to the following DateTime value:

example_date_and_time = {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 16,  
  "minute": 14,  
  "second": 38,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example takes the date and time described in example_date_and_time and returns the same date and time in the "Africa/Dar_es_Salaam" timezone. This timezone is three hours ahead of UTC, the timezone of example_date_and_time. Note how UPDATE_TIMEZONE takes this into account by not only adjusting the value associated with "timeZone", but also the value associated with "hour".

UPDATE_TIMEZONE(example_date_and_time, "Africa/Dar_es_Salaam") = {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 19,  
  "minute": 14,  
  "second": 38,  
  "millisecond": 0  
 },  
 "timeZone": "Africa/Dar_es_Salaam"  
}

Adjusting the time to match the timezone is made possible by the UPDATE_TIMEZONE function recognizing the new timezone. If the given string does not describe a timezone in a parsable format, UPDATE_TIMEZONE will simply return the given DateTime unmodified. This is what happens in the following example, when "This is a string" is given to describe the new timezone. That does not describe a timezone by any TZ database name, and so UPDATE_TIMEZONE makes not changes to the given DateTime:

UPDATE_TIMEZONE(example_date_and_time, "This is a string") = {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 16,  
  "minute": 14,  
  "second": 38,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}