Handle and Convert Dates

Date Formats

Virtually all financial data derives from a time series, functions in Financial Toolbox™ have extensive date-handling capabilities. The toolbox functions support date or date-and-time formats as character vectors, datetime arrays, or serial date numbers.

• Date character vectors are text that represent date and time, which you can use with multiple formats. For example, `'dd-mmm-yyyy HH:MM:SS'`, `'dd-mmm-yyyy'`, and `'mm/dd/yyyy'` are all supported text formats for a date character vector. Most often, you work with date character vectors (such as `14-Sep-1999`) when dealing with dates.

• Datetime arrays, created using `datetime`, are the best data type for representing points in time. `datetime` values have flexible display formats and up to nanosecond precision, and can account for time zones, daylight saving time, and leap seconds. When `datetime` objects are used as inputs to other Financial Toolbox functions, the format of the input `datetime` object is preserved. For example:

```originalDate = datetime('now','Format','yyyy-MM-dd HH:mm:ss'); % Find the next business day b = busdate(originalDate) ```
```b = datetime 2021-05-04 15:59:34```

• Serial date numbers represent a calendar date as the number of days that have passed since a fixed base date. In MATLAB® software, serial date number `1` is January 1,0000 A.D. Financial Toolbox works internally with serial date numbers (such as, `730377`). MATLAB also uses serial time to represent fractions of days beginning at midnight. For example, 6 p.m. equals `0.75` serial days, so 6:00 p.m. on `14-Sep-1999`, in MATLAB, is serial date number `730377.75`

Note

If you specify a two-digit year, MATLAB assumes that the year lies within the 100-year period centered on the current year. See the function `datenum` for specific information. MATLAB internal date handling and calculations generate no ambiguous values. However, whenever possible, use serial date numbers or date character vectors containing four-digit years.

Many Financial Toolbox functions that require dates as input arguments accept date character vectors, datetime arrays, or serial date numbers. If you are dealing with a few dates at the MATLAB command-line level, date character vectors are more convenient. If you are using Financial Toolbox functions on large numbers of dates, as in analyzing large portfolios or cash flows, performance improves if you use datetime arrays or serial date numbers. For more information, see Represent Dates and Times in MATLAB.

Date Conversions

Financial Toolbox provides functions that convert date character vectors to or from serial date numbers. In addition, you can convert character vectors or serial date numbers to datetime arrays.

Functions that convert between date formats are:

 `datedisp` Displays a numeric matrix with date entries formatted as date character vectors. `datenum` Converts a date character vector to a serial date number. `datestr` Converts a serial date number to a date character vector. `datetime` Converts from date character vectors or serial date numbers to create a datetime array. `datevec` Converts a serial date number or date character vector to a date vector whose elements are `[Year Month Day Hour Minute Second]`. `m2xdate` Converts MATLAB serial date number to Excel® serial date number. `x2mdate` Converts Microsoft® Excel serial date number to MATLAB serial date number.

For more information, see Convert Between Text and datetime or duration Values.

Convert Between Datetime Arrays and Character Vectors

A date can be a character vector composed of fields related to a specific date and time. There are several ways to represent dates and times in several text formats. For example, all the following are character vectors represent August 23, 2010 at 04:35:42 PM:

```'23-Aug-2010 04:35:06 PM' 'Wednesday, August 23' '08/23/10 16:35' 'Aug 23 16:35:42.946' ```

A date character vector includes characters that separate the fields, such as the hyphen, space, and colon used here:

`d = '23-Aug-2010 16:35:42' `

Convert one or more date character vectors to a `datetime` array using the `datetime` function. For the best performance, specify the format of the input character vectors as an input to `datetime`.

Note

The specifiers that `datetime` uses to describe date and time formats differ from the specifiers that the `datestr`, `datevec`, and `datenum` functions accept.

`t = datetime(d,'InputFormat','dd-MMM-yyyy HH:mm:ss')`
```t = 23-Aug-2010 16:35:42 ```

Although the date string, `d`, and the `datetime` scalar, `t`, look similar, they are not equal. View the size and data type of each variable.

`whos d t`
``` Name Size Bytes Class Attributes d 1x20 40 char t 1x1 121 datetime ```

Convert a `datetime` array to a character vector that uses `char` or `cellstr`. For example, convert the current date and time to a timestamp to append to a file name.

`t = datetime('now','Format','yyyy-MM-dd''T''HHmmss')`
```t = datetime 2016-12-11T125628```
```S = char(t); filename = ['myTest_',S]```
```filename = 'myTest_2016-12-11T125628'```

Convert Serial Date Numbers to Datetime Arrays

Serial time can represent fractions of days beginning at midnight. For example, 6 p.m. equals `0.75` serial days, so the character vector `'31-Oct-2003, 6:00 PM'` in MATLAB is date number `731885.75`.

Convert one or more serial date numbers to a `datetime` array using the `datetime` function. Specify the type of date number that is being converted:

`t = datetime(731885.75,'ConvertFrom','datenum')`
```t = datetime 31-Oct-2003 18:00:00```

Convert Datetime Arrays to Numeric Values

Some MATLAB functions accept numeric data types but not datetime values as inputs. To apply these functions to your date and time data, first, convert datetime values to meaningful numeric values, and then call the function. For example, the `log` function accepts `double` inputs but not `datetime` inputs. Suppose that you have a `datetime` array of dates spanning the course of a research study or experiment.

`t = datetime(2014,6,18) + calmonths(1:4)`
```t = 1×4 datetime array 18-Jul-2014 18-Aug-2014 18-Sep-2014 18-Oct-2014```

Subtract the origin value. For example, the origin value can be the starting day of an experiment.

`dt = t - datetime(2014,7,1)`
```dt = 1×4 duration array 408:00:00 1152:00:00 1896:00:00 2616:00:00```

`dt` is a `duration` array. Convert `dt` to a `double` array of values in units of years, days, hours, minutes, or seconds by using the `years`, `days`, `hours`, `minutes`, or `seconds` function, respectively.

`x = hours(dt)`
```x = 408 1152 1896 2616```

Pass the `double` array as the input to the `log` function.

`y = log(x)`
```y = 6.0113 7.0493 7.5475 7.8694```

Input Conversions with `datenum`

The `datenum` function is important for using Financial Toolbox software efficiently. `datenum` takes an input date character vector in any of several formats, with `'dd-mmm-yyyy'`, `'mm/dd/yyyy'`, or `'dd-mmm-yyyy, hh:mm:ss.ss'` formats being the most common. The input date character vector can have up to six fields formed by letters and numbers separated by any other characters, such that:

• The day field is an integer from `1` through `31`.

• The month field is either an integer from `1` through `12` or an alphabetical character vector with at least three characters.

• The year field is a nonnegative integer. If only two numbers are specified, then the year is assumed to lie within the 100-year period centered on the current year. If the year is omitted, the current year is the default.

• The hours, minutes, and seconds fields are optional. They are integers separated by colons or followed by `'am'` or `'pm'`.

For example, if the current year is 1999, then all these dates are equivalent:

```'17-May-1999' '17-May-99' '17-may' 'May 17, 1999' '5/17/99' '5/17' ```

Also, both of these formats represent the same time.

```'17-May-1999, 18:30' '5/17/99/6:30 pm' ```

The default format for numbers-only input follows the US convention. Therefore, 3/6 is March 6, not June 3.

With `datenum`, you can convert dates into serial date format, store them in a matrix variable, and then later pass the variable to a function. Alternatively, you can use `datenum` directly in a function input argument list.

For example, consider the function `bndprice` that computes the price of a bond given the yield to maturity. First set up variables for the yield to maturity, coupon rate, and the necessary dates.

```Yield = 0.07; CouponRate = 0.08; Settle = datenum('17-May-2000'); Maturity = datenum('01-Oct-2000'); ```

Then call the function with the variables.

```bndprice(Yield,CouponRate,Settle,Maturity) ```
```ans = 100.3503```

Alternatively, convert date character vectors to serial date numbers directly in the function input argument list.

```bndprice(0.07,0.08,datenum('17-May-2000'),... datenum('01-Oct-2000')) ```
```ans = 100.3503```

`bndprice` is an example of a function designed to detect the presence of date character vectors and make the conversion automatically. For functions like `bndprice`, date character vectors can be passed directly.

```bndprice(0.07,0.08,'17-May-2000','01-Oct-2000') ```
```ans = 100.3503```

The decision to represent dates as either date character vectors or serial date numbers is often a matter of convenience. For example, when formatting data for visual display or for debugging date-handling code, you can view dates more easily as date character vectors because serial date numbers are difficult to interpret. Alternately, serial date numbers are just another type of numeric data, which you can place in a matrix along with any other numeric data for convenient manipulation.

Remember that if you create a vector of input date character vectors, use a column vector, and be sure that all character vectors are the same length. To ensure that the character vectors are the same length, fill the character vectors with spaces or zeros. For more information, see Character Vector Input.

Output Conversions with `datestr`

The `datestr` function converts a serial date number to one of 19 different date character vector output formats showing date, time, or both. The default output for dates is a day-month-year character vector, for example, `24-Aug-2000`. The `datestr` function is useful for preparing output reports.

`datestr` Format

Description

`01-Mar-2000 15:45:17`

day-month-year hour:minute:second

`01-Mar-2000`

day-month-year

`03/01/00`

month/day/year

`Mar`

month, three letters

`M`

month, single letter

`3`

month number

`03/01`

month/day

`1`

day of month

`Wed`

day of week, three letters

`W`

day of week, single letter

`2000`

year, four numbers

`99`

year, two numbers

`Mar01`

month year

`15:45:17`

hour:minute:second

`03:45:17 PM`

hour:minute:second AM or PM

`15:45`

hour:minute

`03:45 PM`

hour:minute AM or PM

`Q1-99`

calendar quarter-year

`Q1`

calendar quarter

Current Date and Time

The `today` and `now` functions return serial date numbers for the current date, and the current date and time, respectively.

`today`
```ans = 736675```
`now`
```ans = 7.3668e+05```

The MATLAB function `date` returns a character vector for the current date.

`date`
```ans = '11-Dec-2016'```

Determining Specific Dates

Financial Toolbox provides many functions for determining specific dates. For example, assume that you schedule an accounting procedure for the last Friday of every month. Use the `lweekdate` function to return those dates for the year 2000. The input argument `6` specifies Friday.

```Fridates = lweekdate(6,2000,1:12); Fridays = datestr(Fridates)```
```Fridays = 12×11 char array '28-Jan-2000' '25-Feb-2000' '31-Mar-2000' '28-Apr-2000' '26-May-2000' '30-Jun-2000' '28-Jul-2000' '25-Aug-2000' '29-Sep-2000' '27-Oct-2000' '24-Nov-2000' '29-Dec-2000' ```

Another example of needing specific dates could be that your company closes on Martin Luther King Jr. Day, which is the third Monday in January. You can use the `nweekdate` function to determine those specific dates for 2011 through 2014.

```MLKDates = nweekdate(3,2,2011:2014,1); MLKDays = datestr(MLKDates)```
```MLKDays = 4×11 char array '17-Jan-2011' '16-Jan-2012' '21-Jan-2013' '20-Jan-2014' ```

Determining Holidays

Accounting for holidays and other nontrading days is important when you examine financial dates. Financial Toolbox provides the `holidays` function, which contains holidays and special nontrading days for the New York Stock Exchange from 1950 through 2030, inclusive. In addition, you can use `nyseclosures` to evaluate all known or anticipated closures of the New York Stock Exchange from January 1, 1885, to December 31, 2050. `nyseclosures` returns a vector of serial date numbers corresponding to market closures between the dates `StartDate` and `EndDate`, inclusive.

In this example, use `holidays` to determine the standard holidays in the last half of 2012.

```LHHDates = holidays('1-Jul-2012','31-Dec-2012'); LHHDays = datestr(LHHDates)```
```LHHDays = 6×11 char array '04-Jul-2012' '03-Sep-2012' '29-Oct-2012' '30-Oct-2012' '22-Nov-2012' '25-Dec-2012'```

You can then use the `busdate` function to determine the next business day in 2012 after these holidays.

```LHNextDates = busdate(LHHDates); LHNextDays = datestr(LHNextDates)```
```LHNextDays = 6×11 char array '05-Jul-2012' '04-Sep-2012' '31-Oct-2012' '31-Oct-2012' '23-Nov-2012' '26-Dec-2012'```

Determining Cash-Flow Dates

To determine cash-flow dates for securities with periodic payments, use `cfdates`. This function accounts for the coupons per year, the day-count basis, and the end-of-month rule. For example, you can determine the cash-flow dates for a security that pays four coupons per year on the last day of the month using an `actual/365` day-count basis. To do so, enter the settlement date, the maturity date, and the parameters for `Period`, `Basis`, and `EndMonthRule`.

```PayDates = cfdates('14-Mar-2000','30-Nov-2001',4,3,1); PayDays = datestr(PayDates)```
```PayDays = 7×11 char array '31-May-2000' '31-Aug-2000' '30-Nov-2000' '28-Feb-2001' '31-May-2001' '31-Aug-2001' '30-Nov-2001' ```