datetime
Arrays that represent points in time
Description
The datetime
data type represents points in time, such as
August 24, 2020, 10:50:30 a.m. A datetime
array specifies the year,
month, day, hour, minute, and second components associated with each point in time
stored in the array (using the proleptic ISO calendar).
Also, datetime
arrays provide:
Flexible formats for both output display and input text parsing.
Storage for fractional seconds out to nanosecond precision.
Properties to account for time zones, daylight saving time, and leap seconds.
Creation
Syntax
Description
returns a scalar
t
= datetimedatetime
array corresponding to the current date and
time.
uses the date specified by t
= datetime(relativeDay
)relativeDay
. The
relativeDay
input can be 'today'
,
'tomorrow'
, 'yesterday'
, or
'now'
.
creates an array of datetime values from the text in
t
= datetime(DateStrings
)DateStrings
representing points in time.
interprets t
= datetime(DateStrings
,'InputFormat',infmt
)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
.
creates a column vector of datetime values from the date vectors in
t
= datetime(DateVectors
)DateVectors
.
creates an array of datetime values for corresponding elements of the
t
= datetime(Y,M,D
)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]
.
also creates t
= datetime(Y,M,D,H,MI,S
)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]
.
adds an t
= datetime(Y,M,D,H,MI,S,MS
)MS
(millisecond) array. All arrays must be of the
same size (or any can be a scalar).
converts the numeric values in t
= datetime(X
,'ConvertFrom',dateType
)X
to a
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.
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
= datetime(___,Name,Value
)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
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
Format of the input text representing dates and times, specified as a character vector or string scalar that contains letter identifiers:
If
infmt
does not include a date specifier, thendatetime
assumes that the values inDateStrings
occur during the current day.If
infmt
does not include a time specifier, thendatetime
assumes that the values inDateStrings
occur at midnight.
This table shows several common input formats and includes examples of the formatted input for the date, Saturday, April 19, 2014 at 9:41:06.12345 PM in New York City.
Value of
infmt | Example |
---|---|
'yyyy-MM-dd' | 2014-04-19 |
'dd/MM/yyyy' | 19/04/2014 |
'dd.MM.yyyy' | 19.04.2014 |
'yyyy年 MM月
dd日' | 2014年 04月 19日 (Characters for
Japanese locale,
ja_JP ) |
'MMMM d, yyyy' | April 19,
2014 |
'eeee, MMMM d, yyyy h:mm
a' | Saturday, April 19,
2014 9:41 PM |
'MMMM d, yyyy HH:mm:ss
Z' | April 19, 2014
21:41:06 -0400 |
'yyyy-MM-dd''T''HH:mmXXX' | 2014-04-19T21:41-04:00 |
'yyyy-MM-dd
HH:mm:ss.SSS' | 2014-04-19
21:41:06.123 |
For input text that represents fractional seconds, you can specify
infmt
with up to nine S
characters to indicate fractional second digits. For example,
'yyyy-MM-dd HH:mm:ss.SSS'
is a format for text
that represents dates and times to millisecond precision.
For a complete list of valid letter identifiers, see the Format
property
for datetime arrays. You can use most of the identifiers as both input
formats and display formats. However, do not use
MMMMM
or any of the e
identifiers to interpret input text, as these identifiers are for
display only.
Note
The letter identifiers that datetime
accepts
are different from the identifiers used by the
datestr
, datenum
, and
datevec
functions.
Data Types: char
| string
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 example, if the minutes element is
70
, then datetime
increases
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
.
If any value is a
NaN
, then the correspondingdatetime
value is aNaT
.If any value is
Inf
or-Inf
, then the correspondingdatetime
value is aInf
or-Inf
.
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
, orD
inputs falls outside the conventional range, thendatetime
adjusts both that element and the same element of the previous input. For details, see the description for theDateVectors
input argument.If any value is a
NaN
, then the correspondingdatetime
value is aNaT
.If any value is
Inf
or-Inf
, then the correspondingdatetime
value is aInf
or-Inf
.
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
Year, month, day, hour, minute, and second arrays specified as numeric
arrays. These arrays must be the same size, or any one can be a scalar.
Specify fractional seconds as part of the seconds input,
S
. The Y,M,D,H,MI
arrays must
contain integer values.
If
Y,M,D,H,MI,S
are all scalars or all column vectors, then you can specify the input arguments as a date vector[Y M D H MI S]
.If an element of the
Y
,M
,D
,H
,MI
, orS
inputs falls outside the conventional range, thendatetime
adjusts both that element and the same element of the previous input. For details, see the description for theDateVectors
input argument.If any value is a
NaN
, then the correspondingdatetime
value is aNaT
.If any value is
Inf
or-Inf
, then the correspondingdatetime
value is aInf
or-Inf
.
Example: 2003,10,24,12,45,07.451
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Y,M,D,H,MI,S,MS
— Year, month, day, hour, minute, second, and millisecond arrays
numeric arrays
Year, month, day, hour, minute, second, and millisecond arrays,
specified as numeric arrays. These arrays must be the same size, or any
one can be a scalar. The Y,M,D,H,MI,S
arrays must
contain integer values. MS
can contain fractional
milliseconds.
If an element of the Y
, M
,
D
, H
, MI
,
S
, or MS
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.
If any value is a
NaN
, then the correspondingdatetime
value is aNaT
.If any value is
Inf
or-Inf
, then the correspondingdatetime
value is aInf
or-Inf
.
Example: 2003,10,24,12,45,07,10.52
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
X
— Numeric values
array
Numeric values, specified as an array.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
dateType
— Type of values in X
'datenum'
| 'excel'
| 'excel1904'
| 'juliandate'
| ...
Type of values in X
, specified as one of these
values.
Value of | Type of Values in
|
---|---|
|
Number of days since 0-Jan-0000 (proleptic ISO calendar). |
| Number of days since 0-Jan-1900. Excel® date numbers are rounded to the nearest microsecond. Note: Excel incorrectly assumes that the year 1900 is a leap year. Therefore, when computing Excel date numbers there is a discontinuity of one extra day between February 28, 1900 and March 1, 1900. |
| Number of days since 0-Jan-1904. Excel date numbers are rounded to the nearest microsecond. Note: Excel incorrectly assumes that the year 1900 is a leap year. Therefore, when computing Excel date numbers there is a discontinuity of one extra day between February 28, 1900 and March 1, 1900. |
|
Number of days since noon UTC 24-Nov-4714 BCE (proleptic Gregorian calendar). If you convert Example:
Convert T = datetime(X,'ConvertFrom','juliandate',... 'TimeZone','America/New_York') Then, you can convert T.TimeZone = '' |
|
Number of days since midnight UTC 17-Nov-1858. If you convert Example:
Convert T = datetime(X,'ConvertFrom','modifiedjuliandate',... 'TimeZone','America/New_York') Then, you can convert T.TimeZone = '' |
|
Number of seconds since 1-Jan-1970 00:00:00 UTC, not counting leap seconds. If you convert Example:
Convert T = datetime(X,'ConvertFrom','posixtime',... 'TimeZone','America/New_York') Then, you can convert T.TimeZone = '' |
|
Dates as YYYYMMDD numeric values. For example,
|
| Number of "clock ticks" since 1-Jan-1900 00:00:00 UTC, where each clock tick is 2^-32 seconds. |
| Number of "clock ticks" since 1-Jan-0001 00:00:00 UTC, where each clock tick is 100 ns. |
| Number of "clock ticks" since 1-Jan-1601 00:00:00 UTC, where each clock tick is 100 ns. |
| Number of nanoseconds that have elapsed
since J2000. The Common Data Format (CDF) defines
the The input
To convert
Note: J2000 is January 1, 2000, 12:00 Terrestrial Time (TT). TT differs from UTC due to two factors:
As a consequence, J2000
actually occurs 64.184 seconds before noon in the
D = datetime(2000,1,1,11,58,55,816,"TimeZone","UTCLeapSeconds") D = 2000-01-01T11:58:55.816Z Example: Create an
X = int64([702077514184000000; ... 702163914184000000; ... 702250314184000000]) X =
3x1 int64 column vector
702077514184000000
702163914184000000
702250314184000000
D = datetime(X,"ConvertFrom","tt2000","TimeZone","UTCLeapSeconds") D =
3x1 datetime array
2022-04-01T09:30:45.000Z
2022-04-02T09:30:45.000Z
2022-04-03T09:30:45.000Z
|
| Number of seconds since the default epoch time. The default epoch time is 1-Jan-1970 00:00:00 UTC. Example: Convert
T = datetime(X,'ConvertFrom','epochtime') |
| Number of seconds since an epoch. To specify an epoch, use the
additional Example: Convert T = datetime(X,'ConvertFrom',... 'epochtime','Epoch','2000-01-01') |
| Number of "clock ticks" since an epoch. In addition to specifying
Example: Convert
T = datetime(X,'ConvertFrom',... 'epochtime','Epoch','2000-01-01','TicksPerSecond',1000) |
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
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
Display format of the values in the output array, specified as the
comma-separated pair consisting of 'Format'
and
one of the following values.
Value of
Format | Description |
---|---|
|
Use the default display format. |
|
Use the format specified by the input
format, |
character vector or string scalar | Use a format you specify with a character vector or string scalar. |
If you specify your own format, then you must use valid letter
identifiers. For a complete list of valid letter identifiers, see
the Format
property.
The factory default format depends on your system locale. To change the default display format, see Default datetime Format.
If you specify a DateStrings
input but do not
specify the 'InputFormat'
parameter, then
datetime
tries to use the
Format
value to interpret
DateStrings
.
Example: 'Format','eeee, MMMM d, yyyy HH:mm:ss'
displays a date and time such as Wednesday, April 9, 2014 21:41:06
.
Data Types: char
| string
Locale
— Locale of DateStrings
character vector | string scalar
Locale of DateStrings
input argument values,
specified as the comma-separated pair consisting of
'Locale'
and a character vector or string
scalar. The Locale
value determines how
datetime
interprets
DateStrings
. However, it does not determine
how the output datetime
values display.
The Locale
value can be:
"system"
, to specify your system locale.A string scalar or character vector in the form
, wherexx
_YY
xx
is a lowercase ISO 639-1 two-letter code that specifies a language, andYY
is an uppercase ISO 3166-1 alpha-2 code that specifies a country.
This table lists some common values for the locale.
Locale | Language | Country |
---|---|---|
"de_DE" | German | Germany |
"en_GB" | English | United Kingdom |
"en_US" | English | United States |
"es_ES" | Spanish | Spain |
"fr_FR" | French | France |
"it_IT" | Italian | Italy |
"ja_JP" | Japanese | Japan |
"ko_KR" | Korean | Korea |
"nl_NL" | Dutch | Netherlands |
"zh_CN" | Chinese (simplified) | China |
You can use the 'Locale'
name-value pair only
when you use the DateStrings
input
argument.
Example: 'Locale',"de_DE"
Note
The Locale
value determines how input text
values are interpreted. The output datetime values always
display in the language specified by the Locale option in the Datetime format section of the Preferences
window.
To change the default datetime locale for display, see Set Command Window Preferences.
To convert datetime values to text using a different locale, use the
char
,cellstr
, orstring
functions.
Data Types: char
| string
PivotYear
— Start year of 100-year date range
year(datetime('now'))-50
(default) | integer
Start year of the 100-year date range in which a two-character
year resides, specified as the comma-separated pair consisting of
'PivotYear'
and an integer. Use a pivot year
to interpret dates that specify the year as two characters. That is,
the pivot year has an effect only when the infmt
argument includes y
or
yy
.
You can use the 'PivotYear'
name-value pair
only when you use the DateStrings
input
argument.
Example: 'PivotYear',1900
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
TimeZone
— Time zone
''
(default) | character vector | string scalar
Time zone, specified as the comma-separated pair consisting of
'TimeZone'
and a character vector or string
scalar that specifies the time zone.
The datetime
function uses the value of
'TimeZone'
to interpret the input data and
set the TimeZone
property of the output array. If
the input data are character vectors or strings that include a time
zone, then the datetime
function converts all
values to the specified time zone.
For more information and a list of time zones, see the TimeZone
property.
Data Types: char
| string
Properties
Format
— Display format
'default'
| character vector | string scalar
Display format, specified as 'default'
, a character
vector, or a string scalar.
Value of Format | Description |
---|---|
| Use the default display format. |
character vector or string scalar | Use a format you specify with a character vector or string scalar. |
If you specify a format of your own, then it must use valid letter identifiers that correspond to the Unicode® Locale Data Markup Language (LDML) standard for dates and times. For more information on the LDML, see Unicode Technical Standard #35, particularly the Date Field Symbol Table.
Example: 'eeee, MMMM d, yyyy HH:mm:ss'
displays a date
and time such as Wednesday, April 9, 2014
21:41:06
.
To separate fields, you can include nonletter characters such as a hyphen,
space, colon, or any non-ASCII characters. To include the letters
A-Z
and a-z
as literal characters
in the format, enclose them in single quotes.
Example: 'uuuu-MM-dd''T''HH:mm:ss'
displays a date and
time, such as 2014-04-09T21:41:06
.
Note
The letter identifiers that datetime
accepts are
different from the identifiers used by the datestr
,
datenum
, and datevec
functions.
The factory default format depends on your system locale. To change the default display format, see Default datetime Format.
Examples of Common Formats
This table lists common display formats. The examples show formatted output for the date, Wednesday, April 9, 2014 at 9:41:06.12345 PM, in New York City.
Value of
Format | Example |
---|---|
'yyyy-MM-dd' | 2014-04-09 |
'dd/MM/yyyy' | 09/04/2014 |
'dd.MM.yyyy' | 09.04.2014 |
'yyyy年 MM月
dd日' | 2014年 04月 09日 (Characters for
Japanese locale,
ja_JP ) |
'MMMM d, yyyy' | April 9,
2014 |
'eeee, MMMM d, yyyy h:mm
a' | Wednesday, April 9,
2014 9:41 PM |
'MMMM d, yyyy HH:mm:ss
Z' | April 9, 2014
21:41:06 -0400 |
'yyyy-MM-dd''T''HH:mmXXX' | 2014-04-09T21:41-04:00 |
'yyyy-MM-dd
HH:mm:ss.SSS' | 2014-04-09
21:41:06.123 |
All Date and Time Formats
Use these identifiers to specify the display formats of date and time fields. The display formats show output for the date, Wednesday, April 9, 2014 at 9:41:06.12345 PM, in New York City.
Letter Identifier | Description | Display |
---|---|---|
G | Era | CE |
y | Gregorian year, with no leading zeros. A Gregorian year value assigns positive values to CE years and negative values to BCE years, with no year being year 0. See the Note that follows this table. | 2014 |
yy | Gregorian year, using only the last two digits. A Gregorian year value assigns positive values to CE years and negative values to BCE years, with no year being year 0. See the Note that follows this table. | 14 |
yyy , yyyy
... | Gregorian year, using at least the number of digits
specified by the number of instances of
'y' . A Gregorian year value
assigns positive values to CE years and negative values
to BCE years, with no year being year 0. | For the year 2014, 'yyy' displays
2014 , while
'yyyyy' displays
02014 . |
u , uu ,
... | ISO year. A single number designating the year. An ISO year value assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0. | 2014 |
Q | Quarter, using one digit | 2 |
QQ | Quarter, using two digits | 02 |
QQQ | Quarter, abbreviated | Q2 |
QQQQ | Quarter, full name | 2nd
quarter |
M | Month, numerical using one or two digits | 4 |
MM | Month, numerical using two digits | 04 |
MMM | Month, abbreviated name | Apr |
MMMM | Month, full name | April |
MMMMM | Month, capitalized first letter | A |
W | Week of the month, using one digit | 2 |
d | Day of the month, using one or two digits | 9 |
dd | Day of the month using two digits | 09 |
D | Day of the year, using one, two, or three digits | 99 |
DD | Day of the year using two digits | 99 |
DDD | Day of the year using three digits | 099
|
e | Day of the week (numerical, using one or two digits) | 4 , where Sunday is the first day
of the week. |
ee | Day of the week (numerical, using two digits) | 04 |
eee | Day, abbreviated name | Wed |
eeee | Day, full name | Wednesday |
eeeee | Day, capitalized first letter | W |
a | Day period (AM or PM) | PM |
h | Hour, 12-hour clock notation using one or two digits | 9 |
hh | Hour, 12-hour clock notation using two digits | 09 |
H | Hour, 24-hour clock notation using one or two digits | 21 |
HH | Hour, 24-hour clock notation using two digits | 21 |
m | Minute, using one or two digits | 41 |
mm | Minute, using two digits | 41 |
s | Second, using one or two digits | 6 |
ss | Second, using two digits | 06 |
S , SS , ...,
SSSSSSSSS | Fractional second, using the number of digits
specified by the number of instances of
'S' (up to 9 digits). | 'SSS' truncates 6.12345 seconds to
6.123 . |
Note
Some identifiers modify their behavior based on locale, input data, the values of other identifiers, or the presence of extra identifiers.
Effects of locale:
When displaying or interpreting localized names, such as day or month names,
datetime
identifiers follow established international standards.To ensure similar behavior across different locales, avoid using identifiers with locale-dependent behavior. In general, such identifiers specify locale-dependent day or month names, or time zone offsets that are locale dependent.
Locale-dependent identifiers include
MMM
,MMMM
,eee
,eeee
,z
, andZZZZ
.
Effects of large year values:
datetime
values later than 144683 years CE or before 140743 BCE display only the year numbers, regardless of the identifiers specified by theFormat
property.
Effects of day and year identifiers:
If you read a two-digit year number and specify the format as
y
oryy
, then the pivot year determines the century to which the year belongs.If you read a day-of-year number and specify a format that contains identifiers for both the day of year (
D
) and Gregorian year (y
), thendatetime
might not read the day-of-year number correctly. Use ISO year (u
) in place ofy
.Use one or more
u
identifiers instead ofy
identifiers to represent the year when working with year numbers near zero.
Effects of extra identifiers:
In general, if you specify more instances of an identifier than are shown in the table, then
datetime
pads the display format for that identifier with leading zeroes.For example, if you specify the hours identifier as
HHHH
, as inuuuu-MM-dd HHHH:mm:ss
, then the display for January 1, 2024, 12:30 p.m. pads the hours field with two leading zeroes.d = datetime(2024,1,1,12,30,0); d.Format = "uuuu-MM-dd HHHH:mm:ss"
d = datetime 2024-01-01 0012:30:00
Similarly, leading zeroes are typically ignored in text inputs, in cases where ignoring those zeroes results in an input format that
datetime
can still parse.d = datetime("2024-01-01 0012:30:00")
d = datetime 2024-01-01 12:30:00
Time Zone Offset Formats
Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific datetime is offset from UTC. A time zone has rules for determining the time zone offset, and the offset can differ at different times of the year. Include a time zone offset identifier in the display format for a datetime array when you want to ensure that the time components are displayed unambiguously.
Letter Identifier | Description | Display |
---|---|---|
z | Abbreviated name of the time zone offset. If
this value is not available, then the time zone
offset uses the short UTC format, such as
This identifier specifies the short localized version of the time zone offset. Its behavior depends on the locale. | EDT |
Z | ISO 8601 basic format with hours, minutes, and optional seconds fields. | -0400 |
ZZZZ | Long UTC format. This identifier specifies the long localized version of the time zone offset. Its behavior depends on the locale. | UTC-04:00 |
ZZZZZ | ISO 8601 extended format with hours, minutes, and optional seconds fields. A time offset of zero is displayed as the ISO 8601 UTC indicator “Z”. | -04:00 |
x or X | ISO 8601 basic format with hours field and optional
minutes field. If you specify X , then
a time offset of zero is displayed as the ISO 8601 UTC
indicator “Z”. | -04 |
xx or
XX | ISO 8601 basic format with hours and minutes fields.
If you specify XX , then a time offset
of zero is displayed as the ISO 8601 UTC indicator
“Z”. | -0400 |
xxx or
XXX | ISO 8601 extended format with hours and minutes
fields. If you specify XXX , then a
time offset of zero is displayed as the ISO 8601 UTC
indicator “Z”. | -04:00 |
xxxx or
XXXX | ISO 8601 basic format with hours, minutes, and
optional seconds fields. If you specify
XXXX , then a time offset of zero
is displayed as the ISO 8601 UTC indicator “Z”. | -0400 |
xxxxx or
XXXXX | ISO 8601 extended format with hours, minutes, and
optional seconds fields. If you specify
XXXXX , then a time offset of zero
is displayed as the ISO 8601 UTC indicator “Z”. | -04:00 |
TimeZone
— Time zone
''
(default) | character vector | string scalar
Time zone, specified as a character vector or string scalar. You can set
this property to change the time zone after you have created a
datetime
array.
To set the time zone and calculate time zone offsets, the
datetime
data type uses code and data provided by the
Internet Assigned Numbers Authority (IANA) in the IANA Time Zone
Database. The version currently used by
datetime
includes recent updates from the IANA. (To
get the version used by datetime
, return the second
output of the timezones
function.)
This table lists the values that you can specify to set the
TimeZone
property.
Specified Value | Resulting Time Zone |
---|---|
| No time zone. The |
Name of a time zone region from the IANA Time Zone Database Example:
| Time zone region that accounts for the current and
historical rules for standard and daylight offsets from
UTC observed in that geographic region. For a complete
list of IANA time zones, see |
ISO 8601 string of the form
Example:
Example:
| Time zone that is a fixed offset from UTC. The
string must encode a value that is greater than
|
Example:
Example:
| Time zone that is a fixed offset from UTC. The
|
| Coordinated Universal Time. |
| Coordinated Universal Time, but the time zone also
accounts for leap seconds. For the list of leap seconds
supported by the |
| The value of the |
This table lists some common names of time zone regions from the IANA Time Zone Database.
Value of TimeZone | UTC Offset | UTC DST Offset |
---|---|---|
'Africa/Johannesburg' | +02:00 | +02:00 |
'America/Chicago' | −06:00 | −05:00 |
'America/Denver' | −07:00 | −06:00 |
'America/Los_Angeles' | −08:00 | −07:00 |
'America/New_York' | −05:00 | −04:00 |
'America/Sao_Paulo' | −03:00 | −02:00 |
'Asia/Hong_Kong' | +08:00 | +08:00 |
'Asia/Kolkata' | +05:30 | +05:30 |
'Asia/Tokyo' | +09:00 | +09:00 |
'Australia/Sydney' | +10:00 | +11:00 |
'Europe/London' | +00:00 | +01:00 |
'Europe/Zurich' | +01:00 | +02:00 |
Data Types: char
| string
Year
— Year number
numeric array
Year 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 year number is an integer value
based on the ISO calendar. Years in the current era are positive and years
in the previous era are zero or negative. For example, the year number of 1
BCE is 0.
If you set the Year
property to a nonleap year for a
datetime
value that occurs on a leap day (February
29), then the Day
and Month
properties
change to March 1.
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
Day-of-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 day-of-month number is an
integer value from 1 to 28, 29, 30, or 31, depending on the month and year.
If you set a value outside that range, then the Month
and
Year
properties adjust accordingly, and the
Day
property stays within the appropriate range. For
example, day 0 corresponds to the last day of the previous month. For
historical dates, the day number is based on the proleptic Gregorian
calendar.
Hour
— Hour number
numeric array
Hour 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 hour number is an integer value
from 0 to 23. If you set a value outside that range, then the
Day
, Month
, and
Year
properties adjust accordingly, and the
Hour
property stays within the appropriate range. For
example, hour -1 corresponds to hour 23 of the previous day.
These conditions apply to datetime arrays with a specific time zone that follows daylight saving time:
When you specify a value for the
Hour
property that would create a nonexistent datetime in the hour gap when daylight saving time begins, the value of theHour
property adjusts to the next hour.When you specify a value for the
Hour
property that would create an ambiguous datetime in the hour overlap when daylight saving time ends, the datetime adjusts to the second of the two times (in standard time) with that hour.
Minute
— Minute number
numeric array
Minute 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 minute number is an integer
value from 0 to 59. If you specify a value outside that range, then the
Hour
, Day
,
Month
, and Year
properties adjust
accordingly, and the Minute
property stays within the
appropriate range. For example, minute -1 corresponds to minute 59 of the
previous hour.
Second
— Second number
numeric array
Second 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 second value is a floating-point
value ordinarily ranging from 0 to less than 60. If you set a value outside
that range, then the Minute
, Hour
,
Day
, Month
, and
Year
properties adjust accordingly, and the
Second
property stays within the appropriate range.
For example, second -1 corresponds to second 59 of the previous
minute.
A datetime
array with a TimeZone
value of 'UTCLeapSeconds'
has seconds ranging from 0 to
less than 61. The values from 60 to 61 represent datetimes that occur during
a leap second. (For the list of leap seconds supported by the
datetime
data type, see leapseconds
.)
SystemTimeZone
— System time zone setting
character vector | string scalar
This property is read-only.
System time zone setting, specified as a character vector or string scalar. The system where MATLAB® is running determines this time zone setting.
Example: America/New_York
Examples
Current Date and Time in Specific Time Zone
Specify the current date and time in the local system time zone.
t = datetime('now','TimeZone','local','Format','d-MMM-y HH:mm:ss Z')
t = datetime
20-Jul-2024 15:04:48 -0400
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
21-Jul-2024 04:04:48 +0900
Date and Time from Character Vectors
Create a datetime
array from a cell array of character vectors.
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.
str = ["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
Create a datetime
value from text that represents a date and time to millisecond precision. To convert text in a format that the 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.
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.
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.
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.
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.
Extended Capabilities
Tall Arrays
Calculate with arrays that have more rows than fit in memory.
The
datetime
function supports tall arrays with the following usage
notes and limitations:
Always specify the input datetime format when creating a tall datetime array for a string array or character vectors in a cell array.
If you specify
'Format'
as'preserveinput'
, then MATLAB might need to evaluate the tall array to determine the format.
For more information, see Tall Arrays.
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
Starting in R2020a, you can use
datetime
arrays in MATLAB code intended for code generation. For more information, see Code Generation for Datetime Arrays (MATLAB Coder) and Datetime Array Limitations for Code Generation (MATLAB Coder).
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.
Usage notes and limitations:
When you create a
datetime
array from the text inDateStrings
, specify the input formatinfmt
.
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced in R2014bR2024b: Improved performance when parsing common formats that include localized names or time zone offsets
datetime
format parsing performance is significantly faster
when parsing common formats that include localized names or time zone offsets. This
list shows a few examples of such formats, which are part of ongoing efforts to
improve datetime
format parsing performance:
dd-MMM-uuuu HH:mm:ss
MMMM/dd/uuuu
QQQ-uuuu
uuuu-MM-dd HH:mm:ss Z
uuuu-MM-dd HH:mm:ss.SSS xxx
For example, this code creates a string array of dates that use a localized
abbreviation for the month of April. The dates in the string array use the
dd-MMM-uuuu HH:mm:ss
format, where the MMM
specifier represents the abbreviated month name. Then the code uses the
datetime
function to parse and convert the string array.
The code is about 17x faster than in the previous release.
function timingTest s = "23-Apr-2024 11:30:" + randi([10,59],10000,1); for i = 1:100 d = datetime(s, ... InputFormat="dd-MMM-uuuu HH:mm:ss", ... Locale="en_US"); end end
The approximate execution times are:
R2024a: 4.75 s
R2024b: 0.27 s
Similarly, this code creates a string array of dates that have a time zone offset
of -0400
. The dates in the string array use the
uuuu-MM-dd HH:mm:ss.SSS Z
format, where the
Z
specifier represents the time zone offset. Then the code
uses the datetime
function to parse and convert the string
array. The code is about 5.8x faster than in the previous release.
function timingTest s = "2024-04-23 11:32:48." + randi(999,10000,1) + " -0400"; for i = 1:100 d = datetime(s, ... InputFormat="uuuu-MM-dd HH:mm:ss.SSS Z", ... TimeZone="local"); end end
The approximate execution times are:
R2024a: 6.35 s
R2024b: 1.10 s
In both cases, the code was timed on a Windows® 11, AMD EPYC™ 74F3 24-Core Processor @ 3.19 GHz test system using the
timeit
function.
timeit(@timingTest)
R2024a: Specify time zone offset using duration
value
You can specify a time zone offset for a datetime
array by
using a duration
value.
To specify an offset when you use the datetime
function,
specify the TimeZone
name-value
argument.
t = datetime("now",TimeZone=hours(5))
To specify an offset after you create a datetime
array, assign
the offset to its TimeZone
property.
t = datetime("now")
t.TimeZone = hours(5)
R2024a: Improved performance when parsing common numeric formats
datetime
format parsing performance is significantly faster
when parsing some common formats. In general, performance is best for text
timestamps in formats that use only numeric specifiers, such as the ISO 8601 format.
This list shows a few examples of such formats, which are part of ongoing efforts to
improve datetime
format parsing performance:
uuuu-MM-dd
andyyyy-MM-dd
MM/dd/uuuu
andMM/dd/yyyy
uuuu-MM-dd'T'HH:mm:ss.SSS'Z'
andyyyy-MM-dd'T'HH:mm:ss.SSS'Z'
For example, this code creates and then parses a string array that contains a
series of dates. The dates in the string array have the
uuuu-MM-dd
numeric format. The datetime
function recognizes the format, parses the strings, and returns
datetime
values. The code is about 16x faster than in the
previous release.
function timingTest() d1 = datetime(2024,1,1:10000); s = string(d1,"uuuu-MM-dd"); for i = 1:100 d2 = datetime(s); end end
The approximate execution times are:
R2023b: 3.13 s
R2024a: 0.19 s
The code was timed on a Windows 11, AMD® EPYC 74F3 24-Core Processor @ 3.19 GHz test system using the
timeit
function:
timeit(@timingTest)
R2020a: 'InputFormat'
identifiers e
, ee
, M
, MM
,
Q
, and QQ
do not recognize names, while
identifiers eee
, MMM
, and
QQQ
do not recognize full names
Starting in R2020a, when you specify one- or two-letter identifiers for the
day-of-week, month, or quarter in the 'InputFormat'
name-value
argument, these identifiers no longer recognize names. They recognize digits
only.
Similarly, three-letter identifiers for abbreviated day-of-week, month, and quarter names no longer recognize full names. They recognize only abbreviations.
The table shows these identifiers with examples of both recognized and unrecognized values.
Identifier | Recognized Examples | Unrecognized Examples |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In previous releases, all these one-, two-, and three-letter identifiers
recognized both abbreviated and full names for day-of-week, month, and quarter
respectively. For example, ee
recognized Wed
as Wednesday, MM
recognized Apr
as April, and
QQ
recognized Q2
as the second quarter.
Similarly, eee
recognized Wednesday
,
MMM
recognized April
, and
QQQ
recognized 2nd quarter
.
For more information on format identifiers, see the Format
property of
datetime
.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)