DATE_FROM_DATETIME

The function DATE_FROM_DATETIME takes a DateTime and returns the isolated date.

This function requires one DateTime as input. It outputs the isolated date 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, DATE_FROM_DATETIME will convert the information given by the DateTime to the provided timezone before returning the date.

Declaration

DATE_FROM_DATETIME(datetime, time_zone) -> date

Parameters

datetime (required, type: DateTime)

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

date (type: date)

The isolated date described in the given DateTime. If a timezone was provided, this date 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 variable:

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 returns the isolated date given by example_date_and_time. Note that the returned values of day, month, and year are exactly the same as the ones provided by the given DateTime:

DATE_FROM_DATETIME(example_date_and_time) -> {  
 "day": 1,   
 "month": 4,   
 "year": 2021  
}

The following example also returns the isolated date from example_date_and_time, but this time the output is in the "Asia/Anadyr" timezone. The Asia/Anadyr timezone is twelve hours ahead of UTC, and the time specified by example_date_and_time is in the mid-afternoon; during afternoon in UTC, the Asia/Anadyr timezone is experiencing early morning the following day. Thus, the returned date is a day ahead of the date within example_date_and_time:

DATE_FROM_DATETIME(example_date_and_time, "Asia/Anadyr"} -> {  
 "day": 2,   
 "month": 4,   
 "year": 2021  
}

While DATE_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, DATE_FROM_DATETIME will default to returning the date in the timezone specified by the given DateTime. The following example returns the isolated date 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 day, month, and year are exactly the same as the ones provided by the given DateTime:

DATE_FROM_DATETIME(example_date_and_time, "this is an string") -> {  
 "day": 1,   
 "month": 4,   
 "year": 2021  
}

example_date_and_time described a date and time in UTC, but this does not need to be the case in order for DATE_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 Asia/Anadyr timezone, which is twelve hours ahead of UTC:

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

The following example returns the isolated date from example_date_and_time2. Note that the day, month, and year returned are exactly the day, month, and year specified by the given DateTime. That is, the returned date is in the Asia/Anadyr timezone, not UTC:

DATE_FROM_DATETIME(example_date_and_time2) -> {  
 "day": 1,   
 "month": 4,   
 "year": 2021  
}

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 Asia/Anadyr timezone, and the Asia/Anadyr timezone is twelve hours ahead of UTC, note that the returned date is a day behind the date specified in example_date_and_time2:

DATE_FROM_DATETIME(example_date_and_time2, "UTC") -> {  
 "day": 31,   
 "month": 3,   
 "year": 2021  
}