Formatted Date and Time Strings

Glossary

• Cultural convention: Data or data formats that are specific to a language, local dialect, or geographic location. Examples are currency symbols, date formats, calendars, numeric separators, and sorting orders.
• Date picture string/time picture string: A string used to represent a date or time format—for example, "MMMM dddd yyyy".
• LCTYPE: A constant defined by Windows that specifies a particular type of locale information.

One of the most useful sets of NLSAPI calls—GetDateFormat, GetTimeFormat, EnumDateFormats, EnumTimeFormats, and EnumCalendarInfo—returns formatted date and time picture strings. EnumDateFormats and EnumTimeFormats, as their names suggest, 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, such as the one in Figure 5-1 below.

Figure 5-1 The Date and Time dialog box from Microsoft Word 6 for Windows.

GetDateFormat and GetTimeFormat return a single string each. 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, as in the following sample code:

DWORD dwRC = ERROR_SUCCESS
LPTSTR pszDate = (LPTSTR) GlobalAlloc(GPTR, MEMSIZE(nLen + 1));

if ( !pszDate )
return (GetLastError());

int nLen = GetDateFormat(GetThreadLocale(), // Use this thread's
// locale.
DATE_LONGDATE, // Flags are passed
// into this function.
NULL, // Use current system
// time.
pszDateFormat, // format selected by
// user
pszDate, // used for formatted
// date
nLen); // used for date buffer
// length

if ( nLen == 0 )
{
dwRC = GetLastError();
GlobalFree(pszDate);
return (dwRC);
}

The short-date and long-date formats correspond to the two date formats displayed in the system Control Panel shown in Figure 5-6. Similarly, you can call GetTimeFormat to request a string containing the current time in one of several default formats. If you want to specify a different date and time, you can fill in a SYSTEMTIME structure, shown below, and pass it into a date and time formatting API.

typedef struct _SYSTEMTIME {
WORD wYear;
WORD wMonth;
WORD wDayOfWeek;
WORD wDay;
WORD wHour;
WORD wMinute;
WORD wSecond;
WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME, *LPSYSTEMTIME

Although the system's default date and time formats are the most commonly used formats for each locale, your application is not limited to these choices. You can construct a picture string that can be passed to either GetDateFormat or GetTimeFormat. For example, on March 15, 1995, the system would interpret the picture string

"'This is 'dddd', day 'dd' of the month of 'MMMM'.'"

for an English-speaking locale as

This is Wednesday, day 15 of the month of March.

For a Spanish-speaking locale, the system would interpret the picture as

This is miercoles, day 15 of the month of marzo.

Windows replaces the dddd, dd, and MMMM combinations with system strings, leaving all letters inside the single quotes untouched. Of course, you could localize the picture string into Spanish so that it would make more sense to a Spanish speaker. Figure 5-2 below summarizes the syntax for customized date and time picture strings.

If you want to retrieve pieces of a date string, such as the localized names of the days of the week or months of the year, you can call the all-purpose function GetLocaleInfo. GetLocaleInfo takes a DWORD parameter called an LCTYPE, which specifies which piece of locale-related information the system should return. GetLocaleInfoW returns a null-terminated Unicode string, and GetLocaleInfoA returns a null-terminated string in the system's default local code page. Figure 5-3 below lists the LCTYPES associated with date and time. You can find descriptions of them in Appendix I.

Figure 5-2 Date and time picture string elements.

Some languages, such as Finnish, German, Polish, and Russian, have several noun forms. If you plan to use localized names provided by the system, have a linguist check to make sure you are using them in the right context. Windows carries both the nominative and genitive forms of Polish and Russian month names; the form changes depending on the month name's position in the string relative to the day name. Windows returns both forms in a single string separated by a null value. The system carries only one form of each month name or day name for all other languages.

Figure 5-3 LCTYPEs for date and time. See Appendix I for full descriptions. The 13th month is for lunar calendars.