UPDATE_TIMEZONE

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