Retrieving Time and Date Strings

One of the most useful sets of NLS calls is the GetDateFormat, GetTimeFormat, EnumDateFormats, EnumTimeFormats, and EnumCalendarInfo functions, which return formatted date and time picture strings. EnumDateFormats and EnumTimeFormats enumerate the date and time picture strings that the system carries for a particular locale. With these two functions, you can build a list of possible date and time strings to present to the user.

GetDateFormat and GetTimeFormat each return a single string. When you use GetDateFormat, your application can request a string containing the correct date in the default short date format (DATE_SHORTDATE) or the default long date format (DATE_LONGDATE) for a particular locale.

For GetTimeFormat, the time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails and sets the last error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime. If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker, based on the specified locale identifier. Examples of time markers are "AM" and "PM" for US English, and "de." and "du." for Mexican Spanish.

The function does not return an error for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, the function defaults to two.

For GetDateFormat, the date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value and returns no error. If any of the other date values are outside the correct range, the function fails and sets the last error to ERROR_INVALID_PARAMETER.

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the specified locale identifier. The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate.

To obtain the short and long date format for the default locale calendar, use the GetLocaleInfo function with the LOCALE_SSHORTDATE or the LOCALE_SLONGDATE flag. To get the date format for an alternate calendar, use GetLocaleInfo with the LOCALE_IOPTIONALCALENDAR flag. To get the date format for a particular calendar, use GetCalendarInfo. To return all the date formats for a particular calendar, use the EnumCalendarInfo or the EnumDateFormatsEx function.

To obtain the time format without performing any actual formatting, use the GetLocaleInfo function with the LOCALE_STIMEFORMAT flag set.