Learn more about Financial Toolbox

Handling and Converting Dates

On this page…
Date Formats Date Conversions Current Date and Time Determining Dates

Date Formats

Since virtually all financial data is dated or derives from a time series, financial functions must have extensive date-handling capabilities. You most often work with date strings (14-Sep-1999) when dealing with dates. Financial Toolbox software works internally with serial date numbers (for example, 730377). A serial date number represents a calendar date as the number of days that has passed since a fixed base date. In MATLAB software, serial date number 1 is January 1, 0000 A.D. 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 date number 730377.75.

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

Many toolbox functions that require dates accept either date strings or serial date numbers. If you are dealing with a few dates at the MATLAB command-line level, date strings are more convenient. If you are using toolbox functions on large numbers of dates, as in analyzing large portfolios or cash flows, performance improves if you use date numbers.

The Financial Toolbox software provides functions that convert date strings to serial date numbers, and vice versa.

Back to Top

Date Conversions

Functions that convert between date formats are

datedisp	Displays a numeric matrix with date entries formatted as date strings
datenum	Converts a date string to a serial date number
datestr	Converts a serial date number to a date string
m2xdate	Converts MATLAB serial date number to Excel serial date number
x2mdate	Converts Excel serial date number to MATLAB serial date number

Another function, datevec, converts a date number or date string to a date vector whose elements are [Year Month Day Hour Minute Second]. Date vectors are mostly an internal format for some MATLAB functions; you would not often use them in financial calculations.

Input Conversions

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

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

• The month field is either an integer from 1 through 12 or an alphabetical string 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 about the current year; if the year is omitted, the current year is used as 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 these are all equivalent

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

and both of these represent the same time.

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

Note that the default format for numbers-only input follows the American convention. Thus 3/6 is March 6, not June 3.

With datenum you can convert dates into serial date format, store them in a matrix variable, 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)

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

bndprice(0.07, 0.08, datenum('17-May-2000'),... 
datenum('01-Oct-2000'))

bndprice is an example of a function designed to detect the presence of date strings and make the conversion automatically. For these functions date strings may be passed directly.

bndprice(0.07, 0.08, '17-May-2000', '01-Oct-2000')

The decision to represent dates as either date strings or serial date numbers is often a matter of convenience. For example, when formatting data for visual display or for debugging date-handling code, it is often much easier to view dates as date strings because serial date numbers are difficult to interpret. Alternatively, serial date numbers are just another type of numeric data, and can be placed in a matrix along with any other numeric data for convenient manipulation.

Remember that if you create a vector of input date strings, use a column vector and be sure all strings are the same length. Fill with spaces or zeros. See Matrices of String Input.

Output Conversions

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

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

Back to Top

Current Date and Time

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

today

ans =
      730693

now

ans =

      730693.48

The MATLAB function date returns a string for today's date.

date

ans =

26-Jul-2000

Back to Top

Determining Dates

The Financial Toolbox software provides many functions for determining specific dates, including functions which account for holidays and other nontrading days. For example, you schedule an accounting procedure for the last Friday of every month. The lweekdate function returns those dates for 2000; the 6 specifies Friday.

Fridates = lweekdate(6, 2000, 1:12);

Fridays = datestr(Fridates)

Fridays =

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

Or your company closes on Martin Luther King Jr. Day, which is the third Monday in January. The nweekdate function determines those dates for 2001 through 2004.

MLKDates = nweekdate(3, 2, 2001:2004, 1);

MLKDays = datestr(MLKDates)

MLKDays =

15-Jan-2001
21-Jan-2002
20-Jan-2003
19-Jan-2004

Accounting for holidays and other nontrading days is important when examining financial dates. The Financial Toolbox software provides the holidays function, which contains holidays and special nontrading days for the New York Stock Exchange between 1950 and 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, you can use holidays to determine the standard holidays in the last half of 2000:

LHHDates = holidays('1-Jul-2000', '31-Dec-2000');

LHHDays = datestr(LHHDates)

LHHDays =

04-Jul-2000
04-Sep-2000
23-Nov-2000
25-Dec-2000

Now use the toolbox busdate function to determine the next business day after these holidays.

LHNextDates = busdate(LHHDates);

LHNextDays = datestr(LHNextDates)

LHNextDays =

05-Jul-2000
05-Sep-2000
24-Nov-2000
26-Dec-2000

The toolbox also provides the cfdates function to determine cash-flow dates for securities with periodic payments. This function accounts for the coupons per year, the day-count basis, and the end-of-month rule. For example, to determine the cash-flow dates for a security that pays four coupons per year on the last day of the month, on an actual/365 day-count basis, just enter the settlement date, the maturity date, and the parameters.

PayDates = cfdates('14-Mar-2000', '30-Nov-2001', 4, 3, 1);

PayDays = datestr(PayDates)

PayDays =

31-May-2000
31-Aug-2000
30-Nov-2000
28-Feb-2001
31-May-2001
31-Aug-2001
30-Nov-2001

Back to Top

Introduction

Formatting Currency

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS