caldiff

Arguments

dt

An array of datetime values.

c

A scalar string specifying the type of calendar difference to compute. The default value is "default".

The following values are accepted:

• "default": returns a calendarDuration containing years, months, days, and time components.

• "Years": returns complete calendar years.

• "Months": returns complete calendar months.

• "Days": returns complete days.

• "Time": returns the elapsed time component as a calendarDuration.

The value of c is case-insensitive.

dim

A scalar specifying the dimension along which successive differences are computed.

dim can be:

• 1 or "r": differences are computed along rows.

• 2 or "c": differences are computed along columns.

• "*": differences are computed using the linear ordering of dt.

• "m": differences are computed along the first non singleton dimension of dt (for compatibility with Matlab).

cal

An array containing successive calendar differences between values of dt.

Description

caldiff computes successive differences between datetime values.

By default, differences are returned as calendarDuration values containing calendar years, calendar months, days, and time components.

For a vector dt, the successive differences are computed between consecutive values:

cal(1) = dt(2) - dt(1)
cal(2) = dt(3) - dt(2)
...
cal(n-1) = dt(n) - dt(n-1)

The optional argument c can be used to select a specific component of the calendar difference.

With c = "years", only complete calendar years are returned. With c = "months", the result is expressed in complete calendar months. With c = "days", only complete days are returned. With c = "time", the result contains only the elapsed time difference.

When dim is specified, successive differences are computed along the selected dimension.

When dim = "*", the input is treated as a linear array and differences are computed between consecutive elements in linear order.

Missing datetime values propagate to the corresponding output values.

Examples

Successive calendar differences

dt = datetime(2024, 1, [1 2 4 7])
d = caldiff(dt)

--> dt = datetime(2024, 1, [1 2 4 7])

 dt = [1x4 datetime]

   2024-01-01   2024-01-02   2024-01-04   2024-01-07

--> d = caldiff(dt)

 d = [1x3 calendarDuration]

    1d    2d    3d

Calendar year differences

dt = [datetime(2020, 6, 15)
    datetime(2021, 6, 15)
    datetime(2023, 6, 15)]
d = caldiff(dt, "years")

--> dt = [datetime(2020, 6, 15)
  >     datetime(2021, 6, 15)
  >     datetime(2023, 6, 15)]

 dt = [3x1 datetime]

   2020-06-15
   2021-06-15
   2023-06-15

--> d = caldiff(dt, "years")

 d = [2x1 calendarDuration]

    1y
    2y

Calendar month differences

dt = [datetime(2024, 1, 15)
    datetime(2024, 2, 15)
    datetime(2024, 5, 15)]
d = caldiff(dt, "months")

--> dt = [datetime(2024, 1, 15)
  >     datetime(2024, 2, 15)
  >     datetime(2024, 5, 15)]

 dt = [3x1 datetime]

   2024-01-15
   2024-02-15
   2024-05-15

--> d = caldiff(dt, "months")

 d = [2x1 calendarDuration]

    1mo
    3mo

Differences along the first dimension

dt = datetime(2024, 1, [1 2 4; 10 20 40])
d = caldiff(dt, "days", 1)

--> dt = datetime(2024, 1, [1 2 4; 10 20 40])

 dt = [2x3 datetime]

   2024-01-01   2024-01-02   2024-01-04
   2024-01-10   2024-01-20   2024-02-09

--> d = caldiff(dt, "days", 1)

 d = [1x3 calendarDuration]

    9d    18d    36d

Differences along the second dimension

dt = datetime(2024, 1, [1 2 4; 10 20 40])
d = caldiff(dt, "days", 2)

--> dt = datetime(2024, 1, [1 2 4; 10 20 40])

 dt = [2x3 datetime]

   2024-01-01   2024-01-02   2024-01-04
   2024-01-10   2024-01-20   2024-02-09

--> d = caldiff(dt, "days", 2)

 d = [2x2 calendarDuration]

     1d     2d
    10d    20d

Linear successive differences

dt = datetime(2024, 1, [1 2; 4 7])

d = caldiff(dt, "days", "*")

--> dt = datetime(2024, 1, [1 2; 4 7])

 dt = [2x2 datetime]

   2024-01-01   2024-01-02
   2024-01-04   2024-01-07

--> d = caldiff(dt, "days", "*")

 d = [1x3 calendarDuration]

    3d    -2d    5d

End-of-month difference

dt = [datetime(2024, 1, 31)
    datetime(2024, 2, 29)]

d = caldiff(dt)

--> dt = [datetime(2024, 1, 31)
  >     datetime(2024, 2, 29)]

 dt = [2x1 datetime]

   2024-01-31
   2024-02-29

--> d = caldiff(dt)

 d = [calendarDuration]

    1mo

Leap year

dt = [datetime(2024, 2, 28)
    datetime(2024, 2, 29)
    datetime(2024, 3, 1)]

d = caldiff(dt)

--> dt = [datetime(2024, 2, 28)
  >     datetime(2024, 2, 29)
  >     datetime(2024, 3, 1)]

 dt = [3x1 datetime]

   2024-02-28
   2024-02-29
   2024-03-01

--> d = caldiff(dt)

 d = [2x1 calendarDuration]

    1d
    1d

See also

• datetime — create points in time
• calendarDuration — create a calendarDuration - duration in days, months and years
• between — Calendar difference between two datetime values

History