datemnth

Date of day in future or past month

Syntax

TargetDate = datemnth(StartDate,NumberMonths)

TargetDate = datemnth(___,DayFlag,Basis,EndMonthRule)

Description

TargetDate = datemnth(StartDate,NumberMonths) determines a date in a future or past month based on movement either forward or backward in time by a given number of months.

Any input 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 an n-row datetime, then NumberMonths must be an N-by-1 vector of integers or a single integer. TargetDate is then an N-by-1 vector of datetimes.

If StartDate is a string or date character vector, TargetDate is returned as a serial date number. Use the function datetime to convert serial date numbers to formatted datetime arrays.

If StartDate is a datetime array, then TargetDate is returned as a datetime array.

TargetDate = datemnth(___,DayFlag,Basis,EndMonthRule) determines a date in a future or past month based on movement either forward or backward in time by a given number of months, using optional input arguments for DayFlag,Basis, and EndMonthRule.

Examples

Determine the Dates of Days in a Future Month

Determine the TargetDate in a future month using a datetime for StartDate.

StartDate = datetime(1997,6,3);
NumberMonths = 6;
DayFlag = 0;
Basis = 0;
EndMonthRule = 1;
 
TargetDate = datemnth(StartDate, NumberMonths, DayFlag,Basis, EndMonthRule)

TargetDate = datetime
   03-Dec-1997

Determine the TargetDate in a future month using a vector for NumberMonths.

NumberMonths = [1; 3; 5; 7; 9];
TargetDate = datemnth(datetime(2001,1,31), NumberMonths)

TargetDate = 5×1 datetime
   28-Feb-2001
   30-Apr-2001
   30-Jun-2001
   31-Aug-2001
   31-Oct-2001

Input Arguments

StartDate — Start date

datetime array | string array | date character vector

Start date, specified as an N-by-1 or 1-by-N vector using a datetime array, string array, or date character vectors.

To support existing code, datemnth also accepts serial date numbers as inputs, but they are not recommended.

Data Types: char | string | datetime

NumberMonths — Number of months in future (positive) or past (negative)

positive or negative integers

Number of months in future (positive) or past (negative), specified as an N-by-1 or 1-by-N vector containing positive or negative integers.

Data Types: double

DayFlag — Flag for how actual day number for target date in future or past month is determined

0 (day number should be the day in the future or past month corresponding to the actual day number of the start date) (default) | numeric with values 0, 1, or 2

Flag for how the actual day number for the target date in future or past month is determined, specified as an N-by-1 or 1-by-N vector using a numeric with values0, 1, or 2.

Possible values are:

• 0 (default) = day number should be the day in the future or past month corresponding to the actual day number of the start date.

• 1 = day number should be the first day of the future or past month.

• 2 = day number should be the last day of the future or past month.

This flag has no effect if EndMonthRule is set to 1.

Data Types: double

Basis — Day-count basis of the instrument

0 (actual/actual) (default) | numeric with value 0 through 13 | vector of numerics with values 0 through 13

Day-count basis to be used when determining the past or future date, specified as a scalar value with an integer with value of 0 through 13, or an N-by-1 or 1-by-N vector of integers with values of 0 through 13.

• 0 = actual/actual (default)

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (BMA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

For more information, see Basis.

Data Types: single | double

EndMonthRule — End-of-month rule flag for month having 30 or fewer days

0 (not in effect) (default) | nonnegative integer [0,1]

End-of-month rule flag for month having 30 or fewer days, specified as a scalar with a nonnegative integer 0 or 1, or as an N-by-1 or 1-by-N vector of values 0 or 1.

• 0 = Ignore rule, meaning that rule is not in effect.

• 1 = Set rule on, meaning that if you are beginning on the last day of a month, and the month has 30 or fewer days, you will end on the last actual day of the future or past month regardless of whether that month has 28, 29, 30 or 31 days.

  Note

  EndOfMonthRule only applies when you input a date that corresponds to the end of month as the StartDate. For example, if you enter 02/28/2023 as the StartDate, the EndOfMonthRule guarantees that the return date matches the last day of the month in the target output date.

  datestr(datemnth('02/28/2023',4,1,0,1))

  ans =
  
      '30-Jun-2023'

  datemnth returns the target date as the last day of June even though the DayFlag is specified to return the first day of June.

Data Types: logical

Output Arguments

TargetDate — Target date in the future or past month

vector

Target date in the future or past month, returned as an N-by-1 or 1-by-N vector.

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although datemnth supports serial date numbers, datetime values are recommended instead. 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.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.