scnlib

scnlib is a modern C++ library for scanning values. Think of it as a more C++-y scanf, or the inverse of {fmt} / std::format.

This library is the reference implementation of the ISO C++ standards proposal P1729 "Text Parsing".

The code lives over at GitHub, at https://github.com/eliaskosunen/scnlib.

#include <scn/scan.h>
#include <print> // for std::println, C++23

int main() {
    auto result = scn::scan<int, double>("42, 3.14", "{}, {}");
    if (result) {
        auto [first, second] = result->values();
        std::println("first: {}, second: {}", first, second);
        // Prints "first: 42, second: 3.14\n"
    }
}

About this documentation

This documentation is for the version 4.0 of the library. For other versions, see the dropdown in the upper right corner of the website. See Changelog for more.

An introductory guide to the library can be found at Guide. Answers to frequently asked questions are listed at FAQ.

The API documentation is organized into modules, that can be found under Modules, behind the link at the top of the page. It can be searched directly using the search function in the navbar, or by pressing the TAB key. The most important modules are probably:

Installation

scnlib uses CMake for building. If you're already using CMake for your project, integration is easy with find_package.

$ mkdir build
$ cd build
$ cmake ..
$ make -j
$ make install

# Find scnlib package
find_package(scn CONFIG REQUIRED)

# Target which you'd like to use scnlib
add_executable(my_program ...)
target_link_libraries(my_program scn::scn)

Another option would be usage through CMake's FetchContent module.

FetchContent_Declare(
        scn
        GIT_REPOSITORY  https://github.com/eliaskosunen/scnlib
        GIT_TAG         v4.0.1
        GIT_SHALLOW     TRUE
)
FetchContent_MakeAvailable(scn)

# ...

target_link_libraries(my_program scn::scn)

Dependencies

scnlib internally optionally depends on fast_float.

By default, the CMake machinery automatically fetches, builds, and links it with FetchContent. It's only used in the implementation, and it isn't visible to the users of the library.

Alternatively, by setting the CMake option SCN_USE_EXTERNAL_FAST_FLOAT to ON, fast_float is searched for using find_package. Use this option if you already have the library installed.

To enable support for regular expressions, a regex engine backend is required. The default option is to use std::regex, but an alternative can be picked by setting SCN_REGEX_BACKEND to Boost or re2 in CMake. These libraries are not downloaded with FetchContent, but must be found externally.

The tests and benchmarks described below depend on GTest and Google Benchmark, respectively. These libraries are also fetched with FetchContent, if necessary, controllable with SCN_USE_EXTERNAL_GTEST and SCN_USE_EXTERNAL_BENCHMARK, respectively.

Library dependencies
Dependency	Version	Required	Information
fast_float	`>= 5.0.0`	⚠️	Required if `SCN_DISABLE_FAST_FLOAT` is `OFF`. Header only. Downloaded by default with `FetchContent`, controlled with `SCN_USE_EXTERNAL_FAST_FLOAT`.
Boost.Regex	N/A	⚠️	Required if `SCN_REGEX_BACKEND` is `Boost`. Must be available externally (not automatically downloaded).
re2	`>= 11.0.0`	⚠️	Required if `SCN_REGEX_BACKEND` is `re2`. Must be available externally (not automatically downloaded).

Tests and benchmarks

To build and run the tests and benchmarks for scnlib, clone the repository, and build it with CMake.

Building and running tests:

$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ make -j
$ ctest -j

Building and running the runtime performance benchmarks:

# create build directory like above
$ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON -DSCN_NATIVE_ARCH=ON ..
$ make -j

# disable CPU frequency scaling
$ sudo cpupower frequency-set --governor performance

# run the benchmark of your choosing
$ ./benchmark/runtime/integer/scn_int_bench

# re-enable CPU frequency scaling
$ sudo cpupower frequency-set --governor powersave

Without CMake

As mentioned above, the implementation of scnlib depends on fast_float. If you're not using CMake, you'll need to download it yourself, and make it available for the build. Since fast_float is a header-only library, it doesn't need to be built.

Headers for scnlib can be found from the include/ directory, and source files from the src/ directory.

Building and linking the library:

$ mkdir build
$ cd build
$ c++ -c -I../include/ ../src/*.cpp -Ipath-to-fast-float
$ ar rcs libscn.a *.o

libscn.a can then be linked, as usual, with your project.

# in your project
$ c++ ... -Lpath-to-scn/build -lscn

Note, that scnlib requires at least C++17, so --std=c++17 (or equivalent, or newer) may need to be included in the build flags.

Configuration

There are numerous flags that can be used to configure the build of the library. All of them can be set through CMake at library build time, and some of them directly on the compiler command line, as indicated on the tables below.

scnlib configuration options
Option	CMake	CLI	Default	Description
`SCN_DISABLE_FAST_FLOAT`	✅	✅	`OFF`	Disable external dependency on FastFloat. Using `ON` requires standard library support for floating-point `std::from_chars`.¹
`SCN_DISABLE_REGEX`	✅	✅	`OFF`	Disable regular expression support
`SCN_REGEX_BACKEND`	✅	⚠️	`"std"`	Regular expression backend to use (use integer values on the command line) Values: `"std"=0`, `"Boost"=1`, `"re2"=2`
`SCN_REGEX_BOOST_USE_ICU`	✅	✅	`OFF`	Use the ICU when using the Boost regex backend (requires `SCN_REGEX_BACKEND` to be `Boost`/`1`)
`SCN_DISABLE_IOSTREAM`	✅	✅	`OFF`	Disable everything related to iostreams
`SCN_DISABLE_LOCALE`	✅	✅	`OFF`	Disable everything related to C++ locales (`std::locale`)
`SCN_DISABLE_FROM_CHARS`	✅	✅	`OFF`	Disable usage of (falling back on) `std::from_chars` when scanning floating-point values
`SCN_DISABLE_STRTOD`	✅	✅	`OFF`	Disable usage of (falling back on) `std::strtod` when scanning floating-point values
`SCN_DISABLE_CHRONO`	✅	✅	`OFF`	Disable all `<chrono>` and `<ctime>` scanners
`SCN_DISABLE_(TYPE)`	✅	✅	`OFF`	Disable support for a specific type

¹: As on October 2024, std::from_chars with floating-point values is supported on libstdc++ v11 and newer, and MSVC 19.24 (VS 2019 16.4) or newer. libc++ doesn't provide any support yet.

Below, ENABLE_FULL is true, if SCN_CI is set in CMake, or scnlib is built as the primary project.

CMake build type configuration
Option	CMake	CLI	Default	Description
`SCN_USE_EXTERNAL_FAST_FLOAT`	✅	❌	`OFF`	Use `find_package` to get fast_float, instead of CMake `FetchContent`
`SCN_USE_EXTERNAL_GTEST`	✅	❌	`OFF`	Use `find_package` to get GTest, instead of CMake `FetchContent`
`SCN_USE_EXTERNAL_BENCHMARK`	✅	❌	`OFF`	Use `find_package` to get Google Benchmark, instead of CMake `FetchContent`
`SCN_TESTS`	✅	❌	`ENABLE_FULL`	Enable building of tests
`SCN_DOCS`	✅	❌	`ENABLE_FULL`	Enable building of documentation (`scn_docs` target, requires `poxy`)
`SCN_EXAMPLES`	✅	❌	`ENABLE_FULL`	Enable building of examples
`SCN_INSTALL`	✅	❌	`ENABLE_FULL`	Enable `install` target
`SCN_BENCHMARKS`	✅	❌	`ENABLE_FULL`	Enable building of (runtime) benchmarks
`SCN_BENCHMARKS_BUILDTIME`	✅	❌	`ENABLE_FULL`	Enable build-time benchmark targets
`SCN_BENCHMARKS_BINARYSIZE`	✅	❌	`ENABLE_FULL`	Enable binary-size benchmark targets
`SCN_FUZZING`	✅	❌	`ENABLE_FULL`	Enable building of fuzzer targets
`SCN_PEDANTIC`	✅	❌	`ENABLE_FULL`	Enable pedantic compilation flags (mostly warnings)
`SCN_WERROR`	✅	❌	`SCN_CI`	Enable warnings-as-errors
`SCN_COVERAGE`	✅	❌	`OFF`	Enable code coverage reporting
`SCN_USE_NATIVE_ARCH`	✅	❌	`OFF`	Add `-march=native`
`SCN_USE_HASWELL_ARCH`	✅	❌	`OFF`	Add `-march=haswell` (used for benchmarking to get a more recent, but reasonable architecture)
`SCN_USE_ASAN`, `_UBSAN`, `_MSAN`	✅	❌	`OFF`	Enable sanitizers

License

The library is open source, licensed under the Apache License, version 2.0.
Copyright (c) 2017 Elias Kosunen
For further details, see the LICENSE file in the repository.