calyears

Calendar duration in years

Syntax

Y = calyears(X)

Description

The calyears function returns an array that represents calendar years. When you use arrays that have the calendarDuration data type in calendar calculations, the calculations take into account leap years, Daylight Saving Time shifts, and the differing lengths of calendar months. To create exact fixed-length years instead, use the years function. A fixed-length year is 365.2425 days long.

Y = calyears(X) returns an array representing calendar years equivalent to the values in X.

• If X is a numeric array, then Y is a calendarDuration array with each element equal to the number of calendar years in the corresponding element of X.

• If X is a calendarDuration array, then calyears returns the number of whole years equivalent to each calendar duration in X.

Examples

Create Array of Calendar Years

X = magic(4);
Y = calyears(X)

Y = 4×4 calendarDuration
   16y    2y    3y   13y
    5y   11y   10y    8y
    9y    7y    6y   12y
    4y   14y   15y    1y

Convert Calendar Durations to Calendar Years

Create an array of calendar durations. Then, convert each value to the equivalent number of whole calendar years.

X = calmonths(21:25) + caldays(8)

X = 1×5 calendarDuration
    1y 9mo 8d   1y 10mo 8d   1y 11mo 8d        2y 8d    2y 1mo 8d

Y = calyears(X)

Y = 1×5

     1     1     1     2     2

Input Arguments

X — Input array

numeric array | calendar duration array | logical array

Input array, specified as a numeric array, calendar duration array, or logical array. If X is a numeric array, it must contain only integer values. That is, you cannot create fractional calendar units.

Output Arguments

Y — Calendar years

scalar | vector | matrix | multidimensional array

Calendar years, returned as a scalar, vector, matrix, or multidimensional array. Y is the same size as X. The data type of Y depends on X.

• If X is a numeric array, then Y is an array of calendar durations in units of equivalent flexible-length calendar years.

• If X is a calendarDuration array, then Y is a double array of integer values representing whole calendar years.

Tips

• calyears creates years that account for leap days when used in calendar calculations. To create exact fixed-length (365.2425 day) years, use the years function.

Extended Capabilities

Tall Arrays

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

The calyears 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