`caldiff`

Differences between consecutive datetime values, as calendar durations.

Category: Language Fundamentals > Data Types

Syntax

d = caldiff(t)

Returns the calendar differences between consecutive elements of t.

d = caldiff(t, components)

Expresses the differences in the given units, such as 'days' or 'months'.

Description

caldiff(t) is to between what diff is to subtraction: it applies between(t(k), t(k+1)) to each neighbouring pair. Working along the first non-singleton dimension, a vector of n dates gives n-1 differences.

With no components, each difference is split into months and days. Passing 'days' forces a pure day count.

Input arguments

t: datetime vector or array.
components: Units to use, for example 'days', 'months', 'years'.

Output arguments

d: calendarDuration array with one fewer element along the working dimension.

Example

Gaps between dates

t = [datetime(2024,1,1) datetime(2024,3,5) datetime(2024,3,6)];
caldiff(t)
caldiff(t(1:2), 'days')

Output

ans = 1×2 calendarDuration array

   2mo 4d       1d
ans = calendarDuration
   64d

caldiff