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.
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.
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 for std::span is available on cppreference.
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.
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 -- sameConstructor 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>-
Microsoft/GSL: The original
spanreference implementation from whichstd::spanwas born. -
martinmoene/span_lite: An alternative implementation which offers C++98 compatibility.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent