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.