Spec-Zone.ru › C++

std::vwprintf, std::vfwprintf, std::vswprintf

Определён в заголовочном файле <cwchar>
int vwprintf( const wchar_t* format, va_list vlist );
(1)
int vfwprintf( std::FILE* stream, const wchar_t* format, va_list vlist );
(2)
int vswprintf( wchar_t* buffer, std::size_t buf_size, const wchar_t* format, va_list vlist );
(3)

Загружает данные из мест, определённых vlist,, преобразует их в эквивалентные широкие строки и записывает результаты в различные назначения.

1) Записывает результаты в stdout.
2) Записывает результаты в файловый поток stream.
3) Записывает результаты в широкую строку buffer. Записывается не более size-1 широких символов, после которых следует нулевой широкий символ.

Параметры

stream - выходной широкий поток для записи
buffer - указатель на широкую строку для записи
buf_size - максимальное число широких символов для записи
format - указатель на широкую строку с завершающим нулевым символом, задающую способ интерпретации данных
vlist - список аргументов переменной длины, содержащий данные для вывода.


Строка format состоит из обычных широких символов (кроме %), которые без изменений копируются в выходной поток, и спецификаций преобразования. Каждая спецификация преобразования имеет следующий формат:

  • вводный символ %.
  • (необязательно) один или несколько флагов, изменяющих поведение преобразования:
    • -: результат преобразования выравнивается по левому краю поля (по умолчанию — по правому).
    • +: знак преобразования со знаком всегда добавляется перед результатом преобразования (по умолчанию перед результатом ставится знак минуса, только если он отрицательный).
    • пробел: если результат преобразования со знаком не начинается со знака или является пустым, перед результатом добавляется пробел. Игнорируется, если присутствует флаг +.
    • #: выполняется преобразование в альтернативной форме. Точные эффекты см. в таблице ниже; в противном случае поведение не определено.
    • 0: при преобразовании целых чисел и чисел с плавающей точкой для заполнения поля используются нули в начале вместо символов пробела. Для целых чисел игнорируется, если точность задана явно. Использование этого флага для других преобразований приводит к неопределённому поведению. Игнорируется, если присутствует флаг -.
  • (необязательно) целочисленное значение или *, задающее минимальную ширину поля. При необходимости результат заполняется символами пробела (по умолчанию): слева при выравнивании по правому краю или справа при выравнивании по левому краю. Если используется *, ширина задаётся дополнительным аргументом типа int, который располагается перед преобразуемым аргументом и аргументом, задающим точность, если он указан. Если значение аргумента отрицательно, это равносильно указанию флага - и положительной ширины поля (Примечание: это минимальная ширина: значение никогда не усекается.).
    • (необязательно) ., за которым следует целое число или *, либо ничего; задаёт точность преобразования. Если используется *, точность задаётся дополнительным аргументом типа int, который располагается перед преобразуемым аргументом, но после аргумента, задающего минимальную ширину поля, если он указан. Если значение этого аргумента отрицательно, оно игнорируется. Если не указано ни число, ни *, точность считается равной нулю. Точные эффекты точности см. в таблице ниже.
    • (необязательно) модификатор длины, задающий размер аргумента (в сочетании со спецификатором формата преобразования он задаёт тип соответствующего аргумента).
    • спецификатор формата преобразования.

Доступны следующие спецификаторы формата:

Спецификатор
преобразования
Описание Ожидаемый
тип аргумента
Модификатор длины→ hh h нет l ll j z t L
Доступно только начиная с C++11→ Да Да Да Да Да
% Записывает буквальный символ %. Спецификация преобразования целиком должна быть %%. Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
c

Записывает один символ.

  • Сначала аргумент преобразуется в wchar_t, как если бы был вызван std::btowc.
  • Если используется модификатор l, аргумент std::wint_t сначала преобразуется в wchar_t.
Н/Д Н/Д
int
std::wint_t
Н/Д Н/Д Н/Д Н/Д Н/Д
s

Записывает строку символов.

  • Аргумент должен быть указателем на начальный элемент массива символов, содержащего последовательность многобайтовых символов, начинающуюся в исходном состоянии сдвига. Она преобразуется в массив широких символов так же, как при вызове std::mbrtowc с нулевым начальным состоянием преобразования.
  • Точность задаёт максимальное число записываемых широких символов. Если точность не указана, записываются все широкие символы до первого нулевого символа, не включая его.
  • Если используется спецификатор l, аргумент должен быть указателем на начальный элемент массива wchar_t.
Н/Д Н/Д
char*
wchar_t*
Н/Д Н/Д Н/Д Н/Д Н/Д
d
i

Преобразует целое число со знаком в десятичное представление [-]dddd.

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, преобразование не выводит символов.
  • Для модификатора z ожидаемым типом аргумента является знаковый вариант std::size_t.
signedchar
short
int
long
longlong
std::intmax_t
※
std::ptrdiff_t
Н/Д
b
B (необязательно)

(C++26)

Преобразует беззнаковое целое число в двоичное представление bbbb.

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, преобразование не выводит символов.
  • При альтернативной реализации перед результатом, если преобразованное значение ненулевое, добавляется 0b или 0B.
unsignedchar
unsignedshort
unsignedint
unsignedlong
unsignedlonglong
std::uintmax_t
std::size_t
беззнаковый вариант std::ptrdiff_t
Н/Д
o

Преобразует беззнаковое целое число в восьмеричное представление oooo.

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, преобразование не выводит символов.
  • При альтернативной реализации точность при необходимости увеличивается, чтобы вывести один ведущий ноль. В этом случае, если и преобразованное значение, и точность равны 0, записывается один 0.
Н/Д
x
X

Преобразует беззнаковое целое число в шестнадцатеричное представление hhhh.

  • Для преобразования с буквами x используются abcdef.
  • Для преобразования с буквами X используются ABCDEF.
  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, преобразование не выводит символов.
  • При альтернативной реализации перед результатом, если преобразованное значение ненулевое, добавляется 0x или 0X.
Н/Д
u

Преобразует беззнаковое целое число в десятичное представление dddd.

  • Точность задаёт минимальное число выводимых цифр.
  • Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, преобразование не выводит символов.
Н/Д
f
F (C++11)

Преобразует число с плавающей точкой в десятичную запись вида [-]ddd.ddd.

  • Точность задаёт точное число цифр после символа десятичной точки.
  • Точность по умолчанию — 6.
  • При альтернативной реализации символ десятичной точки записывается, даже если за ним нет цифр.
  • О преобразовании бесконечности и нечисловых значений см. примечания.
Н/Д Н/Д
double
double (C++11)
Н/Д Н/Д Н/Д Н/Д
longdouble
e
E

Преобразует число с плавающей точкой в десятичную экспоненциальную запись.

  • Для преобразования с e используется запись [-]d.ddd e±dd.
  • Для преобразования с E используется запись [-]d.ddd E±dd.
  • Экспонента содержит не менее двух цифр; дополнительные цифры используются только при необходимости.
  • Если значение равно 0, экспонента также равна 0.
  • Точность задаёт точное число цифр после символа десятичной точки.
  • Точность по умолчанию — 6.
  • При альтернативной реализации символ десятичной точки записывается, даже если за ним нет цифр.
  • О преобразовании бесконечности и нечисловых значений см. примечания.
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
a
A

(C++11)

Преобразует число с плавающей точкой в шестнадцатеричную экспоненциальную запись.

  • Для преобразования с a используется запись [-] 0xh.hhh p±d.
  • Для преобразования с A используется запись [-] 0Xh.hhh P±d.
  • Если аргумент является нормализованным числом с плавающей точкой, первая шестнадцатеричная цифра не равна 0.
  • Если значение равно 0, экспонента также равна 0.
  • Точность задаёт точное число цифр после шестнадцатеричной точки.
  • Точность по умолчанию достаточна для точного представления значения.
  • При альтернативной реализации символ десятичной точки записывается, даже если за ним нет цифр.
  • О преобразовании бесконечности и нечисловых значений см. примечания.
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
g
G

Преобразует число с плавающей точкой в десятичную или десятичную экспоненциальную запись в зависимости от значения и точности.

  • Для преобразования с g выполняется преобразование в стиле e или f.
  • Для преобразования с G выполняется преобразование в стиле E или f(до C++11)F(начиная с C++11).
  • Пусть P равно точности, если она ненулевая, 6, если точность не задана, или 1, если точность равна 0. Тогда, если преобразование в стиле E имело бы экспоненту X:
    • Если P > X ≥ −4, выполняется преобразование в стиле f или F(начиная с C++11) с точностью P − 1 − X.
    • В противном случае выполняется преобразование в стиле e или E с точностью P − 1.
  • Если не запрошено альтернативное представление, конечные нули удаляются; символ десятичной точки также удаляется, если дробная часть отсутствует.
  • О преобразовании бесконечности и нечисловых значений см. примечания.
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
n

Возвращает число символов, записанных этим вызовом функции на данный момент.

  • Результат записывается по адресу, на который указывает аргумент.
  • Спецификация не должна содержать никаких флагов, ширины поля или точности.
  • Для модификатора z ожидаемый тип аргумента — S*, где S — знаковый вариант std::size_t.
signedchar*
short*
int*
long*
longlong*
std::intmax_t*
※
std::ptrdiff_t*
Н/Д
p

Записывает определяемую реализацией последовательность символов, представляющую указатель.

Н/Д Н/Д
void*
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
Примечания

Функции преобразования чисел с плавающей точкой преобразуют бесконечность в inf или infinity. Выбор зависит от реализации.

Не-число преобразуется в nan или nan(char_sequence). Выбор зависит от реализации.

Преобразования F, E, G, A вместо этого выводят INF, INFINITY, NAN.

Спецификатор преобразования, используемый для вывода char, unsignedchar, signedchar, short и unsignedshort, ожидает типы, полученные в результате стандартных преобразований аргументов по умолчанию, однако перед выводом значение будет преобразовано в char, unsignedchar, signedchar, short и unsignedshort. Передавать значения этих типов безопасно благодаря повышению типа, выполняемому при вызове функции с переменным числом аргументов.

Правильные спецификаторы преобразования для целочисленных типов фиксированной ширины (std::int8_t и т. д.) определены в заголовочном файле <cinttypes> (хотя PRIdMAX, PRIuMAX и т. д. являются синонимами %jd, %ju и т. д.).

Спецификатор преобразования %n, записывающий данные в память, часто используется в эксплойтах, когда строки формата зависят от пользовательского ввода.

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

Если спецификация преобразования некорректна, поведение не определено.

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

1,2) Число записанных широких символов в случае успеха или отрицательное значение при ошибке.
3) Число записанных широких символов (не считая завершающего нулевого широкого символа) в случае успеха или отрицательное значение, если произошла ошибка кодирования либо число генерируемых символов равно или превышает size.

Примечания

Для узких строк предусмотрено std::vsnprintf, позволяющее определить необходимый размер выходного буфера. Для широких строк эквивалента нет, поэтому для определения размера буфера программе может потребоваться вызвать std::vswprintf, проверить возвращаемое значение и выделить буфер большего размера, повторяя попытку до успеха.

Пример

См. также

vprintfvfprintfvsprintfvsnprintf
(C++11)
выводит форматированные данные в stdout, файловый поток или буфер
с помощью списка аргументов переменной длины
(функция)
wprintffwprintfswprintf
выводит форматированные данные с широкими символами в stdout, файловый поток или буфер
(функция)
Документация по C для vwprintf, vfwprintf, vswprintf

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/c/vfwprintf

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API