datevec (MATLAB Functions)

Convert date and time to vector of components

V = datevec(N)
V = datevec(S, F)
V = datevec(S, F, P)
[Y, M, D, H, MI, S] = datevec(...)
V = datevec(S)
V = datevec(S, P)

Description

datevec is one of three conversion functions that enable you to express dates and times in any of three formats in MATLAB: a string (or date string), a vector of date and time components (or date vector), or as a numeric offset from a known date in time (or serial date number). Here is an example of a date and time expressed in the three MATLAB formats:

Date String:           '24-Oct-2003 12:45:07'
Date Vector:           [2003  10  24  12  45  07]
Serial Date Number:    7.3188e+005

A serial date number represents the whole and fractional number of days from 1-Jan-0000 to a specific date. The year 0000 is merely a reference point and is not intended to be interpreted as a real year in time.

V = datevec(N) converts one or more date numbers N to date vectors V. Input argument N can be a scalar, vector, or multidimensional array of positive date numbers. datevec returns an m-by-6 matrix containing m date vectors, where m is the total number of date numbers in N.

V = datevec(S, F) converts one or more date strings S to date vectors V using format string F to interpret the date strings in S. Input argument S can be a cell array of strings or a character array where each row corresponds to one date string. All of the date strings in S must have the same format which must be composed of date format symbols according to the table "Free-Form Date Format Specifiers" in the datestr help. Formats with 'Q' are not accepted by datevec. datevec returns an m-by-6 matrix of date vectors, where m is the number of date strings in S.

Certain formats may not contain enough information to compute a date vector. 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. Date strings with two character years are interpreted to be within the 100 years centered around the current year.

V = datevec(S, F, P) converts the date string S to a date vector V using date format F and pivot year P. The pivot year is the starting year of the 100-year range in which a two-character year resides. The default pivot year is the current year minus 50 years.

V = datevec(S, P, F) is the same as the syntax shown above, except the order of the last two arguments are switched.

[Y, M, D, H, MI, S] = datevec(...) takes any of the two syntaxes shown above and returns the components of the date vector as individual variables.

V = datevec(S) converts date string S to date vector V. Input argument S must be in one of the date formats 0, 1, 2, 6, 13, 14, 15, 16, or 23 as defined in the reference page for the datestr function. This calling syntax is provided for backward compatibility, and is significantly slower than the syntax which specifies the format string. If the format is known, the V = datevec(S, F) syntax is recommended.

V = datevec(S, P) converts the date string S using pivot year P. If the format is known, the V = datevec(S, F, P) or V = datevec(S, P, F) syntax should be used.

Note If more than one input argument is used, the first argument must be a date string or array of date strings.

When creating your own date vector, you need not make the components integers. Any components that lie outside their conventional ranges affect the next higher component (so that, for instance, the anomalous June 31 becomes July 1). A zeroth month, with zero days, is allowed.

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

Examples

Obtain a date vector using a string as input:

datevec('12/24/1984 12:45')

ans =
        1984        12        24        12        45         0

Obtain a date vector using a serial date number as input:

t = datenum('12/24/1984 12:45')
t =
     725000.53

datevec(t)

ans =
        1984        12        24        12        45         0

Assign elements of the returned date vector:

[y, m, d, h, mi, s] = datevec('12/24/1984 12:45');

sprintf('Date: %d/%d/%d   Time: %d:%d\n', m, d, y, h, mi)

ans =
   Date: 12/24/1984   Time: 12:45

Use free-form date format 'dd.mm.yyyy' to indicate how you want a nonstandard date string interpreted:

datevec('19.05.2003', 'dd.mm.yyyy')

ans =
        2003        19        5        12        45         0

See Also

datenum, datestr, date, clock, now, datetick

datetick dbclear