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

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.

t = datetime(relativeDay) uses the date specified by relativeDay. The relativeDay input can be 'today', 'tomorrow', 'yesterday', or 'now'.

example

t = datetime(DateStrings) creates an array of datetime values from the text in DateStrings representing points in time.

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.

example

t = datetime(DateVectors) creates a column vector of datetime values from the date vectors in DateVectors.

example

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).

t = datetime(X,'ConvertFrom',dateType) converts the numeric values in 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.

example

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

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, then datetime assumes that the values in DateStrings occur during the current day.
If infmt does not include a time specifier, then datetime assumes that the values in DateStrings 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 corresponding datetime value is a NaT.
If any value is Inf or -Inf, then the corresponding datetime value is a Inf or -Inf.

Example: [2014 10 24 12 45 07]

Example: [2014 10 24]

`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.
If any value is a NaN, then the corresponding datetime value is a NaT.
If any value is Inf or -Inf, then the corresponding datetime value is a Inf or -Inf.

Example: 2003,10,24

`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, or S 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 corresponding datetime value is a NaT.
If any value is Inf or -Inf, then the corresponding datetime value is a Inf or -Inf.

Example: 2003,10,24,12,45,07.451

`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 corresponding datetime value is a NaT.
If any value is Inf or -Inf, then the corresponding datetime value is a Inf or -Inf.

Example: 2003,10,24,12,45,07,10.52

`X` — Numeric values
array

Numeric values, specified as an array.

`dateType` — Type of values in `X`
`'datenum'` | `'excel'` | `'excel1904'` | `'juliandate'` | ...

Type of values in X, specified as one of these values.

Value of `dateType`	Type of Values in `X`
`'datenum'`	Number of days since 0-Jan-0000 (proleptic ISO calendar).
`'excel'`	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.
`'excel1904'`	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.
`'juliandate'`	Number of days since noon UTC 24-Nov-4714 BCE (proleptic Gregorian calendar). If you convert `X` to a `datetime` array without specifying a time zone, then the `datetime` values represent UTC times, not local times. To represent local times, specify a time zone using the `'TimeZone'` name-value pair argument. Example: Convert `X` using the time zone for New York. T = datetime(X,'ConvertFrom','juliandate',... 'TimeZone','America/New_York') Then, you can convert `T` to an unzoned `datetime` array representing local times by assigning an empty character vector to `TimeZone`. T.TimeZone = ''
`'modifiedjuliandate'`	Number of days since midnight UTC 17-Nov-1858. If you convert `X` to a `datetime` array without specifying a time zone, then the `datetime` values represent UTC times, not local times. To represent local times, specify a time zone using the `'TimeZone'` name-value pair argument. Example: Convert `X` using the time zone for New York. T = datetime(X,'ConvertFrom','modifiedjuliandate',... 'TimeZone','America/New_York') Then, you can convert `T` to an unzoned `datetime` array representing local times by assigning an empty character vector to `TimeZone`. T.TimeZone = ''
`'posixtime'`	Number of seconds since 1-Jan-1970 00:00:00 UTC, not counting leap seconds. If you convert `X` to a `datetime` array without specifying a time zone, then the `datetime` values represent UTC times, not local times. To represent local times, specify a time zone using the `'TimeZone'` name-value pair argument. Example: Convert `X` using the time zone for New York. T = datetime(X,'ConvertFrom','posixtime',... 'TimeZone','America/New_York') Then, you can convert `T` to an unzoned `datetime` array representing local times by assigning an empty character vector to `TimeZone`. T.TimeZone = ''
`'yyyymmdd'`	Dates as YYYYMMDD numeric values. For example, `20140402` represents April 2, 2014.
`'ntp'`	Number of "clock ticks" since 1-Jan-1900 00:00:00 UTC, where each clock tick is 2^-32 seconds.
`'.net'`	Number of "clock ticks" since 1-Jan-0001 00:00:00 UTC, where each clock tick is 100 ns.
`'ntfs'`	Number of "clock ticks" since 1-Jan-1601 00:00:00 UTC, where each clock tick is 100 ns.
`'tt2000'`	Number of nanoseconds that have elapsed since J2000. The Common Data Format (CDF) defines the `CDF_TIME_TT2000` (or `TT2000`) data type as a high-resolution time type that handles leap seconds for data in CDF files. For more information, see Requirements for handling leap seconds in CDF. The input `X` must be an `int64` array whose elements represent times in the `TT2000` epoch. To convert `TT2000` times, call `datetime` using the `"ConvertFrom","tt2000"` and `"TimeZone","UTCLeapSeconds"` name-value arguments. The `UTCLeapSeconds` time zone is the only time zone that accounts for leap seconds. Note: J2000 is January 1, 2000, 12:00 Terrestrial Time (TT). TT differs from UTC due to two factors: Leap seconds Difference of 32.184 seconds between TT and atomic clock timekeeping As a consequence, J2000 actually occurs 64.184 seconds before noon in the `UTCLeapSeconds` time zone, at: D = datetime(2000,1,1,11,58,55,816,"TimeZone","UTCLeapSeconds") D = 2000-01-01T11:58:55.816Z Example: Create an `int64` array that represents `TT2000` times. Then convert it to a `datetime` array. 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
`'epochtime'`	Number of seconds since the default epoch time. The default epoch time is 1-Jan-1970 00:00:00 UTC. Example: Convert `X` using the default epoch time. T = datetime(X,'ConvertFrom','epochtime')
`'epochtime','Epoch',epochValue`	Number of seconds since an epoch. To specify an epoch, use the additional `'Epoch'` name-value argument. The value `epochValue` is a scalar `datetime` or a character vector or string scalar that represents the epoch time. Example: Convert `X` using midnight on January 1, 2000 as the epoch. T = datetime(X,'ConvertFrom',... 'epochtime','Epoch','2000-01-01')
`'epochtime','Epoch',epochValue,'TicksPerSecond',n`	Number of "clock ticks" since an epoch. In addition to specifying `epochValue`, you also can specify `n`, which is a scalar integer that specifies the number of "clock ticks" per second. Example: Convert `X` using midnight on January 1, 2000 as the epoch. This conversion interprets the values in `X` as milliseconds since midnight on January 1, 2000, because it is specified that there are 1000 "clock ticks" per second. T = datetime(X,'ConvertFrom',... 'epochtime','Epoch','2000-01-01','TicksPerSecond',1000)

Name-Value Arguments

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
`'default'`	Use the default display format.
`'preserveinput'`	Use the format specified by the input format, `infmt`. If you do not specify `infmt`, then `datetime` determines the format automatically.
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 xx_YY, where xx is a lowercase ISO 639-1 two-letter code that specifies a language, and YY 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, or string 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

`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

expand all

`Format` — Display format
`'default'` | character vector | string scalar

Display format, specified as 'default', a character vector, or a string scalar.

Value of `Format`	Description
`'default'`	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, and ZZZZ.

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 the Format property.

Effects of day and year identifiers:

If you read a two-digit year number and specify the format as y or yy, 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), then datetime might not read the day-of-year number correctly. Use ISO year (u) in place of y.
Use one or more u identifiers instead of y 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 in uuuu-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 `UTC-4`. 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 `datetime` array is "unzoned."
Name of a time zone region from the IANA Time Zone Database Example: `'America/New_York'`	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 `timezones`.
ISO 8601 string of the form `+HH:mm` or `-HH:mm` Example: `'+01:00'` Example: `'-01:00'`	Time zone that is a fixed offset from UTC. The string must encode a value that is greater than `-24:00` and less than `+24:00`. It cannot include fractional seconds.
`duration` scalar (since R2024a) Example: `hours(1)` Example: `hours(-1)`	Time zone that is a fixed offset from UTC. The `duration` scalar must be a value that is greater than `hours(-24)` and less than `hours(24)`. It cannot include fractional seconds.
`'UTC'`	Coordinated Universal Time.
`'UTCLeapSeconds'`	Coordinated Universal Time, but the time zone also accounts for leap seconds. For the list of leap seconds supported by the `datetime` data type, see `leapseconds`.
`'local'`	The value of the `TimeZone` property is set to the IANA time zone that corresponds to the system time zone. When you query the `TimeZone` property, the IANA value is returned.

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 the Hour 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

collapse all

Current Date and Time in Specific Time Zone

Open Live Script

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
   5-Sep-2024 15:32:41 -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
   6-Sep-2024 04:32:41 +0900

Date and Time from Character Vectors

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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 in DateStrings, specify the input format infmt.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2014b

expand all

R2024b: 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 and yyyy-MM-dd
MM/dd/uuuu and MM/dd/yyyy
uuuu-MM-dd'T'HH:mm:ss.SSS'Z' and yyyy-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
`e`	`4`	`Wed` `Wednesday`
`ee`	`04`	`Wed` `Wednesday`
`eee`	`Wed`	`Wednesday`
`M`	`4`	`Apr` `April`
`MM`	`04`	`Apr` `April`
`MMM`	`Apr`	`April`
`Q`	`2`	`Q2` `2nd quarter`
`QQ`	`02`	`Q2` `2nd quarter`
`QQQ`	`Q2`	`2nd quarter`

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.

datetime

Description

Creation

Syntax

Description

Input Arguments

relativeDay — Day relative to current date 'yesterday' | 'today' | 'tomorrow' | 'now'

DateStrings — Text representing dates and times character array | cell array of character vectors | string array

infmt — Format of input text character vector | string scalar

DateVectors — Date vectors matrix

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

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' | ...

Format — Display format 'default' | 'preserveinput' | character vector | string scalar

Locale — Locale of DateStrings character vector | string scalar

PivotYear — Start year of 100-year date range year(datetime('now'))-50 (default) | integer

TimeZone — Time zone '' (default) | character vector | string scalar

Properties

Format — Display format 'default' | character vector | string scalar

Examples of Common Formats

All Date and Time Formats

Time Zone Offset Formats

TimeZone — Time zone '' (default) | character vector | string scalar

Year — Year number numeric array

Month — Month number numeric array

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

Current Date and Time in Specific Time Zone

Date and Time from Character Vectors

Date and Time from String Array

Time from Text Representing Fractional Seconds

Date and Time from Text with Literal Characters

Date and Time from Text in Foreign Language

Date and Time from Vectors

Convert Excel Date Number to Datetime

Tips

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™.

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™.

Version History

R2024b: Improved performance when parsing common formats that include localized names or time zone offsets

R2024a: Specify time zone offset using duration value

R2024a: Improved performance when parsing common numeric formats

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

See Also

Topics

`relativeDay` — Day relative to current date
`'yesterday'` | `'today'` | `'tomorrow'` | `'now'`

`DateStrings` — Text representing dates and times
character array | cell array of character vectors | string array

`infmt` — Format of input text
character vector | string scalar

`DateVectors` — Date vectors
matrix

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

`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'` | ...

`Format` — Display format
`'default'` | `'preserveinput'` | character vector | string scalar

`Locale` — Locale of `DateStrings`
character vector | string scalar

`PivotYear` — Start year of 100-year date range
`year(datetime('now'))-50` (default) | integer

`TimeZone` — Time zone
`''` (default) | character vector | string scalar

`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

`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

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™.

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™.

R2024a: Specify time zone offset using `duration` value

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