21/07/2020 Arrays that represent points in time - MATLAB

datetime
Arrays that represent points in time

Description
datetime arrays represent points in time using the proleptic ISO calendar. datetime values have flexible display
formats up to nanosecond precision and can account for time zones, daylight saving time, and leap seconds.

Creation

Syntax

t = datetime
t = datetime(relativeDay)

t = datetime(DateStrings)
t = datetime(DateStrings,'InputFormat',infmt)

t = datetime(DateVectors)
t = datetime(Y,M,D)
t = datetime(Y,M,D,H,MI,S)
t = datetime(Y,M,D,H,MI,S,MS)

t = datetime(X,'ConvertFrom',dateType)

t = datetime( ___ ,Name,Value)

Description

t = datetime returns a scalar datetime array corresponding to the current date and time.
example
t = datetime(relativeDay) uses the date specified by relativeDay. The relativeDay
input can be 'today', 'tomorrow', 'yesterday', or 'now'.

t = datetime(DateStrings) creates an array of datetime values from the text in

DateStrings representing points in time.
example
t = datetime(DateStrings,'InputFormat',infmt) interprets DateStrings using the
format specified by infmt. All values in the input argument DateStrings must have the same
format.
To avoid ambiguities between similar formats, specify 'InputFormat' and its corresponding
value, infmt.
To control the display format of t, specify the 'Format' name-value pair argument, or set the
Format property of t.
t = datetime(DateVectors) creates a column vector of datetime values from the date vectors example
in DateVectors.

t = datetime(Y,M,D) creates an array of datetime values for corresponding elements of the Y,

M, and D (year, month, day) arrays. The arrays must be of the same size (or any can be a scalar).
You also can specify the input arguments as a date vector, [Y M D].

t = datetime(Y,M,D,H,MI,S) also creates H, MI, and S (hour, minute, and second) arrays. All
arrays must be of the same size (or any can be a scalar). You also can specify the input arguments
as a date vector, [Y M D H MI S].

t = datetime(Y,M,D,H,MI,S,MS) adds an MS (millisecond) array. All arrays must be of the

same size (or any can be a scalar).

https://www.mathworks.com/help/matlab/ref/datetime.html 1/9
21/07/2020 Arrays that represent points in time - MATLAB

t = datetime(X,'ConvertFrom',dateType) converts the numeric values in X to a example

datetime array t. The dateType argument specifies the type of values in X.
If X contains POSIX® times or Julian dates that represent local times, then specify the appropriate
time zone for t using the 'TimeZone' name-value pair argument. If you do not specify a time
zone, then the POSIX times or Julian dates in X are treated as UTC times, not local times.

t = datetime( ___ ,Name,Value) specifies additional options using one or more name-value
pair arguments, in addition to any of the input arguments in the previous syntaxes. For example,
you can specify the display format of t using the 'Format' name-value pair argument.
For best performance when creating datetime values from text, specify either 'Format' or
'InputFormat' and its corresponding value, infmt.
Input Arguments expand all

relativeDay — Day relative to current date

 'yesterday' | 'today' | 'tomorrow' | 'now'

Day relative to the current date, specified as one of the following values.

Value of relativeDay Description

'yesterday' Date of the previous day, at midnight

'today' Current date, at midnight

'tomorrow' Date of the following day, at midnight

'now' Current date and time

DateStrings — Text representing dates and times

 character array | cell array of character vectors | string array

Text representing dates and times, specified as a character array, a cell array of character vectors, or a string
array. The datetime function first attempts to match the format of DateStrings to common formats. If you
know the format, specify 'InputFormat' and its corresponding infmt value, or the 'Format' name-value pair
argument.

Example: '24-Oct-2014 12:45:07'

Example: {'15-Oct-2013','20-Nov-2014'}

Example: ["11-Nov-2016","12-Dec-2016"]

Data Types: char | cell | string

infmt — Format of input text

 character vector | string scalar

DateVectors — Date vectors

 matrix

Date vectors, specified as an m-by-6 or m-by-3 matrix containing m full or partial date vectors, respectively. A full
date vector has six elements, specifying year, month, day, hour, minute, and second, in that order. A partial date
vector has three elements, specifying year, month, and day, in that order. Each element of DateVector should
be a positive or negative integer value except for the seconds element, which can be fractional. If an element falls
outside the conventional range, datetime adjusts both that date vector element and the previous element. For

https://www.mathworks.com/help/matlab/ref/datetime.html 2/9
21/07/2020 Arrays that represent points in time - MATLAB

example, if the minutes element is 70, then datetime adjusts the hours element by 1 and sets the minutes
element to 10. If the minutes element is -15, then datetime decreases the hours element by 1 and sets the
minutes element to 45.

Example: [2014 10 24 12 45 07]

Example: [2014 10 24]
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Y,M,D — Year, month, and day arrays

 numeric arrays

Year, month, and day arrays specified as numeric arrays. These arrays must be the same size, or any one can be
a scalar. Y,M,D should be integer values.

• If Y,M,D are all scalars or all column vectors, then you can specify the input arguments as a date vector, [Y M
D].
• If an element of the Y, M, or D inputs falls outside the conventional range, then datetime adjusts both that
element and the same element of the previous input. For details, see the description for the DateVectors
input argument.

Example: 2003,10,24

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Y,M,D,H,MI,S — Year, month, day, hour, minute, and second arrays

 numeric arrays

Y,M,D,H,MI,S,MS — Year, month, day, hour, minute, second, and millisecond arrays
 numeric arrays

X — Numeric values
 array

dateType — Type of values in X

 'datenum' | 'excel' | 'excel1904' | 'juliandate' | ...

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the
corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any
order as Name1,Value1,...,NameN,ValueN.

Example: 'Format','eeee MMMM d, y','TimeZone','local' applies a display format to datetime values and
specifies the local time zone.

'Format' — Display format

 'default' | 'preserveinput' | character vector | string scalar

'Locale' — Locale of DateStrings

 character vector | string scalar

https://www.mathworks.com/help/matlab/ref/datetime.html 3/9
21/07/2020 Arrays that represent points in time - MATLAB

'PivotYear' — Start year of 100-year date range

 year(datetime('now'))-50 (default) | integer

'TimeZone' — Time zone

 '' (default) | character vector | string scalar

Properties expand all

Format — Display format

 'default' | character vector | string scalar

TimeZone — Time zone

 '' (default) | character vector | string scalar

Year — Year number

 numeric array

Month — Month number

 numeric array

Month number of each value in the datetime array, specified as a numeric array that is the same size and shape
as the datetime array. Each month number is an integer value from 1 to 12. If you set a value outside that
range, then the Year property adjusts accordingly, and the Month property stays within the range 1 to 12. For
example, month 0 corresponds to month 12 of the previous year. For historical dates, the month number is based
on the proleptic Gregorian calendar.

Day — Day-of-month number

 numeric array

Hour — Hour number

 numeric array

Minute — Minute number

 numeric array

Second — Second number

 numeric array

SystemTimeZone — System time zone setting

 character vector | string scalar

Examples
collapse all

https://www.mathworks.com/help/matlab/ref/datetime.html 4/9
21/07/2020 Arrays that represent points in time - MATLAB

 Current Date and Time in Specific Time Zone

Specify the current date and time in the local system time zone.
View MATLAB Command

t = datetime('now','TimeZone','local','Format','d-MMM-y HH:mm:ss Z')

t = datetime
29-Feb-2020 00:09:02 -0500

Specify the current date and time in the time zone represented by Seoul, Korea

t = datetime('now','TimeZone','Asia/Seoul','Format','d-MMM-y HH:mm:ss Z')

t = datetime
29-Feb-2020 14:09:02 +0900

 Date and Time from Character Vectors

Create a datetime array from a cell array of character vectors.

View MATLAB Command

DateStrings = {'2014-05-26';'2014-08-03'};
t = datetime(DateStrings,'InputFormat','yyyy-MM-dd')
t = 2x1 datetime
26-May-2014
03-Aug-2014

The datetime values in t display using the default format, and not the format of the input dates.

 Date and Time from String Array

Starting in R2016b, you can create string arrays with the string
function and convert them to datetime values. View MATLAB Command

str = string({'2016-03-24','2016-04-19'})
str = 1x2 string
"2016-03-24" "2016-04-19"

Convert the strings, specifying the input format as yyyy-MM-dd. The format must be specified as a character
vector, even though str is a string array.

t = datetime(str,'InputFormat','yyyy-MM-dd')
t = 1x2 datetime
24-Mar-2016 19-Apr-2016

Time from Text Representing Fractional Seconds

https://www.mathworks.com/help/matlab/ref/datetime.html 5/9
21/07/2020 Arrays that represent points in time - MATLAB


Create a datetime value from text that represents a date and time
to millisecond precision. To convert text in a format that the View MATLAB Command
datetime function cannot parse without more information, specify
the 'InputFormat' name-value pair argument.

d = '2018-06-25 11:23:37.712';
t = datetime(d,'InputFormat','yyyy-MM-dd HH:mm:ss.SSS')
t = datetime
25-Jun-2018 11:23:37

The conversion does keep the fractional seconds. However, by default datetime arrays do not display fractional
seconds. To display them, specify either the 'Format' name-value pair or the Format property.

t.Format = 'MMM dd, yyyy HH:mm:ss.SSS'

t = datetime
Jun 25, 2018 11:23:37.712

The 'InputFormat' argument applies only to conversions from input text. The Format property specifies the
display for any datetime array.

 Date and Time from Text with Literal Characters

Convert dates in ISO 8601 format to datetime values.

View MATLAB Command
Create a cell array of character vectors containing dates in ISO 8601
format. In this format, the letter T is used as a delimiter that
separates a date and a time. Each character vector includes a time zone offset. The letter Z indicates no offset
from UTC.

DateStrings = {'2014-05-26T13:30-05:00';'2014-08-26T13:30-04:00';'2014-09-26T13:30Z'}
DateStrings = 3x1 cell
{'2014-05-26T13:30-05:00'}
{'2014-08-26T13:30-04:00'}
{'2014-09-26T13:30Z' }

Convert the character vectors to datetime values. When specifying the input format, enclose the letter T in single
quotes to indicate that it is a literal character. Specify the time zone of the output datetime array using the
TimeZone name-value pair argument.

t = datetime(DateStrings,'InputFormat','uuuu-MM-dd''T''HH:mmXXX','TimeZone','UTC')
t = 3x1 datetime
26-May-2014 18:30:00
26-Aug-2014 17:30:00
26-Sep-2014 13:30:00

The datetime values in t display in the default format.

 Date and Time from Text in Foreign Language

Create a cell array of character vectors containing dates in French.

https://www.mathworks.com/help/matlab/ref/datetime.html 6/9
21/07/2020 Arrays that represent points in time - MATLAB

View MATLAB Command

C = {'8 avril 2013','9 mai 2013';'10 juin 2014','11 juillet 2014'}

C = 2x2 cell
{'8 avril 2013'} {'9 mai 2013' }
{'10 juin 2014'} {'11 juillet 2014'}

Convert the character vectors in C to datetime values. If your computer is set to a locale that uses English, you
must specify the 'Locale' name-value pair argument to indicate that the strings are in French.

t = datetime(C,'InputFormat','d MMMM yyyy','Locale','fr_FR')

t = 2x2 datetime
08-Apr-2013 09-May-2013
10-Jun-2014 11-Jul-2014

The datetime values in t display in the default format, and in the language MATLAB uses depending on your
system locale.

 Date and Time from Vectors

Create a datetime array from individual arrays of year, month, and

day values. View MATLAB Command

Create sample numeric arrays of year values Y and day values D. In

this case, the month value M is a scalar.

Y = [2014;2013;2012];
M = 01;
D = [31;30;31];
Create the datetime array.

t = datetime(Y,M,D)
t = 3x1 datetime
31-Jan-2014
30-Jan-2013
31-Jan-2012

Specify a custom display format for the output, using the Format name-value pair argument.

t = datetime(Y,M,D,'Format','eeee, MMMM d, y')

t = 3x1 datetime
Friday, January 31, 2014
Wednesday, January 30, 2013
Tuesday, January 31, 2012

 Convert Excel Date Number to Datetime

Create a sample array of Excel® date numbers that represent a

number of days since January 0, 1900. View MATLAB Command

https://www.mathworks.com/help/matlab/ref/datetime.html 7/9
21/07/2020 Arrays that represent points in time - MATLAB

X = [39558, 39600; 39700, 39800]

X = 2×2

39558 39600
39700 39800

Convert the values in X to datetime values.

t = datetime(X,'ConvertFrom','excel')
t = 2x2 datetime
20-Apr-2008 01-Jun-2008
09-Sep-2008 18-Dec-2008

Tips
• For a list of datetime functions, see Dates and Time.
• For a list of core MATLAB functions that accept datetime arrays as input arguments, see Core Functions
Supporting Date and Time Arrays.

Compatibility Considerations expand all

 'InputFormat' month formats M and MM do not recognize names, and MMM does not
recognize abbreviations
Behavior changed in R2020a

Extended Capabilities

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

 C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

 Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing
Toolbox™.

See Also
NaT | calendarDuration | cellstr | char | duration | leapseconds | string | timezones

Topics
Represent Dates and Times in MATLAB
Set Date and Time Display Format
Specify Time Zones
Generate Sequence of Dates and Time

Introduced in R2014b

https://www.mathworks.com/help/matlab/ref/datetime.html 8/9
21/07/2020 Arrays that represent points in time - MATLAB

https://www.mathworks.com/help/matlab/ref/datetime.html 9/9