`between`

Calendar difference between two datetime values, as a calendarDuration.

Category: Language Fundamentals > Data Types

Syntax

dt = between(t1, t2)

Returns the calendar duration that, added to t1, gives t2, in years, months and days (plus time of day when needed).

dt = between(t1, t2, components)

Restricts the result to the given components, such as 'days' or 'months'.

Description

Unlike plain subtraction, which gives a fixed-length duration in hours, between counts whole calendar units first: years, then months, then days. The result depends on the dates, because months have different lengths, so t1 + between(t1, t2) reproduces t2.

If t2 is earlier than t1 the components are negative.

Input arguments

t1, t2: datetime arrays of the same size, or one scalar.
components: Text naming which units to use: 'years', 'quarters', 'months', 'weeks', 'days' or 'time', or a cell array of them.

Output arguments

dt: calendarDuration array with the same size as the inputs.

Example

Between two dates

t1 = datetime(2020,1,15);
t2 = datetime(2021,3,20);
between(t1, t2)

Output

ans = calendarDuration
   1y 2mo 5d

Notes

In MatLivre 'days' gives a pure day count, but 'months' still splits the result into years, months and days instead of a single month count.

between