Main Content

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

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

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

Value of relativeDayDescription
'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

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

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

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]

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

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

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

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

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

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

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

Numeric values, specified as an array.

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

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.

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 FormatDescription

'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 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 LanguageCountry
"de_DE"GermanGermany
"en_GB"EnglishUnited Kingdom
"en_US"EnglishUnited States
"es_ES"SpanishSpain
"fr_FR"FrenchFrance
"it_IT"ItalianItaly
"ja_JP"JapaneseJapan
"ko_KR"KoreanKorea
"nl_NL"DutchNetherlands
"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.

Data Types: char | string

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

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

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

Value of FormatDescription

'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 FormatExample
'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 IdentifierDescriptionDisplay
GEraCE
yGregorian 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
yyGregorian 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
QQuarter, using one digit2
QQQuarter, using two digits02
QQQQuarter, abbreviatedQ2
QQQQQuarter, full name2nd quarter
MMonth, numerical using one or two digits4
MMMonth, numerical using two digits04
MMMMonth, abbreviated nameApr
MMMMMonth, full nameApril
MMMMMMonth, capitalized first letterA
WWeek of the month, using one digit2
dDay of the month, using one or two digits9
ddDay of the month using two digits09
DDay of the year, using one, two, or three digits99
DDDay of the year using two digits99
DDDDay of the year using three digits099
eDay of the week (numerical, using one or two digits)4, where Sunday is the first day of the week.
eeDay of the week (numerical, using two digits)04
eeeDay, abbreviated nameWed
eeeeDay, full nameWednesday
eeeeeDay, capitalized first letterW
aDay period (AM or PM)PM
hHour, 12-hour clock notation using one or two digits9
hhHour, 12-hour clock notation using two digits09
HHour, 24-hour clock notation using one or two digits21
HHHour, 24-hour clock notation using two digits21
mMinute, using one or two digits41
mmMinute, using two digits41
sSecond, using one or two digits6
ssSecond, using two digits06
S, SS, ..., SSSSSSSSSFractional 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 IdentifierDescriptionDisplay
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
ZISO 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
ZZZZZISO 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 XISO 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 XXISO 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 XXXISO 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 XXXXISO 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 XXXXXISO 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

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

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

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

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.

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

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.

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.

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.

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  

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

Extended Capabilities

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

Version History

Introduced in R2014b

expand all