Main Content

datemnth

Date of day in future or past month

collapse all in page

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.

example

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.

example

Examples

collapse all

Open Live Script

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 = 5x1 datetime
   28-Feb-2001
   30-Apr-2001
   30-Jun-2001
   31-Aug-2001
   31-Oct-2001

Input Arguments

collapse all

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

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

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

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

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

collapse all

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

Version History

Introduced before R2006a

expand all

See Also

| | | | | |

Topics