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

любой из аргументов типа указатель является нулевым указателем
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 символов).
`[`set `]`	Соответствует непустой последовательности символов из множества символов. Если первый символ множества — `^`, то сопоставляются все символы, не входящие в множество. Если множество начинается с `]` или `^]`, то символ `]` также включается во множество. Определяется реализацией, может ли символ `-` в не начальной позиции в сканируемом множестве обозначать диапазон, как в `[0-9]`. Если используется спецификатор ширины, соответствует только до width. Всегда сохраняет нулевой символ в дополнение к сопоставленным символам (поэтому массив аргумента должен иметь место по крайней мере для width+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*`	Н/Д
`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*`	Н/Д	Н/Д	Н/Д	Н/Д	`long double*`
`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 bug 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

Поддержка компилятора
Язык
Заголовки
Поддержка типов
Утилиты программы
Поддержка функций с переменным числом аргументов
Обработка ошибок
Управление динамической памятью
Библиотека строк
Алгоритмы
Численные методы
Утилиты даты и времени
Поддержка ввода/вывода
Поддержка локализации
Поддержка конкурентности (C11)
Технические спецификации
Индекс символов

ru.cppreference.net

Namespaces

Variants