Main Content

# 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

example

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

example

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

example

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

expand all

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.

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.

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

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

expand all

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

CharacterUnitRequired?
`y`Yearsno
`q`Quarters (multiples of 3 months)no
`m`Monthsyes
`w`Weeksno
`d`Daysyes
`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

collapse all

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.

`L = calendarDuration(1,3,15)`
```L = calendarDuration 1y 3mo 15d ```

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.

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

## See Also

Introduced in R2014b

Download ebook