Programming and Data Types

Date Formats

This section covers the following topics:

• "Types of Date Formats"
• "Conversions Between Date Formats"
• "Date String Formats"
• "Output Formats"

Types of Date Formats

MATLAB works with three different date formats: date strings, serial date numbers, and date vectors.

When dealing with dates you typically work with date strings (16-Sep-1996). MATLAB works internally with serial date numbers (729284). A serial date represents a calendar date as the number of days that has passed since a fixed base date. In MATLAB, serial date number 1 is January 1, 0000. MATLAB also uses serial time to represent fractions of days beginning at midnight; for example, 6 p.m. equals 0.75 serial days. So the string '16-Sep-1996, 6:00 pm' in MATLAB is date number 729284.75.

All 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 functions that handle large numbers of dates or doing extensive calculations with dates, you will get better performance if you use date numbers.

Date vectors are an internal format for some MATLAB functions; you do not typically use them in calculations. A date vector contains the elements [year month day hour minute second].

MATLAB provides functions that convert date strings to serial date numbers, and vice versa. Dates can also be converted to date vectors.

Here are examples of the three date formats used by MATLAB.

Date Format	Example
Date string	02-Oct-1996
Serial date number	729300
Date vector	1996 10 2 0 0 0

Conversions Between Date Formats

Functions that convert between date formats are shown below.

Function	Description
datenum	Convert date string to serial date number
datestr	Convert serial date number to date string
datevec	Split date number or date string into individual date elements

Here are some examples of conversions from one date format to another.

• d1 = datenum('02-Oct-1996')
  d1 = 
      729300
  
  d2 = datestr(d1+10)
  d2 = 
     12-Oct-1996
  
  dv1 = datevec(d1)
  dv1 =
      1996      10       2       0       0       0
  
  dv2 = datevec(d2)
  dv2 =
      1996      10      12       0       0       0
  

Date String Formats

The datenum function is important for doing date calculations 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. You can form up to six fields from letters and digits 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 digits are specified, then a year 19yy is assumed; if the year is omitted, then the current year is used as a 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 1996, then these are all equivalent

• '17-May-1996'
  '17-May-96'
  '17-May'
  'May 17, 1996'
  '5/17/96'
  '5/17'
  

and both of these represent the same time

• '17-May-1996, 18:30'
  '5/17/96/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.

If you create a vector of input date strings, use a column vector and be sure all strings are the same length. Fill in with spaces or zeros.

Output Formats

The function datestr(D,dateform) converts a serial date D 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: 01-Mar-1996. You select an alternative output format by using the optional integer argument dateform.

This table shows the date string formats that corespond to each dateform value.

dateform	Format	Description
0	01-Mar-1996 15:45:17	day-month-year hour:minute:second
1	01-Mar-1996	day-month-year
2	03/01/96	month/day/year
3	Mar	month, three letters
4	M	month, single letter
5	3	month
6	03/01	month/day
7	1	day of month
8	Wed	day of week, three letters
9	W	day of week, single letter
10	1996	year, four digits
11	96	year, two digits
12	Mar96	month year
13	15:45:17	hour:minute:second
14	03:45:17 PM	hour:minute:second AM or PM
15	15:45	hour:minute
16	03:45 PM	hour:minute AM or PM
17	Q1-96	calendar quarter-year
18	Q1	calendar quarter

Here are some examples of converting the date March 1, 1996 to various forms using the datestr function.

• d = '01-Mar-1999' 
  d = 
     01-Mar-1999
  
  datestr(d)
  ans =
       01-Mar-1999
  
  datestr(d, 2)
  ans = 
       03/01/99
  
  datestr(d, 17)
  ans = 
       Q1-99
  

Dates and Times

Current Date and Time