vwscanf, vfwscanf, vswscanf, vwscanf_s, vfwscanf_s, vswscanf_s

Определено в заголовке `<wchar.h>`
int vwscanf( const wchar_t *restrict format, va_list vlist );	(1)	(с C99)
int vfwscanf( FILE restrict stream, const wchar_t restrict format, va_list vlist );	(2)	(с C99)
int vswscanf( const wchar_t restrict buffer, const wchar_t restrict format, va_list vlist );	(3)	(с C99)
int vwscanf_s( const wchar_t *restrict format, va_list vlist );	(4)	(с C11)
int vfwscanf_s( FILE restrict stream, const wchar_t restrict format, va_list vlist );	(5)	(с C11)
int vswscanf_s( const wchar_t restrict buffer, const wchar_t restrict format, va_list vlist );	(6)	(с C11)

Считывает данные из различных источников, интерпретирует их в соответствии с format и сохраняет результаты в места, определённые vlist.

1) Считывает данные из stdin.

2) Считывает данные из потока файла stream.

3) Считывает данные из завершающейся нулём широкой строки buffer. Достижение конца строки эквивалентно достижению конца файла для fwscanf

4-6) То же, что (1-3), за исключением того, что %c, %s и %[ спецификаторы преобразования ожидают по два аргумента (обычный указатель и значение типа rsize_t, указывающее размер получающего массива, которое может быть 1 при чтении с помощью %lc в один широкий символ), и за исключением того, что следующие ошибки обнаруживаются во время выполнения и вызывают установленную в данный момент функцию обработчика ограничений обработчик ограничений:

любой из аргументов типа указателя является нулевым указателем
format, stream или buffer является нулевым указателем
количество символов, которое было бы записано с помощью %c, %s или %[, плюс завершающий нулевой символ, превысило бы второй (rsize_t) аргумент, предоставленный для каждого из этих спецификаторов преобразования
необязательно, любая другая обнаруживаемая ошибка, такая как неизвестный спецификатор преобразования

Как и во всех функциях с проверкой границ, vwscanf_s , vfwscanf_s и vswscanf_s гарантированы только в том случае, если __STDC_LIB_EXT1__ определено реализацией, и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdio.h>.

Параметры

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

Строка format состоит из

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

вводный % символ.
(необязательно) символ подавления присваивания *. Если этот параметр присутствует, функция не присваивает результат преобразования ни одному аргументу получателю.
(необязательно) целое число (больше нуля), которое определяет максимальную ширину поля, то есть максимальное количество символов, которое функция разрешается потреблять при выполнении преобразования, заданного текущим спецификатором преобразования. Обратите внимание, что %s и %[ могут привести к переполнению буфера, если ширина не задана.
(необязательно) модификатор длины, который определяет размер аргумента получателя, то есть фактический целевой тип. Это влияет на точность преобразования и правила переполнения. Значение по умолчанию для целевого типа отличается для каждого типа преобразования (см. таблицу ниже).
спецификатор формата преобразования.

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

Спецификатор преобразования	Описание	Тип аргумента
Модификатор длины →		`hh` (C99)	`h`	(нет)	`l`	`ll` (C99)	`j` (C99)	`z` (C99)	`t` (C99)	`L`
`%`	Соответствует литералу `%`.	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д
`c`	Соответствует символу или последовательности символов. Если используется спецификатор ширины, соответствует ровно ширине символов (аргумент должен быть указателем на массив с достаточным объёмом). В отличие от %s и %[, не добавляет нулевой символ в массив.	Н/Д	Н/Д	`char*`	`wchar_t*`	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д
`s`	Соответствует последовательности символов, не являющихся пробелами (строке). Если используется спецификатор ширины, соответствует до ширины или до первой встретившейся последовательности пробельных символов, в зависимости от того, что произойдёт раньше. Всегда записывает нулевой символ в дополнение к сопоставленным символам (так что массив аргументов должен иметь место для по крайней мере ширина+1 символов).
`[`множество`]`	Соответствует непустой последовательности символов из множества символов. Если первый символ множества — `^`, то сопоставляются все символы, не входящие в множество. Если множество начинается с `]` или `^]`, то символ `]` также включается в множество. Определяется реализацией, может ли символ `-` в позиции, отличной от начальной, в наборе сканирования указывать диапазон, как в `[0-9]`. Если используется спецификатор ширины, то сопоставляются только до ширины. Всегда записывает нулевой символ в дополнение к сопоставленным символам (так что массив аргументов должен иметь место для по крайней мере ширина+1 символов)
`d`	Соответствует десятичному целому числу. Формат числа такой же, как ожидается от `wcstol` со значением `10` для аргумента `base`	`signed char` или `unsigned char`	`signed short` или `unsigned short`	`signed int` или `unsigned int`	`signed long` или `unsigned long`	`signed long long` или `unsigned long long`	`intmax_t` или `uintmax_t`	`size_t*`	`ptrdiff_t*`	Н/Д
`i`	Соответствует целому числу. Формат числа такой же, как ожидается от `wcstol` со значением `0` для аргумента `base` (основание определяется первыми сопоставленными символами).
`u`	Соответствует беззнаковому десятичному целому числу. Формат числа такой же, как ожидается от `wcstoul` со значением `10` для аргумента `base`.
`o`	Соответствует беззнаковому восьмеричному целому числу. Формат числа такой же, как ожидается от `wcstoul` со значением `8` для аргумента `base`
`x`, `X`	Соответствует беззнаковому шестнадцатеричному целому числу. Формат числа такой же, как ожидается от `wcstoul` со значением `16` для аргумента `base`
`n`	Возвращает количество прочитанных до этого символов. Входные данные не потребляются. Не увеличивает счётчик присваивания. Если для спецификатора определён оператор подавления присваивания, поведение неопределённо.
`a`, `A`(C99) `e`, `E` `f`, `F`(C99) `g`, `G`	Соответствует числу с плавающей точкой. Формат числа такой же, как ожидается от `wcstof`	Н/Д	Н/Д	`float*`	`double*`	Н/Д	Н/Д	Н/Д	Н/Д	`long double*`
`p`	Сопоставляет определённую реализацией последовательность символов, определяющую указатель. Семейство функций `printf` должно создавать ту же последовательность, используя спецификатор формата `%p`	Н/Д	Н/Д	`void**`	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д	Н/Д

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

Все спецификаторы преобразования, отличные от [, c и n, потребляют и отбрасывают все ведущие пробельные символы (определяемые так же, как если бы вызывался iswspace) перед попыткой разбора входных данных. Эти потреблённые символы не учитываются при определении максимальной ширины поля.

Если спецификатор длины l не используется, спецификаторы преобразования c, s и [ выполняют преобразование символов с широкой кодировки в многобайтовую кодировку так же, как если бы вызывался wcrtomb с объектом mbstate_t, инициализированным нулём, перед преобразованием первого символа.

Спецификаторы преобразования s и [ всегда сохраняют нулевой терминатор в дополнение к сопоставленным символам. Размер целевого массива должен быть по крайней мере на один больше, чем указанная ширина поля. Использование %s или %[ без указания размера целевого массива так же небезопасно, как и gets.

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

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

При разборе неполного значения с плавающей точкой, которое заканчивается экспонентой без цифр, например, при разборе "100er" со спецификатором преобразования %f, последовательность "100e" (самый длинный префикс, который может быть действительным числом с плавающей точкой) потребляется, что приводит к ошибке сопоставления (потреблённая последовательность не может быть преобразована в число с плавающей точкой), с оставшимся "r". Некоторые существующие реализации не следуют этому правилу и отменяют потребление только "100", оставляя "er", например, ошибка glibc 1765.

Значение возврата

1-3) Количество успешно назначенных аргументов-получателей или EOF, если ошибка чтения произошла до назначения первого аргумента-получателя.

4-6) То же, что (1-3), за исключением того, что EOF также возвращается, если произошла ошибка ограничения во время выполнения.

Примечания

Все эти функции могут вызывать va_arg, значение arg неопределено после возврата. Эти функции не вызывают va_end, и это должно быть сделано вызывающей стороной.

Пример

Справочные материалы

Стандарт C11 (ISO/IEC 9899:2011):

7.29.2.6 Функция vfwscanf (стр. 418)
7.29.2.8 Функция vswscanf (стр. 419)
7.29.2.10 Функция vwscanf (стр. 420)
K.3.9.1.7 Функция vfwscanf_s (стр. 632-633)
K.3.9.1.10 Функция vswscanf_s (стр. 635-636)
K.3.9.1.12 Функция vwscanf_s (стр. 637)

Стандарт C99 (ISO/IEC 9899:1999):

7.24.2.6 Функция vfwscanf (стр. 364)
7.24.2.8 Функция vswscanf (стр. 365)
7.24.2.10 Функция vwscanf (стр. 366)

См. также

wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_s (C95)(C95)(C95)(C11)(C11)(C11)	считывает форматированный ввод широких символов из `stdin`, потока файла или буфера (функция)
Документация C++ для `vwscanf, vfwscanf, vswscanf`

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