Spec-Zone.ru › C

wprintf, fwprintf, swprintf, wprintf_s, fwprintf_s, swprintf_s, snwprintf_s

Определено в заголовочном файле <wchar.h> 
int wprintf( const wchar_t* format, ... );
(1) (начиная с C95)
(до C99) 
int wprintf( const wchar_t* restrict format, ... );
(начиная с C99) 
int fwprintf( FILE* stream, const wchar_t* format, ... );
(2) (начиная с C95)
(до C99) 
int fwprintf( FILE* restrict stream,
              const wchar_t* restrict format, ... );
(начиная с C99) 
int swprintf( wchar_t* buffer, size_t bufsz,
              const wchar_t* format, ... );
(3) (начиная с C95)
(до C99) 
int swprintf( wchar_t* restrict buffer, size_t bufsz,
              const wchar_t* restrict format, ... );
(начиная с C99) 
int wprintf_s( const wchar_t* restrict format, ... );
(4) (начиная с C11) 
int fwprintf_s( FILE* restrict stream,
                const wchar_t* restrict format, ... );
(5) (начиная с C11) 
int swprintf_s( wchar_t* restrict buffer, rsize_t bufsz,
                const wchar_t* restrict format, ... );
(6) (начиная с C11) 
int snwprintf_s( wchar_t* restrict s, rsize_t n,
                 const wchar_t* restrict format, ... );
(7) (начиная с C11)

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

1) Записывает результаты в stdout.
2) Записывает результаты в файловый поток stream.
3) Если bufsz больше нуля, записывает результаты в широкую строку buffer. Записывается не более bufsz - 1 широких символов, за которыми следует нулевой широкий символ. Если bufsz равно нулю, ничего не записывается (и buffer может быть нулевым указателем).
4-6) То же, что и (1-3), за исключением того, что во время выполнения обнаруживаются следующие ошибки, вызывающие функцию обработчика ограничений, установленную в данный момент:
  • спецификатор преобразования %n присутствует в format
  • любой аргумент, соответствующий %s, является нулевым указателем
  • format или buffer является нулевым указателем
  • bufsz равно нулю или больше RSIZE_MAX / sizeof(wchar_t)
  • при преобразовании строк и символов возникают ошибки кодирования
  • (только для swprintf_s) количество широких символов, которые требуется записать, включая нулевой символ, превышает bufsz.
7) То же, что и (6), за исключением того, что результат усекается до размера массива, на который указывает s.
Как и для всех функций с проверкой границ, наличие wprintf_s, fwprintf_s, swprintf_s и snwprintf_s гарантируется только в том случае, если реализация определяет __STDC_LIB_EXT1__ и пользователь задает __STDC_WANT_LIB_EXT1__ равным целочисленной константе 1 до подключения <stdio.h>.

Параметры

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


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

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

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

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

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

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

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

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

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

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

(C23)

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

  • Точность задает минимальное количество выводимых цифр. Точность по умолчанию — 1.
  • Если преобразуемое значение и точность равны 0, преобразование не дает символов.
  • В альтернативной форме перед результатом, если преобразуемое значение отлично от нуля, ставится 0b или 0B.
unsignedchar
unsignedshort
unsignedint
unsignedlong
unsignedlonglong
uintmax_t
size_t
версия 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 (C99)

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

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

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

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

(C99)

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

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

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

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

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

  • Результат записывается по адресу, на который указывает аргумент.
  • Спецификация не должна содержать никаких флагов, ширины поля или точности.
  • Для модификатора z ожидаемый тип аргумента — S*, где S является типом size_t со знаком.
signedchar*
short*
int*
long*
longlong*
intmax_t*
※
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. Передавать значения этих типов безопасно благодаря продвижению типов, происходящему при вызове функции с переменным числом аргументов.

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

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

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

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

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

1,2) Количество записанных широких символов при успешном выполнении или отрицательное значение в случае ошибки.
3) Количество записанных широких символов (не считая завершающего нулевого широкого символа) при успешном выполнении или отрицательное значение, если произошла ошибка кодирования либо количество генерируемых символов было равно или больше bufsz (в том числе если bufsz равно нулю).
4,5) Количество записанных широких символов при успешном выполнении или отрицательное значение в случае ошибки.
6) Количество широких символов (не считая завершающего нулевого символа), записанных в buffer. Возвращает отрицательное значение при ошибках кодирования и переполнении. При всех остальных ошибках возвращает ноль.
7) Количество широких символов (не считая завершающего нулевого символа), которые были бы записаны в buffer, если бы bufsz имел достаточный размер, или отрицательное значение при возникновении ошибки. (То есть запись прошла успешно и завершилась полностью только в том случае, если возвращаемое значение неотрицательно и меньше bufsz.)

Примечания

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

snwprintf_s, в отличие от swprintf_s, усекает результат до размера массива, на который указывает buffer, хотя большинство функций с проверкой границ считают усечение ошибкой.

Пример

#include <locale.h>
#include <wchar.h>

int main(void)
{
    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
    setlocale(LC_ALL, "en_US.utf8");
    swprintf(warr, sizeof warr / sizeof* warr,
             L"Converted from UTF-8: '%s'", narrow_str);
    wprintf(L"%ls\n", warr);
}

Вывод:

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

Ссылки

  • Стандарт C23 (ISO/IEC 9899:2024):
    • 7.29.2.1 Функция fwprintf (с. TBD)
    • 7.29.2.3 Функция swprintf (с. TBD)
    • 7.29.2.11 Функция wprintf (с. TBD)
    • K.3.9.1.1 Функция fwprintf_s (с. TBD)
    • K.3.9.1.4 Функция swprintf_s (с. TBD)
    • K.3.9.1.13 Функция wprintf_s (с. TBD)
  • Стандарт C17 (ISO/IEC 9899:2018):
    • 7.29.2.1 Функция fwprintf (с. TBD)
    • 7.29.2.3 Функция swprintf (с. TBD)
    • 7.29.2.11 Функция wprintf (с. TBD)
    • K.3.9.1.1 Функция fwprintf_s (с. TBD)
    • K.3.9.1.4 Функция swprintf_s (с. TBD)
    • K.3.9.1.13 Функция wprintf_s (с. TBD)
  • Стандарт C11 (ISO/IEC 9899:2011):
    • 7.29.2.1 Функция fwprintf (с. 403-410)
    • 7.29.2.3 Функция swprintf (с. 416)
    • 7.29.2.11 Функция wprintf (с. 421)
    • K.3.9.1.1 Функция fwprintf_s (с. 628)
    • K.3.9.1.4 Функция swprintf_s (с. 630-631)
    • K.3.9.1.13 Функция wprintf_s (с. 637-638)
  • Стандарт C99 (ISO/IEC 9899:1999):
    • 7.24.2.1 Функция fwprintf (с. 349-356)
    • 7.24.2.3 Функция swprintf (с. 362)
    • 7.24.2.11 Функция wprintf (с. 366)

См. также

printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s
(C99)(C11)(C11)(C11)(C11)
 выводит форматированный текст в stdout, файловый поток или буфер
(функция)
vwprintfvfwprintfvswprintfvwprintf_svfwprintf_svswprintf_svsnwprintf_s
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 выводит форматированный текст с широкими символами в stdout, файловый поток
или буфер, используя список переменных аргументов
(функция)
fputws
(C95)
 записывает строку широких символов в файловый поток
(функция)
Документация C++ для wprintf, fwprintf, swprintf

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

Spec-Zone.ru

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