datestr

Convert date and time to string format

collapse all in page

Syntax

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

Description

example

Note

While datestr returns text representing dates and times, it is recommended that you use datetime values to represent points in time, and then convert them to text using the char, cellstr, or string functions.

DateString = datestr(t) converts the datetime values in the input array t to text representing dates and times.

The datestr function returns a character array with m rows, where m is the total number of datetime values in t. By default, datestr returns text in the format, day-month-year hour:minute:second. If hour:minute:second is 00:00:00, then the text returned has the format, day-month-year.

example

DateString = datestr(DateVector) converts date vectors to text representing dates and times. The datestr function returns a character array with m rows, where m is the total number of date vectors in DateVector.

example

DateString = datestr(DateNumber) converts serial date numbers to text representing dates and times. The datestr function returns a character array with m rows, where m is the total number of date numbers in DateNumber.

example

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

DateString = datestr(DateStringIn) converts DateStringIn to text in the format, day-month-year hour:minute:second. All dates and times represented 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 dates that specify the year as two characters.

example

DateString = datestr(___,'local') returns the date in the language of the current locale. This language is the language you select by means of your computer's operating system. If you leave 'local' out of the argument list, datestr returns text 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

collapse all

Open Live Script
t = [datetime('now');datetime('tomorrow')]
t = 2x1 datetime
   17-Aug-2020 15:34:50
   18-Aug-2020 00:00:00


DateString = datestr(t)
DateString = 2x20 char array
    '17-Aug-2020 15:34:50'
    '18-Aug-2020 00:00:00'

datestr returns text representing the dates and times in the format, day-month-year hour:minute:second.

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

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

datestr returns text representing the date and time in the default format.

Open Live Script

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

You can specify this format using symbolic identifiers. 

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

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

formatOut = 2;
datestr(now,formatOut)
ans = 
'08/17/20'

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

dt = datestr(now,'mmmm dd, yyyy HH:MM:SS.FFF AM')
dt = 
'August 17, 2020  3:34:43.863 PM'
Open Live Script

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 output text does not influence which characters actually become part of the text; they only determine whether or not to include the characters. MATLAB® selects AM or PM based on the time entered.

Open Live Script

Call datenum inside of datestr to specify the format of the input text representing a date. 

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

Convert multiple character vectors representing dates by passing them in a cell array.

All input dates 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 = 3x11 char array
    '16-Sep-2007'
    '14-May-1996'
    '29-Nov-2010'

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

Open Live Script

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'
Open Live Script

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, use a pivot year of 2000. 

PivotYear = 2000;
datestr(DateStringIn,formatOut,PivotYear)
ans = 
'16-Apr-2055'

Convert a date number to text 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

collapse all

Dates and times, specified as a datetime array.

Data Types: datetime

Date vectors, specified as an m-by-6 matrix, where m is the number of full (six-element) date vectors. Each element of DateVector must be a positive or negative integer value except for 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, then 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

Serial date numbers, specified as an array of positive double-precision numbers.

Example: 731878

Data Types: double

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

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

Note

The symbolic identifiers describing date and time formats are different from the identifiers 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 text representing time

3:45:02 PM

The formatOut character vector 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 and Time 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

Text representing dates and times to convert, specified as a single character vector, a cell array of character vectors, or a string array, where each row corresponds to one date and time.

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

All text representing dates and times must have the same date format, and they must be in one of the following date formats.

Format of Text Representing Dates and Times

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 and time format to another, first pass the text to the datenum function, so that you can specify the format of the inputs. This approach ensures that the format of the input dates and times is correctly interpreted. For example, see Convert Date String from Custom Format.

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 dates 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

Note

If the input date format specifies a four-character year, then the last two characters are truncated, and the first two characters specify the year. For example, if the date and pivot year are specified as ('25122015','ddmmyyyy',2000), then the resulting date is 25-12-2020, not 25-12-2015.

Data Types: double

Output Arguments

collapse all

Text representing dates and times, returned as a character array with m rows, where m is the total number of input dates and times. The default output 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.

Tips

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

Extended Capabilities

See Also

| | | | | |

Topics

Introduced before R2006a

MATLAB Documentation

Support