Financial Toolbox™

datestr - Create date string

Syntax

S = datestr(V)
S = datestr(N)
S = datestr(D, F)
S = datestr(S1, F, P)
S = datestr(..., 'local')

Description

datestr is one of three conversion functions that enable you to express dates and times in any of three formats in MATLAB^® software: 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.

S = datestr(V) converts one or more date vectors V to date strings S. Input V must be an m-by-6 matrix containing m full (six-element) date vectors. Each element of V 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 V.

S = datestr(N) converts one or more serial date numbers N to date strings S. Input argument N 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 N.

S = datestr(D, F) converts one or more date vectors, serial date numbers, or date strings D into the same number of date strings S. Input argument F is a format number or string that determines the format of the date string output. Valid values for F are given in the table Standard MATLAB^® Date Format Definitions , below. Input F may also contain a free-form date format string consisting of format tokens shown in the table Free-Form Date Format Specifiers , below.

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

S = datestr(S1, F, P) converts date string S1 to date string S, applying format F to the output string, and using pivot year P 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 S1 must have the same format.

S = datestr(..., 'local') returns the string in a localized format. The default is US English ('en_US'). This argument must come last in the argument sequence.

Note   The vectorized calling syntax can offer significant performance improvement for large arrays.

Standard MATLAB^® Date Format Definitions

Note   dateform numbers 0, 1, 2, 6, 13, 14, 15, 16, and 23 produce a string suitable for input to datenum or datevec. Other date string formats do not work with these functions unless you specify a date form in the function call.

Note   For date formats that specify only a time (for example., dateform numbers 13, 14, 15, and 16), MATLAB software sets the date to January 1 of the current year.

Time formats like 'h:m:s', 'h:m:s.s', 'h:m pm', ... can also be part of the input array S. If you do not specify a format string F, or if you specify F as -1, the date string format defaults to the following:

The following table shows the string symbols to use in specifying a free-form format for the output date string. MATLAB interprets these symbols according to your computer's language setting and the current MATLAB language setting.

Note   You cannot use more than one format specifier for any date or time field. For example, datestr(n, 'dddd dd mmmm') specifies two formats for the day of the week, and thus returns an error.

Free-Form Date Format Specifiers

Note   Free-form specifiers AM and PM from the table above are identical. They do not influence which characters are displayed following the time (AM versus PM), but only whether or not they are displayed. MATLAB software selects AM or PM based on the time entered.

Remarks

A vector of three or six numbers could represent either a single date vector, or a vector of individual serial date numbers. For example, the vector [2000 12 15 11 45 03] could represent either 11:45:03 on December 15, 2000 or a vector of date numbers 2000, 12, 15, and so on. MATLAB uses the following general rule in interpreting vectors associated with dates:

• A 3- or 6-element vector having a first element within an approximate range of 500 greater than or less than the current year is considered by MATLAB to be a date vector. Otherwise, it is considered to be a vector of serial date numbers.

To specify dates outside of this range as a date vector, first convert the vector to a serial date number using the datenum function as shown here:

datestr(datenum([1400 12 15 11 45 03]), ...
        'mmm.dd,yyyy HH:MM:SS')
ans =
   Dec.15,1400 11:45:03

Examples

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

datestr(now)

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

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

Format the same showing only the date and 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

Display the returned date string using your own format made up of symbols shown in the Free-Form Date Format Specifiers table above.

datestr(now, 'dd.mm.yyyy')

ans =
   28.03.2005

Convert a nonstandard date form into a standard MATLAB date form by first converting to a date number and then to a string:

datestr(datenum('28.03.2005', 'dd.mm.yyyy'), 2)

ans =
   03/28/05

See Also

dateaxis, datedisp, datenum, datevec, daysact, now, today

datenum

datevec