datetime

Arrays that represent points in time

Description

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

Creation

Syntax

t = datetime

t = datetime(relativeDay)

t = datetime(DateStrings)

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

t = datetime(DateVectors)

t = datetime(Y,M,D)

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

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

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

t = datetime(___,Name,Value)

Description

t = datetime returns a scalar datetime array corresponding to the current date and time.

example

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

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

example

t = datetime(DateStrings,'InputFormat',infmt) interprets DateStrings using the format specified by infmt. All values in the input argument DateStrings must have the same format.

To avoid ambiguities between similar formats, specify 'InputFormat' and its corresponding value, infmt.

To control the display format of t, specify the 'Format' name-value pair argument, or set the Format property of t.

example

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

t = datetime(Y,M,D) creates an array of datetime values for corresponding elements of the Y, M, and D (year, month, day) arrays. The arrays must be of the same size (or any can be a scalar). You also can specify the input arguments as a date vector, [Y M D].

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

t = datetime(Y,M,D,H,MI,S,MS) adds an MS (millisecond) array. All arrays must be of the same size (or any can be a scalar).

example

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.

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.

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 adjusts the hours element by 1 and sets the minutes element to 10. If the minutes element is -15, then datetime decreases the hours element by 1 and sets the minutes element to 45.

Example: [2014 10 24 12 45 07]

Example: [2014 10 24]

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

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

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

Example: 2003,10,24

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

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.

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.
`'epochtime','Epoch',epochValue`	Number of seconds since an epoch. You must also specify `epochValue`, which is a scalar `datetime`, or a character vector or string scalar representing the epoch time. Example: Return the number of days since January 1, 2000. 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: Return the number of days since January 1, 2000, where `X` represents the time in milliseconds since or before that date. T = datetime(X,'ConvertFrom',... 'epochtime','Epoch','2000-01-01','TicksPerSecond',1000)

Name-Value Pair Arguments

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

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

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

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 character vector or string scalar 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 panel.

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.

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`	Year, with no leading zeros. See the Note that follows this table.	`2014`
`yy`	Year, using last two digits. See the Note that follows this table.	`14`
`yyy`, `yyyy` ...	Year, using at least the number of digits specified by the number of instances of `'y'`	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

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 characters instead of y characters to represent the year when working with year numbers near zero.
Datetime values later than 144683 years CE or before 140743 BCE display only the year numbers, regardless of the specified Format value.

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`.	`EDT`
`Z`	ISO 8601 basic format with hours, minutes, and optional seconds fields.	`-0400`
`ZZZZ`	Long UTC format.	`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 use this property to change the time zone after creating 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.)

The value of TimeZone can be:

'', to create an “unzoned” datetime array that does not belong to a specific time zone.
The name of a time zone region from the IANA Time Zone Database; for example, 'America/Los_Angeles'. The name of a time zone region accounts for the current and historical rules for standard and daylight offsets from UTC that are observed in a geographic region.
An ISO 8601 character vector of the form +HH:mm or -HH:mm; for example, '+01:00', to specify a time zone that is a fixed offset from UTC.
'UTC', to create a datetime array in Universal Coordinated Time.
'UTCLeapSeconds', to create a datetime array in Universal Coordinated Time that accounts for leap seconds. For the list of leap seconds supported by the datetime data type, see leapseconds.
'local', to create a datetime array in 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
   17-Aug-2020 15:38:40 -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
   18-Aug-2020 04:38:40 +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 = string({'2016-03-24','2016-04-19'})

str = 1x2 string
    "2016-03-24"    "2016-04-19"

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

t = datetime(str,'InputFormat','yyyy-MM-dd')

t = 1x2 datetime
   24-Mar-2016   19-Apr-2016

Time from Text Representing Fractional Seconds

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.

Compatibility Considerations

expand all

`'InputFormat'` month formats `M` and `MM` do not recognize names, and `MMM` does not recognize full month names

Behavior changed in R2020a

Starting in R2020a, when you specify month formats in the 'InputFormat' name-value pair argument, the M and MM formats do not recognize month names. Also, the MMM format recognizes only abbreviated names, not full month names. In previous releases, all these formats recognized both abbreviated and full month names.

For more information on formats, see the Format property.

Extended Capabilities

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

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

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

Documentation

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

Compatibility Considerations

'InputFormat' month formats M and MM do not recognize names, and MMM does not recognize full month names

Extended Capabilities

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

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

See Also

Topics

MATLAB Documentation

Support

`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

`'InputFormat'` month formats `M` and `MM` do not recognize names, and `MMM` does not recognize full month names

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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