GetDateFormatEx function (datetimeapi.h)
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.
Syntax
int GetDateFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpDate,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpDateStr,
[in] int cchDate,
[in, optional] LPCWSTR lpCalendar
);
Parameters
[in, optional] lpLocaleName
Pointer to a locale name, or one of the following predefined values.
[in] dwFlags
Flags specifying various function options that can be set if lpFormat is set to NULL. The application can specify a combination of the following values and LOCALE_USE_CP_ACP or LOCALE_NOUSEROVERRIDE.
If the application does not specify DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE, or DATE_LONGDATE, and lpFormat is set to NULL, DATE_SHORTDATE is the default.
[in, optional] lpDate
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.
[in, optional] lpFormat
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.
[out, optional] lpDateStr
Pointer to a buffer in which this function retrieves the formatted date string.
[in] cchDate
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.
[in, optional] lpCalendar
Reserved; must set to NULL.
Return value
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.
Remarks
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.
The DATE_LONGDATE format includes two kinds of date patterns: patterns that include the day of the week and patterns that do not include the day of the week. For example, "Tuesday, October 18, 2016" or "October 18, 2016". If your application needs to ensure that dates use one of these kinds of patterns and not the other kind, your application should perform the following actions:
- Call the EnumDateFormatsExEx function to get all of the date formats for the DATE_LONGDATE format.
- Look for the first date format passed to the callback function that you specified for EnumDateFormatsExEx that matches your requested calendar identifier and has a date format string that matches the requirements of your application. For example, look for the first date format that includes "dddd" if your application requires that the date include the full name of the day of the week, or look for the first date format that includes neither "ddd" nor "dddd" if your application requires that the date includes nether the abbreviated name nor the full name of the day of the week.
- Call the GetDateFormatEx function with the lpFormat parameter set to the date format string that you identified as the appropriate format in the callback function.
If the presence or absence of the day of the week in the long date format does not matter to your application, your application can call GetDateFormatEx directly without first enumerating all of the long date formats by calling EnumDateFormatsExEx.
Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.
Beginning in Windows 8: GetDateFormatEx is declared in Datetimeapi.h. Before Windows 8, it was declared in Winnls.h.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | datetimeapi.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for