snncpp

A modern, safer alternative to the C++ Standard Library (for Linux/BSD).

Features

• Immutable and mutable array_view, including [c]strview.
• Safe and efficient string parsing with ranges (example).
• Strings with and without Small String Optimization (str/strbuf).
• Vector with optional small capacity and trivially relocatable optimization (vec).
• Date and time library with IANA time zone database (time/).
• result/optional with reference support.
• .range()/.view(...) member functions to discourage the use of iterators.
• Validation member functions like .all(...) and .any(...) on iterable containers.
• Safe integral class and a decimal class with a static/dynamic scale (num/).
• Command line options parsing (env/).
• Filesystem library (file/).
• Fast JSON parsing (json/).
• Go-like build-tool with fuzzing support.
• And much more...

Goals

• Safe by default or even harder to shoot yourself in the foot (see Safety).
• Readable and well tested code.
• High performance without sacrificing on the points above.

Non-goals

• Replacing the entire C++ Standard Library. This library uses the C++ Standard Library throughout where appropriate, e.g. type traits, concepts, algorithms and utility functions like std::move.

Requirements

• C++20
• 64-bit

Officially supported platforms

This library currently targets POSIX and is developed and tested on:

Limitations

• No wide character support (by design).
• No Windows support (most code outside of file::, random:: and process:: should work)[^contribwelcome].
• No grapheme support[^contribwelcome].
• No big-endian support[^contribwelcome].

[^contribwelcome]: Contributions welcome.

Overview

Build tool

The snncpp Go-like build-tool can build C++ projects that follow the same naming convention and directory structure as snn-core. It understands simple preprocessing directives (example) and will link with libraries listed in #include comments (example).

The build-tool executable is snn (by default), run it without any arguments to see what commands are available:

$ snn
Usage: snn <command> [arguments]

Commands:
build   Build one or more applications
gen     Generate a makefile for one or more applications
run     Build and run a single application with optional arguments
runall  Build and run one or more applications

For more information run a command without arguments, e.g.:
snn build

For example, to run all unit tests in the pair/ subdirectory:

$ snn runall --verbose pair/*.test.cc
clang++ --config ./.clang -iquote ../ -c -o pair/common.test.o pair/common.test.cc
clang++ --config ./.clang -o pair/common.test pair/common.test.o -L/usr/local/lib/
clang++ --config ./.clang -iquote ../ -c -o pair/core.test.o pair/core.test.cc
clang++ --config ./.clang -o pair/core.test pair/core.test.o -L/usr/local/lib/
./pair/common.test
./pair/core.test

Getting started

The Getting started guide for the build-tool shows how to use snn-core.

Safety

Overview

• Ranges and views are preferred over iterators.
• Views will not bind to temporaries by default.
• String ranges (c[strrng]) make string parsing/validation safe and very efficient (example).
• Hidden undefined behavior (UB) is minimized, e.g. .front() returns an optional and .front(promise::not_empty) explicitly shows that we know that the container is not empty.
• The use of operators like *expr (indirection/dereference), expr-> (member access via pointer) and expr[...] (subscript) in user code should be rare.
• No uninitialized containers (unless explicitly asked for).
• not_null and byte_size wrappers for low level memory operations.
• Consistent naming, e.g. .size() for byte size and .count() for element count.
• .size() is only available when sizeof(value_type) == 1, .byte_size() is always available (on contiguous containers).
• No silent narrowing, e.g. .value_or(...).
• Consistent brace initialization.

Promises

Promise tags are used to:

• Prevent misuse and differentiate constructors, e.g. promise::has_capacity, promise::is_sorted and promise::null_terminated.
• Select a different overload, e.g. .value() throws and .value(promise::has_value) asserts.
• Select a more performant overload, e.g. promise::no_overlap.
• Bypass expensive checks, e.g. promise::is_utf8.

Promises are not used when there is an implicit promise that can be checked with the snn_should() macro, for example:

• Wrapping a pointer with not_null.
• Wrapping an integral with not_zero.
• Wrapping functions, e.g. ascii::as_lower() and json::stream::as_*().

Promises are not used when the intent is clear and contained in a single statement, even if the arguments can't be validated, for example:

• Constructing an object T from a data pointer and a size T{data, size}.
• Copying memory with mem::raw::copy(...).
• Reading a fixed byte count from a pointer with mem::raw::load<Int>(...).

A promise is recommended when a static count is part of the type, e.g. array_view<..., Count>. Here T{data} is error prone if the count isn't included in the statement, whereas T{data, promise::has_capacity} is less so.

Assertions

Compiling with the snn_assert() macro disabled is not recommended, especially for public production builds.

If NDEBUG is defined as a macro name then snn_assert() does nothing (optimized build or not). In non-optimized builds snn_assert() is another name for assert(). In optimized builds snn_assert() simply calls __builtin_trap() if the condition is false.

In non-optimized builds snn_should() is another name for snn_assert(). In optimized builds snn_should() does nothing.

Checked with snn_assert():

• Promises where the check isn't expensive or is easily optimized away. Example: .at(index, promise::within_bounds) or .front(promise::not_empty).

Checked in non-optimized builds with snn_should():

• Promises where the check is expensive or not easily optimized away.
• not_null & not_zero wrappers.
• as_*() functions, where there is an implicit promise that the value is valid.

Never checked:

• Iterator invalidation.
• array_view<T, ...> invalidation.

Using sanitizers in development help to catch bugs that this library can't protect against. The build-tool has a --sanitize option that enables sanitizers.

Internal audits

Assumption: Sane types

It is assumed that all types are "sane":

• If a type is copy constructible it must also be move constructible.
• If a type is copy assignable it must also be move assignable.
• If a type is move constructible it must also be nothrow move constructible.
• If a type is move assignable it must also be nothrow move assignable.

This can be checked with the sane concept, but is not enforced. The worst thing that can happen if a type is not "sane" is that a function with a noexcept specifier throws and std::terminate() is called.

Assumption: 57-bit virtual address space

It is assumed that the largest addressable memory block is always less than 128 PiB (57-bit virtual address space). 128 PiB is less than constant::limit<usize>::max / 100.

This means that code like the following could never overflow:

auto decode(const cstrview s)
{
    const usize decoded_size = s.size() * 4;
    ...
}

Code like the following could theoretically overflow:

auto decode(const cstrview s)
{
    const usize decoded_size = s.size() * 200;
    ...
}

A comment that includes the string "57-bit-virtual-address-space" should be added everywhere this assumption is made.

Naming conventions

All identifiers should be in snake_case with the following exceptions:

• Template parameters should be in upper CamelCase (capitalized first letter). Example: I, Int, UInt or UnsignedInt.
• Type declarations and constexpr variables that directly depend on template parameters can also be in CamelCase. Example: using UInt = std::make_unsigned_t<Int>.
• Private/protected member functions and variables should have an underscore suffix. Example: value_, names_ or error_count_.
• If a reserved keyword can't be avoided or if it's simply the best name for an identifier, it must have an underscore prefix. Example: fn::_not, html::element::type::_template or http::method::_delete.
• Function-like macros should be lowercase with "snn_" prefix. Example: snn_assert() or snn_should().
• Macro constants should be uppercase with "SNN_" prefix. Example: SNN_ASSERT_BOOL or SNN_INT128_BOOL.

Documentation

Generated API documentation is planned. Until then the code itself (which is pretty readable outside of the detail namespace) and examples/unit tests should hopefully be enough to use this library.

License

See LICENSE.md. Copyright © 2022 Mikael Simonsson.