std::vscanf, std::vfscanf, std::vsscanf

int vscanf( const char* format, std::va_list vlist );

int vfscanf( std::FILE* stream, const char* format, std::va_list vlist );

int vsscanf( const char* buffer, const char* format, std::va_list vlist );

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

Параметры

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

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

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

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

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

Спецификаторы преобразования lc, ls, и l[ выполняют преобразование многобайтовых символов в символы расширенной кодировки, как если бы вызывали mbrtowc с объектом mbstate_t, инициализированным нулём перед преобразованием первого символа.

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

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

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

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

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

Количество успешно прочитанных аргументов или EOF в случае ошибки.

Примечания

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

Пример

#include <cstdarg>
#include <cstdio>
#include <iostream>
#include <stdexcept>
 
void checked_sscanf(int count, const char* buf, const char *fmt, ...)
{
    std::va_list ap;
    va_start(ap, fmt);
    if (std::vsscanf(buf, fmt, ap) != count)
        throw std::runtime_error("parsing error");
    va_end(ap);
}
 
int main()
{
    try
    {
        int n, m;
        std::cout << "Parsing '1 2'... ";
        checked_sscanf(2, "1 2", "%d %d", &n, &m);
        std::cout << "success\n";
        std::cout << "Parsing '1 a'... ";
        checked_sscanf(2, "1 a", "%d %d", &n, &m);
        std::cout << "success\n";
    }
    catch (const std::exception& e)
    {
        std::cout << e.what() << '\n';
    }
}

Parsing '1 2'... success
Parsing '1 a'... parsing error

См. также