datestr

Convert date and time to string format

Syntax

  • DateString = datestr(t) example
  • DateString = datestr(DateVector) example
  • DateString = datestr(DateNumber) example
  • DateString = datestr(___,formatOut) example
  • DateString = datestr(DateStringIn)
  • DateString = datestr(DateStringIn,formatOut,PivotYear) example
  • DateString = datestr(___,'local') example

Description

example

DateString = datestr(t) converts the datetime values in datetime array t to date strings. datestr returns a column vector of m date strings, where m is the total number of datetime values in t.

By default, datestr returns date strings in the format, day-month-year hour:minute:second. If hour:minute:second = 00:00:00, then the date string returned has the format, day-month-year.

example

DateString = datestr(DateVector) converts date vectors to date strings. datestr returns a column vector of m date strings, where m is the total number of date vectors in DateVector.

example

DateString = datestr(DateNumber) converts serial date numbers to date strings. datestr returns a column vector of m date strings, where m is the total number of date numbers in DateNumber.

example

DateString = datestr(___,formatOut) specifies the format of the output date strings using formatOut. You can use formatOut with any of the input arguments in the above syntaxes.

DateString = datestr(DateStringIn) converts DateStringIn to date strings in the format, day-month-year hour:minute:second. All date strings in DateStringIn must have the same format.

example

DateString = datestr(DateStringIn,formatOut,PivotYear) converts DateStringIn to DateString, in the format specified by formatOut, and using optional PivotYear to interpret date strings that specify the year as two characters.

example

DateString = datestr(___,'local') returns the date string in the language of the current locale. This is the language you select 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. Use local with any of the previous syntaxes. The local argument must be last in the argument sequence.

Examples

expand all

Convert datetime Array to Date Strings

t = [datetime('now');datetime('tomorrow')]
DateString = datestr(t)
t = 

   19-Sep-2014 23:52:07
   20-Sep-2014 00:00:00


DateString =

19-Sep-2014 23:52:07
20-Sep-2014 00:00:00

datestr returns date strings in the format, day-month-year hour:minute:second.

Convert Date Vector to Date String

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

datestr(DateVector)
ans =

02-Apr-2009 11:07:18

datestr returns a date string in the default date string format.

Convert Date and Time to Specific Format

Format the current date in the mm/dd/yy format.

You can specify this format using a string of symbolic identifiers.

formatOut = 'mm/dd/yy';
datestr(now,formatOut)
ans =

09/19/14

Alternatively, you can specify this format using a numeric identifier.

formatOut = 2;
datestr(now,formatOut)
ans =

09/19/14

You can reformat the date and time, and also show milliseconds.

dt = datestr(now,'mmmm dd, yyyy HH:MM:SS.FFF AM')
dt =

September 19, 2014 11:52:02.393 PM

Convert 12-Hour Time String to 24-Hour Equivalent

Convert the 12-hour time 05:32 p.m. to its 24-hour equivalent.

datestr('05:32 PM','HH:MM')
ans =

17:32

Convert the 24-hour time 05:32 to its 12-hour equivalent.

datestr('05:32','HH:MM PM')
ans =

 5:32 AM

The use of AM or PM in the formatOut string does not influence which characters actually become part of the date string; they only determine whether or not to include them in the date string. MATLAB® selects AM or PM based on the time entered.

Convert Date String from Custom Format

Call datenum inside of datestr to specify the format of the input date string.

formatOut = 'dd mmm yyyy';
datestr(datenum('16-04-55','dd-mm-yy',1900),formatOut)
ans =

16 Apr 1955

Convert Multiple Date Strings

Convert more than one date string input by passing 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

datestr returns a character array of converted date strings in the format, day-month-year.

Convert Date String with Values Outside Normal Range

Call datenum inside of datestr to return the expected value, because the date below uses a value outside its normal range (month=13).

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

24-Jan-1989

Use a Pivot Year

Change the pivot year to change the year range.

Use a pivot year of 1900.

DateStringIn = '4/16/55';
formatOut = 1;
PivotYear = 1900;
datestr(DateStringIn,formatOut,PivotYear)
ans =

16-Apr-1955

For the same date string, use a pivot year of 2000.

PivotYear = 2000;
datestr(DateStringIn,formatOut,PivotYear)
ans =

16-Apr-2055

Return Date String in Local Language

Convert a date number to a date string in the language of the current locale.

Use the local argument in a French locale.

DateNumber = 725935;
formatOut = 'mmmm-dd-yyyy';
str = datestr(DateNumber,formatOut,'local')
str =
Juillet-17-1987

You can make the same call without specifying 'local'.

str = datestr(DateNumber,formatOut)
str =
July-17-1987

In this case, the output defaults to the English language.

Input Arguments

expand all

tdatetime valuesscalar | vector | matrix | multidimensional array

datetime values, specified as a scalar, vector, matrix, or multidimensional datetime array.

DateVector — Date vectorsmatrix

Date vectors, specified as an m-by-6 matrix, where m is the number of full (six-element) date vectors. Each element of DateVector should be a positive or negative integer value with the exception of the seconds element, which can be fractional. If an element falls outside the conventional range, datestr adjusts both that date vector element and the previous element. For example, if the minutes element is 70, datestr adjusts the hours element by 1 and sets the minutes element to 10. If the minutes element is -15, then datestr decreases the hours element by 1 and sets the minutes element to 45. Month values are an exception. datestr sets month values less than 1 to 1.

Example: [2003,10,24,12,45,07]

Data Types: double

DateNumber — Serial date numbersscalar | vector | matrix | array

Serial date numbers, specified as a scalar, vector, matrix, or array of positive double-precision numbers.

Example: 731878

Data Types: double

formatOut — Format of the date string output-1 (default) | string | integer

Format of the date string output, specified as a string of symbolic identifiers or an integer that corresponds to a predefined format. If you do not specify formatOut, then datestr returns a date string in the default date string format dd-mmm-yyyy HH:MM:SS (day-month-year hour:minute:second). By default, if HH:MM:SS = 00:00:00 then the date string returned has the format dd-mmm-yyyy.

The following table shows symbolic identifiers you can use to construct the formatOut string. You can include characters such as a hyphen, space, or colon to separate the fields.

    Note:   The symbolic identifiers describing date string formats are different from those that describe the display formats of datetime arrays.

Symbolic Identifier

Description

Example

yyyy

Year in full

1990, 2002

yy

Year in two digits

90, 02

QQ

Quarter year using letter Q and one digit

Q1

mmmm

Month using full name

March, December

mmm

Month using first three letters

Mar, Dec

mm

Month in two digits

03, 12

m

Month using capitalized first letter

M, D

dddd

Day using full name

Monday, Tuesday

ddd

Day using first three letters

Mon, Tue

dd

Day in two digits

05, 20

d

Day using capitalized first letter

M, T

HH

Hour in two digits
(no leading zeros when symbolic identifier AM or PM is used)

05, 5 AM

MM

Minute in two digits

12, 02

SS

Second in two digits

07, 59

FFF

Millisecond in three digits

057

AM or PM

AM or PM inserted in date string

3:45:02 PM

The formatOut string must follow these guidelines:

  • You cannot specify any field more than once. For example, you cannot use 'yy-mmm-dd-m' because it has two month identifiers. The one exception to this is that you can combine one instance of dd with one instance of any of the other day identifiers. For example, 'dddd mmm dd yyyy' is a valid input.

  • When you use AM or PM, the HH field is also required.

  • You only can use QQ alone or with a year specifier.

This table lists predefined date formats that you can use with datestr.

Numeric Identifier

Date String Format

Example

-1 (default)

'dd-mmm-yyyy HH:MM:SS' or 'dd-mmm-yyyy' if 'HH:MM:SS'= 00:00:00

01-Mar-2000 15:45:17 or 01-Mar-2000

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

'yyyy-mm-dd'
(ISO 8601)

2000-03-01

30

'yyyymmddTHHMMSS'
(ISO 8601)

20000301T154517

31

'yyyy-mm-dd HH:MM:SS'

2000-03-01 15:45:17

DateStringIn — Date strings to convertstring | cell array

Date strings to convert, specified as a single string or a cell array of strings, where each row corresponds to one date string.

datestr considers two-character date string years (for example, '79') to fall within the 100-year range centered around the current year.

All date strings must have the same date format, and they must be in one of the following date formats.

Date String Format

Example

'dd-mmm-yyyy HH:MM:SS'

01-Mar-2000 15:45:17

'dd-mmm-yyyy'

01-Mar-2000

'mm/dd/yyyy'

03/01/2000

'mm/dd/yy'

03/01/00

'mm/dd'

03/01

'mmm.dd,yyyy HH:MM:SS'

Mar.01,2000 15:45:17

'mmm.dd,yyyy'

Mar.01,2000

'yyyy-mm-dd HH:MM:SS'

2000-03-01 15:45:17

'yyyy-mm-dd'

2000-03-01

'yyyy/mm/dd'

2000/03/01

'HH:MM:SS'

15:45:17

'HH:MM:SS PM'

3:45:17 PM

'HH:MM'

15:45

'HH:MM PM'

3:45 PM

    Note:   When converting from one date string format to another, you should first pass the strings to the datenum function, so that you can specify the format of the input date strings. This ensures that the format of the input date strings is correctly interpreted. For example, see Convert Date String from Custom Format.

PivotYear — Start year of 100-year date rangepresent minus 50 years (default) | integer

Start year of the 100-year date range in which a two-character year resides, specified as an integer. Use a pivot year to interpret date strings that specify the year as two characters.

If formatIn contains the time of day, the pivot year is computed from the current time of the current day, month, and year. Otherwise it is computed from midnight of the current day, month, and year.

Example: 2000

Data Types: double

Output Arguments

expand all

DateString — Date stringsstring | two-dimensional character array

Date strings, returned as a character array with m rows, where m is the total number of input date vectors, serial date numbers, or date strings. The default output date string format is dd-mmm-yyyy HH:MM:SS (day-month-year hour:minute:second) unless the hours, minutes and seconds are all 0 in which case HH:MM:SS is suppressed.

More About

expand all

Tips

  • To convert a date string not in a predefined MATLAB® date format, first convert the date string to a date number, using either datenum or datevec.

Was this topic helpful?