Carryover in Date Vectors and Strings
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
10. If the minutes element is -
15, then MATLAB decreases the hours element by
1 and sets the minutes
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
datestr functions adjust for the
month element that is outside the conventional range. However,
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 -
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,
datestr behave differently. The
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
d1 = datetime([2022 -5 3 0 0 0])
d1 = datetime 03-Jul-2021
datestr instead sets the month component of the output to
January 2022. When the input has a month component that is less than
datestr treats it as
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
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
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.