Inconsistent date formats across time functions

I'm converting dates, and noticed that the format specifiers in datetime() are inconsistent with formats in datestr(). A full specification for datetime for year-month-day hour:minutes would be 'yyyy-MM-dd HH:mm', while in datestr it is 'yyyy-mm-dd HH:MM', with month and minute indicators flipping. This difference does make converting between string and numerical formats prone to programming errors.

Answer 1

[Steven Lord]

That's correct, as called out in the documentation for datetime, the documentation describing how to set the display format for those arrays, and the documentation for datenum. See the big blue Note boxes on each of the three pages.

Why did we do this? From a post on Loren's blog written when datetime was first introduced:

"If you are a frequent user of date string formats, you'll recognize that some of the format specifiers for datetime are different from those for the datestr, datenum, and datevec functions.. The new format syntax allows for more options and is now consistent with the Unicode Locale Data Markup Language (LDML) standard."

I understand your concern about accidentally making a mistake in your format string. If your format string includes a minute specifier in a location that "looks like" it should be a month specifier or vice versa, we issue a warning to try to help you avoid those types of programming errors. In release R2017b:

>> d = datetime('2017-12-06 16:10', 'InputFormat', 'yyyy-mm-dd HH:MM')
Warning: The format 'yyyy-mm-dd HH:MM' contains a field for minute (m) in what appears
to be a date portion. You might have intended to use the symbol for month (M) rather
than for minute (m). See the datetime.Format property for a complete description
of the identifiers used in format character vectors. 
> In verifyFormat (line 23)
  In datetime (line 608) 
d = 
  datetime
   06-Oct-2017 16:12:00
>> d = datetime('2017-12-06 16:10', 'InputFormat', 'yyyy-MM-dd HH:mm')
d = 
  datetime
   06-Dec-2017 16:10:00

I added some extra line breaks into the warning message to avoid scrolling in the preview, but I didn't change the text of the warning. I think this warning was introduced in the release when datetime was introduced.

Answer 2

[Peter Perkins]

"This difference does make converting between string and numerical formats prone to programming errors."

Robert, you may mean that you are using the datestr function to create text from datetime. You probably don't need to do that. With datetime, you may not need to convert to text at all. And if you do need to, use cellstr, or better, string, to do it. Both of those use the dateime array's format, or accept a format using the same "language" as datetime.

One of the benefits of using datetime is that you likely do not need to be converting back and forth between datestrs, datenums, and datevecs to do the operations that each of those legacy types is good at. All of the functionality, and more, is built into datetime itself. One data type. Hope this helps.

[Robert Heaton]

Thanks for the tip, but I'm not entirely clear on what you mean by "using string" to do it. I'm searching directories for files constructed on a pattern that embeds the current date, so need to use the underlying year/month/day data to get the correct pattern (to complicate it even more, the file name contains a span of dates, so I need to grab the current date, subtract the span of days and then reconstruct the string in the correct pattern. Since datetime and datestr take the same variable type, I just find it odd that format specifiers would be different.

[Robert Heaton]

Reviewed the help docs once again, and think I see what you mean. In the examples for the datetime function, there are several that use the key word "Format" to specify the output as a string from individual components; this feature isn't well highlighted in the help pages, as the description implies that you will only get a numerical value returned from the function rather than a string.

[Walter Roberson]

When you char() or cellstr() or string() a datetime, the Format will be used to produce character representations.

[Peter Perkins]

Each datetime array has a .Format property that you can set at construction time, or by assigning a new value to that property. The .Format property primarily controls how the array displays in the command window.

When you convert a datetime array to text using the char (probably don't want that unless there's only one datetime), cellstr, or string functions (methods, really), by default the text is created using that same .Format property. But you can also pass in a format to use in the conversion.

Notice I have not said anything about the datestr function. It works on datetimes, but just for backwards compatibility. Stick with char for one, or cellstr or string (preferred these days) for more than one.

Robert, I'm not really following the issue that you are raising with the doc. Could you be more specific what is not clear?

Answer 3

[Benjamin Gaudin]

Would love to see more consistency for minutes and months

>> dt = datestr(now,'mmmm dd, yyyy HH:MM')

dt =

    'March 13, 2020 11:15'

>> t = datetime( 'now', 'Format', 'd-MM-y HH:mm')

t = 

  datetime

   13-03-2020 11:15

[Walter Roberson]

That is not going to happen. As Steven explained, Mathworks moved to use an international standard. They are not going to change now (more than 6 years later) to revert back to non-standard, and they cannot change the datestr/datenum for compatibility with the international standards because too many old programs would break.

The international standard can be a bit difficult to remember sometimes; there is a lot of mental inertia behind HH:MM. But realistically it is not going to change.

[Peter Perkins]

Don't mix the new datetime, duration, and calendarDuration types with the old datenum, datestr, and datetick functions. In fact, best to no longer use the old stuff at all if possible. Everything works, but when you mix them together you are guaranteed to confuse yourself, and there is no need to do so unless you are passing values to functions that only accept datenums. In current MATLAB itself, I know of only a small number of plotting functions where that's the case. If you run into that situation with functions in toolboxes, contact support and point it out.