datestr - Convert date and time to string format

Syntax

Description

datestr is one of three conversion functions that enable you to express dates and times in any of three formats in your MATLAB application: a string (or date string), a vector of date and time components (or date vector), or as a numeric offset from a known date in time (or serial date number). Here is an example of a date and time expressed in the three MATLAB formats:

Date String:           '24-Oct-2003 12:45:07'
Date Vector:           [2003  10  24  12  45  07]
Serial Date Number:    7.3188e+005

A serial date number represents the whole and fractional number of days from 1-Jan-0000 to a specific date. The year 0000 is merely a reference point and is not intended to be interpreted as a real year in time.

See Working with Date Strings in the MATLAB Programming documentation for more information on creating or converting to a date string.

DateString = datestr(DateVector) converts one or more date vectors DateVector to an equal number of date strings DateString. Input DateVector must be an m-by-6 matrix containing m full (six-element) date vectors. Each element of DateVector must be a positive double-precision number. datestr returns a column vector of m date strings, where m is the total number of date vectors in DateVector. Each output string is in the default date string format: day-month-year hour:minute:second.

DateString = datestr(DateNumber) converts one or more serial date numbers DateNumber to date strings DateString. Input argument DateNumber can be a scalar, vector, or multidimensional array of positive double-precision numbers. datestr returns a column vector of m date strings, where m is the total number of date numbers in DateNumber. Each output string is in the default date string format: day-month-year hour:minute:second.

DateString = datestr(DateTime, FieldSpecOut) converts one or more date vectors, serial date numbers, or date strings DateTime into the same number of date strings DateStr. Input FieldSpecOut is a field specifier string that determines the format of the date string output. Valid values for FieldSpecOut are given in the table Symbolic Identifiers for Individual Fields in the MATLAB Programming Fundamentals documentation. Input FieldSpecOut may also contain a numeric identifier that identifies some of the more commonly used formats. See the table Numeric Identifiers for Predefined Formats for a list of these identifiers.

DateString2 = datestr(DateString1, FieldSpecOut, PivotYear) converts date string DateString1 to date string DateString2, applying format FieldSpecOut to the output string, and using PivotYear as the starting year of the 100-year range in which a two-character year resides. The default pivot year is the current year minus 50 years. All date strings in DateString1 must have the same format.

DateString2 = datestr(datenum(DateString1, FieldSpecIn), FieldSpecOut) converts one or more date strings DateString1 into the same number of date strings DateString2. Input FieldSpecIn is a field specifier that identifies the content of the DateString1 input string. Input FieldSpecOut is a field specifier that determines the format of the date string output. See the two tables linked to above for valid field specifiers.

Note   See the Tips section below if the DateTime input is in a nondefault date string, date vector, or serial date number form.

Date strings with 2-character years are interpreted to be within the 100 years centered around the current year.

DateString = datestr(..., 'local') returns the date string in the language of the current locale. This is the language you currently have selected by means of your computer's operating system. If you leave local out of the argument list, datestr returns the date string in the default language, which is US English. The local argument must come last in the argument sequence.

For example, in a French locale, calling datestr with 'local' specified and format FieldSpecOut set to mmmm-dd-yyyy returns Jun-11–2009. Making the same call, without specifying 'local' defaults to the English language and thus returns June-11-2009.

Tips

To convert a nonstandard date form into a MATLAB date form, first convert the nonstandard date form to a date number, using either datenum or datevec.

Examples

Convert date vector v to a date string:

v = [2009, 4, 2, 11, 7, 18];

datestr(v)
ans =
   02-Apr-2009 11:07:18

Return the current date and time in a string using the default format, 0:

datestr(now)

ans =
   28-Mar-2005 15:36:23

Format the current date in the mm/dd/yy format. Note that you can specify this format either by number or by string.

datestr(now, 2)     -or-     datestr(now, 'mm/dd/yy')

ans =
   03/28/05

This example uses several format specifiers. The second line converts the input date string to a serial date number n because the input string str is not in the default form for a date string (day precedes month):

str = 'Sep 13, 1986';
n = datenum(str, 'mmm dd, yyyy');

[datestr(n, 'ddd ') datestr(n, 'mmm dd, ''yy')]
ans =
   Sat Sep 13, '86

[datestr(n, 'dddd ') datestr(n, 'mmmm dd, yyyy')]
ans =
   Saturday September 13, 1986

Reformat the date and time, and also show milliseconds:

dt = datestr(now, 'mmmm dd, yyyy HH:MM:SS.FFF AM')
dt =
   March 28, 2005  3:37:07.952 PM

Change the pivot year and note the effect on the output:

datestr('4/16/55', 1, 1900)
ans =
   16-Apr-1955

datestr('4/16/55', 1, 2000)
ans =
   16-Apr-2055

The date below uses a nonstandard date form (month=13). Call datenum inside of datestr to get the correct return value:

datestr(datenum('13/24/88', 'mm/dd/yy'))
ans =
   24-Jan-1989

Calling datestr with more than one date string input returns a character array of converted date strings. Pass the multiple date strings in a cell array. All input date strings must use the same format. For example, the following command passes three dates that all use the mm/dd/yyyy format:

datestr(datenum({'09/16/2007';'05/14/1996';'11/29/2010'}, ...
    'mm/dd/yyyy'))
ans =
    16-Sep-2007
    14-May-1996
    29-Nov-2010

See Also

clock | date | datenum | datetick | datevec | now

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