Financial Toolbox

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 the Financial Toolbox 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 to 31.
• The month field is either an integer from 1 to 12 or an alphabetic 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, e.g., 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

Date Formats

Current Date and Time