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
31-Aug-2021
01-Sep-2021
02-Sep-2021

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

01-Sep-2021 10:30:08   01-Oct-2021 10:30:08   01-Nov-2021 10:30:08

Column 4

01-Dec-2021 10:30:08

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

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

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

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