# datevec

Convert date and time to vector of components

The `datevec` function creates a numeric array whose values represent the date and time components of years, months, days, hours, minutes, and seconds. However, the best way to represent points in time is by using the `datetime` data type. The best way to represent elapsed time is by using the `duration` or `calendarDuration` data types.

## Syntax

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

## Description

example

````DateVector = datevec(t)` converts the datetime values in `datetime` array `t` to date vectors. `datevec` returns an `m`-by-6 matrix where each row corresponds to a datetime value in `t`.```

example

````DateVector = datevec(DateNumber)` converts one or more date numbers to date vectors. `datevec` 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 date strings to date vectors. If the date string format is known, use `formatIn`. Syntaxes without `formatIn` are significantly slower than those that include it.```

example

````DateVector = datevec(DateString,formatIn)` uses `formatIn` to interpret each date string. ```
````DateVector = datevec(DateString,PivotYear)` uses `PivotYear` to interpret date strings that specify the year as two characters. If the date string format is known, use `formatIn`. Syntaxes without `formatIn` are significantly slower than those that include it.```

example

````DateVector = datevec(DateString,formatIn,PivotYear)` uses `formatIn` to interpret each date string, and `PivotYear` to interpret date strings that specify 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). `datevec` returns milliseconds as a fractional part of the seconds (`S`) output.```

## Examples

collapse all

### Convert datetime Array to Date Vectors

```format short g t = [datetime('now');datetime('tomorrow')] DateVector = datevec(t) ```
```t = 23-Feb-2015 09:36:28 24-Feb-2015 00:00:00 DateVector = 2015 2 23 9 36 28.959 2015 2 24 0 0 0 ```

### Convert Date Number to Date Vector

```format short g n = 733779.651; datevec(n) ```
```ans = 2009 1 6 15 37 26.4 ```

### Convert Date String to Date Vector

```DateString = '28.03.2005'; formatIn = 'dd.mm.yyyy'; datevec(DateString,formatIn) ```
```ans = 2005 3 28 0 0 0 ```

`datevec` returns a date vector for the date string with the format `'dd.mm.yyyy'`.

### Convert Multiple Date Strings to Date Vectors

Pass multiple date strings in a cell array. All input date strings must use the same format.

```DateString = {'09/16/2007';'05/14/1996';'11/29/2010'}; formatIn = 'mm/dd/yyyy'; datevec(DateString,formatIn) ```
```ans = 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.0e+03 * 2.0150 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 date string `'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 a date string to a date vector using the default pivot year.

```DateString = '12-jun-17'; formatIn = 'dd-mmm-yy'; DateVector = datevec(DateString,formatIn) ```
```DateVector = 2017 6 12 0 0 0 ```

Convert the same date string to a date vector using 1800 as the pivot year.

```DateVector = datevec(DateString,formatIn,1800) ```
```DateVector = 1817 6 12 0 0 0 ```

### Assign Elements of Returned Date Vector

Convert a date string 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

### `t` — `datetime` valuesscalar | vector | matrix | multidimensional array

`datetime` values, specified as a scalar, vector, matrix, or multidimensional `datetime` array.

### `DateNumber` — Serial date numberscalar | vector | multidimensional array

Serial date number, specified as a scalar, vector, or multidimensional array of positive double-precision numbers.

Example: `731878`

Data Types: `double`

### `DateString` — Date stringsstring | character array | 1–D cell array of strings

Date strings, specified as a character array where each row corresponds to one date string, or as a one dimensional cell array of strings. All of the date strings 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 date string format is known, you should also specify `formatIn`. If you do not specify `formatIn`, `DateString` must be in one of the following formats.

Date String Format

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 string formats are different from those that describe the display formats of `datetime` arrays.

Certain date string formats might not contain enough information to convert the date string. 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 date string 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 date string is greater than 12 and the second entry is less than or equal to 12, then `datevec` considers the date string to be in `'yy/mm/dd'` format.

### `formatIn` — Format of the input date stringstring

Format of the input date string, specified as a string of symbolic identifiers.

The following table shows symbolic identifiers you can use to construct the `formatIn` string. You can include characters such as a hyphen, space, or colon to separate the fields.

 Note:   The symbolic identifiers describing date string formats are different from those 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 date string

`3:45:02` `PM`

The `formatIn` string 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 rangepresent 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 date strings 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`

Data Types: `double`

## Output Arguments

collapse all

### `DateVector` — Date vectorsvector | 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 date strings.

### `[Y,M,D,H,MN,S]` — Components of the date vectorscalar

Components of the date vector (year, month, day, hour, minute, and second), returned as individual scalar variables. Each variable is a scalar or a vector. 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

• When computing date vectors, `datevec` sets month values less than 1 to 1. 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.

collapse all

### Tips

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