README.md
1
2[](https://en.wikipedia.org/wiki/C%2B%2B#Standardization)
3[](http://www.boost.org/LICENSE_1_0.txt)
4[](https://travis-ci.org/tcbrindle/span)
5[](https://ci.appveyor.com/project/tcbrindle/span/branch/master)
6[](https://godbolt.org/z/-vlZZR)
7
8`std::span` implementation for C++11 and later
9==============================================
10
11This repository contains a single-header implementation of C++20's `std::span`,
12conforming to the C++20 committee draft.
13It is compatible with C++11, but will use newer language features if they
14are available.
15
16It differs from the implementation in the [Microsoft GSL](https://github.com/Microsoft/GSL/)
17in that it is single-header and does not depend on any other GSL facilities. It
18also works with C++11, while the GSL version requires C++14.
19
20Usage
21-----
22
23The recommended way to use the implementation simply copy the file `span.hpp`
24from `include/tcb/` into your own sources and `#include` it like
25any other header. By default, it lives in namespace `tcb`, but this can be
26customised by setting the macro `TCB_SPAN_NAMESPACE_NAME` to an appropriate string
27before `#include`-ing the header -- or simply edit the source code.
28
29The rest of the repository contains testing machinery, and is not required for
30use.
31
32Compatibility
33-------------
34
35This implementation requires a conforming C++11 (or later) compiler, and is tested as far
36back as GCC 5, Clang 3.5 and MSVC 2015 Update 3. Older compilers may work, but this is not guaranteed.
37
38Documentation
39-------------
40
41Documentation for `std::span` is available [on cppreference](https://en.cppreference.com/w/cpp/container/span).
42
43Implementation Notes
44--------------------
45
46### Bounds Checking ###
47
48This implementation of `span` includes optional bounds checking, which is handled
49either by throwing an exception or by calling `std::terminate()`.
50
51The default behaviour with C++14 and later is to check the macro `NDEBUG`:
52if this is set, bounds checking is disabled. Otherwise, `std::terminate()` will
53be called if there is a precondition violation (i.e. the same behaviour as
54`assert()`). If you wish to terminate on errors even if `NDEBUG` is set, define
55the symbol `TCB_SPAN_TERMINATE_ON_CONTRACT_VIOLATION` before `#include`-ing the
56header.
57
58Alternatively, if you want to throw on a contract violation, define
59`TCB_SPAN_THROW_ON_CONTRACT_VIOLATION`. This will throw an exception of an
60implementation-defined type (deriving from `std::logic_error`), allowing
61cleanup to happen. Note that defining this symbol will cause the checks to be
62run even if `NDEBUG` is set.
63
64Lastly, if you wish to disable contract checking even in debug builds,
65`#define TCB_SPAN_NO_CONTRACT_CHECKING`.
66
67Under C++11, due to the restrictions on `constexpr` functions, contract checking
68is disabled by default even if `NDEBUG` is not set. You can change this by
69defining either of the above symbols, but this will result in most of `span`'s
70interface becoming non-`constexpr`.
71
72### `constexpr` ###
73
74This implementation is fully `constexpr` under C++17 and later. Under earlier
75versions, it is "as `constexpr` as possible".
76
77Note that even in C++17, it is generally not possible to declare a `span`
78as non-default constructed `constexpr` variable, for the same reason that you
79cannot form a `constexpr` pointer to a value: it involves taking the address of
80a compile-time variable in a way that would be visible at run-time.
81You can however use a `span` freely in a `constexpr` function. For example:
82
83```cpp
84// Okay, even in C++11
85constexpr std::ptrdiff_t get_span_size(span<const int> span)
86{
87 return span.size();
88}
89
90constexpr int arr[] = {1, 2, 3};
91constexpr auto size = get_span_size(arr); // Okay
92constexpr span<const int> span{arr}; // ERROR -- not a constant expression
93constexpr const int* p = arr; // ERROR -- same
94```
95
96Constructor deduction guides are provided if the compiler supports them. For
97older compilers, a set of `make_span()` functions are provided as an extension
98which use the same logic, for example:
99
100 ```cpp
101 constexpr int c_array[] = {1, 2, 3};
102 std::array<int, 3> std_array{1, 2, 3};
103 const std::vector<int> vec{1, 2, 3};
104
105 auto s1 = make_span(c_array); // returns span<const int, 3>
106 auto s2 = make_span(std_array); // returns span<int, 3>
107 auto s3 = make_span(vec); // returns span<const int, dynamic_extent>
108 ```
109
110Alternatives
111------------
112
113* [Microsoft/GSL](https://github.com/Microsoft/GSL): The original `span` reference
114 implementation from which `std::span` was born.
115
116* [martinmoene/span_lite](https://github.com/martinmoene/span-lite): An
117 alternative implementation which offers C++98 compatibility.
118
119
){kind=link}
){kind=link}
){kind=link}
){kind=link}