Spec-Zone.ru › C

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, указывающее размер принимающего массива; при чтении с помощью %lc в один широкий символ размер может быть равен 1), а также за исключением того, что во время выполнения обнаруживаются следующие ошибки и вызывается установленная в данный момент функция обработчика ограничений:
  • любой аргумент указательного типа является нулевым указателем
  • 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 состоит из

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

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

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

Совпадает с символом или последовательностью символов.

  • Если указана ширина, совпадает ровно с width широкими символами (аргумент должен быть указателем на массив достаточного размера).
  • В отличие от %s и %[, не добавляет к массиву нулевой символ.
 Н/Д Н/Д
char*
wchar_t*
Н/Д Н/Д Н/Д Н/Д Н/Д
s

Совпадает с последовательностью непробельных символов (строкой).

  • Если указана ширина, совпадает не более чем с width символами или до первого пробельного символа — в зависимости от того, что встретится раньше.
  • Всегда сохраняет нулевой символ в дополнение к совпавшим символам (поэтому в массиве аргумента должно быть место как минимум для width+1 символов).
[набор ]

Совпадает с непустой последовательностью символов из набора символов.

  • Если первый символ набора — ^, совпадают все символы, не входящие в набор.
  • Если набор начинается с ] или ^], то символ ] также включается в набор.
  • Реализация определяет, может ли символ - в позиции, отличной от начальной, в сканируемом наборе обозначать диапазон, как в [0-9].
  • Если указана ширина, совпадает не более чем с width символами.
  • Всегда сохраняет нулевой символ в дополнение к совпавшим символам (поэтому в массиве аргумента должно быть место как минимум для width+1 символов).
d

Совпадает с десятичным целым числом.

  • Формат числа такой же, как ожидаемый функцией wcstol при значении 10 для аргумента base.
signedchar* or unsignedchar*
signedshort* or unsignedshort*
signedint* or unsignedint*
signedlong* or unsignedlong*
signedlonglong* or unsignedlonglong*
intmax_t* or uintmax_t*
size_t*
ptrdiff_t*
Н/Д
b (C23)

Совпадает с беззнаковым двоичным целым числом.

  • Формат числа такой же, как ожидаемый функцией wcstoul при значении 2 для аргумента base.
i

Совпадает с целым числом.

  • Формат числа такой же, как ожидаемый функцией wcstol при значении 0 для аргумента base (основание определяется по первым разобранным символам).
u

Совпадает с беззнаковым десятичным целым числом.

  • Формат числа такой же, как ожидаемый функцией wcstoul при значении 10 для аргумента base.
o

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

  • Формат числа такой же, как ожидаемый функцией wcstoul при значении 8 для аргумента base.
x
X

Совпадает с беззнаковым шестнадцатеричным целым числом.

  • Формат числа такой же, как ожидаемый функцией wcstoul при значении 16 для аргумента base.
n

Возвращает количество уже прочитанных символов.

  • Входные данные не считываются. Счётчик присваиваний не увеличивается.
  • Если для спецификатора задан оператор подавления присваивания, поведение не определено.
a (C99)
A (C99)
e
E
f
F (C99)
g
G

Совпадает с числом с плавающей точкой.

  • Формат числа такой же, как ожидаемый функцией wcstof.
 Н/Д Н/Д
float*
double*
Н/Д Н/Д Н/Д Н/Д
longdouble*
p

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

  • Семейство функций printf должно формировать ту же последовательность с помощью спецификатора формата %p.
 Н/Д Н/Д
void**
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
Примечания

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

За исключением спецификатора %, элемент входных данных (или, для %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/c/io/vfwscanf

Spec-Zone.ru

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