# caldiff

Calendar math successive differences

## Syntax

``dt = caldiff(t)``
``dt = caldiff(t,components)``
``dt = caldiff(t,components,dim)``

## Description

example

````dt = caldiff(t)` calculates time differences between adjacent datetime values in `t` in terms of the calendar components years, months, days, and time. `caldiff` calculates differences along the first array dimension whose size does not equal 1.If `t` is a vector of length `m`, then `dt = caldiff(t)` returns a vector of length `m-1`. The elements of `dt` are the differences between adjacent elements of `t`.dt = [between(t(1),t(2)), between(t(2),t(3)),..., between(t(m-1),t(m))]If `t` is a nonvector `p`-by-`m` matrix, then ```dt = caldiff(t)``` returns a matrix of size `(p-1)`-by-`m`, whose elements are the differences between the rows of `t`.dt(:,I) = [between(t(1,I),t(2,I), between(t(2,I),t(3,I)), ..., between(t(p-1,I),t(p,I))]```

example

````dt = caldiff(t,components)` finds the differences between successive datetimes in `t` in terms of the specified calendar or time components.```
````dt = caldiff(t,components,dim)` finds the differences between successive datetimes along the dimension specified by `dim`.```

## Examples

collapse all

Create a `datetime` array and then compute the differences between the values in terms of calendar components.

`t = [datetime('yesterday');datetime('today');datetime('tomorrow')]`
```t = 3x1 datetime 28-Feb-2020 29-Feb-2020 01-Mar-2020 ```
`D = caldiff(t)`
```D = 2x1 calendarDuration 1d 1d ```

Create a `datetime` array and then compute the differences between the values in terms of days.

`t = datetime('now') + calmonths(0:3)`
```t = 1x4 datetime Columns 1 through 3 29-Feb-2020 00:11:15 29-Mar-2020 00:11:15 29-Apr-2020 00:11:15 Column 4 29-May-2020 00:11:15 ```
`D = caldiff(t,'days')`
```D = 1x3 calendarDuration 29d 31d 30d ```

Computer the differences between the datetime values in terms of weeks and days.

`D = caldiff(t,{'weeks','days'})`
```D = 1x3 calendarDuration 4w 1d 4w 3d 4w 2d ```

## Input Arguments

collapse all

Input date and time, specified as a `datetime` array.

Calendar or time components, specified as one of the following character vectors, or a cell array or string array containing one or more of these values:

• `'years'`

• `'quarters'`

• `'months'`

• `'weeks'`

• `'days'`

• `'time'`

Except for `'time'`, the above components are flexible lengths of time. For example, one month represents a different length of time when added to a datetime in January than when added to a datetime in February.

`caldiff` operates on the calendar or time components in decreasing order, starting with the largest component.

In general, `t(2:m)` is not equal to ```t(1:m-1) + dt```, unless you include `'time'` in `components`.

Example: `{'years','quarters'}`

Data Types: `char` | `cell` | `string`

Dimension to operate along, specified as a positive integer. If no value is specified, the default is the first array dimension whose size does not equal 1.

## Output Arguments

collapse all

Difference array, returned as a scalar, vector, matrix, or multidimensional `calendarDuration` array.

## Tips

• To compute successive differences between datetimes in `t1` and `t2` as exact, fixed-length units of hours, minutes, and seconds, use `diff(t)`.