| Platform SDK: International Features |
The GetDateFormat function formats a date as a date string for a specified locale. The function formats either a specified date or the local system date.
int GetDateFormat( LCID Locale, // locale DWORD dwFlags, // options CONST SYSTEMTIME *lpDate, // date LPCTSTR lpFormat, // date format LPTSTR lpDateStr, // formatted string buffer int cchDate // size of buffer );
This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values.
| Value | Meaning |
|---|---|
| LOCALE_SYSTEM_DEFAULT | Default system locale. |
| LOCALE_USER_DEFAULT | Default user locale. |
If lpFormat is NULL, you can specify a combination of the following values.
| Value | Meaning |
|---|---|
| LOCALE_NOUSEROVERRIDE | If set, the function formats the string using the system default–date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default–date format. |
| LOCALE_USE_CP_ACP | Uses the system ANSI code page for string translation instead of the locale's code page. |
| DATE_SHORTDATE | Uses the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH. |
| DATE_LONGDATE | Uses the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH. |
| DATE_YEARMONTH | Uses the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE. |
| DATE_USE_ALT_CALENDAR | Uses the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar. |
| DATE_LTRREADING | Adds marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING. |
| DATE_RTLREADING | Adds marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING |
If you do not specify either DATE_YEARMONTH, DATE_SHORTDATE, or DATE_LONGDATE, and lpFormat is NULL, then DATE_SHORTDATE is the default.
Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table (for example, "MM" not "mm"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.
| Picture | Meaning |
|---|---|
| d | Day of month as digits with no leading zero for single-digit days. |
| dd | Day of month as digits with leading zero for single-digit days. |
| ddd | Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale. |
| dddd | Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale. |
| M | Month as digits with no leading zero for single-digit months. |
| MM | Month as digits with leading zero for single-digit months. |
| MMM | Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale. |
| MMMM | Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale. |
| y | Year as last two digits, but with no leading zero for years less than 10. |
| yy | Year as last two digits, but with leading zero for years less than 10. |
| yyyy | Year represented by full four digits. |
| gg | Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string. |
For example, to get the date string
"Wed, Aug 31 94"
use the following picture string:
"ddd',' MMM dd yy"
If the function succeeds, the return value is the number of TCHARs written to the lpDateStr buffer, or if the cchDate parameter is zero, the number of bytes or characters required to hold the formatted date string. The count includes the terminating null.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:
The earliest date possible with this function is January 1, 1601.
The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the locale identifier.
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 function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.
If the lpFormat parameter is a bad format string, no errors are returned. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L"yyyy" and L"yy" (the 'L' indicates a Unicode (16-bit characters) string). If L"y" is passed in, the function assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than 4 date (L"dddd") or 4 month (L"MMMM") pictures are passed in, then the function defaults to L"dddd" or L"MMMM".
Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be: L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.
When the date picture contains a numeric form of the day (either d or dd) followed by the full month name (MMMM), the genitive form of the month name is returned in the date string.
To obtain the default short and long date format without performing any actual formatting, use the GetLocaleInfo function with the LOCALE_SSHORTDATE or LOCALE_SLONGDATE parameter. To get the date format for an alternate calendar, use GetLocaleInfo with the LOCALE_IOPTIONALCALENDAR parameter. To get the date format for a particular calendar, use GetCalendarInfo. Also, to return all of the date formats for a particular calendar, you can use EnumCalendarInfo or EnumDateFormatsEx.
Windows 2000: The ANSI version of this function will fail if it is used with a Unicode-only LCID. See Language Identifiers.
Windows NT/2000: Requires Windows NT 3.5 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Winnls.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.
National Language Support Overview, National Language Support Functions, EnumCalendarInfo, EnumDateFormatsEx, GetCalendarInfo, GetLocaleInfo, GetTimeFormat, SYSTEMTIME