Converting Date Vector Returns Unexpected Output

Note

The `datenum` and `datestr` functions are not recommended. Instead, use `datetime` values to represent points in time rather than serial date numbers or date vectors. Unlike these numeric representations, `datetime` values display in a human-readable format, often avoiding the need for conversion to text.

If you need to convert a date vector to text, the best practice is to first convert it to a `datetime` value, and then to convert the `datetime` value to text by using the `string` or `char` functions. For more information on updating your code to use `datetime` values, see Replace Discouraged Instances of Serial Date Numbers and Date Strings.

While you can convert date vectors to text directly by using the `datestr` function, you might get unexpected results, as described in this section.

Because a date vector is a 1-by-6 row vector of numbers, the `datestr` function might interpret input date vectors as vectors of serial date numbers and return unexpected output. Or it might interpret vectors of serial date numbers as date vectors. This ambiguity exists because `datestr` has a heuristic rule for interpreting a 1-by-6 row vector as either a date vector or a vector of six serial date numbers. The same ambiguity applies to inputs that are `m`-by-6 numeric matrices, where each row can be interpreted either as a date vector or as six serial date numbers.

For example, consider a date vector that includes the year 3000. This year is outside the range of years that `datestr` interprets as elements of date vectors. Therefore, the input is interpreted as a 1-by-6 vector of serial date numbers.

```d = datestr([3000 11 05 10 32 56]) ```
```d = 6×11 char array '18-Mar-0008' '11-Jan-0000' '05-Jan-0000' '10-Jan-0000' '01-Feb-0000' '25-Feb-0000' ```

Here `datestr` interprets 3000 as a serial date number, and converts it to the text `'18-Mar-0008'` (the date that is 3000 days after 0-Jan-0000). Also, `datestr` converts the next five elements as though they also were serial date numbers.

There are two methods for converting such a date vector to text.

• The recommended method is to convert the date vector to a `datetime` value. Then convert it using the `char`, `cellstr`, or `string` function. The `datetime` function always treats 1-by-6 numeric vectors as date vectors.

```dt = datetime([3000 11 05 10 32 56]); ds = string(dt) ```
```dt = "05-Nov-3000 10:32:56" ```
• As an alternative, convert it to a serial date number using the `datenum` function. Then, convert the date number to a character vector using `datestr`.

```dn = datenum([3000 11 05 10 32 56]); ds = datestr(dn) ```
```ds = '05-Nov-3000 10:32:56' ```

When converting dates to text, `datestr` interprets input as either date vectors or serial date numbers using a heuristic rule. Consider an `m`-by-6 matrix. The `datestr` function interprets the matrix as `m` date vectors when:

• The first five columns contain integers.

• The absolute value of the sum of each row is in the range 1500–2500.

If either condition is false, for any row, then `datestr` interprets the `m`-by-6 matrix as an `m`-by-6 matrix of serial date numbers.

Usually, dates with years in the range 1700–2300 are interpreted as date vectors. However, `datestr` might interpret rows with month, day, hour, minute, or second values outside their normal ranges as serial date numbers. For example, `datestr` correctly interprets the following date vector for the year 2020:

```d = datestr([2020 06 21 10 51 00]) ```
```d = '21-Jun-2020 10:51:00' ```

But given a day value outside the typical range (1–31), `datestr` returns a date for each element of the vector.

```d = datestr([2020 06 2110 10 51 00]) ```
```d = 6×11 char array '12-Jul-0005' '06-Jan-0000' '10-Oct-0005' '10-Jan-0000' '20-Feb-0000' '00-Jan-0000' ```

Again, the `datetime` function always treats numeric inputs as date vectors. In this case, it calculates an appropriate date, interpreting `2110` as the 2110th day since the beginning of June 2020.

```d = datetime([2020 06 2110 10 51 00]) ```
```d = datetime 11-Mar-2026 10:51:00 ```
• When you have a matrix of date vectors that `datestr` might interpret incorrectly as serial date numbers, convert the matrix by using either the `datetime` or `datenum` functions. Then convert those values to text.

• When you have a matrix of serial date numbers that `datestr` might interpret as date vectors, first convert the matrix to a column vector. Then, use `datestr` to convert the column vector.