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 character array of date character vectors, then NumberMonths must be an N-by-1 vector of integers or a single integer. TargetDate is then an N-by-1 vector of date numbers.

If StartDate is a serial date number or date character vector, TargetDate is returned as a serial date number. Use datestr to convert serial date numbers to formatted date character vectors.

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 date character vector for StartDate.

StartDate = '03-Jun-1997';
NumberMonths = 6;
DayFlag = 0;
Basis = 0;
EndMonthRule = 1;
 
TargetDate = datemnth(StartDate, NumberMonths, DayFlag,...
Basis, EndMonthRule)

TargetDate = 729727

datestr(TargetDate)

ans = 
'03-Dec-1997'

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

Day = datemnth(datetime('3-jun-2001','Locale','en_US'), 6, 0, 0, 0)

Day = datetime
   03-Dec-2001

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

NumberMonths = [1; 3; 5; 7; 9];
TargetDate = datemnth('31-jan-2001', NumberMonths); 
datestr(TargetDate)

ans = 5x11 char array
    '28-Feb-2001'
    '30-Apr-2001'
    '30-Jun-2001'
    '31-Aug-2001'
    '31-Oct-2001'

Input Arguments

StartDate — Start date

serial date number | date character vector | datetime object

Start date, specified as an N-by-1 or 1-by-N vector using serial date numbers, date character vectors, or datetime arrays.

Data Types: double | char | 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.

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 containing the serial date number (default) or datetime (if StartDate is a datetime array) of the target date.

Version History

Introduced before R2006a