Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan 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
   18-Sep-2017
   19-Sep-2017
   20-Sep-2017

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

   19-Sep-2017 18:11:00   19-Oct-2017 18:11:00   19-Nov-2017 18:11:00

Column 4

   19-Dec-2017 18:11:00

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

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

D = caldiff(t,{'weeks','days'})
D = 1x3 calendarDuration array
   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).

Introduced in R2014b

Was this topic helpful?