std::wprintf, std::fwprintf, std::swprintf

Определён в заголовочном файле `<cwchar>`
int wprintf( const wchar_t* format, ... );	(1)
int fwprintf( std::FILE* stream, const wchar_t* format, ... );	(2)
int swprintf( wchar_t* buffer, std::size_t size, const wchar_t* format, ... );	(3)

Загружает данные из указанных местоположений, преобразует их в соответствующие широкие строки и записывает результаты в различные потоки вывода.

1) Записывает результаты в stdout.

2) Записывает результаты в файловый поток stream.

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

Параметры

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

Строка 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` используется запись [-] `0x`h.hhh `p`±d. Для преобразования `A` используется запись [-] `0X`h.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 (в том числе когда size равно нулю).

Примечания

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

Пример

#include <clocale>
#include <cwchar>
#include <iostream>
#include <locale>

int main()
{
    char narrow_str[] = "z\u00df\u6c34\U0001f34c";
                  // or "zß水🍌";
                  // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
    wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator
    std::setlocale(LC_ALL, "en_US.utf8");

    std::swprintf(warr, sizeof warr/sizeof *warr,
                  L"Converted from UTF-8: '%s'", narrow_str);

    std::wcout.imbue(std::locale("en_US.utf8"));
    std::wcout << warr << '\n';
}

Вывод:

Converted from UTF-8: 'zß水🍌'

См. также

printffprintfsprintfsnprintf (C++11)	выводит форматированный текст в `stdout`, файловый поток или буфер (функция)
vwprintfvfwprintfvswprintf	выводит форматированный текст с широкими символами в `stdout`, файловый поток или буфер, используя список аргументов переменной длины (функция)
fputws	записывает широкую строку в файловый поток (функция)
Документация по C для `wprintf, fwprintf, swprintf`

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