MATLAB®

Dates and Times

Overview

The MATLAB^® software represents date and time information in either of three formats: date strings, serial date numbers, or date vectors. You have the choice of using any of these formats. If you work with more than one date and time format, MATLAB provides functions to help you easily convert from one format to another, (e.g., from a string to a serial date number).

When using date strings, you have an additional option of choosing from 19 different string styles to express date and/or time information.

Back to Top

Types of Date Formats

The three MATLAB date and time formats are

• Date Strings

• Serial Date Numbers

• Date Vectors

This table shows examples of the three formats.

Date Strings

There are a number of different styles in which to express date and time information as a date string. For example, several possibilities for October 31, 2003 at 3:45:17 in the afternoon are

31-Oct-2003 15:45:17
10/31/03
15:45:17
03:45:17 PM

If you are working with a small number of dates at the MATLAB command line, then date strings are often the most convenient format to use.

Note   The MATLAB date function returns the current date as a string.

Serial Date Numbers

A serial date number 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 '31-Oct-2003, 6:00 pm' in MATLAB is date number 731885.75.

MATLAB works internally with serial date numbers. If you are using functions that handle large numbers of dates or doing extensive calculations with dates, you get better performance if you use date numbers.

Note   The MATLAB now function returns the current date and time as a serial date number.

Date Vectors

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

Note   The MATLAB clock function returns the current date and time as a serial vector.

Back to Top

Conversions Between Date Formats

Functions that convert between date formats are shown below.

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

Back to Top

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.

Back to Top

Output Formats

The command 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 correspond to each dateform value.

Converting Output Format with datestr

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

Back to Top

Current Date and Time

The function date returns a string for today's date:

date
ans =
     02-Oct-1996

The function now returns the serial date number for the current date and time:

now
ans =
     729300.71

datestr(now)
ans =
     02-Oct-1996 16:56:16

datestr(floor(now))
ans = 
     02-Oct-1996

Back to Top

Function Summary

MATLAB provides the following functions for time and date handling:

• Current Date and Time Functions

• Conversion Functions

• Utility Functions

• Timing Measurement Functions

Current Date and Time Functions

Conversion Functions

Utility Functions

Timing Measurement Functions

Back to Top

Characters and Strings

Structures