datevec

Convert date and time to vector of components

Syntax

DateVector = datevec(t)

DateVector = datevec(DateString)

DateVector = datevec(DateString,formatIn)

DateVector = datevec(DateString,PivotYear)

DateVector = datevec(DateString,formatIn,PivotYear)

[Y,M,D,H,MN,S] = datevec(___)

Description

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. For more information on updating your code, see Version History or Replace Discouraged Instances of Serial Date Numbers and Date Strings.

DateVector = datevec(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 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.

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

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

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.

[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). The datevec function returns milliseconds as a fractional part of the seconds (S) output.

Examples

Convert datetime Array to Date Vectors

format short g

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

t = 2x1 datetime
   05-Sep-2024 15:20:54
   06-Sep-2024 00:00:00

DateVector = datevec(t)

DateVector = 2×6

         2024            9            5           15           20       54.701
         2024            9            6            0            0            0

Convert Text Representing Date to Date Vector

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

Convert Multiple Date Strings to Date Vectors

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

Convert Date with Milliseconds to Date Vector

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

ans = 1×6
103 ×

    2.0240    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 Date String to Date Vector Using Pivot 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

Assign Elements of Returned Date Vector

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

t — Dates and times

array of datetime or duration values

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

If any element of t is a NaT or NaN, then the corresponding date vector returned by datevec is a 6-element row vector of NaNs.

Data Types: datetime | duration | calendarDuration

DateString — Text representing dates and times

character array | cell vector of character vectors | string vector

Text representing dates and times, specified as a character array where each row contains text representing one point in time, as a cell vector of character vectors, or as a string vector. All rows of a character array, or all elements of a cell vector or string vector, 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, then 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.

formatIn — Format of the input text representing dates and times

character vector | string scalar

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

PivotYear — Start year of 100-year date range

present minus 50 years (default) | integer

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

DateVector — Date vectors

vector | matrix

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 or duration array, and any element is a NaT or NaN, then the corresponding date vector returned by datevec is a 6-element row vector of NaNs.

[Y,M,D,H,MN,S] — Components of the date vector

numeric scalars | numeric vectors

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

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

Tips

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

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The datevec 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.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

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

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• Only these syntaxes are supported:

  DateVector = datevec(t)

  [Y,M,D,H,MN,S] = datevec(t)

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2022b: Using serial date numbers is not recommended

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 the hms, ymd, or datevec functions, or use the Year, Month, Day, Hour, Minute, and Second properties of datetime values.

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

d = datetime("now")

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 of d.

monthValue = d.Month

monthValue =

     4