# datevec

Convert date and time to vector of components

## Syntax

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

## Description

example

``` NoteWhile 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. `DateVector = datevec(t)` converts the `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.```

example

````DateVector = datevec(DateNumber)` converts one or more date numbers to date vectors. The `datevec` function 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 syntaxes 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 syntaxes 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). The `datevec` function returns milliseconds as a fractional part of the seconds (`S`) output.```

## Examples

collapse all

```format short g t = [datetime('now');datetime('tomorrow')]```
```t = 2x1 datetime 26-Feb-2022 12:01:10 27-Feb-2022 00:00:00 ```
`DateVector = datevec(t)`
```DateVector = 2×6 2022 2 26 12 1 10.767 2022 2 27 0 0 0 ```
```format short g n = 733779.651; datevec(n)```
```ans = 1×6 2009 1 6 15 37 26.4 ```
```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.0220 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')`
```y = 2012 ```
```m = 2 ```
```d = 1 ```
```h = 0 ```
```mn = 0 ```
```s = 0 ```

## Input Arguments

collapse all

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

Data Types: `datetime` | `duration` | `calendarDuration`

Serial date number, specified as an 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, 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.

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

## Version History

Introduced before R2006a