MATLAB Function Reference  datestr

Convert date and time to string format

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

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

 dateform (number) dateform (string) Example `0` `'dd-mmm-yyyy HH:MM:SS'` `01-Mar-2000 15:45:17` `1` `'dd-mmm-yyyy'` `01-Mar-2000` `2` `'mm/dd/yy'` `03/01/00 ` `3` `'mmm'` `Mar` `4` `'m'` `M` `5` `'mm'` `03 ` `6` `'mm/dd'` `03/01` `7` `'dd'` `01` `8` `'ddd'` `Wed ` `9` `'d'` `W` `10` `'yyyy'` `2000` `11` `'yy'` `00` `12` `'mmmyy'` `Mar00` `13` `'HH:MM:SS'` `15:45:17` `14` `'HH:MM:SS PM'` `3:45:17 PM` `15` `'HH:MM'` `15:45` `16` `'HH:MM PM'` `3:45 PM` `17` `'QQ-YY'` `Q1-01` `18` `'QQ'` `Q1` `19` `'dd/mm'` `01/03` `20` `'dd/mm/yy'` `01/03/00` `21` `'mmm.dd,yyyy HH:MM:SS'` `Mar.01,2000 15:45:17` `22` `'mmm.dd,yyyy'` `Mar.01,2000` `23` `'mm/dd/yyyy'` `03/01/2000` `24` `'dd/mm/yyyy'` `01/03/2000` `25` `'yy/mm/dd'` `00/03/01` `26` `'yyyy/mm/dd'` `2000/03/01` `27` `'QQ-YYYY'` `Q1-2001` `28` `'mmmyyyy'` `Mar2000` `29 (ISO 8601)` `'yyyy-mm-dd'` `2000-03-01` `30 (ISO 8601)` `'yyyymmddTHHMMSS'` `20000301T154517` `31` `'yyyy-mm-dd HH:MM:SS'` `2000-03-01 15:45:17`

 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.

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:

 1 If `S` contains date information only, e.g., 01-Mar-1995 16 If `S` contains time information only, e.g., 03:45 PM 0 If `S` is a date vector, or a string that contains both date and time information, e.g., 01-Mar-1995 03:45

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.

 Symbol Interpretation Example `yyyy` Show year in full. `1990`, `2002` `YY` Show year in two digits. `90`, `02` `mmmm` Show month using full name. `March`, `December` `mmm` Show month using first three letters. `Mar`, `Dec` `mm` Show month in two digits. `03`, `12` `m` Show month using capitalized first letter. `M`, `D` `dddd` Show day using full name. `Monday`, `Tuesday` `ddd` Show day using first three letters. `Mon`, `Tue` `dd` Show day in two digits. `05`, `20` `d` Show day using capitalized first letter. `M`, `T` `HH` Show hour in two digits (no leading zeros when free-form specifier `AM` or `PM` is used (see last entry in this table)). `05`, `5` `AM` `MM` Show minute in two digits. `12`, `02` `SS` Show second in two digits. `07`, `59` `AM or PM` Append `AM` or `PM` to date string (see note below). `3:45:02` `PM`

 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 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, etc.. 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-Jan-2003 13:41:27
```

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 =
01/28/03
```

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.01.2003
```

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('24.01.2003', 'dd.mm.yyyy'), 2)

ans =
01/24/03
```

See Also

`datenum`, `datevec`, `date`, `clock`, `now`, `datetick`

© 1994-2005 The MathWorks, Inc.