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