Семейство функций wprintf является эквивалентом семейства printf
для работы с широкими символами. Функции из этого семейства производят
вывод широких символов.
Функции wprintf и vwprintf производят вывод широких символов в
поток stdout. stdout должен быть открыт не для байтовых операций;
см. функцию fwide, где содержится более полная об этом информация.
Функции fwprintf и vfwprintf производят вывод широких символов в
поток stream. stream должен быть открыт не для байтовых операций;
см. функцию fwide, где содержится более полная об этом информация.
Функции swprintf и vswprintf производят вывод широких символов
в массив широких символов.
Программист должен быть уверен, что в wcs достаточно места для maxlen
широких символов.
Все эти функции очень похожи на printf, vprintf, fprintf,
vfprintf, sprintf, vsprintf, но отличаются от них в следующем:
*
Строка format представляет собой строку широких символов.
*
Вывод функций представляет собой широкие символы, а не байты.
*
swprintf и vswprintf имеют аргумент maxlen, а
sprintf и vsprintf - нет. snprintf и vsnprintf
имеют аргумент maxlen, но не возвращают -1 при переполнении буфера
в системах Linux.
Правила преобразования символов c и s различны:
c
Если модификатора
l
нет, то аргумент
int
преобразуется в широкий символ с помощью вызова функции
btowc;
затем полученный широкий символ записывается.
Если модификатор
l
существует, то записывается аргумент (широкий символ)
wint_t.
s
Если модификатор
l
отсутствует, то: аргумент
``const char *''
ожидается в виде указателя на массив элементов типа "символ" (указателя на
строку), содержащего многобайтовую символьную последовательность.
Символы массива будут преобразованы в широкие символы последовательным
вызовом функции
mbrtowc
с учетом первоначального состояния. Результирующие широкие символы будут
записаны последовательно до завершающего нулевого символа (но не включая
его). Если количество символов определено, то записывается количество
символов, меньшее определенного числа или равное ему. Обратите внимание, что
количество символов определяет число
широких символов,
а не
байтов
или
позиций печати,
которые будут записаны. Массив должен содержать завершающий нулевой байт
на случай, если определенное в вызове количество байтов окажется
недостаточным, то есть при конвертировании широкого символа возникнет
ситуация, когда размер полученной последовательности слишком велик для
размещения ее в массиве.
-- Если модификатор
l
присутствует: аргумент
``const wchar_t *''
ожидается в виде указателя на массив элементов типа "символ" (указателя
на строку), содержащего многобайтовую символьную последовательность.
Массив должен содержать завершающий нулевой байт на случай, если
определенное в вызове количество байтов окажется недостаточным, то есть
при конвертировании широкого символа возникнет ситуация, когда размер
полученной последовательности слишком велик для размещения ее в массиве.
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
Функции возвращают количество записанных широких символов, кроме
завершающего нулевого символа для функций swprintf и
vswprintf. В случае ошибки возвращается -1.
Поведение wprintf зависит от категории LC_CTYPE текущей системной локали.
Если строка format содержит широкие символы не формата ASCII, то
программа будет работать корректно, только если категория LC_CTYPE текущей
системной локали в момент выполнения действия совпадает с категорией
LC_CTYPE текущей системной локали в момент компиляции. Это происходит
потому, что представление
wchar_t
зависит от платформы и локали. GNU libc отображает широкие символы,
используя универсальную кодовую таблицу Unicode (ISO-10646), но другие
платформы могут не следовать этому. Кроме того, использование
универсальных имен символов ISO C99 в форме \unnnn не решает этой
проблемы. Следовательно, в интернационализированных программах строка
format должна содержать только широкие символы из множества ASCII
или они должны быть сконструированы во время выполнения в стиле i18n
(т.е с использованием
gettext
или
iconv
с последующим
mbstowcs).