GetCalendarDateFormatEx
Returns a properly formatted date string for the specified locale using the specified date and calendar. The user may specify the short date format, the long date format, the year month format, or a custom format pattern.
BOOL GetCalendarDateFormatEx(LPCWSTR lpszLocale,DWORD dwFlags,const LPCALDATETIME lpCalDateTime,LPCWSTR lpFormat,LPWSTR lpDateStr,int cchDate);
Parameters
lpszLocale
[in] Pointer to a locale name, or one of the following predefined values.- LOCALE_NAME_SYSTEM_DEFAULT
- LOCALE_NAME_USER_DEFAULT Details of these values are provided in LCTYPE Constants (National Language Support).
dwFlags
[in] Flags specifying function options. If lpFormat is not set to a null pointer, this parameter must be set to 0. If lpFormat is NULL, your application can specify a combination of the following values:Value Meaning LOCALE_NOUSEROVERRIDE Format the string using the system default date format for the specified locale. If this flag is not set, the function formats the string using any user overrides to the default date format for the locale. This flag can only be set if lpFormat is set to a null pointer. Note: Since LOCALE_NOUSEROVERRIDE disables user preferences, its use is discouraged. DATE_SHORTDATE Use the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH. DATE_LONGDATE Use the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH. DATE_YEARMONTH Use the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE. DATE_LTRREADING Add marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING. DATE_RTLREADING Add marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING lpCalDateTime
[in] Pointer to a CALDATETIME structure that contains the date and calendar information to be formatted.lpFormat
[in] Pointer to a format picture string that is used to form the date string. The format picture string must be zero-terminated. The function uses the locale only for information not specified in the format picture string, for example, the day and month names for the locale. The application sets this parameter to a null pointer if the function is to use the date format of the specified locale.Picture Meaning d Format day of month as digits with no leading zero for single-digit days. dd Format day of month as digits with leading zero for single-digit days. ddd Format day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale. dddd Format day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale. M Format month as digits with no leading zero for single-digit months. MM Format month as digits with leading zero for single-digit months. MMM Format month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale. MMMM Format month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale. y Format year as last two digits, but with no leading zero for years less than 10. yy Format year as last two digits, but with leading zero for years less than 10. yyyy Represent year by full four or five digits, depending on the calendar used. Thai Buddhist and Korean calendars both have five digit years. The "yyyy" pattern will show five digits for these two calendars, and four digits for all other supported calendars. yyyyy Format identically to "yyyy". gg Format 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. lpDateStr
[out] Pointer to a buffer in which this function receives the formatted date string.cchDate
[in] Size, in WCHAR values, of the lpDateStr buffer. Alternatively, the application can set this parameter to 0. In this case, the function returns the number of characters required to hold the formatted date string, and the lpDateStr parameter is not used.
Return Values
Returns the number of WCHAR values written to the lpDateStr buffer if successful. If the cchDate parameter is set to 0, the function returns the number of characters required to hold the formatted date string, including the terminating null character.
This function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError. GetLastError can return one of the following error codes:
- ERROR_INSUFFICIENT_BUFFER
- ERROR_INVALID_FLAGS
- ERROR_INVALID_PARAMETER
- ERROR_DATE_OUT_OF_RANGE
Remarks
The earliest date supported by this function is January 1, 1601.
This function does not have an associated header or library file. Call LoadLibrary with the DLL name (Kernel32.dll) to obtain a module handle. Then call GetProcAddress with that module handle and this function name to get the address of this function.
This function is deprecated and will be unavailable in subsequent versions.
Requirements
** Windows NT/2000/XP/Vista:** Windows Vista only.
** Windows 95/98/Me:** Unsupported.
** Implementation:** Implemented by Kernel32.dll.
See Also
National Language Support, National Language Support Functions, NLS: Name-based APIs Sample, EnumCalendarInfoExEx, EnumDateFormatsExEx, GetCalendarInfoEx, GetDateFormat, GetDateFormatEx, GetLocaleInfoEx