calendarDuration

Methods

⌂ calendarDuration

Method Reference: calendarDuration.calendarDuration

calendarDuration: calD = calendarDuration (X)
calendarDuration: calD = calendarDuration (Y, MO, D)
calendarDuration: calD = calendarDuration (Y, MO, D, H, MI, S)
calendarDuration: calD = calendarDuration (Y, MO, D, T)
calendarDuration: calD = calendarDuration (…, 'Format', FMT)

Create a new array of calendar durations.

calD = calendarDuration (X) returns an array of calendar durations from numeric matrix X, which must have either three or six columns, representing years, months, days, hours, minutes, and seconds, accordingly. All but seconds must be represented as whole duration units by integer values.

calD = calendarDuration (Y, MO, D) returns an array of calendar durations from numeric arrays Y, MO, and D, which correspond to years, months, and days, respectively. The size of calD is the common size of the numeric input arguments, which must be of the same size or scalars. A scalar input functions as a constant array of the same size as the other inputs.

calD = calendarDuration (Y, MO, D, H, MI, S) returns an array of calendar durations from numeric arrays Y, MO, D, H, MI, and S, which correspond to years, months, days, hours, minutes, and seconds, respectively. The size of calD is the common size of the numeric input arguments, which must be of the same size or scalars. A scalar input functions as a constant array of the same size as the other inputs.

calD = calendarDuration (Y, MO, D, T) returns an array of calendar durations from numeric arrays Y, MO, and D, which correspond to years, months, and days, as well as a time duration array T. The size of calD is the common size of the data input arguments, which must be of the same size or scalars. A scalar input functions as a constant array of the same size as the other inputs.

Numeric input arrays Y, MO, D, H, and MI must contain integer values corresponding to whole calendar units. S can also be contain fractions of seconds.

calD = calendarDuration (…, 'Format', FMT) specifies the format in which calD is displayed. FMT must be a character vector containing the following letters.

  • 'y' years
  • 'q' quarters of a year
  • 'm' months
  • 'w' weeks
  • 'd' days
  • 't' time duration

Each character must be specified only once in the same order as they appear in the above list. 'm', 'd', and 't' characters must always be included in the format specification. Any characters besides these listed above are ignored.

calD = calendarDuration () returns a scalar array of calendar durations with a value of zero days. To create an empty calendarDuration array, use calendarDuration ([], [], []).

See also: calyears, calquarters, calmonths, calweeks, caldays, calendarDuration, iscalendarduration, datetime, duration

Source Code: calendarDuration

Example: 1

calendarDuration represents a span in calendar units — years, months, days, and a time-of-day. A calendar month or year is a real calendar step, not a fixed number of days, which is what sets it apart from duration. Give years, months and days:

 calendarDuration (1, 3, 10)
ans =
  calendarDuration

   1y 3mo 10d

Example: 2

Overflowing whole units normalise: 14 months rolls up into 1 year 2 months. Days are kept separate (a month has no fixed number of days), so 40 stays 40.

 calendarDuration (1, 14, 40)
ans =
  calendarDuration

   2y 2mo 40d

Example: 3

The six-argument form adds a time-of-day: years, months, days, hours, minutes, seconds.

 calendarDuration (0, 2, 5, 6, 30, 0)
ans =
  calendarDuration

   2mo 5d 6h 30m 0s

Example: 4

The 'Format' option controls how the SAME span is broken down for display. A format must contain m, d and t; it may also use y (years), q (quarters) and w (weeks), listed in the order y q m w d t. Here one span shown four ways:

 calendarDuration (1, 14, 40, 'Format', 'ymdt')
ans =
  calendarDuration

   2y 2mo 40d
 calendarDuration (1, 14, 40, 'Format', 'mdt')
ans =
  calendarDuration

   26mo 40d
 calendarDuration (1, 14, 40, 'Format', 'qmwdt')
ans =
  calendarDuration

   8q 2mo 5w 5d
 calendarDuration (1, 14, 40, 'Format', 'ymwdt')
ans =
  calendarDuration

   2y 2mo 5w 5d

Example: 5

A numeric matrix with three (or six) columns builds a whole array at once — one calendar duration per row.

 calendarDuration ([1, 2, 15; 0, 6, 3])
ans =
  2x1 calendarDuration array

    1y 2mo 15d    
    6mo 3d