strftime, wcsftime, _strftime_l, _wcsftime_l

Статья
06/09/2015

Форматируют строку времени.

size_t strftime(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr 
);
size_t _strftime_l(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr,
   _locale_t locale
);
size_t wcsftime(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr 
);
size_t _wcsftime_l(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr,
   _locale_t locale
);

Параметры

strDest
Выходная строка.
maxsize
Размер буфера strDest, измеренный в символах (char или wchart_t).
format
Строка управления форматом.
timeptr
структура данных tm
locale
Используемый языковой стандарт.

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

strftime возвращает количество символов в strDest, и wcsftime возвращает соответствующее количество расширенных символов.

Если общее количество символов, включая null в конце строки, больше maxsize, то и strftime, и wcsftime возвращают 0, и содержимое strDest не определено.

Количество символов в strDest равно числу строковых литералов в format, также, как все символы, которые могут быть добавлены в format через коды форматирования. Символ null, завершающий строку, не учитывается в возвращаемом значении.

Заметки

Функции strftime и wcsftime форматируют значение времени tm в timeptr в соответствии с предоставленным аргументом format и сохраняют результат в буфере strDest*.* Максимум maxsize символов помещаются в строку. Описание полей в структуре timeptr см. в разделе asctime. wcsftime - эквивалент strftime для расширенных символов; её указывающий на строку аргумент указывает на строку из расширенных символов. В остальном эти функции ведут себя идентично.

Примечание

В версиях до Visual C++ 2005 документация описывала параметр format функции wcsftime как имеющий тип данных const wchar_t *, но фактической реализацией типа данных format был const char *.Реализация типа данных formatбыла обновлена в соответствии с предыдущей и текущей документацией, то есть теперь это const wchar_t *.

Эта функция проверяет свои параметры. Если strDest, format или timeptr указывают на null, или если структура данных tm, на которую указывает timeptr, недопустима (например, если она содержит значения вне диапазона времени или даты), или если строка format содержит недопустимый код форматирования, то вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если выполнение может быть продолжено, функция возвращает 0 и устанавливает errno в значение EINVAL.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_tcsftime	strftime	strftime	wcsftime

Аргумент format состоит из одного или нескольких кодов; как в printf, коды форматирования начинаются знаком процента (%). Символы, которые не начинаются с %, копируются неизмененными в strDest*.* Категория LC_TIME текущего языкового стандарта влияет на форматирование вывода strftime. (Дополнительные сведения по LC_TIME см. в разделе setlocale.) Функции без суффикса _l используют текущий языковой стандарт. Версии этих функций с суффиксом _l идентичны за исключением того, что они принимают языковой стандарт в качестве параметра и используют его вместо текущего языкового стандарта. Для получения дополнительной информации см. Языковой стандарт.

Коды форматирования для strftime перечислены ниже:

%a
Сокращенное название дня недели
%A
Полное название дня недели
%b
Сокращенное название месяца
%B
Полное название месяца
%c
Представление даты и времени, подходящее для языкового стандарта
%d
День месяца в виде десятичного числа (01 - 31)
%H
Час в 24-часовом формате (00 - 23)
%I
Час в 12-часовом формате (01 - 12)
%j
День года как десятичное число (001 — 366)
%m
Месяц как десятичное число (01 - 12)
%M
Минута как десятичное число (00 - 59)
%p
Индикатор A.M./P.M. текущего языкового стандарта для 12-часового формата
%S
Секунда как десятичное число (00 — 59)
%U
Неделя года как десятичное число, с воскресеньем в качестве первого дня недели (00 — 53)
%w
День недели как десятичное число (0 - 6; Воскресенье равно 0)
%W
Неделя года как десятичное число, с понедельником в качестве первого дня недели (00 — 53)
%x
Представление дат для текущего языкового стандарта
%X
Представление времени для текущего языкового стандарта
%y
Год без века как десятичное число (00 - 99)
%Y
Год с веком как десятичное число
%z, %Z
Либо название часового пояса, либо его аббревиатура, в зависимости от настроек реестра; отсутствие символов, если часовой пояс неизвестен
%%
Знак процента

Как в функции printf, флаг # может предшествовать любому коду форматирования. В этом случае значение кода формата изменяется следующим образом.

Код формата	Значение
%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#%	Флаг # игнорируется.
%#c	Представление полной даты и времени в соответствии с текущим языковым стандартом. Например: "Tuesday, March 14, 1995, 12:41:29".
%#x	Представление полной даты, соответствующее текущему языковому стандарту. Например: "Tuesday, March 14, 1995".
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y	Удаление лидирующих нулей (если они есть).