datevec - Convert date and time to vector of components - MATLAB (original) (raw)

Convert date and time to vector of components

Syntax

Description

[DateVector](#btfyhto-1-DateVector) = datevec([t](#btfyhto-1-t)) converts the input array to _date vectors_—that is, numeric row vectors with six elements that represent the year, month, day, hour, minute, and second components of the input dates and times.

If the input array t is a datetime orduration array having m elements, thendatevec returns an m-by-6 matrix where each row corresponds to a value in t.

If t is a datetime array, then its values represent points in time. Each row ofDateVector represents a specific date and time.
If t is a duration array, then its values represent elapsed time. Each row ofDateVector represents a length of time measured in fixed-length time units. For this reason, the values in the second column of DateVector (representing number of months) are always zeros. For more information, see the Limitations.

example

[DateVector](#btfyhto-1-DateVector) = datevec([DateString](#btfyhto-1%5Fsep%5Fshared-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 syntaxes that include it.

[DateVector](#btfyhto-1-DateVector) = datevec([DateString](#btfyhto-1%5Fsep%5Fshared-DateString),[formatIn](#btfyhto-1-formatIn)) uses formatIn to interpret the dates and times represented byDateString.

example

[DateVector](#btfyhto-1-DateVector) = datevec([DateString](#btfyhto-1%5Fsep%5Fshared-DateString),[PivotYear](#btfyhto-1%5Fsep%5Fshared-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 asformatIn. Syntaxes without formatIn are significantly slower than syntaxes that include it.

[DateVector](#btfyhto-1-DateVector) = datevec([DateString](#btfyhto-1%5Fsep%5Fshared-DateString),[formatIn](#btfyhto-1-formatIn),[PivotYear](#btfyhto-1%5Fsep%5Fshared-PivotYear)) uses formatIn to interpret the dates and times represented byDateString, and PivotYear to interpret text that specifies the year as two characters. You can specifyformatIn and PivotYear in either order.

example

[[Y,M,D,H,MN,S]](#btfyhto-1-YMDHMNS) = datevec(___) returns the components of the date vector as individual variablesY, M, D,H, MN, and S (year, month, day, hour, minutes, and seconds). The datevec function returns milliseconds as a fractional part of the seconds (S) output.

example

Examples

collapse all

format short g

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

t = 2×1 datetime 01-Feb-2025 08:46:50 02-Feb-2025 00:00:00

DateVector = 2×6

     2025            2            1            8           46       50.078
     2025            2            2            0            0            0

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

ans = 1×6

    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 = 3×6

    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×6 103 ×

2.0250    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 = 1×6

    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 = 1×6

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

Input Arguments

collapse all

Dates and times, specified as an array of datetime orduration values.

If any element of t is a NaT orNaN, then the corresponding date vector returned bydatevec is a 6-element row vector ofNaNs.

Data Types: datetime | duration | calendarDuration

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

Example: 'dddd, mmm dd, yyyy'

The following table shows symbolic identifiers that 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 the identifiers that describe the display formats ofdatetime 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 one or two digits	3, 06,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 one or two digits	5, 09,20
d	Day using capitalized first letter	M,T
HH	Hour in two digits (no leading zeros when symbolic identifier AM orPM 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, theHH field is also required.
datevec does not accept formats that include'QQ'

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.

If the input is a datetime orduration array, and any element is aNaT or NaN, then the corresponding date vector returned by datevec is a 6-element row vector of NaNs.

Components of the date vector (year, month, day, hour, minute, and second), returned as numeric scalars or numeric vectors. Milliseconds are a fractional part of the seconds output. When converting adatetime array t, these components are equal to the values of the Year,Month, Day,Hour, Minute, andSecond properties. For example, Y = t.Year.

Limitations

If the first input argument is a datetime array, a numeric array, or text representing dates and times, then datevec sets any month values less than 1 to 1 in the output. Day values,D, less than 1 are set to the last day of the previous month minus |D|. However, if 0 ≤DateNumber < 1, thendatevec(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.
If the first input argument is a duration array, then the output of datevec does not represent points in time, but rather lengths of time measured in fixed-length time units. Each row of the output matrix represents a duration as the number of years, months, days, hours, minutes, and seconds whose sum is the total length of time represented by the corresponding element of the input duration array.
However, a month cannot be a fixed-length time unit because different months have different numbers of days. Therefore the number of months is always zero. Instead, datevec represents a duration as the number of years (each 365.2425 days long), the number of days (each 86,400 seconds long), and the number of hours, minutes, and seconds whose sum is that duration. As another consequence, the number of days can be greater than 31.

Tips

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

Extended Capabilities

expand all

Thedatevec function supports tall arrays with the following usage notes and limitations:

First argument must be a column vector, character vector, or character array.

For more information, see Tall Arrays.

Usage notes and limitations:

Starting in R2020b, in generated code this function supports onlydatetime and duration arrays as inputs. You cannot specify serial date numbers or text as inputs in generated code.

Version History

Introduced before R2006a

expand all

Using datevec with serial date numbers as inputs is not recommended. Use the datetime data type to represent points in time instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To split datetime values into date and time components, use thehms, ymd, ordatevec functions, or use the Year,Month, Day, Hour,Minute, and Second properties ofdatetime values.

For example, call datevec on a datetime value that represents the current date and time.

d = datetime 15-Apr-2022 15:53:28

format shortg dateVector = datevec(d)

dateVector =

    2022           4          15          15          53          28

To access one component, use the corresponding datetime property. For example, get the value of the Month property ofd.