nweekdate

(Not recommended; use dateshift) Date of specific occurrence of weekday in month

nweekdate is not recommended because it returns a serial date number. To return the specified occurrence of a weekday as a datetime value, use the dateshift function. If you do use nweekdate, consider setting the outputType option to "datetime". For more information on updating your code, see Version History or Replace Discouraged Instances of Serial Date Numbers and Date Strings.

Syntax

Date = nweekdate(n,Weekday,Year,Month,NextDay,outputType)

Date = nweekdate(n,Weekday,Year,Month)

Description

Date = nweekdate(n,Weekday,Year,Month,NextDay,outputType) returns the date for the nth occurrence of Weekday in the given year and month. Weekday is an integer from 1 (Sunday) through 7 (Saturday), and n is an integer from 1 through 5 that specifies the nth occurrence. A nonzero value for NextDay requires that the week also includes the specified subsequent weekday. Setting outputType to "datetime" is recommended.

Date = nweekdate(n,Weekday,Year,Month) returns the date as a serial date number. This syntax is equivalent to nweekdate(n,Weekday,Year,Month,0,"datenum").

Examples

Single Date

Determine the first Friday in June 2021.

Date = nweekdate(1,6,2021,6,0,"datetime")

Date = datetime
   04-Jun-2021

Find the first Friday in a week that also contains a Monday in June 2021.

Date = nweekdate(1,6,2021,6,2,"datetime")

Date = datetime
   11-Jun-2021

If you specify only n, the weekday, year, and month, nweekdate returns a serial date number.

Date = nweekdate(1,6,2021,6)

Date = 
738311

However, using datetime values is recommended. To convert serial date numbers, use the datetime function.

Date = datetime(Date,"ConvertFrom","datenum")

Date = datetime
   04-Jun-2021

Multiple Dates

Determine the first Monday in May for 2019, 2020, and 2021.

yrs = 2019:2021;
Date = nweekdate(1,2,yrs,5,0,"datetime")

Date = 1×3 datetime
   06-May-2019   04-May-2020   03-May-2021

Input Arguments

n — nth occurrence of weekday in month

scalar | vector

nth occurrence of the weekday in a month, specified as a scalar or vector of integers between 1 and 5.

If n is larger than the last occurrence of Weekday, then the output is either a serial date number whose value is zero, or a datetime value whose date is December 31, 1 BCE.

If you specify a vector for n and for Weekday, Year, or Month, then all vectors must be the same length. The output Date is a vector of the same length.

Weekday — Weekday number

scalar | vector

Weekday number, specified as a scalar or vector of integers between 1 and 7.

• 1 — Sunday

• 2 — Monday

• 3 — Tuesday

• 4 — Wednesday

• 5 — Thursday

• 6 — Friday

• 7 — Saturday

If you specify a vector for Weekday and for n, Year, or Month, then all vectors must be the same length. The output Date is a vector of the same length.

Year — Year

scalar | vector

Year, specified as a scalar or vector of four-digit integer values.

If you specify a vector for Year and for n, Weekday, or Month, then all vectors must be the same length. The output Date is a vector of the same length.

Month — Month number

scalar | vector

Month number, specified as scalar or vector of integers between 1 and 12.

If you specify a vector for Month and for n, Weekday, or Year, then all vectors must be the same length. The output Date is a vector of the same length.

NextDay — Subsequent weekday in week

0 (default) | scalar | vector

Subsequent weekday in week to include with Weekday, specified as a scalar or vector of integers between 0 and 7. A value of 0 indicates that the week only needs to include Weekday. Values 1 through 7 are the same as for Weekday.

If you specify a vector for NextDay and for n, Weekday, Year, or Month, then all vectors must be the same length. The output Date is a vector of the same length.

outputType — Output data type

"datenum" (default) | "datetime"

Output data type, specified as "datenum" or "datetime".

Specifying "datetime" is recommended, which returns Date as a datetime scalar or vector. For compatibility with previous releases, the default value is "datenum", which returns Date as serial date numbers.

Output Arguments

Date — Date of specified occurrence in month

double | datetime

Date for the specified occurrence in the month, returned as a scalar or vector of type double or datetime. The type depends on the value of outputType.

Version History

Introduced before R2006a

R2022a: Not recommended

There are no plans to remove nweekdate. However, the dateshift function is recommended instead because it returns datetime values, not serial date numbers. 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 return the specified occurrence of a weekday in a month, start by specifying the first day of the month as a datetime value. Then use dateshift to shift the start of the month to the specified occurrence of the weekday.

For example, return the first Tuesday of October, 2021 as a datetime value.

october = datetime(2021,10,1);
firstTuesday = dateshift(october,"dayofweek","Tuesday",1)

firstTuesday = datetime
   05-Oct-2021

If you do plan to use nweekdate, consider returning its output as a datetime value instead of a serial date number.

firstTuesday = nweekdate(1,3,2021,10,0,"datetime")

firstTuesday = datetime
   05-Oct-2021

R2022a: Moved to MATLAB from Financial Toolbox

Previously, nweekdate required Financial Toolbox™.