Formats a date as a date string for a locale specified by name. The function formats either a specified date or the local system date.
Note The application should call this function in preference to GetDateFormat if designed to run only on Windows Vista and later.
Note This function can format data that changes between releases, for example, due to a custom locale. If your application must persist or transmit data, see Using Persistent Locale Data.
int GetDateFormatEx( _In_opt_ LPCWSTR lpLocaleName, _In_ DWORD dwFlags, _In_opt_ const SYSTEMTIME *lpDate, _In_opt_ LPCWSTR lpFormat, _Out_opt_ LPWSTR lpDateStr, _In_ int cchDate, _In_opt_ LPCWSTR lpCalendar );
- lpLocaleName [in, optional]
Pointer to a locale name, or one of the following predefined values.
- dwFlags [in]
Caution Use of LOCALE_NOUSEROVERRIDE is strongly discouraged as it disables user preferences.
If the application does not specify DATE_YEARMONTH, DATE_SHORTDATE, or DATE_LONGDATE, and lpFormat is set to NULL, DATE_SHORTDATE is the default.
- lpDate [in, optional]
Pointer to a SYSTEMTIME structure that contains the date information to format. The application can set this parameter to NULL if the function is to use the current local system date.
- lpFormat [in, optional]
Pointer to a format picture string that is used to form the date. Possible values for the format picture string are defined in Day, Month, Year, and Era Format Pictures.
For example, to get the date string "Wed, Aug 31 94", the application uses the picture string "ddd',' MMM dd yy".
The function uses the specified locale only for information not specified in the format picture string, for example, the day and month names for the locale. The application can set this parameter to NULL to format the string according to the date format for the specified locale.
- lpDateStr [out, optional]
Pointer to a buffer in which this function retrieves the formatted date string.
- cchDate [in]
Size, in characters, of the lpDateStr buffer. The application can set this parameter to 0 to return the buffer size required to hold the formatted date string. In this case, the buffer indicated by lpDateStr is not used.
- lpCalendar [in, optional]
Reserved; must set to NULL.
Returns the number of characters 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, which can return one of the following error codes:
- ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
- ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
The earliest date supported by 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 structure indicated 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 members of the SYSTEMTIME structure indicated by lpDate. These include wHour, wMinute, wSecond, and wMilliseconds.
If the lpFormat parameter contains a bad format string, the function returns no errors, but just forms the best possible date string. For example, the only year pictures that are valid are L"yyyy" and L"yy", where 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 four date (L"dddd") or four month (L"MMMM") pictures are passed in, the function defaults to L"dddd" or L"MMMM".
The application should enclose any text that should remain in its exact form in the date string within single quotation marks in the date format picture. The single quotation mark can 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 is: 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 both a numeric form of the day (either d or dd) and the full month name (MMMM), the genitive form of the month name is retrieved in the date string.
To obtain the default short and long date format without performing any actual formatting, the application should use GetLocaleInfoEx with the LOCALE_SSHORTDATE or LOCALE_SLONGDATE constant. To get the date format for an alternate calendar, the application uses GetLocaleInfoEx with the LOCALE_IOPTIONALCALENDAR constant. To get the date format for a particular calendar, the application uses GetCalendarInfoEx, passing the appropriate Calendar Identifier. It can call EnumCalendarInfoEx or EnumDateFormatsEx to retrieve date formats for a particular calendar.
This function can retrieve data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.
Beginning in Windows 8: GetDateFormatEx is declared in Datetimeapi.h. Before Windows 8, it was declared in Winnls.h.
Windows Phone 8.1: This API is supported.
Minimum supported client
|Windows Vista [desktop apps | Windows Store apps]|
Minimum supported server
|Windows Server 2008 [desktop apps | Windows Store apps]|
- National Language Support
- National Language Support Functions
- Day, Month, Year, and Era Format Pictures
- NLS: Name-based APIs Sample