Note: This page has been translated by MathWorks. Please click here

To view all translated materials including this page, select Japan from the country navigator on the bottom of this page.

To view all translated materials including this page, select Japan from the country navigator on the bottom of this page.

Lengths of time in variable-length calendar units

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.

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.

`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)`

`L = calendarDuration(`

creates an array of calendar durations from numeric arrays
`Y,M,D`

)`Y`

, `M`

, and `D`

,
containing the number of years, months, and days, respectively.

`L = calendarDuration(Y,M,D,`

also includes hours, minutes, and seconds specified by `H,MI,S`

)`H`

,
`MI`

, and `S`

, respectively.

`L = calendarDuration(Y,M,D,`

creates an array of calendar durations from numeric arrays containing the
number of years, months, and days, and a duration array `T`

)`T`

containing elapsed times.

`L = calendarDuration(`

creates
an array of calendar durations from a numeric matrix.`X`

)

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:is the same as:t + calendarDuration(1,2,3)

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

Was this topic helpful?