caldiff

R2026b

Calendar math successive differences

Syntax

dt = caldiff(t)

dt = caldiff(t,components)

dt = caldiff(t,components,dim)

dt = caldiff(t,components,__,ArithmeticMethod=arithmeticMethod)

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.

dt = caldiff(t,components,__,ArithmeticMethod=arithmeticMethod) sets the arithmetic method of the returned calendar duration dt.

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
   06-Aug-2026
   07-Aug-2026
   08-Aug-2026

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
   07-Aug-2026 00:44:05   07-Sep-2026 00:44:05   07-Oct-2026 00:44:05   07-Nov-2026 00:44:05

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.

arithmeticMethod — Arithmetic method of the returned calendar duration

"default" | "endofmonth" | "endofquarter"

Arithmetic method of the returned calendar duration, specified as one of the values in this table.

Value	Description
"default"	The returned calendar duration has ArithmeticMethod set to "default", and preserves the day of the month in datetime arithmetic.
"endofmonth"	The returned calendar duration has ArithmeticMethod set to "endofmonth", and preserves month ends in datetime arithmetic.
"endofquarter"	The returned calendar duration has ArithmeticMethod set to "endofquarter", and preserves quarter ends in datetime arithmetic.

Use ArithmeticMethod="endofmonth" only when components is "months", and use ArithmeticMethod="endofquarter" only when components is "quarters".

Data Types: string | char

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.

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

Version History

Introduced in R2014b

R2026b: Specify arithmetic method of returned calendar duration

The caldiff function now supports the ArithmeticMethod name-value argument. Use the ArithmeticMethod to specify the arithmetic method of the returned calendar duration.