It used to be right, dammit!

by Michael S. Kaplan, published on 2008/09/24 10:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2008/09/24/8963238.aspx

The GetDateFormat function from the NLS API has been around for a while.

Like since NT 3.5 and Windows 95.

The documentation for this function has of course been expanded and modified and edited many times since it was initially added to the Platform SDK.

One bit from the documentation has probably been around since the very beginning:

dwFlags
    [in] Flags specifying various function options that can be set if lpFormat is set to a null pointer. If lpFormat is not set to a null pointer, this parameter must be set to 0. The application can specify a combination of the following values.

One bit of it:

If lpFormat is not set to a null pointer, this parameter must be set to 0.

used to be right.

And it was right for a reason -- because most of the flags relate to specifying the kind of format to use and such things are really only interesting if you aren't passing a format.

I mean, how on the earth can a function respect a request to modify th builtin format like DATE_SHORTDATE or DATE_LONGDATE or DATE_YEARMONTH or LOCALE_NOUSEROVERRIDE if you pass your own format that would ignore your request?

Better to fail fast and fail consistently!

But then new flags like

• LOCALE_USE_CP_ACP, that only affects the encoding (code page) of the returned string when the ANSI function is called, and
• DATE_USE_ALT_CALENDAR, that mostly only affects the date value itself that will be formatted and not the underlying format used, and
• DATE_LTRREADING and DATE_RTLREADING, that only affects characters to insert into the resultant formatted string
  

Any of those might make sense to want to add even when you explicitly pass a format.

It would be completely unfair if we didn't let you pass one of them if you needed the results.

Luckily, the function itself works for these cases, even though the documentation doesn't know about this!

Especially since there is that GetDateFormat wrapper that will add sometimes add flags even if the lpFormat is not null....

No worries, the documentation can be updated. The weird part is that this really has been wrong for a long time. No one ever noticed it before, even to complain about how the wrapper function might be wrong?

I guess it means no one reads the documentation either.... :-)

This post brought to you by U+200f, RIGHT-TO-LEFT MARKER

referenced by

go to newer or older post, or back to index or month or day