Main Content

Convert date and time to vector of components

**Note**

While you can represent dates and times as date vectors, it is
recommended that you use `datetime`

values to
represent points in time, and `duration`

or `calendarDuration`

values
to represent elapsed times.

converts the `DateVector`

= datevec(`t`

)`datetime`

or `duration`

value
`t`

to a *date vector*—that is, a
numeric vector whose six elements represent the year, month, day, hour, minute,
and second components of `t`

.

If `t`

is a `datetime`

or
`duration`

array having `m`

elements, then
`datevec`

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

represents a specific date and time.If

`t`

is a`duration`

array, then its values represent elapsed time. Each row of`DateVector`

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.

converts one or more date numbers to date vectors. The
`DateVector`

= datevec(`DateNumber`

)`datevec`

function returns an `m`

-by-6
matrix containing `m`

date vectors, where `m`

is the total number of date numbers in `DateNumber`

.

converts text representing dates and times to date vectors. If the format used
in the text is known, specify the format as `DateVector`

= datevec(`DateString`

)`formatIn`

.
Syntaxes without `formatIn`

are significantly slower than
syntaxes that include it.

uses `DateVector`

= datevec(`DateString`

,`formatIn`

)`formatIn`

to interpret the dates and times
represented by `DateString`

.

uses `DateVector`

= datevec(`DateString`

,`PivotYear`

)`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 syntaxes that include it.

uses `DateVector`

= datevec(`DateString`

,`formatIn`

,`PivotYear`

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

returns
the components of the date vector as individual variables `[Y,M,D,H,MN,S]`

= datevec(___)`Y`

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

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

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