calmonths

R2026b

Calendar duration in months

Syntax

M = calmonths(X)

M = calmonths(X,ArithmeticMethod=arithmeticMethod)

Description

The calmonths function returns an array that represents calendar months. 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. For calculations that involve fixed lengths of time, use the duration data type.

M = calmonths(X) returns an array representing calendar months equivalent to the values in X.

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

• If X is a calendarDuration array, then M is a double array with each element equal to the number of whole calendar months in the corresponding element of X.

M = calmonths(X,ArithmeticMethod=arithmeticMethod) specifies how M handles arithmetic with datetime values. For this syntax, X must be a numeric array.

Examples

Create Array of Calendar Months

X = magic(4);
M = calmonths(X)

M = 4×4 calendarDuration
   1y 4mo      2mo      3mo   1y 1mo
      5mo     11mo     10mo      8mo
      9mo      7mo      6mo       1y
      4mo   1y 2mo   1y 3mo      1mo

Add Calendar Months to Ends of Months

Create a datetime value whose date component is the end of January.

D = datetime('2021-01-31')

D = datetime
   31-Jan-2021

Add an array of calendar months to D by using the calmonths function. Since February has fewer days than January, it is unambiguous that adding a calendar month to January 31st results in a date of February 28th (since 2021 is not a leap year).

D = D + calmonths(0:2)

D = 1×3 datetime
   31-Jan-2021   28-Feb-2021   31-Mar-2021

Now create a datetime value whose date component is the end of February.

D2 = datetime('2021-02-28')

D2 = datetime
   28-Feb-2021

Calendar months have differing lengths. However, March and April have more days than February. So adding calendar months to February 28th results in dates of March 28th and April 28th.

D2 = D2 + calmonths(0:2)

D2 = 1×3 datetime
   28-Feb-2021   28-Mar-2021   28-Apr-2021

If you want to preserve month ends when adding calendar months to February 28th, create the calendarDuration array with ArithmeticMethod="endofmonth".

D3 = datetime('2021-02-28')

D3 = datetime
   28-Feb-2021

D3 = D3 + calmonths(0:2,ArithmeticMethod="endofmonth")

D3 = 1×3 datetime
   28-Feb-2021   31-Mar-2021   30-Apr-2021

Because February 28th is a month-end date, using end-of-month arithmetic preserves month ends and results in the dates of March 31st and April 30th.

Convert Calendar Durations to Calendar Months

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

X = calmonths(15:17) + caldays(8) + hours(1.2345)

X = 1×3 calendarDuration
   1y 3mo 8d 1h 14m 4.2s   1y 4mo 8d 1h 14m 4.2s   1y 5mo 8d 1h 14m 4.2s

M = calmonths(X)

M = 1×3

    15    16    17

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.

arithmeticMethod — Method for handling arithmetic with datetime values

"default" (default) | "endofmonth"

Method for handling arithmetic with datetime values, specified as one of the values in this table.

Value	Description
"default"	In datetime arithmetic, preserve the day of the month when the resulting month contains that day. Otherwise, use the last day of the resulting month. For example, datetime(2000,9,30)+calmonths(1,ArithmeticMethod="default") returns a datetime value of "30-Oct-2000".
"endofmonth"	In datetime arithmetic, preserve month-end dates for datetime values that occur on the last day of a month. For all other datetime values, use the same behavior as "default". For example, datetime(2000,9,30)+calmonths(1,ArithmeticMethod="endofmonth") returns a datetime value of "31-Oct-2000".

Data Types: string | char

Extended Capabilities

Tall Arrays

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

The calmonths 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™.

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

Version History

Introduced in R2014b

R2026b: Preserve end-of-month dates in datetime arithmetic

Use the ArithmeticMethod name-value argument to create calendar months that preserve month-end dates in arithmetic with month-end datetime values. Previously, calendar months preserved the day of the month.

If you load a calendarDuration array with the ArithmeticMethod property into an earlier MATLAB release (R2014b through R2026a), the earlier release ignores the ArithmeticMethod property, and the loaded calendarDuration array uses the default arithmetic method that preserves the day of the month.