Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

라이선스가 부여된 사용자만 번역 문서를 볼 수 있습니다. 번역 문서를 보려면 로그인하십시오.

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 DateStrings must have the same format.

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

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

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: string({'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 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 PM in New York City.

Value of FormatExample
'yyyy-MM-dd'2014-04-19
'dd/MM/yyyy'19/04/2014
'dd.MM.yyyy'19.04.2014
'yyyy年 MM月 dd日'2014年 04月 19日
'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

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

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]

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

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

  • If Y,M,D are all scalars or all column vectors, then you can specify the input arguments as a date vector, [Y,M,D].

  • If an element of the Y, M, or D inputs falls outside the conventional range, then datetime adjusts both that element and the same element of the previous input. For details, see the description for the DateVectors input argument.

Example: 2003,10,24

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

Year, month, day, hour, minute, and second arrays specified as a scalar, vector, matrix, or array. 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

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

Year, month, day, hour, minute, second, and millisecond arrays, specified as a scalar, vector, matrix, or array. 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

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

Numeric values, specified as a scalar, matrix, or multidimensional 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.

'epochtime','Epoch',epochValue

Number of seconds since an epoch.

You must additionally specify epochValue, which is a scalar datetime or a character vector representing the epoch time.

Example: Return the number of days since January 1, 2000.

T = datetime(X,'ConvertFrom',...
'epochtime','Epoch','2000-01-01')

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

expand all

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.

'defaultdate'

Use the default display format for datetime values created without time components.

'preserveinput'

Use the format specified by the input format, infmt. If you do not specify infmt, then datetime determines the format automatically.

character vector

Use a format you specify with a character vector.

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

Locale of DateStrings input argument values, specified as the comma-separated pair consisting of 'Locale' and a character vector. 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 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 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, see Set Command Window Preferences.

Data Types: char

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 that specifies the TimeZone property.

Data Types: char

Properties

expand all

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

Value of FormatDescription

'default'

Use the default display format.

'defaultdate'

Use the default display format for datetime values created without time components.

character vector

Use a format you specify with a character vector.

If you use a character vector to 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 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日
'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

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
yYear, with no leading zeros. See the Note that follows this table.2014
yyYear, 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
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

  • 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 IdentifierDescriptionDisplay
zAbbreviated 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
ZISO 8601 basic format with hours, minutes, and optional seconds fields.-0400
ZZZZLong UTC format.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. The value of TimeZone specifies the time zone that the datetime function uses to interpret the input data. TimeZone also specifies the time zone of the output array. If the input data are character vectors that include a time zone, then the datetime function converts all values to the specified time zone.

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.

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

You also can use the timezones function to display a list of IANA time zone names that the datetime function accepts.

Data Types: char

Year number of each value in the datetime array, specified as a scalar or a vector, matrix, or multidimensional array 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 scalar or a vector, matrix, or multidimensional array 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 scalar or a vector, matrix, or multidimensional array 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 scalar or a vector, matrix, or multidimensional array 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 scalar or a vector, matrix, or multidimensional array 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 scalar or a vector, matrix, or multidimensional array 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.

This property is read-only.

System time zone setting, specified as a character vector. The system where MATLAB® is running determines this time zone setting.

Example: America/New_York

Examples

expand 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
   1-Sep-2017 17:09:14 -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
   2-Sep-2017 06:09:15 +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 array
   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 = string({'2016-03-24','2016-04-19'})
str = 1x2 string array
    "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 array
   24-Mar-2016   19-Apr-2016

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 array
    {'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 array
   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 array
    {'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 array
   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 array
   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 array
   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 = 

       39558       39600
       39700       39800

Convert the values in X to datetime values.

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

Tips

Extended Capabilities

Introduced in R2014b

Was this topic helpful?