`std::span` implementation for C++11 and later

This repository contains a single-header implementation of C++20’s std::span,
conforming to the C++20 committee draft.
It is compatible with C++11, but will use newer language features if they
are available.

It differs from the implementation in the Microsoft GSL
in that it is single-header and does not depend on any other GSL facilities. It
also works with C++11, while the GSL version requires C++14.

Usage

The recommended way to use the implementation simply copy the file span.hpp
from include/tcb/ into your own sources and #include it like
any other header. By default, it lives in namespace tcb, but this can be
customised by setting the macro TCB_SPAN_NAMESPACE_NAME to an appropriate string
before #include-ing the header — or simply edit the source code.

The rest of the repository contains testing machinery, and is not required for
use.

Compatibility

This implementation requires a conforming C++11 (or later) compiler, and is tested as far
back as GCC 5, Clang 3.5 and MSVC 2015 Update 3. Older compilers may work, but this is not guaranteed.

Documentation

Documentation for std::span is available on cppreference.

Implementation Notes

Bounds Checking

This implementation of span includes optional bounds checking, which is handled
either by throwing an exception or by calling std::terminate().

The default behaviour with C++14 and later is to check the macro NDEBUG:
if this is set, bounds checking is disabled. Otherwise, std::terminate() will
be called if there is a precondition violation (i.e. the same behaviour as
assert()). If you wish to terminate on errors even if NDEBUG is set, define
the symbol TCB_SPAN_TERMINATE_ON_CONTRACT_VIOLATION before #include-ing the
header.

Alternatively, if you want to throw on a contract violation, define
TCB_SPAN_THROW_ON_CONTRACT_VIOLATION. This will throw an exception of an
implementation-defined type (deriving from std::logic_error), allowing
cleanup to happen. Note that defining this symbol will cause the checks to be
run even if NDEBUG is set.

Lastly, if you wish to disable contract checking even in debug builds,
#define TCB_SPAN_NO_CONTRACT_CHECKING.

Under C++11, due to the restrictions on constexpr functions, contract checking
is disabled by default even if NDEBUG is not set. You can change this by
defining either of the above symbols, but this will result in most of span‘s
interface becoming non-constexpr.

`constexpr`

This implementation is fully constexpr under C++17 and later. Under earlier
versions, it is “as constexpr as possible”.

Note that even in C++17, it is generally not possible to declare a span
as non-default constructed constexpr variable, for the same reason that you
cannot form a constexpr pointer to a value: it involves taking the address of
a compile-time variable in a way that would be visible at run-time.
You can however use a span freely in a constexpr function. For example:

// Okay, even in C++11
constexpr std::ptrdiff_t get_span_size(span<const int> span)
{
    return span.size();
}
constexpr int arr[] = {1, 2, 3};
constexpr auto size = get_span_size(arr); // Okay
constexpr span<const int> span{arr}; // ERROR -- not a constant expression
constexpr const int* p = arr; // ERROR -- same

Constructor deduction guides are provided if the compiler supports them. For
older compilers, a set of make_span() functions are provided as an extension
which use the same logic, for example:

   constexpr int c_array[] = {1, 2, 3};
   std::array<int, 3> std_array{1, 2, 3};
   const std::vector<int> vec{1, 2, 3};
   auto s1 = make_span(c_array);   // returns span<const int, 3>
   auto s2 = make_span(std_array); // returns span<int, 3>
   auto s3 = make_span(vec);       // returns span<const int, dynamic_extent>

Alternatives

Microsoft/GSL: The original span reference
implementation from which std::span was born.
martinmoene/span_lite: An
alternative implementation which offers C++98 compatibility.

std::span implementation for C++11 and later