TIME_FROM_DATETIME

The function TIME_FROM_DATETIME takes a DateTime and returns the isolated time.

This function requires a DateTime as input. It outputs the isolated time described by the given DateTime. As an option, it can also take as input a string indicating the desired timezone of the output. If this timezone differs from the timezone of the DateTime object, TIME_FROM_DATETIME will convert the information given by the DateTime to the provided timezone before returning the time.

Declaration

TIME_FROM_DATETIME(datetime, time_zone) -> time

Parameters

datetime (required, type: object) Any DateTime.

time_zone (optional, type: string) A string representation of the desired timezone. The recognized representations are given by the TZ database names described in this list of database timezones.

Return Values

time (type: time) The isolated time described in the given DateTime. If a timezone was provided, this time will be in the designated timezone; otherwise, it will default to the timezone of the given DateTime.

Examples

It's possible to hardcode a DateTime, but it quickly gets cumbersome. To avoid this, assume all formulas have access to the following DateTime object:

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

The following example returns the isolated time given by example_date_and_time. Note that the returned values of hour, minute, second, and millisecond are exactly the same as the ones provided by the given DateTime:

TIME_FROM_DATETIME(example_date_and_time) -> {  
 "hour": 10,   
 "minute": 23,   
 "second": 14,   
 "millisecond": 0   
}

The following example also returns the isolated time from example_date_and_time, but this time the output is in the "Africa/Addis_Ababa" timezone, which is three hours ahead of UTC. Note that the returned hour value is three greater than the hour value given directly in example_date_and_time:

TIME_FROM_DATETIME(example_date_and_time, "Africa/Addis_Ababa") -> {  
 "hour": 13,   
 "minute": 23,   
 "second": 14,   
 "millisecond": 0   
}

While TIME_FROM_DATETIME will run no matter the contents of the string given for time_zone, it only recognizes the TZ database names described in this list of database timezones. If the entered string does not describe the desired timezone in a recognizable format, TIME_FROM_DATETIME will default to returning the time in the timezone specified by the given DateTime. The following example returns the isolated time from example_date_and_time. Note that it it does not recognize "this is a string" as a valid timezone, and so the returned values of hour, minute, second, and millisecond are exactly the same as the ones provided by the given DateTime:

TIME_FROM_DATETIME(example_date_and_time, "this is an string") -> {  
 "hour": 10,   
 "minute": 23,   
 "second": 14,   
 "millisecond": 0   
}

example_date_and_time described a date and time in UTC, but this does not need to be the case in order for TIME_FROM_DATETIME to default to the timezone of the given DateTime. To demonstrate, assume the following formulas have access to the following DateTime object, which describes a date and time in the Africa/Algiers timezone, which is an hour ahead of UTC:

example_date_and_time2 = {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 10,  
  "minute": 23,  
  "second": 14,  
  "millisecond": 0  
 },  
 "timeZone": "Africa/Algiers"  
}

The following example returns the isolated time from example_date_and_time2. Note that the hour, minute, second, and millisecond returned are exactly the hour, minute, second, and millisecond specified by the given DateTime. That is, the returned date is in the Africa/Algiers timezone, not UTC:

TIME_FROM_DATETIME(example_date_and_time2) -> {  
 "hour": 10,   
 "minute": 23,   
 "second": 14,   
 "millisecond": 0   
}

This last example returns the isolated date given by example_date_and_time2 in UTC. Because the time given by example_date_and_time2 is in the morning in the Africa/Algiers timezone – an hour ahead of UTC – note that the returned time is an hour behind the time specified in example_date_and_time2:

TIME_FROM_DATETIME(example_date_and_time2, "UTC") -> {  
 "hour": 9,   
 "minute": 23,   
 "second": 14,   
 "millisecond": 0   
}