Main Content

Carryover in Date Vectors and Strings

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, and have properties to account for time zones and leap seconds. For more information on updating your code to use datetime values, see Replace Discouraged Instances of Serial Date Numbers and Date Strings.

If an element falls outside the conventional range, MATLAB® adjusts both that date vector element and the previous element. For example, if the minutes element is 70, MATLAB adjusts the hours element by 1 and sets the minutes element to 10. If the minutes element is -15, then MATLAB decreases the hours element by 1 and sets the minutes element to 45.

In this example, the month element has a value of 22. MATLAB increments the year value to 2022 and sets the month to October. Both the datetime and datestr functions adjust for the month element that is outside the conventional range. However, datestr is not recommended.

d1 = datetime([2021 22 03 00 00 00])

d1 = 

  datetime

   03-Oct-2022

d2 = datestr([2021 22 03 00 00 00])

d2 =

    '03-Oct-2022'

The functions account for negative values the same way in any component that is not a month component. For example, these calls both take inputs with month specified as 7 (July) and the number of days specified as -5. They both subtract five from the last day of June, which is June 30, to yield a return date of June 25, 2022.

d1 = datetime([2022 07 -05 00 00 00])

d1 = 

  datetime

   25-Jun-2022

d2 = datestr([2022 07 -05 00 00 00])

d2 =

    '25-Jun-2022'

The exception to this rule occurs when the month component is a number less than 1. In that case, datetime and datestr behave differently. The datetime function subtracts the month component from the beginning of the year component, so that the output date occurs during the previous year. For example, this call with inputs for the year 2022 returns a date of July 3, 2021 because the month component is -5.

d1 = datetime([2022 -5 3 0 0 0])

d1 = 

  datetime

   03-Jul-2021

However, datestr instead sets the month component of the output to January 2022. When the input has a month component that is less than 1, datestr treats it as 1.

d2 = datestr([2022 -5 3 0 0 0])

d2 =

    '03-Jan-2022'

The carrying forward of values also applies when you use the datenum function to convert text representing dates and times. For example, datenum interprets October 3, 2022 and September 33, 2022 as the same date, and returns the same serial date number. But again, datenum is not recommended.

d = datenum("2022-10-03")

d =

      738797

d = datenum("2022-09-33")

d =

      738797

However, the datetime function does not interpret the text representing September 33, 2022. It does not attempt to carry over values in text that specifies dates and times outside convention ranges. Instead the result is an error.

d = datetime("2022-10-03")

d = 

  datetime

   03-Oct-2022

d = datetime("2022-09-33")

Error using datetime
Could not recognize the date/time format of '2022-09-33'. You can specify a format using the 'InputFormat'
parameter. If the date/time text contains day, month, or time zone names in a language foreign to the
'en_US' locale, those might not be recognized. You can specify a different locale using the 'Locale'
parameter.