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

Create array based on current date, or convert from date strings or numbers

The datetime function creates an array that represents 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.

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) creates an array of datetime values for corresponding elements of the Y, M,D,H, MI, and S (year, month, day, hour, minute, and second) 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,H,MI,S].

t = datetime(Y,M,D,H,MI,S,MS) creates an array of datetime values for corresponding elements of the Y, M,D,H, MI, S, and MS (year, month, day, hour, minute, second, and millisecond) arrays. The 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.

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
   24-Feb-2017 12:14:00 -0500

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
   25-Feb-2017 02:14:00 +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 = 2×1 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 = 1×2 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 = 1×2 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 = 3×1 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 = 3×1 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 = 2×2 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 = 2×2 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 = 3×1 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 = 3×1 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 = 2×2 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

Input Arguments

collapse 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 some common formats. If you know the format, specify 'InputFormat' and its corresponding value, infmt, 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 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 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, 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 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, 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 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 the following 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.

collapse all

Display format of the values in the output array, y, 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.

The factory default format depends on your system locale. To change the default display format, see Default datetime Format.

Alternatively, use the letters A-Z and a-z to construct a custom value for Format. These letters correspond to the Unicode® Locale Data Markup Language (LDML) standard for dates. You can include non-ASCII or nonletter characters such as a hyphen, space, or colon to separate the fields. To include the letters A-Z and a-z as literal characters in the format, enclose them with single quotes.

Example: 'Format','eeee, MMMM d, yyyy HH:mm:ss' displays a date and time such as Saturday, April 19, 2014 21:41:06.

This table shows several common display formats and examples of the formatted output for the date, Saturday, April 19, 2014 at 9:41:06 PM in New York City. For a complete list of valid letter identifiers, see the Format property for datetime arrays.

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

    Note:   The letter identifiers that datetime accepts are different from the identifiers used by the datestr, datenum, and datevec functions.

If you specify a DateStrings input but do not specify the 'InputFormat' parameter, then datetime tries to use the Format value to interpret DateStrings.

Data Types: char

Locale of the values in DateStrings, 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 region, specified as the comma-separated pair consisting of 'TimeZone' and 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, T. 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.

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

Output Arguments

collapse all

Dates and time, returned as a datetime array. Each element includes a date and a time of day.

t has the following properties.

PropertyDescription
FormatDisplay format of the values in t, specified as a character vector
TimeZoneTime zone in which the values in t are interpreted, specified as a character vector
YearArray containing the year number of each element in t
MonthArray containing the month number of each element in t
DayArray containing the day of month number of each element in t
HourArray containing the hour of each element in t
MinuteArray containing the minute of each element in t
SecondArray containing the second, including a fractional part, of each element in t

After you create a datetime array, t, you can access or change the value of any of its properties using dot notation. For example, to display the values of t in the format, 'yyyy-MM-dd', type:

t.Format = 'yyyy-MM-dd';

Extended Capabilities

Introduced in R2014b

Was this topic helpful?