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

Статья
08/23/2023

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

Примечание Приложение должно вызывать эту функцию в предпочтительном режиме GetDateFormat , если оно предназначено для работы только в Windows Vista и более поздних версиях.

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

Синтаксис

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

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

[in] dwFlags

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

Осторожностью Использование LOCALE_NOUSEROVERRIDE настоятельно не рекомендуется, так как оно отключает пользовательские настройки.

Значение	Значение
DATE_AUTOLAYOUT	Windows 7 и более поздних версий: Определите необходимость в макете чтения справа налево и слева направо с помощью языковых стандартов и сведений календаря и добавьте соответствующие метки. Это значение нельзя использовать с DATE_LTRREADING или DATE_RTLREADING. DATE_AUTOLAYOUT предпочтительнее, чем DATE_LTRREADING и DATE_RTLREADING, так как для определения правильного добавления меток используются языковые параметры и календари.
DATE_LONGDATE	Используйте длинный формат даты. Это значение нельзя использовать с DATE_MONTHDAY, DATE_SHORTDATE или DATE_YEARMONTH.
DATE_LTRREADING	Добавление меток для макета чтения слева направо. Это значение нельзя использовать с DATE_RTLREADING.
DATE_RTLREADING	Добавление меток для макета чтения справа налево. Это значение нельзя использовать с DATE_LTRREADING
DATE_SHORTDATE	Используйте короткий формат даты. Это значение по умолчанию. Это значение нельзя использовать с DATE_MONTHDAY, DATE_LONGDATE или DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Используйте альтернативный календарь, если он существует, для форматирования строки даты. Если этот флаг установлен, функция использует формат по умолчанию для этого альтернативного календаря, а не какие-либо пользовательские переопределения. Переопределения пользователя будут использоваться только в том случае, если для указанного альтернативного календаря нет формата по умолчанию.
DATE_YEARMONTH	Windows Vista: Используйте формат года/месяца. Это значение нельзя использовать с DATE_MONTHDAY, DATE_SHORTDATE или DATE_LONGDATE.
DATE_MONTHDAY	Windows 10. Используйте сочетание форматов месяцев и дней, подходящих для указанного языкового стандарта. Это значение нельзя использовать с DATE_YEARMONTH, DATE_SHORTDATE или DATE_LONGDATE.

Если приложение не указывает 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. Любое из значений параметров было недопустимым.

Примечание Этот API обновляется для поддержки изменений в японской эре за май 2019 г. Если приложение поддерживает японский календарь, убедитесь, что он правильно обрабатывает новую эру. Дополнительные сведения см. в статье Подготовка приложения к изменению японской эры .

Самая ранняя дата, поддерживаемая этой функцией, — 1 января 1601 года.

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

Значения даты в структуре, указанной 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 г.". Если приложению необходимо убедиться, что даты используют один из этих типов шаблонов, а не другой, приложение должно выполнить следующие действия:

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	datetimeapi.h
Библиотека	Kernel32.lib
DLL	Kernel32.dll