This is machine translation

Translated by

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

collapse all in page

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

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

t = datetime(DateVectors)
example
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)
example

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.

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

Current Date and Time in Specific Time Zone

Open 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

   4-Oct-2016 20:03:15 -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

   5-Oct-2016 09:03:16 +0900

Date and Time from Character Vectors

Open 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 = 

  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.

Date and Time from String Array

Open Script

Starting in R2016b, you can create string arrays with the string function and convert them to datetime values.

str = string({'24-March-2016','19-April-2016'})

str = 

  1×2 string array

    "24-March-2016"    "19-April-2016"

Convert the strings with the output format set to dd/MM/yyyy. The format must be specified as a character vector, even though str is a string array.

t = datetime(str,'Format','dd/MM/yyyy')

t = 

  1×2 datetime array

   24/03/2016   19/04/2016

Date and Time from Text with Literal Characters

Open 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 =

  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.

Date and Time from Text in Foreign Language

Open 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 =

  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.

Date and Time from Vectors

Open 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 = 

  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

Convert Excel Date Number to Datetime

Open 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 =

       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

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

`infmt` — Format of input text representing dates and times
character vector

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.
If infmt includes a time-zone specifier and you do not specify a time zone, then datetime creates unzoned datetimes and ignores any time-zone information in DateStrings.

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 `Format`	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日`
`'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

`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
scalar | vector | matrix | array

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

`Y,M,D,H,MI,S` — Year, month, day, hour, minute, and second arrays
scalar | vector | matrix | array

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

`Y,M,D,H,MI,S,MS` — Year, month, day, hour, minute, second, and millisecond arrays
scalar | vector | matrix | array

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

`X` — Numeric values
scalar | matrix | multidimensional array

Numeric values, specified as a scalar, matrix, or multidimensional array.

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

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.
`'excel1904'`	Number of days since 0-Jan-1904 Excel date numbers are rounded to the nearest microsecond.
`'juliandate'`	Number of days since noon UTC 24-Nov-4714 BCE (Gregorian calendar)
`'modifiedjuliandate'`	Number of days since midnight UTC 17-Nov-1858
`'posixtime'`	Number of seconds since 1-Jan-1970 00:00:00 UTC
`'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. This example returns 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

`'Format'` — Display format
`'default'` | `'defaultdate'` | `'preserveinput'` | character vector

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 `Format`	Description
`'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 `Format`	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日`
`'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'` — Locale of `DateStrings`
character vector

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

`'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 region
`''` (default) | character vector

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

Output Arguments

collapse all

`t` — Dates and time
`datetime` array

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

t has the following properties.

Property	Description
`Format`	Display format of the values in `t`, specified as a character vector
`TimeZone`	Time zone in which the values in `t` are interpreted, specified as a character vector
`Year`	Array containing the year number of each element in `t`
`Month`	Array containing the month number of each element in `t`
`Day`	Array containing the day of month number of each element in `t`
`Hour`	Array containing the hour of each element in `t`
`Minute`	Array containing the minute of each element in `t`
`Second`	Array 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';

More About

collapse all

Tall Array Support

This function supports tall arrays with the limitation:

Always specify the input datetime format when creating a tall datetime array for character vectors in a cell array.

For more information, see Tall Arrays.

Documentation

This is machine translation

datetime

Syntax

Description

Examples

Current Date and Time in Specific Time Zone

Date and Time from Character Vectors

Date and Time from String Array

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

Input Arguments

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

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

infmt — Format of input text representing dates and timescharacter vector

DateVectors — Date vectorsmatrix

Y,M,D — Year, month, and day arraysscalar | vector | matrix | array

Y,M,D,H,MI,S — Year, month, day, hour, minute, and second arraysscalar | vector | matrix | array

Y,M,D,H,MI,S,MS — Year, month, day, hour, minute, second, and millisecond arraysscalar | vector | matrix | array

X — Numeric valuesscalar | matrix | multidimensional array

dateType — Type of values in X'datenum' | 'excel' | 'juliandate' | 'posixtime' | 'yyyymmdd' | ...

Name-Value Pair Arguments

'Format' — Display format'default' | 'defaultdate' | 'preserveinput' | character vector

'Locale' — Locale of DateStringscharacter vector

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

'TimeZone' — Time zone region'' (default) | character vector

Output Arguments

t — Dates and timedatetime array

More About

Tall Array Support

See Also

Introduced in R2014b

Select Your Country

Americas

Europe

Asia Pacific

MATLAB Documentation

Other Documentation

Support

Tackling Big Data with MATLAB

`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 representing dates and times
character vector

`DateVectors` — Date vectors
matrix

`Y,M,D` — Year, month, and day arrays
scalar | vector | matrix | array

`Y,M,D,H,MI,S` — Year, month, day, hour, minute, and second arrays
scalar | vector | matrix | array

`Y,M,D,H,MI,S,MS` — Year, month, day, hour, minute, second, and millisecond arrays
scalar | vector | matrix | array

`X` — Numeric values
scalar | matrix | multidimensional array

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

`'Format'` — Display format
`'default'` | `'defaultdate'` | `'preserveinput'` | character vector

`'Locale'` — Locale of `DateStrings`
character vector

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

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

`t` — Dates and time
`datetime` array