Main Content

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.

datevecConverts 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'

See Also

| | | | | | | | | | |

Related Examples

More About

External Websites