datestr

(Not recommended; use string or char) Convert date and time to string format

datestr is not recommended. To convert datetime values to text, use the string or char function instead. For more information on updating your code, see Version History or Replace Discouraged Instances of Serial Date Numbers and Date Strings.

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

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.

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.

Note: In some circumstances, datestr interprets a date vector as though it were a vector of six date numbers. For more information, see Converting Date Vector Returns Unexpected Output.

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.

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.

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.

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

Convert datetime Array to Date Strings

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

t = 2x1 datetime
   05-Sep-2024 15:20:53
   06-Sep-2024 00:00:00

DateString = datestr(t)

DateString = 2x20 char array
    '05-Sep-2024 15:20:53'
    '06-Sep-2024 00:00:00'

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

Convert Date Vector to Text

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.

Convert Date and Time to Specific Format

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 = 
'09/05/24'

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

formatOut = 2;
datestr(now,formatOut)

ans = 
'09/05/24'

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

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

dt = 
'September 05, 2024  3:20:50.058 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 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.

Convert Date String from Custom Format

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'

Convert Multiple Date Strings

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.

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

t — Dates and times

datetime array

Dates and times, specified as a datetime array.

Note: The datestr function does not accept datetime values that are NaTs as inputs.

Data Types: datetime

DateVector — Date vectors

matrix

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

DateNumber — Serial date numbers

array of positive double-precision numbers

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

Example: 731878

Data Types: double

formatOut — Format of the output representing dates and times

-1 (default) | character vector | string scalar | integer

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

DateStringIn — Text representing dates and times to convert

character vector | cell array | string array

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.

PivotYear — Start year of 100-year date range

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

DateString — Text representing dates and times

character vector | two-dimensional character array

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

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The datestr function supports tall arrays with the following usage notes and limitations:

• The first argument must be a column vector or an array returned by datevec.

• If the first argument is a datevec array, then the rows must be within the year range 1500:2499.

For more information, see Tall Arrays.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

R2022b: Not recommended

There are no plans to remove datestr. However, the string and char functions are recommended instead for converting datetime arrays to text. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

For example, represent the current date and time as a datetime value. Then convert it to a string.

d = datetime("now")

d = datetime
   15-Apr-2022 15:53:28

str = string(d)

str = 
    "15-Apr-2022 15:53:28"

To convert a date vector to text, first convert it to a datetime value. Then convert it to text.

dv = [2022 4 15 15 53 28];
d = datetime(dv);
d = string(d)

d = 
    "15-Apr-2022 15:53:28"