Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

caldiff

Calendar math successive differences

Syntax

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

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 array
   15-Mar-2018
   16-Mar-2018
   17-Mar-2018

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

   16-Mar-2018 17:07:02   16-Apr-2018 17:07:02   16-May-2018 17:07:02

Column 4

   16-Jun-2018 17:07:02

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

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

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

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

Introduced in R2014b

Was this topic helpful?