# DateTime

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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

## Examples

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

```json
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](../airscript-expressions/datetime-functions/format_datetime) function returns the time described by a DateTime into a string that is more intuitive for most people to parse:

```javascript
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:

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