caldiff

Calendar math successive differences

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

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

Calendar Differences Between Datetime Values

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 = 3×1 datetime
   08-Aug-2025
   09-Aug-2025
   10-Aug-2025

D = caldiff(t)

D = 2×1 calendarDuration
   1d
   1d

Differences Using Specific Calendar Components

Create a datetime array and then compute the differences between the values in terms of days.

t = datetime('now') + calmonths(0:3)

t = 1×4 datetime
   09-Aug-2025 12:09:44   09-Sep-2025 12:09:44   09-Oct-2025 12:09:44   09-Nov-2025 12:09:44

D = caldiff(t,'days')

D = 1×3 calendarDuration
   31d   30d   31d

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

D = caldiff(t,{'weeks','days'})

D = 1×3 calendarDuration
   4w 3d   4w 2d   4w 3d

Input Arguments

t — Input date and time

datetime array

Input date and time, specified as a datetime array.

components — Calendar or time components

'years' | 'quarters' | 'months' | 'weeks' | 'days' | 'time' | cell array of character vectors | string 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

dim — Dimension to operate along

positive integer

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

dt — Difference array

scalar | vector | matrix | multidimensional array

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

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The caldiff function supports tall arrays with the following usage notes and limitations:

• The dim input must be specified. Use caldiff(t,'',dim) to use the default components.

For more information, see Tall Arrays.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2014b