wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

Определено в заголовочном файле `<wchar.h>`
int wscanf( const wchar_t* format, ... );	(1)	(начиная с C95) (до C99)
int wscanf( const wchar_t* restrict format, ... );	(1)		(начиная с C99)
int fwscanf( FILE* stream, const wchar_t* format, ... );	(2)	(начиная с C95) (до C99)
int fwscanf( FILE* restrict stream, const wchar_t* restrict format, ... );	(2)		(начиная с C99)
int swscanf( const wchar_t* buffer, const wchar_t* format, ... );	(3)	(начиная с C95) (до C99)
int swscanf( const wchar_t* restrict buffer, const wchar_t* restrict format, ... );	(3)		(начиная с C99)
int wscanf_s( const wchar_t* restrict format, ...);	(4)	(начиная с C11)
int fwscanf_s( FILE* restrict stream, const wchar_t* restrict format, ...);	(5)	(начиная с C11)
int swscanf_s( const wchar_t* restrict s, const wchar_t* restrict format, ...);	(6)	(начиная с C11)

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

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

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

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

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

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

Как и для всех функций с проверкой границ, наличие wscanf_s, fwscanf_s и swscanf_s гарантируется только в том случае, если реализация определяет __STDC_LIB_EXT1__, а пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед подключением <wchar.h>.

Параметры

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

Строка 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, если нарушено ограничение времени выполнения.

Пример

#include <stdio.h>
#include <string.h>
#include <wchar.h>

#define NUM_VARS   3
#define ERR_READ   2
#define ERR_WRITE  3

int main(void)
{
    wchar_t state[64];
    wchar_t capital[64];
    unsigned int population = 0;
    int elevation = 0;
    int age = 0;
    float pi = 0;

#if INTERACTIVE_MODE
    wprintf(L"Enter state, age, and pi value: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#else
    wchar_t* input = L"California 170 3.141592";
    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);

    FILE* fp = tmpfile();
    if (fp)
    {
        // write some data to temp file
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807"))
        {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // rewind file pointer
        rewind(fp);

        // read data into variables
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
                L"Highest elevation: %dft\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

Возможный вывод:

State: California
Age  : 170 years
Pi   : 3.14159

State  : Mississippi
Capital: Jackson
Jackson population (in 2020): 420000
Highest elevation: 807ft

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.29.2.2 Функция fwscanf (стр.: TBD)
7.29.2.4 Функция swscanf (стр.: TBD)
7.29.2.12 Функция wscanf (стр.: TBD)
K.3.9.1.2 Функция fwscanf_s (стр.: TBD)
K.3.9.1.5 Функция swscanf_s (стр.: TBD)
K.3.9.1.14 Функция wscanf_s (стр.: TBD)

Стандарт C17 (ISO/IEC 9899:2018):

7.29.2.2 Функция fwscanf (стр.: TBD)
7.29.2.4 Функция swscanf (стр.: TBD)
7.29.2.12 Функция wscanf (стр.: TBD)
K.3.9.1.2 Функция fwscanf_s (стр.: TBD)
K.3.9.1.5 Функция swscanf_s (стр.: TBD)
K.3.9.1.14 Функция wscanf_s (стр.: TBD)

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

7.29.2.2 Функция fwscanf (стр.: 410-416)
7.29.2.4 Функция swscanf (стр.: 417)
7.29.2.12 Функция wscanf (стр.: 421)
K.3.9.1.2 Функция fwscanf_s (стр.: 628-629)
K.3.9.1.5 Функция swscanf_s (стр.: 631)
K.3.9.1.14 Функция wscanf_s (стр.: 638)

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

7.24.2.2 Функция fwscanf (стр.: 356-362)
7.24.2.4 Функция swscanf (стр.: 362)
7.24.2.12 Функция wscanf (стр.: 366-367)

См. также

vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	считывает форматированный ввод широких символов из `stdin`, файлового потока или буфера с использованием списка переменного числа аргументов (функция)
Документация C++ для `wscanf, fwscanf, swscanf`

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