calendarDuration

Lengths of time in variable-length calendar units

Description

The values in calendar duration arrays represent elapsed time in calendar units of variable length. For example, the number of days in a month depends on the particular month of the year. Calculations with calendar durations account for daylight saving time changes and leap years. Use calendar duration arrays to simplify calculations on datetime arrays that involve calendar units, such as days and months.

Creation

You can create calendar duration arrays that have specified time units using the calyears, calquarters, calmonths, calweeks, and caldays functions. For example, to create an array that has elapsed times of 1, 2, and 3 calendar months, use the calmonths function.

M = calmonths(1:3)

M = 

  1×3 calendarDuration array

   1mo   2mo   3mo

You also can create a calendar duration array using the calendarDuration function, described below.

Syntax

L = calendarDuration(Y,M,D)

L = calendarDuration(Y,M,D,H,MI,S)

L = calendarDuration(Y,M,D,T)

L = calendarDuration(X)

L = calendarDuration(___,'Format',displayFormat)

Description

L = calendarDuration(Y,M,D) creates an array of calendar durations from numeric arrays Y, M, and D, containing the number of years, months, and days, respectively.

L = calendarDuration(Y,M,D,H,MI,S) also includes hours, minutes, and seconds specified by H, MI, and S, respectively.

L = calendarDuration(Y,M,D,T) creates an array of calendar durations from numeric arrays containing the number of years, months, and days, and a duration array T containing elapsed times.

L = calendarDuration(X) creates an array of calendar durations from a numeric matrix.

L = calendarDuration(___,'Format',displayFormat) additionally specifies displayFormat as the value of the Format property of L. The Format property changes the display of L but not its values. You can use this syntax with any of the arguments from the previous syntaxes.

Input Arguments

Y,M,D — Years, months, and days (as separate arguments)

numeric arrays

Years, months, and days, specified as numeric arrays. These arrays either must be the same size, or any can be a scalar. Y,M,D must contain only integer values.

Specifying month values greater than 12 is equivalent to specifying a number of years plus a number of months. For example, 25 months are equal to 2 years and 1 month. However, day values are not equivalent to a number of months because the number of days in a month is not fixed, and cannot be determined until you add the calendar duration to a specific datetime.

Example: L = calendarDuration(2,10,24) returns a calendar duration of 2 years, 10 months, and 24 days.

H,MI,S — Hours, minutes, and seconds (as separate arguments)

numeric arrays

Hours, minutes, and seconds, specified as numeric arrays. These arrays either must be the same size, or any can be a scalar. Specify fractional seconds as part of S. The H and MI arrays must contain only integer values.

Specifying month values greater than 12 is equivalent to specifying a number of years plus a number of months. For example, 25 months are equal to 2 years and 1 month. Minute values greater than 60 carry over to a number of hours. Second values greater than 60 carry over to a number of minutes. However, day values are not equivalent to a number of months because the number of days in a month is not fixed and cannot be determined until you add the calendar duration to a specific datetime. Similarly, hour values are not equivalent to a number of calendar days.

Example: L = calendarDuration(2,10,24,12,45,07.451) returns a calendar duration of 2 years, 10 months, 24 days, 12 hours, 45 minutes, and 7.451 seconds.

T — Elapsed times

duration array

Elapsed times, specified as a duration array. T either must be the same size as the Y, M, and D input arguments or be a scalar.

Example: T = hours(5); L = calendarDuration(2,10,24,T) adds a duration of 5 hours to L.

X — Years, months, days, and optionally, times

numeric matrix

Years, months, days, and optionally, times, specified as a numeric matrix. X must have either three or six columns. The first three columns contain the number of years, months, and days, respectively. If X has six columns, then the last three columns contain the number of hours, minutes, and seconds, respectively.

All columns must contain integer values, except for the sixth column. You can specify fractional seconds in the sixth column.

Example: L = calendarDuration([2 10 24]) returns a calendar duration of 2 years, 10 months, and 24 days.

Example: L = calendarDuration([2 10 24 12 45 07.451]) returns a calendar duration of 2 years, 10 months, 24 days, 12 hours, 45 minutes, and 7.451 seconds.

Properties

Format — Display format

'ymdt' (default) | character vector | string scalar

Display format for calendar durations, specified as a combination of the characters y, q, m, w, d, and t, in that order. The format must include m, d, and t.

Character	Unit	Required?
y	Years (multiples of 12 months)	no
q	Quarters (multiples of 3 months)	no
m	Months	yes
w	Weeks (multiples of 7 days)	no
d	Days	yes
t	Time (hours, minutes, and seconds)	yes

To specify the number of digits displayed for fractional seconds, use the format function.

If the value of a date or time component is zero, then it is not displayed.

Example: L.Format = 'yqmdt' displays each value in L as the number of calendar years, quarters, months, and days, along with its time component.

Examples

Use Calendar Durations with Datetime Values

Create a datetime value.

D = datetime(2017,7,1)

D = datetime
   01-Jul-2017

Create a datetime array in which each value starts on the first day of a different month. One convenient way to create such an array is to add an array of calendar months to D.

First, create an array of calendar months using the calmonths function.

C = calmonths(0:3)

C = 1x4 calendarDuration
   0mo   1mo   2mo   3mo

Then, add D and C. Since C is a calendar duration array, this operation accounts for the fact that months can have different numbers of days.

M = D + C

M = 1x4 datetime
   01-Jul-2017   01-Aug-2017   01-Sep-2017   01-Oct-2017

Due to leap years and Daylight Saving Time, calendar years, months, and days can have varying lengths. To accommodate these varying lengths of time, use calendar duration arrays for arithmetic operations on datetime arrays.

Create Calendar Duration

L = calendarDuration(1,3,15)

L = calendarDuration
   1y 3mo 15d

Specify Numeric and Duration Inputs That Overflow

Create a numeric array representing numbers of days.

D = [1 3;4 2]

D = 2×2

     1     3
     4     2

Create a duration array representing elapsed times in hours. One element specifies 25 hours, which is longer than one day.

T = hours([1 2; 25 12])

T = 2x2 duration
    1 hr    2 hr
   25 hr   12 hr

Create a calendar duration array. Specify input arguments D, T, and scalar values for the year and month. The second input, 13, specifies more months than there are in one year.

L = calendarDuration(1,13,D,T)

L = 2x2 calendarDuration
    2y 1mo 1d 1h 0m 0s    2y 1mo 3d 2h 0m 0s
   2y 1mo 4d 25h 0m 0s   2y 1mo 2d 12h 0m 0s

Month values greater than 12 carry over to years in the display. However, hour values greater than 24 do not carry over to days in the display. Due to Daylight Saving Time, the number of hours in a calendar day is not necessarily 24 hours.

Specify Display Format

Create a calendar duration array and specify a format that displays the values in terms of months, weeks, days, and time.

L = calendarDuration(1,1,5:9,'Format','mwdt')

L = 1x5 calendarDuration
      13mo 5d      13mo 6d      13mo 1w   13mo 1w 1d   13mo 1w 2d

Since the format does not include 'y' for years, the input values of 1 year and 1 month display as their sum, 13mo. While 't' must be specified, the time component is not displayed if the hours, minutes, and seconds are all zero.

Tips

• For more information on functions that accept or return calendar duration arrays, see Dates and Time.

• When you add a calendarDuration array that contains more than one unit to a datetime, MATLAB^® always adds the larger units first. If t is a datetime, then this command:

  t + calendarDuration(1,2,3)

  is the same as:

  t + calyears(1) + calmonths(2) + caldays(3)

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The calendarDuration function fully supports tall arrays. For more information, see Tall Arrays.

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2014b