Функция GetDateFormatEx (datetimeapi.h)

Форматирует дату в виде строки даты для языкового стандарта, указанного по имени. Функция форматирует указанную дату или локальную системную дату.

Синтаксис

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
);

Параметры

[in, optional] lpLocaleName

Указатель на имя языкового стандарта или одно из следующих предопределенных значений.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFlags

Флаги, указывающие различные параметры функций, которые можно задать, если для lpFormat задано значение NULL. Приложение может указать сочетание следующих значений и LOCALE_USE_CP_ACP или LOCALE_NOUSEROVERRIDE.

Если приложение не указывает DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE или DATE_LONGDATE, а для параметра lpFormat задано значение NULL, по умолчанию используется DATE_SHORTDATE.

[in, optional] lpDate

Указатель на структуру SYSTEMTIME , содержащую сведения о дате для форматирования. Приложение может задать для этого параметра значение NULL , если функция использует текущую локальную системную дату.

[in, optional] lpFormat

Указатель на строку изображения формата, которая используется для формирования даты. Возможные значения для строки рисунка формата определяются в значениях "День", "Месяц", "Год" и "Эра".

Например, чтобы получить строку даты "Ср, 31 августа 94", приложение использует строку рисунка "ddd",' MMM dd yy.

Функция использует указанный языковой стандарт только для сведений, не указанных в строке рисунка формата, например названия дней и месяцев для языкового стандарта. Приложение может задать для этого параметра значение NULL , чтобы отформатировать строку в соответствии с форматом даты для указанного языкового стандарта.

[out, optional] lpDateStr

Указатель на буфер, в котором эта функция извлекает отформатированную строку даты.

[in] cchDate

Размер буфера lpDateStr (в символах). Приложение может задать для этого параметра значение 0, чтобы вернуть размер буфера, необходимый для хранения отформатированной строки даты. В этом случае буфер, указанный lpDateStr , не используется.

[in, optional] lpCalendar

Защищены; Параметр должен иметь значение NULL.

Возвращаемое значение

Возвращает число символов, записанных в буфер lpDateStr в случае успешного выполнения. Если для параметра cchDate задано значение 0, функция возвращает количество символов, необходимое для хранения форматируемой строки даты, включая завершающий символ NULL.

Эта функция возвращает значение 0, если не удалось. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:

• ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или неправильно задано значение NULL.
• ERROR_INVALID_FLAGS. Значения, предоставленные для флагов, были недопустимыми.
• ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

Комментарии

Название дня, сокращенное название дня, название месяца и сокращенное название месяца локализованы на основе идентификатора языкового стандарта.

Значения даты в структуре, указанной lpDate , должны быть допустимыми. Функция проверяет каждое из значений даты: год, месяц, день и день недели. Если указан неправильный день недели, функция использует правильное значение и не возвращает ошибок. Если какие-либо другие значения даты находятся за пределами правильного диапазона, функция завершается сбоем и задает для последней ошибки значение ERROR_INVALID_PARAMETER.

Функция игнорирует элементы времени структуры SYSTEMTIME , указанные lpDate. К ним относятся wHour, wMinute, wSecond и wMilliseconds.

Если параметр lpFormat содержит строку неправильного формата, функция не возвращает ошибок, а просто формирует наилучшую строку даты. Например, единственными допустимыми изображениями года являются L"yyyy" и L"yy", где "L" обозначает строку Юникода (16-битовые символы). Если передается L "y", функция принимает L"yyy". Если передается L "yyy", функция принимает L"yyyy". Если передается более четырех изображений даты (L"dddd") или четырех месяцев (L"MMMM"), функция по умолчанию использует значение L"dddd" или L"MMMM".

Приложение должно заключать любой текст, который должен оставаться в точном виде, в строке даты в одинарных кавычках на рисунке формата даты. Одинарные кавычки также можно использовать в качестве escape-символа, чтобы в строке даты отображалась одна кавычка. Однако escape-последовательность должна быть заключена в две одинарные кавычки. Например, чтобы отобразить дату как "Май '93", строка формата: L"MMMM '''yy". Первая и последняя кавычки являются включающими кавычками. Вторая и третья одинарные кавычки — это escape-последовательность, позволяющая отображать одинарные кавычки до века.

Если рисунок даты содержит числовую форму дня (d или dd) и полное название месяца (MMMM), в строке даты извлекается родительская форма названия месяца.

Чтобы получить короткий и длинный формат даты по умолчанию без фактического форматирования, приложение должно использовать GetLocaleInfoEx с LOCALE_SSHORTDATE или константой LOCALE_SLONGDATE . Чтобы получить формат даты для альтернативного календаря, приложение использует GetLocaleInfoEx с константой LOCALE_IOPTIONALCALENDAR . Чтобы получить формат даты для определенного календаря, приложение использует GetCalendarInfoEx, передав соответствующий идентификатор календаря. Он может вызывать EnumCalendarInfoEx или EnumDateFormatsEx для получения форматов даты для определенного календаря.

Эта функция может получать данные из пользовательских языковых стандартов. Данные не обязательно будут одинаковыми с компьютера на компьютер или между запусками приложения. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Формат DATE_LONGDATE включает два типа шаблонов дат: шаблоны, включающие день недели, и шаблоны, которые не включают день недели. Например, "Вторник, 18 октября 2016 г." или "18 октября 2016 г.". Если приложению необходимо убедиться, что даты используют один из этих типов шаблонов, а не другой, приложение должно выполнить следующие действия:

1. Вызовите функцию EnumDateFormatsExEx, чтобы получить все форматы дат для формата DATE_LONGDATE.
2. Найдите первый формат даты, переданный функции обратного вызова, указанной для EnumDateFormatsExEx, который соответствует запрошенным идентификаторам календаря и имеет строку формата даты, соответствующую требованиям приложения. Например, найдите формат первой даты, включающий "dddd", если ваше приложение требует, чтобы дата включала полное название дня недели, или найдите первый формат даты, который не содержит ни "ddd", ни "dddd", если ваше приложение требует, чтобы дата включала в себя сокращенное или полное название дня недели.
3. Вызовите функцию GetDateFormatEx с параметром lpFormat , задав строку формата даты, которую вы определили как соответствующий формат в функции обратного вызова.

Если наличие или отсутствие дня недели в формате длинной даты не имеет значения для приложения, приложение может вызвать GetDateFormatEx напрямую, не перечисляя все форматы длинных дат, вызвав EnumDateFormatsExEx.

Начиная с Windows 8. Если приложение передает языковые теги в эту функцию из пространства имен Windows.Globalization, оно должно сначала преобразовать теги, вызвав ResolveLocaleName.

Начиная с Windows 8: GetDateFormatEx объявляется в Datetimeapi.h. До Windows 8 он был объявлен в Winnls.h.

Требования

См. также

Изображения в формате "День", "Месяц", "Год" и "Эра"

EnumDateFormatsExEx

GetCalendarInfoEx

GetDateFormat

NLS: пример API на основе имен

Поддержка национальных языков

Функции поддержки национальных языков