# Working with Dates and Times

Working with dates and times is a notoriously difficult problem, the most famous incantation being Y2K. Airkit provides a comprehensive system to work with dates and times for this precise reason. There are three data types to familiarize yourself with, the [Datetime](../variable-data-types/the-datetime-variable-data-type), the [Date](../variable-data-types/the-date-variable-data-type), and the [Time](../variable-data-types/the-time-variable-data-type) types. The best way to think of these is by analogy. A Datetime is a specific time marked on your calendar. A Date is a particular day's square on your calendar. A Time is a particular configuration of your clock.

If you would like to find the current Datetime you can use the [NOW](../airscript-expressions/datetime-functions/now) function.

```javascript
NOW()
```

Other ways to create a date/time are to use the functions [DATETIME](../airscript-expressions/datetime-functions/datetime), [DATE](../airscript-expressions/datetime-functions/date), and [TIME](../airscript-expressions/datetime-functions/time). Using January 9th, 2007 9:41 AM as an example Datetime\*\*:\*\*

```javascript
DATETIME(DATE(2007, 1, 9), TIME(9, 41, 0), "America/Los_Angeles")  
DATE(2007, 1, 9)  
TIME(9, 41, 0)
```

To retrieve the year of our example Date use the [YEAR](../airscript-expressions/datetime-functions/year) function:

```javascript
YEAR(example_date)
```

The [YEAR](../airscript-expressions/datetime-functions/year) function can also be used to retrieve the year from our example Datetime:

```javascript
YEAR(example_datetime)
```

Use the [DATE\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/date.md_from_datetime) and the [TIME\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.md_from_datetime) functions to convert a Datetime to a **Date** or **Time** respectively:

```javascript
DATE_FROM_DATETIME(example_datetime)  
TIME_FROM_DATETIME(example_datetime)
```

The following functions can be used to retrieve different parts of Datetimes, Dates, and Times

| Function Name                                                                                               | Description                                          |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [DATE\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/date.md_from_datetime) | Returns the **date** portion of a **Datetime.**      |
| [TIME\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.md_from_datetime) | Returns the **time** portion of a **Datetime.**      |
| [YEAR](../airscript-expressions/datetime-functions/year)                                                    | Returns the **year** of a **Datetime** or **Date**   |
| [MONTH](../airscript-expressions/datetime-functions/month)                                                  | Returns the **month** of a **Datetime** or **Date**  |
| [DAY](../airscript-expressions/datetime-functions/day)                                                      | Returns the **day** of a **Datetime** or **Date**    |
| [HOUR](../airscript-expressions/datetime-functions/hour)                                                    | Returns the **hour** of a **Datetime** or **Time**   |
| [MINUTE](../airscript-expressions/datetime-functions/minute)                                                | Returns the **minute** of a **Datetime** or **Time** |
| [SECOND](../airscript-expressions/datetime-functions/second)                                                | Returns the **second** of a **Datetime** or **Time** |

### Formatting

The [FORMAT\_DATETIME](../airscript-expressions/datetime-functions/format_datetime), [FORMAT\_DATE](../airscript-expressions/datetime-functions/format_date), and [FORMAT\_TIME](../airscript-expressions/datetime-functions/format_time) functions allow you to create a String from a Datetime, Date, or Time. Use these functions when you would like to display a **Datetime**, **Date**, or **Time** to a user so that Airkit can format it correctly according to the user's locale and timezone. For example, to display our example Datetime as **January 9, 2007 9:41 AM PST**:

```javascript
FORMAT_DATETIME(example_datetime, "MMMM do, YYYY h:mm A")
```

or just the time as **9:41 AM**:

```javascript
FORMAT_DATETIME(example_datetime, "h:mm A")
```

### Modifying

#### Modifying with a Specific Value

If you want to change a particular portion of a Datetime, there are several functions that will allow you to do so. For example, if you wanted to change the year of our example Datetime from **2007** to **2010**, you would use the [UPDATE\_YEAR](../airscript-expressions/datetime-functions/update_year) function to create a new Datetime by changing only the year:

```javascript
UPDATE_YEAR(example_datetime, 2010)
```

This function works equally well on Dates:

```javascript
UPDATE_YEAR(example_datetime, 2010)
```

If you wanted to update the calendar date of the Datetime, you can use the [UPDATE\_DATE](../airscript-expressions/datetime-functions/update_date) function to create a new Datetime, with a new calendar date, but the same time:

```javascript
UPDATE_DATE(example_datetime, DATE(2010, 4, 3))
```

**Datetimes**, **Dates**, and **Times** can be modified using the following functions

| Function Name                                                                                        | Description                                               |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [UPDATE\_DATE](../airscript-expressions/datetime-functions/update_date)                              | Changes the **date** portion of a **Datetime.**           |
| [UPDATE\_TIME](../airscript-expressions/datetime-functions/update_time)                              | Changes the **time** portion of a **Datetime.**           |
| [UPDATE\_TIMEZONE](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/update_time.mdzone) | Changes the **timezone** of a **Datetime.**               |
| [UPDATE\_YEAR](../airscript-expressions/datetime-functions/update_year)                              | Changes the **year** of a **Datetime** or **Date**        |
| [UPDATE\_MONTH](../airscript-expressions/datetime-functions/update_month)                            | Changes the **month** of a **Datetime** or **Date**       |
| [UPDATE\_DAY](../airscript-expressions/datetime-functions/update_day)                                | Changes the **day** of a **Datetime** or **Date**         |
| [UPDATE\_HOUR](../airscript-expressions/datetime-functions/update_hour)                              | Changes the **hour** of a **Datetime** or **Time**        |
| [UPDATE\_MINUTE](../airscript-expressions/datetime-functions/update_minute)                          | Changes the **minute** of a **Datetime** or **Time**      |
| [UPDATE\_SECOND](../airscript-expressions/datetime-functions/update_second)                          | Changes the **second** of a **Datetime** or **Time**      |
| [UPDATE\_MILLISECOND](../airscript-expressions/datetime-functions/update_millisecond)                | Changes the **millisecond** of a **Datetime** or **Time** |

#### Modifying with a Relative Value

The [ADD\_TO\_DATETIME](../airscript-expressions/datetime-functions/add_to_datetime) and [SUBTRACT\_FROM\_DATETIME](../airscript-expressions/datetime-functions/subtract_from_datetime) functions allow you to create a new date by adding or removing time units. You could add six months, or 169 days to our example date\*\*:\*\*

```javascript
ADD_TO_DATETIME(example_datetime, 6, "M")  
ADD_TO_DATETIME(example_datetime, 169, "d")
```

### Timestamps

When interfacing with external systems, you'll often encounter Datetimes that are represented either as a Number or a String.

#### **Datetime as a Number**

An Epoch timestamp is a Number representing the number of seconds (or milliseconds) that have elapsed since January 1st, 1970. For example the timestamp in milliseconds for January 9ith, 2007 is **1168364460000**. When you encounter a Datetime in this format look to the [DATETIME\_FROM\_TIMESTAMP](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/datetime.md_from_timestamp) function which turns an Epoch timestamp measured in milliseconds into a proper Datetime.

```javascript
DATETIME_FROM_TIMESTAMP(1168364460000)
```

To go in the other direction look no further than the [TIMESTAMP\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.mdstamp_from_datetime) function.

```javascript
TIMESTAMP_FROM_DATETIME(example_datetime)
```

If your particular timestamp looks like it is missing three zeros than the previous example, you are likely working with timestamps in seconds, provide second parameter **"s"**

```javascript
DATETIME_FROM_TIMESTAMP(1168364460, "s")  
TIMESTAMP_FROM_DATETIME(example_datetime, "s")
```

#### **Datetime as a String**

The other commonly used timestamp type is a string with the format **"YYYY-MM-DDTHH:mm:ssZ"**. To convert between a timestamp of this format and a Datetime use the [DATETIME\_FROM\_FORMAT](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/datetime.md_from_format) and [FORMAT\_DATETIME](../airscript-expressions/datetime-functions/format_datetime) functions.

```javascript
DATETIME_FROM_FORMAT("2007-01-09T09:41:00Z")  
FORMAT_DATETIME(example_datetime)
```

### Timezones

Note that one of our previous examples reproduced below included a timezone:

```javascript
DATETIME(DATE(2007, 1, 9), TIME(9, 41, 0), "America/Los_Angeles")
```

This is important because, in addition to a Date and a Time, Datetimes also have an associated timezone.

### Relevant Functions

* [NOW](../airscript-expressions/datetime-functions/now)
* [TODAY](../airscript-expressions/datetime-functions/today)
* [DATETIME](../airscript-expressions/datetime-functions/datetime)
* [DATE](../airscript-expressions/datetime-functions/date)
* [TIME](../airscript-expressions/datetime-functions/time)
* [DATE\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/date.md_from_datetime)
* [TIME\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.md_from_datetime)
* [YEAR](../airscript-expressions/datetime-functions/year)
* [MONTH](../airscript-expressions/datetime-functions/month)
* [DAY](../airscript-expressions/datetime-functions/day)
* [HOUR](../airscript-expressions/datetime-functions/hour)
* [MINUTE](../airscript-expressions/datetime-functions/minute)
* [SECOND](../airscript-expressions/datetime-functions/second)
* [FORMAT\_DATE](../airscript-expressions/datetime-functions/format_date)
* [FORMAT\_TIME](../airscript-expressions/datetime-functions/format_time)
* [UPDATE\_DATE](../airscript-expressions/datetime-functions/update_date)
* [UPDATE\_TIME](../airscript-expressions/datetime-functions/update_time)
* [UPDATE\_TIMEZONE](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/update_time.mdzone)
* [UPDATE\_YEAR](../airscript-expressions/datetime-functions/update_year)
* [UPDATE\_MONTH](../airscript-expressions/datetime-functions/update_month)
* [UPDATE\_DAY](../airscript-expressions/datetime-functions/update_day)
* [UPDATE\_HOUR](../airscript-expressions/datetime-functions/update_hour)
* [UPDATE\_MINUTE](../airscript-expressions/datetime-functions/update_minute)
* \<UPDATE\_SECOND>
* [UPDATE\_MILLISECOND](../airscript-expressions/datetime-functions/update_millisecond)
* [ADD\_TO\_DATETIME](../airscript-expressions/datetime-functions/add_to_datetime)
* [SUBTRACT\_FROM\_DATETIME](../airscript-expressions/datetime-functions/subtract_from_datetime)
* [DATE\_DELTA](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/date.md_delta)
* [TIME\_DELTA](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.md_delta)
* [DATETIME\_FROM\_TIMESTAMP](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/datetime.md_from_timestamp)
* [TIMESTAMP\_FROM\_DATETIME](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.mdstamp_from_datetime)
* [DATETIME\_FROM\_FORMAT](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/datetime.md_from_format)
* [DATE\_FROM\_FORMAT](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/date.md_from_format)
* [TIME\_FROM\_FORMAT](https://github.com/airkit/airkit-docs/blob/master/docs/v17-15/time.md_from_format)
