wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

int wscanf( const wchar_t *format, ... );

int wscanf( const wchar_t *restrict format, ... );

int fwscanf( FILE *stream, const wchar_t *format, ... );

int fwscanf( FILE *restrict stream,
             const wchar_t *restrict format, ... );

int swscanf( const wchar_t *buffer, const wchar_t *format, ... );

int swscanf( const wchar_t *restrict buffer,
             const wchar_t *restrict format, ... );

int wscanf_s( const wchar_t *restrict format, ...);

int fwscanf_s( FILE *restrict stream,
               const wchar_t *restrict format, ...);

int swscanf_s( const wchar_t *restrict s,
               const wchar_t *restrict format, ...);

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

Параметры

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

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

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

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

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

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

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

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

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

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

Возвращаемое значение

Пример

#include <stdio.h>
#include <wchar.h>
#include <string.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

Справочная информация

• Стандарт 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)

См. также