Documentation

caldiff

Calendar math successive differences

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 array
25-Aug-2019
26-Aug-2019
27-Aug-2019

D = caldiff(t)
D = 2x1 calendarDuration array
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 array
Columns 1 through 3

26-Aug-2019 11:10:25   26-Sep-2019 11:10:25   26-Oct-2019 11:10:25

Column 4

26-Nov-2019 11:10:25

D = caldiff(t,'days')
D = 1x3 calendarDuration array
31d   30d   31d

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

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

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