# between

Calendar math differences

## Syntax

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

## Description

The `between` function returns the calendar differences between two datetime arrays. When `between` calculates the calendar difference between two datetime values, it takes into account leap years, Daylight Saving Time shifts, and the differing lengths of calendar months. To calculate differences as exact fixed-length durations, use subtraction instead, as in ```dt = t2 - t1```.

````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.```

example

## Examples

collapse all

Create two `datetime` arrays.

`t1 = datetime('now')`
```t1 = datetime 20-Jul-2024 15:09:24 ```
`t2 = datetime('tomorrow','Format','dd-MMM-yyyy HH:mm:ss') + caldays(0:2)`
```t2 = 1x3 datetime 21-Jul-2024 00:00:00 22-Jul-2024 00:00:00 23-Jul-2024 00:00:00 ```

Find the difference between the two arrays.

`dt = between(t1,t2)`
```dt = 1x3 calendarDuration 8h 50m 35.127s 1d 8h 50m 35.127s 2d 8h 50m 35.127s ```

`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