# Documentation

## Date and Time Arithmetic

This example shows how to add and subtract date and time values to calculate future and past dates and elapsed durations in exact units or calendar units. You can add, subtract, multiply, and divide date and time arrays in the same way that you use these operators with other MATLAB® data types. However, there is some behavior that is specific to dates and time.

### Add and Subtract Durations to Datetime Array

Create a datetime scalar. By default, datetime arrays are not associated wtih a time zone.

```t1 = datetime('now') ```
```t1 = 24-Aug-2015 17:18:39 ```

Find future points in time by adding a sequence of hours.

```t2 = t1 + hours(1:3) ```
```t2 = 24-Aug-2015 18:18:39 24-Aug-2015 19:18:39 24-Aug-2015 20:18:39 ```

Verify that the difference between each pair of datetime values in `t2` is 1 hour.

```dt = diff(t2) ```
```dt = 01:00:00 01:00:00 ```

`diff` returns durations in terms of exact numbers of hours, minutes, and seconds.

Subtract a sequence of minutes from a datetime to find past points in time.

```t2 = t1 - minutes(20:10:40) ```
```t2 = 24-Aug-2015 16:58:39 24-Aug-2015 16:48:39 24-Aug-2015 16:38:39 ```

Add a numeric array to a `datetime` array. MATLAB® treats each value in the numeric array as a number of exact, 24-hour days.

```t2 = t1 + [1:3] ```
```t2 = 25-Aug-2015 17:18:39 26-Aug-2015 17:18:39 27-Aug-2015 17:18:39 ```

### Add to Datetime with Time Zone

If you work with datetime values in different time zones, or if you want to account for daylight saving time changes, work with datetime arrays that are associated with time zones. Create a `datetime` scalar representing March 8, 2014 in New York.

```t1 = datetime(2014,3,8,0,0,0,'TimeZone','America/New_York') ```
```t1 = 08-Mar-2014 00:00:00 ```

Find future points in time by adding a sequence of fixed-length (24-hour) days.

```t2 = t1 + days(0:2) ```
```t2 = 08-Mar-2014 00:00:00 09-Mar-2014 00:00:00 10-Mar-2014 01:00:00 ```

Because a daylight saving time shift occurred on March 9, 2014, the third datetime in `t2` does not occur at midnight.

Verify that the difference between each pair of datetime values in `t2` is 24 hours.

```dt = diff(t2) ```
```dt = 24:00:00 24:00:00 ```

You can add fixed-length durations in other units such as years, hours, minutes, and seconds by adding the outputs of the `years`, `hours`, `minutes`, and `seconds` functions, respectively.

To account for daylight saving time changes, you should work with calendar durations instead of durations. Calendar durations account for daylight saving time shifts when they are added to or subtracted from datetime values.

Add a number of calendar days to `t1`.

```t3 = t1 + caldays(0:2) ```
```t3 = 08-Mar-2014 00:00:00 09-Mar-2014 00:00:00 10-Mar-2014 00:00:00 ```

View that the difference between each pair of datetime values in `t3` is not always 24 hours due to the daylight saving time shift that occurred on March 9.

```dt = diff(t3) ```
```dt = 24:00:00 23:00:00 ```

### Add Calendar Durations to Datetime Array

Add a number of calendar months to January 31, 2014.

```t1 = datetime(2014,1,31) ```
```t1 = 31-Jan-2014 ```
```t2 = t1 + calmonths(1:4) ```
```t2 = 28-Feb-2014 31-Mar-2014 30-Apr-2014 31-May-2014 ```

Each datetime in `t2` occurs on the last day of each month.

Calculate the difference between each pair of datetime values in `t2` in terms of a number of calendar days using the `caldiff` function.

```dt = caldiff(t2,'days') ```
```dt = 31d 30d 31d ```

The number of days between successive pairs of datetime values in `dt` is not always the same because different months consist of a different number of days.

Add a number of calendar years to January 31, 2014.

```t2 = t1 + calyears(0:4) ```
```t2 = 31-Jan-2014 31-Jan-2015 31-Jan-2016 31-Jan-2017 31-Jan-2018 ```

Calculate the difference between each pair of datetime values in `t2` in terms of a number of calendar days using the `caldiff` function.

```dt = caldiff(t2,'days') ```
```dt = 365d 365d 366d 365d ```

The number of days between successive pairs of datetime values in `dt` is not always the same because 2016 is a leap year and has 366 days.

You can use the `calquarters`, `calweeks`, and `caldays` functions to create arrays of calendar quarters, calendar weeks, or calendar days that you add to or subtract from datetime arrays.

Adding calendar durations is not commutative. When you add more than one `calendarDuration` array to a datetime, MATLAB® adds them in the order in which they appear in the command.

Add 3 calendar months followed by 30 calendar days to January 31, 2014.

```t2 = datetime(2014,1,31) + calmonths(3) + caldays(30) ```
```t2 = 30-May-2014 ```

First add 30 calendar days to the same date, and then add 3 calendar months. The result is not the same because when you add a calendar duration to a datetime, the number of days added depends on the original date.

```t2 = datetime(2014,1,31) + caldays(30) + calmonths(3) ```
```t2 = 02-Jun-2014 ```

### Calendar Duration Arithmetic

Create two calendar durations and then find their sum.

```d1 = calyears(1) + calmonths(2) + caldays(20) ```
```d1 = 1y 2mo 20d ```
```d2 = calmonths(11) + caldays(23) ```
```d2 = 11mo 23d ```
```d = d1 + d2 ```
```d = 2y 1mo 43d ```

When you sum two or more calendar durations, a number of months greater than 12 roll over to a number of years. However, a large number of days does not roll over to a number of months, because different months consist of different numbers of days.

Increase `d` by multiplying it by a factor of 2. Calendar duration values must be integers, so you can multiply them only by integer values.

```2*d ```
```ans = 4y 2mo 86d ```

### Calculate Elapsed Time in Exact Units

Subtract one `datetime` array from another to calculate elapsed time in terms of an exact number of hours, minutes, and seconds.

Find the exact length of time between a sequence of datetime values and the start of the previous day.

```t2 = datetime('now') + caldays(1:3) ```
```t2 = 25-Aug-2015 17:18:40 26-Aug-2015 17:18:40 27-Aug-2015 17:18:40 ```
```t1 = datetime('yesterday') ```
```t1 = 23-Aug-2015 ```
```dt = t2 - t1 ```
```dt = 65:18:40 89:18:40 113:18:40 ```
```whos dt ```
``` Name Size Bytes Class Attributes dt 1x3 144 duration ```

`dt` contains durations in the format, hours:minutes:seconds.

View the elapsed durations in units of days by changing the `Format` property of `dt`.

```dt.Format = 'd' ```
```dt = 2.7213 days 3.7213 days 4.7213 days ```

Scale the duration values by multiplying `dt` by a factor of 1.2. Because durations have an exact length, you can multiply and divide them by fractional values.

```dt2 = 1.2*dt ```
```dt2 = 3.2656 days 4.4656 days 5.6656 days ```

### Calculate Elapsed Time in Calendar Units

Use the `between` function to find the number of calendar years, months, and days elapsed between two dates.

```t1 = datetime('today') ```
```t1 = 24-Aug-2015 ```
```t2 = t1 + calmonths(0:2) + caldays(4) ```
```t2 = 28-Aug-2015 28-Sep-2015 28-Oct-2015 ```
```dt = between(t1,t2) ```
```dt = 4d 1mo 4d 2mo 4d ```

## See Also

Was this topic helpful?

Get trial now