Basic scanning API module

The core public-facing interface of the library.

The following functions use a format string syntax similar to that of std::format. See more at Format strings.

When these functions take a source as input, it must model the scannable_source concept. See more at Scannable sources.

Functions

template <typename... Args>
auto input(scan_format_string<std::FILE*, Args...> format) →  scan_result_type< std::FILE *, Args... > -> auto
template <typename... Args>
auto prompt(const char* msg, scan_format_string<std::FILE*, Args...> format) →  scan_result_type< std::FILE *, Args... > -> auto
template <typename... Args, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan(Source&& source, scan_format_string<Source, Args...> format) →  scan_result_type< Source, Args... > -> auto
template <typename... Args, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan(Source&& source, scan_format_string<Source, Args...> format, std::tuple<Args...>&& default_args) →  scan_result_type< Source, Args... > -> auto
template <typename T, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan_value(Source&& source) →  scan_result_type< Source, T > -> auto
template <typename T, typename Source, std::enable_if_t<detail::is_file_or_narrow_range<Source>>* = nullptr>
auto scan_value(Source&& source, T default_value) →  scan_result_type< Source, T > -> auto

Function documentation

template <typename... Args>
auto input(scan_format_string<std::FILE*, Args...> format) →  scan_result_type< std::FILE *, Args... >

Scan from stdin.

Equivalent to scn::scan<...>(stdin, ...).

auto result = scn::input<int>("{}");

template <typename... Args>
auto prompt(const char* msg, scan_format_string<std::FILE*, Args...> format) →  scan_result_type< std::FILE *, Args... >

Write msg to stdout, and call input<Args...>(format)

template <typename... Args, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan(Source&& source, scan_format_string<Source, Args...> format) →  scan_result_type< Source, Args... >

Scans Args... from source, according to the specifications given in the format string (format). Returns the resulting values in an object of type scan_result, alongside a subrange pointing to the unused input.

Example:

if (auto result = scn::scan<int>("123", "{}"))
    int value = result->value();

template <typename... Args, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan(Source&& source, scan_format_string<Source, Args...> format, std::tuple<Args...>&& default_args) →  scan_result_type< Source, Args... >

scan with explicitly supplied default values

Can be used, for example, for pre-allocating a scanned string:

std::string str;
str.reserve(64);

// As long as the read string fits in `str`,
// does not allocate
auto result = scn::scan<std::string>(source, "{}",
                                     {std::move(str)});
// Access the read string with result->value()

template <typename T, typename Source, typename = std::enable_if_t<detail::is_file_or_narrow_range<Source>>>
auto scan_value(Source&& source) →  scan_result_type< Source, T >

scan a single value, with default options.

Essentially equivalent to: scn::scan<T>(source, "{}"), except it can skip parsing the format string, gaining performance.

template <typename T, typename Source, std::enable_if_t<detail::is_file_or_narrow_range<Source>>* = nullptr>
auto scan_value(Source&& source, T default_value) →  scan_result_type< Source, T >

scan a single value, with default options, and a default value.