DATETIME

The function DATETIME combines the information contained in a given Date, Time, and timezone (represented in a string) into a single DateTime.

This function takes three pieces of input: a Date, a Time, and a string (describing a timezone according to its TZ database name). It returns a single DateTime, containing all information represented by the input.

Declaration

DATETIME(date, time, time_zone) -> datetime

Parameters

date (required, type: Date)

Any Date.

time (required, type: Time)

Any Time.

time_zone (optional, type: string, default: "UTC")

A string containing a timezone. Timezones must be described by their TZ database names.

Return Values

datetime (type: DateTime)

A DateTime containing the information given by date, time, and time_zone.

Examples

Assuming the following examples have access to the following Date and Time values:

example_date = {  
 "day": 16  
 "month": 4  
 "year": 2021  
}  
  
example_time = {  
 "hour": 13  
 "minute": 26  
 "second": 32  
 "millisecond": 0  
}

The following example takes the date described by example_date and the time described by example_time and creates a single DateTime with the information contained in both. Note that no timezone was specified, so the timezone of the created DateTime defaults to "UTC":

DATETIME(example_date, example_time) ->{  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 13,  
  "minute": 26,  
  "second": 32,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The following example is given the same Date and Time values as the example above, but the timezone is defined, not as "UTC", but as "Africa/Dar_es_Salaam". Note that this timezone is three hours ahead of UTC, but this does not impact the time information in the returned DateTime; the hour, minute, second, and millisecond values all correspond with their analogous values in example_time. The DATETIME function assumes the given time information is in the relevant timezone:

DATETIME(example_date, example_time, "Africa/Dar_es_Salaam") ->{  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 13,  
  "minute": 26,  
  "second": 32,  
  "millisecond": 0  
 },  
 "timeZone": "Africa/Dar_es_Salaam"  
}