## 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. ```