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...>&& initial_args) →  scan_result_type< Source, Args... > -> auto
template <typename T, std::enable_if_t<detail::is_scan_int_type<T>>* = nullptr>
auto scan_int(std::string_view source, int base = 10) →  scan_result_type< std::string_view, T > -> auto
template <typename T, std::enable_if_t<detail::is_scan_int_type<T>>* = nullptr>
auto scan_int_exhaustive_valid(std::string_view source) →  T -> 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 initial_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...>&& initial_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, std::enable_if_t<detail::is_scan_int_type<T>>* = nullptr>
auto scan_int(std::string_view source, int base = 10) →  scan_result_type< std::string_view, T >

Fast integer reading.

Quickly reads an integer from a std::string_view. Skips preceding whitespace.

Reads in the specified base, allowing a base prefix. Set base to 0 to detect the base from the input. base must either be 0, or in range [2, 36].

template <typename T, std::enable_if_t<detail::is_scan_int_type<T>>* = nullptr>
auto scan_int_exhaustive_valid(std::string_view source) →  T

Very fast integer reading.

Quickly reads an integer from a std::string_view.

Be very careful when using this one! Its speed comes from some very heavy assumptions about the validity of the input:

  • source must not be empty.
  • source contains nothing but the integer: no leading or trailing whitespace, no extra junk. Leading - is allowed for signed types, no + is allowed.
  • The parsed value does not overflow.
  • The input is a valid base-10 integer. Breaking these assumptions will lead to UB.

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 initial_value) →  scan_result_type< Source, T >

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