Main Content

caldiff

Calendar math successive differences

collapse all in page

Syntax

dt = caldiff(t)
dt = caldiff(t,components)
dt = caldiff(t,components,dim)

Description

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.

example

dt = caldiff(t,components,dim) finds the differences between successive datetimes along the dimension specified by dim.

Examples

collapse all

Open Live Script

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
   04-Sep-2024
   05-Sep-2024
   06-Sep-2024


D = caldiff(t)
D = 2x1 calendarDuration
   1d
   1d
Open Live Script

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
   05-Sep-2024 15:40:55   05-Oct-2024 15:40:55   05-Nov-2024 15:40:55   05-Dec-2024 15:40:55


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

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

Extended Capabilities

Version History

Introduced in R2014b

See Also

| | |