# UPDATE_TIMEZONE

Chandra Bergmann

#### 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

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