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.

datevec

Convert date and time to vector of components

The datevec function creates a numeric array whose values represent the date and time components of years, months, days, hours, minutes, and seconds. However, the best way to represent points in time is by using the datetime data type. The best way to represent elapsed time is by using the duration or calendarDuration data types.

Syntax

  • DateVector = datevec(t)
    example
  • DateVector = datevec(DateNumber)
    example
  • DateVector = datevec(DateString)
  • DateVector = datevec(DateString,formatIn)
    example
  • DateVector = datevec(DateString,PivotYear)
  • DateVector = datevec(DateString,formatIn,PivotYear)
    example
  • [Y,M,D,H,MN,S] = datevec(___)
    example

Description

example

DateVector = datevec(t) converts the datetime values in datetime array t to date vectors. datevec returns an m-by-6 matrix where each row corresponds to a datetime value in t.

example

DateVector = datevec(DateNumber) converts one or more date numbers to date vectors. datevec returns an m-by-6 matrix containing m date vectors, where m is the total number of date numbers in DateNumber.

DateVector = datevec(DateString) converts text representing dates and times to date vectors. If the format used in the text is known, specify the format as formatIn. Syntaxes without formatIn are significantly slower than those that include it.

example

DateVector = datevec(DateString,formatIn) uses formatIn to interpret the dates and times represented by DateString.

DateVector = datevec(DateString,PivotYear) uses PivotYear to interpret text that specifies the year as two characters. If the format used in the text is known, specify the format as formatIn. Syntaxes without formatIn are significantly slower than those that include it.

example

DateVector = datevec(DateString,formatIn,PivotYear) uses formatIn to interpret the dates and times represented by DateString, and PivotYear to interpret text that specifies the year as two characters. You can specify formatIn and PivotYear in either order.

example

[Y,M,D,H,MN,S] = datevec(___) returns the components of the date vector as individual variables Y, M, D, H, MN, and S (year, month, day, hour, minutes and seconds). datevec returns milliseconds as a fractional part of the seconds (S) output.

Examples

collapse all

format short g

t = [datetime('now');datetime('tomorrow')]
DateVector = datevec(t)
t = 

  2×1 datetime array

   04-Oct-2016 20:15:21
   05-Oct-2016 00:00:00


DateVector =

         2016           10            4           20           15       21.888
         2016           10            5            0            0            0

format short g

n = 733779.651;
datevec(n)
ans =

         2009            1            6           15           37         26.4

DateString = '28.03.2005';
formatIn = 'dd.mm.yyyy';
datevec(DateString,formatIn)
ans =

        2005           3          28           0           0           0

datevec returns a date vector for text representing a date with the format 'dd.mm.yyyy'.

Pass multiple dates as character vectors in a cell array. All input dates must use the same format.

DateString = {'09/16/2007';'05/14/1996';'11/29/2010'};
formatIn = 'mm/dd/yyyy';
datevec(DateString,formatIn)
ans =

        2007           9          16           0           0           0
        1996           5          14           0           0           0
        2010          11          29           0           0           0

datevec('11:21:02.647','HH:MM:SS.FFF')
ans =

   1.0e+03 *

    2.0160    0.0010    0.0010    0.0110    0.0210    0.0026

In the output date vector, milliseconds are a fractional part of the seconds field. The text '11:21:02.647' does not contain enough information to convert to a full date vector. The days default to 1, months default to January, and years default to the current year.

Convert text representing a date to a date vector using the default pivot year.

DateString = '12-jun-17';
formatIn = 'dd-mmm-yy';
DateVector = datevec(DateString,formatIn)
DateVector =

        2017           6          12           0           0           0

Convert the same date to a date vector using 1800 as the pivot year.

DateVector = datevec(DateString,formatIn,1800)
DateVector =

        1817           6          12           0           0           0

Convert text representing a date to a date vector and return the components of the date vector.

[y, m, d, h, mn, s] = datevec('01.02.12','dd.mm.yy')
y =

        2012


m =

     2


d =

     1


h =

     0


mn =

     0


s =

     0

Input Arguments

collapse all

datetime values, specified as a scalar, vector, matrix, or multidimensional datetime array.

Serial date number, specified as a scalar, vector, or multidimensional array of positive double-precision numbers.

Example: 731878

Data Types: double

Text representing dates and times, specified as a character array where each row contains text representing one point in time, or as a one dimensional cell array of character vectors. All rows of a character array, or all elements of a cell array, must have the same format.

Example: '24–Oct-2003 12:45:07'

Example: ['19-Sep-2013';'20-Sep-2013';'21-Sep-2013']

Example: {'15-Oct-2010' '20-Nov-2012'}

If the format used in the text is known, you should also specify formatIn. If you do not specify formatIn, DateString must be in one of the following formats.

Format of Text Representing Dates and Times

Example

'dd-mmm-yyyy HH:MM:SS'

01-Mar-2000 15:45:17

'dd-mmm-yyyy'

01-Mar-2000

'mm/dd/yyyy'

03/01/2000

'mm/dd/yy'

03/01/00

'mm/dd'

03/01

'mmm.dd,yyyy HH:MM:SS'

Mar.01,2000 15:45:17

'mmm.dd,yyyy'

Mar.01,2000

'yyyy-mm-dd HH:MM:SS'

2000-03-01 15:45:17

'yyyy-mm-dd'

2000-03-01

'yyyy/mm/dd'

2000/03/01

'HH:MM:SS'

15:45:17

'HH:MM:SS PM'

3:45:17 PM

'HH:MM'

15:45

'HH:MM PM'

3:45 PM

    Note:   The symbolic identifiers describing date and time formats are different from those that describe the display formats of datetime arrays.

Certain formats might not contain enough information to convert text representations of dates and times. In those cases, hours, minutes, and seconds default to 0, days default to 1, months default to January, and years default to the current year. datevec and datenum consider two-character years (e.g., '79') to fall within the 100-year range centered around the current year.

When you do not specify formatIn, note the following:

  • For the formats that specify the month as two digits (mm), the month value must not be greater than 12.

  • However, for the format 'mm/dd/yy', if the first entry in the text is greater than 12 and the second entry is less than or equal to 12, then datevec considers the text to be in 'yy/mm/dd' format.

Format of the input text representing dates and times, specified as a character vector of symbolic identifiers.

The following table shows symbolic identifiers you can use to construct the formatIn character vector. You can include characters such as a hyphen, space, or colon to separate the fields.

    Note:   The symbolic identifiers describing date and time formats are different from those that describe the display formats of datetime arrays.

Symbolic Identifier

Description

Example

yyyy

Year in full

1990, 2002

yy

Year in two digits

90, 02

QQ

Quarter year using letter Q and one digit

Q1

mmmm

Month using full name

March, December

mmm

Month using first three letters

Mar, Dec

mm

Month in two digits

03, 12

m

Month using capitalized first letter

M, D

dddd

Day using full name

Monday, Tuesday

ddd

Day using first three letters

Mon, Tue

dd

Day in two digits

05, 20

d

Day using capitalized first letter

M, T

HH

Hour in two digits
(no leading zeros when symbolic identifier AM or PM is used)

05, 5 AM

MM

Minute in two digits

12, 02

SS

Second in two digits

07, 59

FFF

Millisecond in three digits

057

AM or PM

AM or PM inserted in text representing time

3:45:02 PM

The formatIn value must follow these guidelines:

  • You cannot specify any field more than once. For example, you cannot use 'yy-mmm-dd-m' because it has two month identifiers. The one exception to this is that you can combine one instance of dd with one instance of any of the other day identifiers. For example, 'dddd mmm dd yyyy' is a valid input.

  • When you use AM or PM, the HH field is also required.

  • datevec does not accept formats that include 'QQ'

Start year of the 100-year date range in which a two-character year resides, specified as an integer. Use a pivot year to interpret dates that specify the year as two characters.

If formatIn contains the time of day, the pivot year is computed from the current time of the current day, month, and year. Otherwise it is computed from midnight of the current day, month, and year.

Example: 2000

    Note:   If the input date format specifies a four-character year, then the last two characters are truncated, and the first two characters specify the year. For example, if the date and pivot year are specified as ('25122015','ddmmyyyy',2000), then the resulting date is 25-12-2020, not 25-12-2015.

Data Types: double

Output Arguments

collapse all

Date vectors, returned as an m-by-6 matrix, where each row corresponds to one date vector, and m is the total number of input date numbers or character vectors representing dates and times.

Components of the date vector (year, month, day, hour, minute, and second), returned as individual scalar variables. Each variable is a scalar or a vector. Milliseconds are a fractional part of the seconds output. When converting a datetime array t, these components are equal to the values of the Year, Month, Day, Hour, Minute, and Second properties. For example, Y = t.Year.

Limitations

  • When computing date vectors, datevec sets month values less than 1 to 1. Day values, D, less than 1 are set to the last day of the previous month minus |D|. However, if 0 ≤ DateNumber < 1, then datevec(DateNumber) returns a date vector of the form [0 0 0 H MN S], where H, MN, and S are hours, minutes, and seconds, respectively.

More About

collapse all

Tall Array Support

This function fully supports tall arrays. For more information, see Tall Arrays.

Tips

  • The vectorized calling syntax can offer significant performance improvement for large arrays.

See Also

| |

Introduced before R2006a

Was this topic helpful?