caldiff - Calendar math successive differences - MATLAB (original) (raw)

Calendar math successive differences

Syntax

Description

[dt](#bugc64h-1-dt) = caldiff([t](#bugc64h-1%5Fsep%5Fshared-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, thendt = caldiff(t) returns a vector of lengthm-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 nonvectorp-by-m matrix, then dt = caldiff(t) returns a matrix of size(p-1)-by-m, whose elements are the differences between the rows oft.
  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](#bugc64h-1-dt) = caldiff([t](#bugc64h-1%5Fsep%5Fshared-t),[components](#bugc64h-1-components)) finds the differences between successive datetimes in t in terms of the specified calendar or time components.

example

[dt](#bugc64h-1-dt) = caldiff([t](#bugc64h-1%5Fsep%5Fshared-t),[components](#bugc64h-1-components),[dim](#bugc64h-1-dim)) finds the differences between successive datetimes along the dimension specified bydim.

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 = 3×1 datetime 31-Jan-2025 01-Feb-2025 02-Feb-2025

D = 2×1 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 = 1×4 datetime 01-Feb-2025 09:02:33 01-Mar-2025 09:02:33 01-Apr-2025 09:02:33 01-May-2025 09:02:33

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

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

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

D = 1×3 calendarDuration 4w 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' incomponents.

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

expand all

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

Version History

Introduced in R2014b