months

(Not recommended; use between) Number of whole months between dates

months is not recommended. Use the between function instead because it accepts datetime values as inputs. For more information on updating your code, see Version History or Replace Discouraged Instances of Serial Date Numbers and Date Strings.

Syntax

MyMonths = months(StartDate,EndDate)

MyMonths = months(___,EndMonthFlag)

Description

MyMonths = months(StartDate,EndDate) returns the number of whole months between StartDate and EndDate. If EndDate is earlier than StartDate, MyMonths is negative.

MyMonths = months(___,EndMonthFlag) returns the number of whole months between StartDate and EndDate using an optional argument for EndMonthFlag. If EndDate is earlier than StartDate, MyMonths is negative.

Examples

Determine the Number of Whole Months Between Dates

Find the number of whole months using date strings.

MyMonths = months("may 31 2000", "jun 30 2000", 1)

MyMonths = 
1

Find the number of whole months using date strings when the optional EndMonthFlag = 0.

MyMonths = months("may 31 2000","jun 30 2000", 0)

MyMonths = 
0

Find the number of whole months using a string array.

Dates = ["mar 31 2002"; "apr 30 2002"; "may 31 2002"];
MyMonths = months(Dates, "jun 30 2002")

MyMonths = 3×1

     3
     2
     1

Input Arguments

StartDate — Starting date for number of whole months between dates

serial date number | string array | character array | cell array of character vectors

Starting date for number of whole months between dates, specified as a serial date number or a string array, character array, or cell array of character vectors formatted to represent dates.

Any input argument can contain multiple values, but if so, all other inputs must contain the same number of values or a single value that applies to all. For example, if StartDate is a string array with n elements that each represent a date, then EndDate either must represent n dates or a single date. MyMonths is then an n-by-1 vector of numbers.

If StartDate is a character array with multiple rows, then each row must represent a date.

Data Types: double | string | char

EndDate — Ending date for number of whole months between dates

serial date number | string array | character array | cell array of character vectors

Ending date for number of whole months between dates, specified as a serial date number or a string array, character array, or cell array of character vectors formatted to represent dates.

Any input argument can contain multiple values, but if so, all other inputs must contain the same number of values or a single value that applies to all. For example, if EndDate is a string array with n elements that each represent a date, then StartDate either must represent n dates or a single date. MyMonths is then an n-by-1 vector of numbers.

If EndDate is a character array with multiple rows, then each row must represent a date.

Data Types: double | string | char

EndMonthFlag — Flag for end-of-month rule

1 (default) | nonnegative integer with values 0 or 1

Flag for end-of-month rule, specified as a nonnegative integer with values 0 or 1.

If StartDate and EndDate are end-of-month dates and EndDate has fewer days than StartDate, EndMonthFlag = 1. In this case, EndDate is treated as the end of a whole month, while EndMonthFlag = 0 does not.

Data Types: logical

Output Arguments

MyMonths — Number of whole months between dates

nonnegative integer

Number of whole months between dates, returned as a nonnegative integer.

Version History

Introduced before R2006a

R2022a: Not recommended

There are no plans to remove months. However, the between function is recommended instead because it accepts datetime values as inputs. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

For example, create datetime values for January 1, 2021, and the current date. Then determine the number of months between them.

dt1 = datetime("2021-01-01")
dt2 = datetime("today")
numMonths = between(dt1,dt2,"months")

R2022a: Moved to MATLAB from Financial Toolbox

Previously, months required Financial Toolbox™.