The DateTime Data Type pairs a Date with a Time and a timezone. It is used when performing operations that deal with dates and times.

The DateTime Data Type makes it easy to work with precise times regardless of the timezone used to describe them. When working with DateTimes described in different timezones, Airkit will account for any discrepancy automatically.

Structure

The DateTime Data Type is an object that describes a date and time the following properties:

• date (date) - a date object with the following properties:

  • day (number) - the day of a month, where indexing begins at 1.
  • month (number) -  the month of a year, where 1 represents January, whereas 12 represents December.
  • year (number) - a year.

• time (time) - a time object with the following properties:

  • hour (number) - a hour of a day represented by a 24-hour clock.
  • minute (number) - the number of minutes into the hour.
  • second (number) - the number of seconds into the minute.
  • millisecond (number) - the number of milliseconds into the second.

• timeZone (string) - the timezone of the described date and time, described by its TZ database name

Examples

Assume all of the following examples have access to the example DateTime, example_datetime:

example_datetime = {  
  "date": {  
    "day": 21,  
    "month": 6,  
    "year": 2021  
},  
  "time": {  
    "hour": 20,  
    "minute": 56,  
    "second": 32,  
    "millisecond": 647  
},  
  "timeZone": "UTC"  
}

DateTime values can be returned by and given to Airscript expressions. For instance, the FORMAT_DATETIME function returns the time described by a DateTime into a string that is more intuitive for most people to parse:

FORMAT_DATETIME(  
  example_datetime,   
  "MMMM Do, YYYY h:mm A z"
) -> "June 21st, 2021 8:56 PM UTC"

This allows the complications of varying timezones to be handled under the hood. For instance, example_datetime is in UTC, but the FORMAT_DATETIME function can easily be used to display its equivalent time in the CDT timezone:

FORMAT_DATETIME(  
   example_datetime,  
   "MM/DD/YY h:mm A z",  
   "en-EN",  
   "America/Chicago"  
) -> 06/21/21 3:56 PM CDT