matlab.datetime.compatibility.convertDatenum

Convert inputs to datetime values in a backward-compatible way

Since R2022a

Syntax

dt = matlab.datetime.compatibility.convertDatenum(d)

[dt,wasDatenum] = matlab.datetime.compatibility.convertDatenum(d)

Description

Use this function in code where you intend to perform calculations on datetime values but, to preserve compatibility, need to interpret text timestamps in the same way that datenum interprets them. This function is designed to be a compatibility layer for use by customers who write functions.

dt = matlab.datetime.compatibility.convertDatenum(d) converts the date and time input to a datetime array. For backward compatibility, this function supports the subset of datestr formats that the datenum function recognizes when it converts text timestamps without a format specifier.

[dt,wasDatenum] = matlab.datetime.compatibility.convertDatenum(d) additionally returns a logical value that is 1 (true) if d is an array of serial date numbers or text timestamps, and 0 (false) if d is a datetime array.

Examples

Convert Date and Time Inputs

Convert date and time inputs to datetime values.

For example, convert a text timestamp, which is a string whose format encodes a date, a time, or both. If the format of the text timestamp is MM/dd/yy, then the datetime function considers the format to be ambiguous. Also, it interprets a two-digit year as being near the year 0 CE. So the year component of dt is 22 CE instead of 2022 CE.

d = "01/02/22";
dt = datetime(d)

Warning: Successfully converted the text to datetime using the format 'MM/dd/uuuu', but the format is ambiguous and could also be 'dd/MM/uuuu'. To create datetimes from text with a specific format call:

  datetime(textinput,'InputFormat',infmt)

dt = datetime
   02-Jan-0022

To convert this timestamp to a datetime value in a way that is backward-compatible with the datenum function, use the matlab.datetime.compatibility.convertDatenum function. This conversion makes use of the subset of datestr formats that datenum recognizes when it converts text timestamps without a format specifier. In particular, the two-digit year is taken to mean the year 2022 CE.

dt = matlab.datetime.compatibility.convertDatenum(d)

dt = datetime
   02-Jan-2022

This function also converts serial date numbers. Create a serial date number and convert it to a datetime value.

d = datenum(d)

d = 738523

dt = matlab.datetime.compatibility.convertDatenum(d)

dt = datetime
   02-Jan-2022

Report If Conversion Is Required

Convert a text timestamp. The function returns the second output argument, wasDatenum, with a value of 1, indicating that the input required conversion.

d = "01-Jan-2022 12:45:07";
[dt,wasDatenum] = matlab.datetime.compatibility.convertDatenum(d)

dt = datetime
   01-Jan-2022 12:45:07

wasDatenum = logical
   1

Call the function on a datetime value. The second output is 0 because the input is already a datetime value.

d = datetime("today")

d = datetime
   05-Sep-2024

[dt,wasDatenum] = matlab.datetime.compatibility.convertDatenum(d)

dt = datetime
   05-Sep-2024

wasDatenum = logical
   0

Input Arguments

d — Input dates and times

serial date numbers | text timestamps | datetime array

Input dates and times, specified as serial date numbers, text timestamps, or a datetime array.

If d is:

• an array of serial date numbers, then this function converts it to a datetime array by using the datetime function.

• an array of one or more text timestamps, then this function first converts it to an array of serial date numbers by using the datenum function. Then it converts the serial date number array to a datetime array by using datetime.

  Therefore, this function maintains backward compatibility with the rules that datenum uses for converting text timestamps without a format specifier.

• a datetime array, then this function returns it unaltered.

Data Types: string | char | double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime

Output Arguments

dt — Output array

datetime array

Output array, returned as a datetime array.

wasDatenum — Input data type

1 | 0

Input data type, returned as 1 or 0.

This argument is 1 (true) if input d is an array of serial date numbers or text timestamps, and 0 (false) if input d is a datetime array.

Tips

• To enable code that works with datetime arrays to accept text timestamps or serial date numbers as inputs in a backward-compatible way, add a call to matlab.datetime.compatibility.convertDatenum at the beginning of your code.

  For example, if you have defined a function myFunc that accepts two input arguments, and the second input argument can be an array of text timestamps, serial date numbers, or datetime values, process it by using matlab.datetime.compatibility.convertDatenum. Leave the rest of your code unchanged.

  function y = myFunc(A,D)
      D = matlab.datetime.compatibility.convertDatenum(D);
      <line 1 of original code>
      <line 2 of original code>
      ...

  In this example, matlab.datetime.compatibility.convertDatenum overwrites the input argument D. If D is already a datetime array, then it is unaltered.

• To return an output that matches the data type of the input argument, use the second output of matlab.datetime.compatibility.convertDatenum.

  For example, if you have defined a function myFunc that calls the dateshift function, then you must use datetime values in that calculation. But if the input to myFunc could be an array of serial date numbers, then you can use the value of wasDatenum to decide if myFunc returns an array of serial date numbers or a datetime array.

  To convert a datetime array to an array of serial date numbers, use the convertTo function.

  function DT = myFunc(D)
      [D,wasDatenum] = matlab.datetime.compatibility.convertDatenum(D);
      DT = dateshift(D,"end","month");
      if wasDatenum
         DT = convertTo(DT,"datenum")
      end
  end

Version History

Introduced in R2022a