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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[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:

1. Call the EnumDateFormatsExEx function to get all of the date formats for the DATE_LONGDATE format.
2. 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.
3. 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

See also

Day, Month, Year, and Era Format Pictures

EnumDateFormatsExEx

GetCalendarInfoEx

GetDateFormat

NLS: Name-based APIs Sample

National Language Support

National Language Support Functions