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.

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

#include <scn/scan.h>
#include <print> // for std::print, 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 2.0 of the library. For version 1.1, see https://v1.scnlib.dev/.

An introductory guide to the library can be found at Guide. Instructions for migrating to v2.0 from v1.1 can be found at Migration Guide v1.1 -> v2.0.

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         v2.0.2
        GIT_SHALLOW     TRUE
)
FetchContent_MakeAvailable(scn)

# ...

target_link_libraries(my_program scn::scn)

Dependencies

scnlib internally depends on fast_float and simdutf.

By default, the CMake machinery automatically fetches, builds, and links these libraries through FetchContent. These libraries are only used in the implementation, and they are not visible to the users of the library.

Alternatively, by setting the CMake options SCN_USE_EXTERNAL_FAST_FLOAT or SCN_USE_EXTERNAL_SIMDUTF to ON, these libraries are searched for using find_package. Use these options, if you already have these libraries 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.

If your standard library doesn't have an available C++20 <ranges> implementation, a single-header version of NanoRange is also bundled with the library, inside the directory include/scn/external.

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

Library dependencies
DependencyVersionRequired

Information

simdutf>= 4.0.0

Downloaded by default with FetchContent, controlled with SCN_USE_EXTERNAL_SIMDUTF.
If not using CMake, must be manually linked with your final build.

fast_float>= 6.0.0

Header only. Downloaded by default with FetchContent, controlled with SCN_USE_EXTERNAL_FAST_FLOAT.

Boost.RegexN/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 and simdutf. If you're not using CMake, you'll need to download and build these libraries yourself, and link them with your final binary. Note, that fast_float is a header-only library, so there's nothing to link, but simdutf isn't.

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 -Ipath-to-simdutf
$ ar rcs libscn.a *.o

libscn.a can then be linked, as usual, with your project. Don't forget to also include simdutf to be linked.

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

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
OptionCMakeCLIDefault

Description

SCN_DISABLE_REGEXOFF

Disable regular expression support

SCN_REGEX_BACKEND⚠️"std"

Regular expression backend to use<br>(use integer values on the command line)
Values: "std"=0, "Boost"=1,"re2"=2`

SCN_REGEX_BOOST_USE_ICUOFF

Use the ICU when using the Boost regex backend
(requires SCN_REGEX_BACKEND to be Boost/1)

SCN_DISABLE_IOSTREAMOFF

Disable everything related to iostreams

SCN_DISABLE_LOCALEOFF

Disable everything related to C++ locales (std::locale)

SCN_DISABLE_FROM_CHARSOFF

Disable usage of (falling back on) std::from_chars when scanning floating-point values

SCN_DISABLE_STRTODOFF

Disable usage of (falling back on) std::strtod when scanning floating-point values

SCN_DISABLE_(TYPE)OFFDisable support for a specific type

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

CMake build type configuration
OptionCMakeCLIDefault

Description

SCN_USE_EXTERNAL_SIMDUTFOFF

Use find_package to get simdutf, instead of CMake FetchContent

SCN_USE_EXTERNAL_FAST_FLOATOFF

Use find_package to get fast_float, instead of CMake FetchContent

SCN_TESTSENABLE_FULL

Enable building of tests

SCN_DOCSENABLE_FULL

Enable building of documentation
(scn_docs target, requires poxy)

SCN_EXAMPLESENABLE_FULL

Enable building of examples

SCN_INSTALLENABLE_FULL

Enable install target

SCN_BENCHMARKSENABLE_FULL

Enable building of (runtime) benchmarks

SCN_BENCHMARKS_BUILDTIMEENABLE_FULL

Enable build-time benchmark targets

SCN_BENCHMARKS_BINARYSIZEENABLE_FULL

Enable binary-size benchmark targets

SCN_FUZZINGENABLE_FULL

Enable building of fuzzer targets

SCN_PEDANTICENABLE_FULL

Enable pedantic compilation flags (mostly warnings)

SCN_WERRORSCN_CI

Enable warnings-as-errors

SCN_COVERAGEOFF

Enable code coverage reporting

SCN_USE_NATIVE_ARCHOFF

Add -march=native

SCN_USE_HASWELL_ARCHOFF

Add -march=haswell
(used for benchmarking to get a more recent, but reasonable architecture)

SCN_USE_ASAN, _UBSAN, _MSANOFFEnable 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.