UPDATE_TIMEZONE UPDATE_TIMEZONE

UPDATE_TIMEZONE

Chandra Bergmann 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

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

 

Was this article helpful?

0 out of 0 found this helpful