# between

Calendar math differences

## Syntax

``dt = between(t1,t2)``
``dt = between(t1,t2,components)``

## Description

example

````dt = between(t1,t2)` returns the differences between the datetime values in `t1` and `t2`. The `dt` output is a `calendarDuration` array in terms of the calendar components years, months, days, and time, such that `t2 = t1+dt`.```

example

````dt = between(t1,t2,components)` returns the differences between datetime values in terms of the specified calendar or time components.```

## Examples

collapse all

Create two `datetime` arrays.

`t1 = datetime('now')`
```t1 = datetime 26-Feb-2022 12:12:23 ```
`t2 = datetime('tomorrow','Format','dd-MMM-yyyy HH:mm:ss') + caldays(0:2)`
```t2 = 1x3 datetime 27-Feb-2022 00:00:00 28-Feb-2022 00:00:00 01-Mar-2022 00:00:00 ```

Find the difference between the two arrays.

`dt = between(t1,t2)`
```dt = 1x3 calendarDuration 11h 47m 36.877s 1d 11h 47m 36.877s 2d 11h 47m 36.877s ```

`between` returns a `calendarDuration` array containing differences in terms of days, hours, minutes, and seconds.

Create a sequence of datetimes over a 6-month period. Then, find the number of days between the first date and each of the dates in the sequence.

```t1 = datetime(2013,1,1); t2 = dateshift(t1,'end','month',0:4)```
```t2 = 1x5 datetime 31-Jan-2013 28-Feb-2013 31-Mar-2013 30-Apr-2013 31-May-2013 ```
`dt = between(t1,t2,'Days')`
```dt = 1x5 calendarDuration 30d 58d 89d 119d 150d ```

## Input Arguments

collapse all

Input date and time, specified as a `datetime` array, character vector, cell array of character vectors, or string array. At least one of inputs `t1` and `t2` must be a `datetime` array. `t1` and `t2` must be the same size unless one is a scalar.

Input date and time, specified as a `datetime` array, character vector, cell array of character vectors, or string array. At least one of inputs `t1` and `t2` must be a `datetime` array. `t1` and `t2` must be the same size unless one is a scalar.

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.

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

In general, `t2` is not equal to ```t1 + dt```, unless you include `'time'` in `components`.

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

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

## Output Arguments

collapse all

Difference array, returned as a `calendarDuration` array.

## Tips

• To compute differences between datetime values in `t1` and `t2` as exact, fixed-length durations, use `t2-t1`.

## Version History

Introduced in R2014b