Replace Discouraged Instances of Serial Date Numbers and Date Strings

As of R2022b, serial date numbers and date strings are not recommended for specifying dates and times in MATLAB^®. Serial date numbers represent dates and times as the number of days since a fixed, preset date. Date strings represent dates and times as formatted text. Instead, use the datetime data type to represent points in time, and the duration and calendarDuration data types to represent elapsed times.

In particular, the datetime data type provides many advantages over serial date numbers. These advantages include:

Flexible formats for both output display and input text parsing
Storage for fractional seconds out to nanosecond precision
Properties to account for time zones, daylight saving time, and leap seconds

MATLAB functions offer equivalent support for datetime arrays. That is, functions that accept serial date numbers or date strings as inputs also accept datetime arrays as inputs. For example, the plot function accepts both serial date numbers and datetime arrays. If you specify datetime arrays, then plot automatically formats axis and tick labels using properties of the datetime inputs. This plotting capability is another example of the advantages provided by datetime arrays.

This topic shows you how to remove serial date numbers and date strings from your MATLAB code. You can convert them to the recommended data types, replace functions and syntaxes that use serial date numbers or date strings, and update your own functions while maintaining backward compatibility.

Convert Serial Date Numbers and Date Strings

You can convert serial date numbers and date strings to datetime arrays. The datetime function is the recommended function for most conversions.

To convert serial date numbers, use datetime.

d = 738522;
d = datetime(d,"ConvertFrom","datenum")

To convert date strings, use datetime.
```
d = datetime("2022-06-28 12:34:56")
```
To specify the input format, use the InputFormat name-value argument.
```
d = "28 June 2022";
d = datetime(d,"InputFormat","dd MMMM yyyy")
```
To convert text timestamps that represent elapsed time as hours, minutes, and seconds, use the duration function.
```
d = duration("08:17:43")
```

Replace Functions That Use Date Numbers

There are older date and time functions in MATLAB that use serial date numbers, or return results as serial date numbers or date strings. For example, the datenum function returns specified dates and times as serial date numbers. The datestr function returns dates and times as date strings. Functions such as date, now, and today return serial date numbers or date strings. These functions are not recommended.

This table describes common date and time operations, the discouraged functions that perform these operations, and their recommended replacements. There are no plans to remove the discouraged functions described in the table.

Operation	Discouraged Function	Recommended Replacement
Add time to points in time.	`addtodate`	Add `duration` or `calendarDuration` values to `datetime` values. Example: Add array of hours. d = datetime("2022-01-01"); d = d + hours(0:4:12) Example: Add array of calendar months. d = datetime("2022-01-01"); d = d + calmonths(0:2)
Return current time (as a date vector).	`clock`	Use `datetime` or `datetime("now")`, and `datevec` to convert to a date vector. Example: Return current time as `datetime` value. d = datetime % or d = datetime("now") Example: Return current time as date vector. d = datevec(datetime)
Return current date (as text).	`date`	Use `datetime("today")`. Example: Return current date as `datetime` value. d = datetime("today") Example: Return current date as text. d = datetime("today"); d = string(d)
Specify dates and times (as data type treated numerically).	`datenum`	Use `datetime` values. Example: Convert serial date number to `datetime` value. d = 738522; d = datetime(d,"ConvertFrom","datenum")
Specify dates and times (as text).	`datestr`	Use the `string` or `char` function. Example: Convert `datetime` value to text. d = datetime(2022,6,28,12,34,56) d = string(d)
Convert date vector to text.	`datestr`	Use the `string` or `char` function. Example: Convert date vector to `datetime` value, then to text. dv = [2022 6 28 12 34 56]; d = datetime(dv) d = string(d)
Return last dates of months.	`eomdate`	Use the `dateshift` function with `datetime` values as inputs. Example: Return last date of current month as `datetime` value. d = datetime("today") endMonth = dateshift(d,"end","month") Example: Return last date of month given `y` and `m` as numeric inputs for year and month. y = 2022; m = 6; endMonth = dateshift(datetime(y,m,1),"end","month")
Calculate difference between two points in time.	`etime`	Subtract `datetime` values or use the `between` function. Example: Subtract `datetime` values. The result is a `duration` value representing elapsed time in units of fixed length. startOfToday = datetime("today") currentTime = datetime("now") elapsedTime = currentTime - startOfToday Example: Return difference between `datetime` values. The result is a `calendarDuration` value representing elapsed time in calendar units of variable length. d1 = datetime("2022-01-01") d2 = datetime("now") elapsedTime = between(d1,d2)
Return date of last occurrence of weekday in month.	`lweekdate`	Use the `dateshift` and `datetime` functions. Example: Return last Tuesday of October 2021 as `datetime` value. october = datetime(2021,10,1); endOfOctober = dateshift(october,"end","month"); lastTuesday = dateshift(endOfOctober,"dayofweek","Tuesday","previous")
Convert dates and times to Excel^® serial date numbers.	`m2xdate`	Use the `exceltime` function. Example: Return current date as Excel serial date number. d = datetime("today") excelNum = exceltime(d)
Return number of whole months between dates.	`months`	Use the `between` function with `datetime` values as inputs. Example: Return number of months between January 1, 2021, and current date. d1 = datetime("2021-01-01") d2 = datetime("today") numMonths = between(d1,d2,"months")
Return current time.	`now`	Use `datetime` or `datetime("now")`. Example: Return current time as `datetime` value. d = datetime % or d = datetime("now")
Return date of specific occurrence of weekday in month.	`nweekdate`	Use the `dateshift` and `datetime` functions. Example: Return first Tuesday of October 2021 as `datetime` value. october = datetime(2021,10,1); firstTuesday = dateshift(october,"dayofweek","Tuesday",1)
Return current date.	`today`	Use `datetime("today")`. Example: Return current date as `datetime` value. d = datetime("today")
Return weeks in year (as numbers).	`weeknum`	Use the `week` function with `datetime` values as inputs. Example: Return week of year for current date. d = datetime("today") weekNumber = week(d,"weekofyear")
Convert Excel serial date numbers to MATLAB dates and times.	`x2mdate`	Use the `datetime` with `dateType` as `"excel"`. Example: Convert Excel serial date number to `datetime` value. excelNum = 44481 dt = datetime(excelNum,"ConvertFrom","excel")

Discouraged Syntaxes for Date and Time Components

There are date and time functions in MATLAB that return components of input dates and times. The components of points in time are years, quarters, months, days, hours, minutes, and seconds. For example, June 28, 2022, 12:34:56 p.m. has a year component of 2022 and a day component of 28. Though not shown, it also has a quarter component of 2 because it occurs during the second quarter of 2022.

The functions that return date and time components are year, quarter, month, and so on. The datevec, ymd, hms, and timeofday functions also return components as numeric vectors or matrices. All of these functions support datetime arrays as inputs.

Many of these functions also support serial date numbers and date strings as inputs. However, the syntaxes that support these inputs are not recommended. Instead, use datetime arrays as inputs. The table shows discouraged syntaxes and recommended syntaxes for these functions.

There are no plans to remove support for serial date numbers and date strings from these functions.

Date and Time Component Function	Discouraged Syntax	Recommended Syntax
`datevec`	dateVector = datevec(738700.52426) dateVector = datevec("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") dateVector = datevec(d)
`day`	dayNum = day(738700.52426) dayNum = day("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") dayNum = day(d) % or dayNum = d.Day
`hour`	hourNum = hour(738700.52426) hourNum = hour("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") hourNum = hour(d) % or hourNum = d.Hour
`minute`	minuteNum = minute(738700.52426) minuteNum = minute("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") minuteNum = minute(d) % or minuteNum = d.Minute
`month`	monthNum = month(738700.52426) monthNum = month("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") monthNum = month(d) % or monthNum = d.Month
`quarter`	quarterNum = quarter(738700.52426) quarterNum = quarter("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") quarterNum = quarter(d)
`second`	secondNum = second(738700.52426) secondNum = second("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") secondNum = second(d) % or secondNum = d.Second
`year`	yearNum = year(738700.52426) yearNum = year("2022-06-28 12:34:56")	d = datetime("2022-06-28 12:34:56") yearNum = year(d) % or yearNum = d.Year

Guidelines for Updating Your Own Functions

If you write code for other MATLAB users, then it is to your advantage to update your functions to accept datetime arrays while maintaining backward compatibility with serial date numbers and date strings. Adoption of datetime arrays makes your code consistent with MathWorks^® products.

In existing code, accept datetime arrays as input arguments. If an input argument can be an array of serial date numbers or date strings, then update your code so that the argument can also be a datetime array.
If your code is already based on serial date numbers or date strings, then a simple and quick method to accept datetime inputs is to convert them as the first step in the code. To convert datetime arrays to serial date numbers, use the convertTo function. To convert datetime arrays to date strings, use the string or char function.
For example, if your function myFunc accepts serial date numbers, update it to accept a datetime array too. Leave the rest of your code unaltered.
```
function y = myFunc(d)
    if (isdatetime(d))
        d = convertTo(d,"datenum")
    <line 1 of original code>
    <line 2 of original code>
    ...
```
In general, do not change the output type. Even if your existing code returns serial date numbers or date strings, it is a best practice to maintain the expected output type when other users depend on your code.
In the long term, consider rewriting your existing code to perform time-based calculations in terms of datetime arrays. If you simply convert datetime inputs to serial date numbers or date strings, then you lose information in their properties, such as time zones.
If you rewrite your code and it is code that accepted date strings as inputs, then you might need to consider backward compatibility. To preserve backward compatibility, you can interpret date strings in the same way that the datenum function interprets them.
To convert a date string to a datetime value in a backward-compatible way, use the matlab.datetime.compatibility.convertDatenum function. This function is designed to be a compatibility layer for your functions.
```
d = "01/02/22";
d = matlab.datetime.compatibility.convertDatenum(d)
```
In new code, use datetime arrays as the primary data type for representing points in time. Use duration arrays as the primary type for representing elapsed times.
If you must also accept serial date numbers and date strings as input arguments, then use the datetime function to convert them.