feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Utils: Exchange std::span implementation

Browse Source 
The old implementation was not supporting iterators. Which made it a
little bit complicated to use it together with algorithms.

Change-Id: I99cf43dffb4bcb83a953ca1c68ebc65722142ad9
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Reviewed-by: Qt CI Patch Build Bot <ci_patchbuild_bot@qt.io>
This commit is contained in:
Marco Bubke
2023-09-05 16:32:58 +02:00
parent 14b96533fc
commit b8f97713c5
5 changed files with 2289 additions and 523 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -423,11 +423,11 @@ we thank the authors who made this possible:
committee draft. It is compatible with C++11, but will use newer language
features if they are available.
https://github.com/tcbrindle/span
https://github.com/martinmoene/span-lite
QtCreator/src/libs/3rdparty/span
Copyright Tristan Brindle, 2018
Copyright 2018-2021 Martin Moene
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

4
doc/qtcreator/src/overview/creator-acknowledgements.qdoc
View File

@@ -368,7 +368,7 @@
the C++20 committee draft. It is compatible with C++11, but will use
newer language features if they are available.
Copyright Tristan Brindle, 2018
Copyright 2018-2021 Martin Moene
Distributed under the \l {http://boost.org/LICENSE_1_0.txt}
{Boost Software License, Version 1.0}.
@@ -376,7 +376,7 @@
The source code can be found here:
\list
\li \l{https://github.com/tcbrindle/span}
\li \l{https://github.com/martinmoene/span-lite}
\li QtCreator/src/libs/3rdparty/span
\li \l{https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/src/libs/3rdparty/span}
\endlist

641
src/libs/3rdparty/span/README.md vendored
View File

@@ -1,118 +1,557 @@
<a id="top"></a>
# span lite: A single-file header-only version of a C++20-like span for C++98, C++11 and later
[![Standard](https://img.shields.io/badge/c%2B%2B-11/14/17/20-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization)
[![License](https://img.shields.io/badge/license-BSL-blue.svg)](http://www.boost.org/LICENSE_1_0.txt)
[![Build Status](https://travis-ci.org/tcbrindle/span.svg?branch=master)](https://travis-ci.org/tcbrindle/span)
[![Build status](https://ci.appveyor.com/api/projects/status/ow7cj56s108fs439/branch/master?svg=true)](https://ci.appveyor.com/project/tcbrindle/span/branch/master)
[![Try it on godbolt online](https://img.shields.io/badge/on-godbolt-blue.svg)](https://godbolt.org/z/-vlZZR)
[![Language](https://img.shields.io/badge/C%2B%2B-98/11/14/17/20-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) [![License](https://img.shields.io/badge/license-BSL-blue.svg)](https://opensource.org/licenses/BSL-1.0) [![Build Status](https://github.com/martinmoene/span-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/martinmoene/span-lite/actions/workflows/ci.yml) [![Build status](https://ci.appveyor.com/api/projects/status/1ha3wnxtam547m8p?svg=true)](https://ci.appveyor.com/project/martinmoene/span-lite) [![Version](https://badge.fury.io/gh/martinmoene%2Fspan-lite.svg)](https://github.com/martinmoene/span-lite/releases) [![download](https://img.shields.io/badge/latest-download-blue.svg)](https://github.com/martinmoene/span-lite/blob/master/include/nonstd/span.hpp) [![Conan](https://img.shields.io/badge/on-conan-blue.svg)](https://conan.io/center/span-lite) [![Try it on wandbox](https://img.shields.io/badge/on-wandbox-blue.svg)](https://wandbox.org/permlink/venR3Ko2Q4tlvcVk) [![Try it on godbolt online](https://img.shields.io/badge/on-godbolt-blue.svg)](https://godbolt.org/z/htwpnb)
`std::span` implementation for C++11 and later
==============================================
**Contents**
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.
- [Example usage](#example-usage)
- [In a nutshell](#in-a-nutshell)
- [License](#license)
- [Dependencies](#dependencies)
- [Installation and use](#installation-and-use)
- [Synopsis](#synopsis)
- [Reported to work with](#reported-to-work-with)
- [Building the tests](#building-the-tests)
- [Other implementations of span](#other-implementations-of-span)
- [Notes and references](#notes-and-references)
- [Appendix](#appendix)
It differs from the implementation in the [Microsoft GSL](https://github.com/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](https://en.cppreference.com/w/cpp/container/span).
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:
## Example usage
```cpp
// Okay, even in C++11
constexpr std::ptrdiff_t get_span_size(span<const int> span)
#include "nonstd/span.hpp"
#include <array>
#include <vector>
#include <iostream>
std::ptrdiff_t size( nonstd::span<const int> spn )
{
return span.size();
return spn.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
int main()
{
int arr[] = { 1, };
std::cout <<
"C-array:" << size( arr ) <<
" array:" << size( std::array <int, 2>{ 1, 2, } ) <<
" vector:" << size( std::vector<int >{ 1, 2, 3, } );
}
```
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:
### Compile and run
```cpp
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>
```bash
prompt> g++ -std=c++11 -Wall -I../include -o 01-basic.exe 01-basic.cpp && 01-basic.exe
C-array:1 array:2 vector:3
```
Alternatives
------------
## In a nutshell
* [Microsoft/GSL](https://github.com/Microsoft/GSL): The original `span` reference
implementation from which `std::span` was born.
**span lite** is a single-file header-only library to provide a bounds-safe view for sequences of objects. The library provides a [C++20-like span](http://en.cppreference.com/w/cpp/container/span) for use with C++98 and later. If available, `std::span` is used, unless [configured otherwise](#configuration). *span-lite* can detect the presence of [*byte-lite*](https://github.com/martinmoene/byte-lite) and if present, it provides `as_bytes()` and `as_writable_bytes()` also for C++14 and earlier.
* [martinmoene/span_lite](https://github.com/martinmoene/span-lite): An
alternative implementation which offers C++98 compatibility.
**Features and properties of span lite** are ease of installation (single header), freedom of dependencies other than the standard library. To compensate for the class template argument deduction that is missing from pre-C++17 compilers, `nonstd::span` can provide `make_span` functions. See [configuration](#configuration).
## License
*span lite* is distributed under the [Boost Software License](https://github.com/martinmoene/span-lite/blob/master/LICENSE.txt).
## Dependencies
*span lite* has no other dependencies than the [C++ standard library](http://en.cppreference.com/w/cpp/header).
## Installation and use
*span lite* is a single-file header-only library. Put `span.hpp` in the [include](include) folder directly into the project source tree or somewhere reachable from your project.
## Synopsis
**Contents**
[Documentation of `std::span`](#documentation-of-stdspan)
[Later additions](#later-additions)
[Non-standard extensions](#non-standard-extensions)
[Configuration](#configuration)
## Documentation of `std::span`
Depending on the compiler and C++-standard used, `nonstd::span` behaves less or more like `std::span`. To get an idea of the capabilities of `nonstd::span` with your configuration, look at the output of the [tests](test/span.t.cpp), issuing `span-main.t --pass @`. For `std::span`, see its [documentation at cppreference](http://en.cppreference.com/w/cpp/container/span).
## Later additions
### `back()` and `front()`
*span lite* can provide `back()` and `front()` member functions for element access. See the table below and section [configuration](#configuration).
## Non-standard extensions
### Construct from std::initializer_list (p2447)
*span lite* can provide construction from a std::initializer_list<> as a constant set of values as proposed in [p2447](https://wg21.link/p2447). See the table below and section [configuration](#configuration).
### Construct from container
To construct a span from a container with compilers that cannot constrain such a single-parameter constructor to containers, *span lite* provides a constructor that takes an additional parameter of type `with_container_t`. Use `with_container` as value for this parameter. See the table below and section [configuration](#configuration).
### Construct from `std::array` with const data
*span lite* can provide construction of a span from a `std::array` with const data. See the table below and section [configuration](#configuration).
### `operator()`
*span lite* can provide member function call `operator()` for element access. It is equivalent to `operator[]` and has been marked `[[deprecated]]`. Its main purpose is to provide a migration path.
### `at()`
*span lite* can provide member function `at()` for element access. Unless exceptions have been disabled, `at()` throws std::out_of_range if the index falls outside the span. With exceptions disabled, `at(index_t)` delegates bounds checking to `operator[](index_t)`. See the table below and sections [configuration](#configuration) and [disable exceptions](#disable-exceptions).
### `swap()`
*span lite* can provide a `swap()`member function. See the table below and section [configuration](#configuration).
### `operator==()` and other comparison functions
*span lite* can provide functions to compare the content of two spans. However, C++20's span will not provide comparison and _span lite_ will omit comparison at default in the near future. See the table below and section [configuration](#configuration). See also [Revisiting Regular Types](#regtyp).
### `same()`
*span lite* can provide function `same()` to determine if two spans refer as identical spans to the same data via the same type. If `same()` is enabled, `operator==()` incorporates it in its comparison. See the table below and section [configuration](#configuration).
### `first()`, `last()` and `subspan()`
*span lite* can provide functions `first()`, `last()` and `subspan()` to avoid having to use the *dot template* syntax when the span is a dependent type. See the table below and section [configuration](#configuration).
### `make_span()`
*span lite* can provide `make_span()` creator functions to compensate for the class template argument deduction that is missing from pre-C++17 compilers. See the table below and section [configuration](#configuration).
### `byte_span()`
*span lite* can provide `byte_span()` creator functions to represent an object as a span of bytes. This requires the C++17 type `std::byte` to be available. See the table below and section [configuration](#configuration).
| Kind | std | Function or method |
|--------------------|------|--------------------|
| **Macro** |&nbsp;| macro **`span_FEATURE_WITH_INITIALIZER_LIST_P2447`** |
| **Constructor**<br>&nbsp; |&nbsp;| constexpr explicit **span**( std::initializer_list&lt;value_type> il ) noexcept<br>explicit for non-dynamic extent |
| &nbsp; |&nbsp;| &nbsp; |
| **Macro**<br>&nbsp;|&nbsp;| macro **`span_FEATURE_WITH_CONTAINER`**<br>macro **`span_FEATURE_WITH_CONTAINER_TO_STD`** |
| **Types** |&nbsp;| **with_container_t** type to disambiguate below constructors |
| **Objects** |&nbsp;| **with_container** value to disambiguate below constructors |
| **Constructors** |&nbsp;| macro **`span_FEATURE_CONSTRUCTION_FROM_STDARRAY_ELEMENT_TYPE`**|
| &nbsp; |&nbsp;| template&lt;class Container><br>constexpr **span**(with_container_t, Container & cont) |
| &nbsp; |&nbsp;| template&lt;class Container><br>constexpr **span**(with_container_t, Container const & cont) |
| &nbsp; |&nbsp;| &nbsp; |
| **Methods** |&nbsp;| macro **`span_FEATURE_MEMBER_CALL_OPERATOR`** |
| &nbsp; |&nbsp;| constexpr reference **operator()**(index_t idx) const<br>Equivalent to **operator[]**(), marked `[[deprecated]]` |
| &nbsp; |&nbsp;| &nbsp; |
| **Methods** |&nbsp;| macro **`span_FEATURE_MEMBER_AT`** |
| &nbsp; |&nbsp;| constexpr reference **at**(index_t idx) const<br>May throw std::out_of_range exception |
| &nbsp; |&nbsp;| &nbsp; |
| **Methods** |&nbsp;| macro **`span_FEATURE_MEMBER_BACK_FRONT`** (on since v0.5.0) |
| &nbsp; |&nbsp;| constexpr reference **back()** const noexcept |
| &nbsp; |&nbsp;| constexpr reference **front()** const noexcept |
| &nbsp; |&nbsp;| &nbsp; |
| **Method** |&nbsp;| macro **`span_FEATURE_MEMBER_SWAP`** |
| &nbsp; |&nbsp;| constexpr void **swap**(span & other) noexcept |
| &nbsp; |&nbsp;| &nbsp; |
| **Free functions** |&nbsp;| macro **`span_FEATURE_COMPARISON`** |
|<br><br>== != < > <= >= |&nbsp;| template&lt;class T1, index_t E1, class T2, index_t E2><br>constexpr bool<br>**operator==**( span<T1,E1> const & l, span<T2,E2> const & r) noexcept |
| &nbsp; |&nbsp;| &nbsp; |
| **Free function** |&nbsp;| macro **`span_FEATURE_SAME`** |
| &nbsp; |&nbsp;| template&lt;class T1, index_t E1, class T2, index_t E2><br>constexpr bool<br>**same**( span<T1,E1> const & l, span<T2,E2> const & r) noexcept |
| &nbsp; |&nbsp;| &nbsp; |
| **Free functions**<br>&nbsp;<br>&nbsp; |&nbsp;| macros **`span_FEATURE_NON_MEMBER_FIRST_LAST_SUB`**,<br>**`span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_SPAN`**,<br>**`span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_CONTAINER`** |
| &nbsp; |&nbsp;| &nbsp; |
| **Free functions** |&nbsp;| macro **`span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_SPAN`** |
| &nbsp; | &nbsp; | template&lt;extent_t Count, class T, extent_t Extent><br>constexpr span&lt;T,Count><br>**first**(span&lt;T,Extent> spn) |
| &nbsp; | &nbsp; | template&lt;class T, extent_t Extent ><br>constexpr span&lt;T><br>**first**(span&lt;T,Extent> spn, size_t count) |
| &nbsp; | &nbsp; | template&lt;extent_t Count, class T, extent_t Extent><br>constexpr span&lt;T,Count><br>**last**(span&lt;T,Extent> spn) |
| &nbsp; | &nbsp; | template&lt;class T, extent_t Extent ><br>constexpr span&lt;T><br>**last**(span&lt;T,Extent> spn, size_t count) |
| &nbsp; | &nbsp; | template&lt;size_t Offset, extent_t Count, class T, extent_t Extent><br>constexpr span&lt;T, Count><br>**subspan**(span&lt;T, Extent> spn) |
| &nbsp; | &nbsp; | template&lt;class T, extent_t Extent><br>constexpr span&lt;T><br>**subspan**( span&lt;T, Extent> spn, size_t offset, extent_t count = dynamic_extent) |
| &nbsp; |&nbsp;| &nbsp; |
| **Free functions** |&nbsp;| macro **`span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_CONTAINER`** |
| &nbsp; | >= C++11 | template&lt;extent_t Count, class T><br>constexpr auto<br>**first**(T & t) ->... |
| &nbsp; | >= C++11 | template&lt;class T><br>constexpr auto<br>**first**(T & t, index_t count) ->... |
| &nbsp; | >= C++11 | template&lt;extent_t Count, class T><br>constexpr auto<br>**last**(T & t) ->... |
| &nbsp; | >= C++11 | template&lt;class T><br>constexpr auto<br>**last**(T & t, extent_t count) ->... |
| &nbsp; | >= C++11 | template&lt;index_t Offset, extent_t Count = dynamic_extent, class T><br>constexpr auto<br>**subspan**(T & t) ->... |
| &nbsp; | >= C++11 | template&lt;class T><br>constexpr auto<br>**subspan**(T & t, index_t offset, extent_t count = dynamic_extent) ->... |
| &nbsp; | &nbsp; | &nbsp; |
| **Free functions**<br>&nbsp; |&nbsp;| macro **`span_FEATURE_MAKE_SPAN`**<br>macro **`span_FEATURE_MAKE_SPAN_TO_STD`** |
| &nbsp; | &nbsp; | template&lt;class T><br>constexpr span&lt;T><br>**make_span**(T \* first, T \* last) noexcept |
| &nbsp; | &nbsp; | template&lt;class T><br>constexpr span&lt;T><br>**make_span**(T \* ptr, index_t count) noexcept |
| &nbsp; | &nbsp; | template&lt;class T, size_t N><br>constexpr span&lt;T,N><br>**make_span**(T (&arr)[N]) noexcept |
| &nbsp; | >= C++11 | template&lt;class T, size_t N><br>constexpr span&lt;T,N><br>**make_span**(std::array&lt;T,N> & arr) noexcept |
| &nbsp; | >= C++11 | template&lt;class T, size_t N><br>constexpr span&lt;const T,N><br>**make_span**(std::array&lt;T,N > const & arr) noexcept |
| &nbsp; | >= C++11 | template&lt;class T><br>constexpr span&lt;T><br>**make_span**(std::initializer_list&lt;T> il) noexcept |
| &nbsp; | >= C++11 | template&lt;class Container><br>constexpr auto<br>**make_span**(Container & cont) -><br>&emsp;span&lt;typename Container::value_type> noexcept |
| &nbsp; | >= C++11 | template&lt;class Container><br>constexpr auto<br>**make_span**(Container const & cont) -><br>&emsp;span&lt;const typename Container::value_type> noexcept |
| &nbsp; | &nbsp; | template&lt;class Container><br>span&lt;typename Container::value_type><br>**make_span**( with_container_t, Container & cont ) |
| &nbsp; | &nbsp; | template&lt;class Container><br>span&lt;const typename Container::value_type><br>**make_span**( with_container_t, Container const & cont ) |
| &nbsp; | < C++11 | template&lt;class T, Allocator><br>span&lt;T><br>**make_span**(std::vector&lt;T, Allocator> & cont) |
| &nbsp; | < C++11 | template&lt;class T, Allocator><br>span&lt;const T><br>**make_span**(std::vector&lt;T, Allocator> const & cont) |
| &nbsp; | &nbsp; | &nbsp; |
| **Free functions** |&nbsp;| macro **`span_FEATURE_BYTE_SPAN`** |
| &nbsp; | >= C++11 | template&lt;class T><br>span&lt;T, sizeof(T)><br>**byte_span**(T & t) |
| &nbsp; | >= C++11 | template&lt;class T><br>span&lt;const T, sizeof(T)><br>**byte_span**(T const & t) |
## Configuration
### Tweak header
If the compiler supports [`__has_include()`](https://en.cppreference.com/w/cpp/preprocessor/include), *span lite* supports the [tweak header](https://vector-of-bool.github.io/2020/10/04/lib-configuration.html) mechanism. Provide your *tweak header* as `nonstd/span.tweak.hpp` in a folder in the include-search-path. In the tweak header, provide definitions as documented below, like `#define span_CONFIG_NO_EXCEPTIONS 1`.
### Standard selection macro
\-D<b>span\_CPLUSPLUS</b>=199711L
Define this macro to override the auto-detection of the supported C++ standard, if your compiler does not set the `__cplusplus` macro correctly.
### Select `std::span` or `nonstd::span`
At default, *span lite* uses `std::span` if it is available and lets you use it via namespace `nonstd`. You can however override this default and explicitly request to use `std::span` or span lite's `nonstd::span` as `nonstd::span` via the following macros.
-D<b>span\_CONFIG\_SELECT\_SPAN</b>=span_SPAN_DEFAULT
Define this to `span_SPAN_STD` to select `std::span` as `nonstd::span`. Define this to `span_SPAN_NONSTD` to select `nonstd::span` as `nonstd::span`. Default is undefined, which has the same effect as defining to `span_SPAN_DEFAULT`.
### Select extent type
-D<b>span_CONFIG_EXTENT_TYPE</b>=std::size_t
Define this to `std::ptrdiff_t` to use the signed type. The default is `std::size_t`, as in C++20 (since v0.7.0).
### Select size type
-D<b>span_CONFIG_SIZE_TYPE</b>=std::size_t
Define this to `std::ptrdiff_t` to use the signed type. The default is `std::size_t`, as in C++20 (since v0.7.0). Note `span_CONFIG_SIZE_TYPE` replaces `span_CONFIG_INDEX_TYPE` which is deprecated.
### Disable exceptions
-D<b>span_CONFIG_NO_EXCEPTIONS</b>=0
Define this to 1 if you want to compile without exceptions. If not defined, the header tries and detect if exceptions have been disabled (e.g. via `-fno-exceptions`). Disabling exceptions will force contract violation to use termination, see [contract violation macros](#contract-violation-response-macros). Default is undefined.
### Provide construction from std::initializer_list (p2447)
-D<b>span_FEATURE_WITH_INITIALIZER_LIST_P2447</b>=0
Define this to 1 to enable constructing a span from a std::initializer_list<> as a constant set of values. See proposal [p2447](https://wg21.link/p2447). Default is undefined.
### Provide construction using `with_container_t`
-D<b>span_FEATURE_WITH_CONTAINER</b>=0
Define this to 1 to enable constructing a span using `with_container_t`. Note that `span_FEATURE_WITH_CONTAINER` takes precedence over `span_FEATURE_WITH_CONTAINER_TO_STD`. Default is undefined.
-D<b>span_FEATURE_WITH_CONTAINER_TO_STD</b>=*n*
Define this to the highest C++ language version for which to enable constructing a span using `with_container_t`, like 98, 03, 11, 14, 17, 20. You can use 99 for inclusion with any standard, but prefer to use `span_FEATURE_WITH_CONTAINER` for this. Note that `span_FEATURE_WITH_CONTAINER` takes precedence over `span_FEATURE_WITH_CONTAINER_TO_STD`. Default is undefined.
### Provide construction from `std::array` with const data
-D<b>span_FEATURE_CONSTRUCTION_FROM_STDARRAY_ELEMENT_TYPE</b>=0
Define this to 1 to enable constructing a span from a std::array with const data. Default is undefined.
### Provide `operator()` member function
-D<b>span_FEATURE_MEMBER_CALL_OPERATOR</b>=0
Define this to 1 to provide member function `operator()`for element access. It is equivalent to `operator[]` and has been marked `[[deprecated]]`. Its main purpose is to provide a migration path. Default is undefined.
### Provide `at()` member function
-D<b>span_FEATURE_MEMBER_AT</b>=0
Define this to 1 to provide member function `at()`. Define this to 2 to include index and size in message of std::out_of_range exception. Default is undefined.
### Provide `back()` and `front()` member functions
-D<b>span_FEATURE_MEMBER_BACK_FRONT</b>=1 _(on since v0.5.0)_
Define this to 0 to omit member functions `back()` and `front()`. Default is undefined.
### Provide `swap()` member function
-D<b>span_FEATURE_MEMBER_SWAP</b>=0
Define this to 1 to provide member function `swap()`. Default is undefined.
### Provide `operator==()` and other comparison functions
-D<b>span_FEATURE_COMPARISON</b>=0
Define this to 1 to include the comparison functions to compare the content of two spans. C++20's span does not provide comparison and _span lite_ omits comparison from v0.7.0. Default is undefined.
### Provide `same()` function
-D<b>span_FEATURE_SAME</b>=0
Define this to 1 to provide function `same()` to test if two spans refer as identical spans to the same data via the same type. If `same()` is enabled, `operator==()` incorporates it in its comparison. Default is undefined.
### Provide `first()`, `last()` and `subspan()` functions
-D<b>span_FEATURE_NON_MEMBER_FIRST_LAST_SUB</b>=0
Define this to 1 to enable both `span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_SPAN` and `span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_CONTAINER`. Default is undefined.
-D<b>span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_SPAN</b>=0
Define this to 1 to provide functions `first()`, `last()` and `subspan()` that take a `span<>` (work with C++98). This implies `span_FEATURE_MAKE_SPAN` to provide functions `make_span()` that are required for this feature. Default is undefined.
-D<b>span_FEATURE_NON_MEMBER_FIRST_LAST_SUB_CONTAINER</b>=0
Define this to 1 to provide functions `first()`, `last()` and `subspan()` that take a compatible container (requires C++11). This implies `span_FEATURE_MAKE_SPAN` to provide functions `make_span()` that are required for this feature. Default is undefined.
### Provide `make_span()` functions
-D<b>span_FEATURE_MAKE_SPAN</b>=0
Define this to 1 to provide creator functions `nonstd::make_span()`. This feature is implied by using `span_FEATURE_NON_MEMBER_FIRST_LAST_SUB=1`. Note that `span_FEATURE_MAKE_SPAN` takes precedence over `span_FEATURE_MAKE_SPAN_TO_STD`. Default is undefined.
-D<b>span_FEATURE_MAKE_SPAN_TO_STD</b>=*n*
Define this to the highest C++ language version for which to provide creator functions `nonstd::make_span()`, like 98, 03, 11, 14, 17, 20. You can use 99 for inclusion with any standard, but prefer to use `span_FEATURE_MAKE_SPAN` for this. Note that `span_FEATURE_MAKE_SPAN` takes precedence over `span_FEATURE_MAKE_SPAN_TO_STD`. Default is undefined.
### Provide `byte_span()` functions
-D<b>span_FEATURE_BYTE_SPAN</b>=0
Define this to 1 to provide creator functions `nonstd::byte_span()`. Default is undefined.
### Contract violation response macros
*span-lite* provides contract violation response control as suggested in proposal [N4415](http://wg21.link/n4415).
\-D<b>span\_CONFIG\_CONTRACT\_LEVEL\_ON</b> (*default*)
Define this macro to include both `span_EXPECTS` and `span_ENSURES` in the code. This is the default case.
\-D<b>span\_CONFIG\_CONTRACT\_LEVEL\_OFF</b>
Define this macro to exclude both `span_EXPECTS` and `span_ENSURES` from the code.
\-D<b>span\_CONFIG_CONTRACT\_LEVEL\_EXPECTS\_ONLY</b>
Define this macro to include `span_EXPECTS` in the code and exclude `span_ENSURES` from the code.
\-D<b>span\_CONFIG\_CONTRACT\_LEVEL\_ENSURES\_ONLY</b>
Define this macro to exclude `span_EXPECTS` from the code and include `span_ENSURES` in the code.
\-D<b>span\_CONFIG\_CONTRACT\_VIOLATION\_TERMINATES</b> (*default*)
Define this macro to call `std::terminate()` on a contract violation in `span_EXPECTS`, `span_ENSURES`. This is the default case.
\-D<b>span\_CONFIG\_CONTRACT\_VIOLATION\_THROWS</b>
Define this macro to throw an exception of implementation-defined type that is derived from `std::runtime_exception` instead of calling `std::terminate()` on a contract violation in `span_EXPECTS` and `span_ENSURES`. See also [disable exceptions](#disable-exceptions).
Reported to work with
--------------------
The table below mentions the compiler versions *span lite* is reported to work with.
OS | Compiler | Where | Versions |
------------:|:-----------|:--------|:---------|
**GNU/Linux**| Clang/LLVM | Travis | 3.5.0, 3.6.2, 3.7.1, 3.8.0, 3.9.1, 4.0.1 |
&nbsp; | GCC | Travis | 5.5.0, 6.4.0, 7.3.0 |
**OS X** | ? | Local | ? |
**Windows** | Clang/LLVM | Local | 6.0.0 |
&nbsp; | GCC | Local | 7.2.0 |
&nbsp; | Visual C++<br>(Visual Studio)| Local | 8 (2005), 10 (2010), 11 (2012),<br>12 (2013), 14 (2015), 15 (2017) |
&nbsp; | Visual C++<br>(Visual Studio)| AppVeyor | 10 (2010), 11 (2012),<br>12 (2013), 14 (2015), 15 (2017) |
## Building the tests
To build the tests you need:
- [CMake](http://cmake.org), version 3.0 or later to be installed and in your PATH.
- A [suitable compiler](#reported-to-work-with).
The [*lest* test framework](https://github.com/martinmoene/lest) is included in the [test folder](test).
The following steps assume that the [*span lite* source code](https://github.com/martinmoene/span-lite) has been cloned into a directory named `./span-lite`.
1. Create a directory for the build outputs.
cd ./span-lite
md build && cd build
2. Configure CMake to use the compiler of your choice (run `cmake --help` for a list).
cmake -G "Unix Makefiles" -DSPAN_LITE_OPT_BUILD_TESTS=ON ..
3. Optional. You can control above configuration through the following options:
`-DSPAN_LITE_OPT_BUILD_TESTS=ON`: build the tests for span, default off
`-DSPAN_LITE_OPT_BUILD_EXAMPLES=OFF`: build the examples, default off
4. Build the test suite.
cmake --build .
5. Run the test suite.
ctest -V
All tests should pass, indicating your platform is supported and you are ready to use *span lite*.
## Other implementations of span
- *gsl-lite* [span](https://github.com/martinmoene/gsl-lite/blob/73c4f16f2b35fc174fc2f09d44d5ab13e5c638c3/include/gsl/gsl-lite.hpp#L1221).
- Microsoft GSL [span](https://github.com/Microsoft/GSL/blob/master/include/gsl/span).
- Google Abseil [span](https://github.com/abseil/abseil-cpp/blob/master/absl/types/span.h).
- Marshall Clow's [libc++ span snippet](https://github.com/mclow/snippets/blob/master/span.cpp).
- Tristan Brindle's [Implementation of C++20's std::span for older compilers](https://github.com/tcbrindle/span).
- [Search _span c++_ on GitHub](https://github.com/search?l=C%2B%2B&q=span+c%2B%2B&type=Repositories&utf8=%E2%9C%93).
## Notes and references
*Interface and specification*
- [span on cppreference](https://en.cppreference.com/w/cpp/container/span).
- [p0122 - C++20 Proposal](http://wg21.link/p0122).
- [span in C++20 Working Draft](http://eel.is/c++draft/views).
*Presentations*
- TBD
*Proposals*
- [p0122 - span: bounds-safe views for sequences of objects](http://wg21.link/p0122).
- [p1024 - Usability Enhancements for std::span](http://wg21.link/p1024).
- [p1419 - A SFINAE-friendly trait to determine the extent of statically sized containers](http://wg21.link/p1419).
- [p0805 - Comparing Containers](http://wg21.link/p0805).
- [p1085 - Should Span be Regular?](http://wg21.link/p0805).
- [p0091 - Template argument deduction for class templates](http://wg21.link/p0091).
- [p0856 - Restrict Access Property for mdspan and span](http://wg21.link/p0856).
- [p1428 - Subscripts and sizes should be signed](http://wg21.link/p1428).
- [p1089 - Sizes Should Only span Unsigned](http://wg21.link/p1089).
- [p1227 - Signed size() functions](http://wg21.link/p1227).
- [p1872 - span should have size_type, not index_type](http://wg21.link/p1872).
- [p2447 - std::span and the missing constructor](https://wg21.link/p2447).
- [lwg 3101 - span's Container constructors need another constraint](https://cplusplus.github.io/LWG/issue3101).
- [Reddit - 2018-06 Rapperswil ISO C++ Committee Trip Report](https://www.reddit.com/r/cpp/comments/8prqzm/2018_rapperswil_iso_c_committee_trip_report/)
- [Reddit - 2018-11 San Diego ISO C++ Committee Trip Report](https://www.reddit.com/r/cpp/comments/9vwvbz/2018_san_diego_iso_c_committee_trip_report_ranges/).
- [Reddit - 2019-02 Kona ISO C++ Committee Trip Report](https://www.reddit.com/r/cpp/comments/au0c4x/201902_kona_iso_c_committee_trip_report_c20/).
- [Reddit - 2019-07 Cologne ISO C++ Committee Trip Report](https://www.reddit.com/r/cpp/comments/cfk9de/201907_cologne_iso_c_committee_trip_report_the/)
- [Reddit - 2019-11 Belfast ISO C++ Committee Trip Report](https://www.reddit.com/r/cpp/comments/dtuov8/201911_belfast_iso_c_committee_trip_report/)
- <a id="regtyp"></a>Titus Winters. [Revisiting Regular Types](https://abseil.io/blog/20180531-regular-types). Abseil Blog. 31 May 2018.
## Appendix
### A.1 Compile-time information
The version of *span lite* is available via tag `[.version]`. The following tags are available for information on the compiler and on the C++ standard library used: `[.compiler]`, `[.stdc++]`, `[.stdlanguage]` and `[.stdlibrary]`.
### A.2 Span lite test specification
<details>
<summary>click to expand</summary>
<p>
```Text
span<>: Terminates construction from a nullptr and a non-zero size (C++11)
span<>: Terminates construction from two pointers in the wrong order
span<>: Terminates construction from a null pointer and a non-zero size
span<>: Terminates creation of a sub span of the first n elements for n exceeding the span
span<>: Terminates creation of a sub span of the last n elements for n exceeding the span
span<>: Terminates creation of a sub span outside the span
span<>: Terminates access outside the span
span<>: Throws on access outside the span via at(): std::out_of_range [span_FEATURE_MEMBER_AT>0][span_CONFIG_NO_EXCEPTIONS=0]
span<>: Termination throws std::logic_error-derived exception [span_CONFIG_CONTRACT_VIOLATION_THROWS=1]
span<>: Allows to default-construct
span<>: Allows to construct from a nullptr and a zero size (C++11)
span<>: Allows to construct from two pointers
span<>: Allows to construct from two iterators
span<>: Allows to construct from two iterators - empty range
span<>: Allows to construct from two iterators - move-only element
span<>: Allows to construct from an iterator and a size
span<>: Allows to construct from an iterator and a size - empty range
span<>: Allows to construct from an iterator and a size - move-only element
span<>: Allows to construct from two pointers to const
span<>: Allows to construct from a non-null pointer and a size
span<>: Allows to construct from a non-null pointer to const and a size
span<>: Allows to construct from a temporary pointer and a size
span<>: Allows to construct from a temporary pointer to const and a size
span<>: Allows to construct from any pointer and a zero size (C++98)
span<>: Allows to construct from a pointer and a size via a deduction guide (C++17)
span<>: Allows to construct from an iterator and a size via a deduction guide (C++17)
span<>: Allows to construct from two iterators via a deduction guide (C++17)
span<>: Allows to construct from a C-array
span<>: Allows to construct from a C-array via a deduction guide (C++17)
span<>: Allows to construct from a const C-array
span<>: Allows to construct from a C-array with size via decay to pointer (potentially dangerous)
span<>: Allows to construct from a const C-array with size via decay to pointer (potentially dangerous)
span<>: Allows to construct from a std::initializer_list<> (C++11)
span<>: Allows to construct from a std::initializer_list<> as a constant set of values (C++11, p2447)
span<>: Allows to construct from a std::array<> (C++11)
span<>: Allows to construct from a std::array via a deduction guide (C++17)
span<>: Allows to construct from a std::array<> with const data (C++11, span_FEATURE_CONSTR..._ELEMENT_TYPE=1)
span<>: Allows to construct from an empty std::array<> (C++11)
span<>: Allows to construct from a container (std::vector<>)
span<>: Allows to construct from a container via a deduction guide (std::vector<>, C++17)
span<>: Allows to tag-construct from a container (std::vector<>)
span<>: Allows to tag-construct from a const container (std::vector<>)
span<>: Allows to copy-construct from another span of the same type
span<>: Allows to copy-construct from another span of a compatible type
span<>: Allows to copy-construct from a temporary span of the same type (C++11)
span<>: Allows to copy-assign from another span of the same type
span<>: Allows to copy-assign from a temporary span of the same type (C++11)
span<>: Allows to create a sub span of the first n elements
span<>: Allows to create a sub span of the last n elements
span<>: Allows to create a sub span starting at a given offset
span<>: Allows to create a sub span starting at a given offset with a given length
span<>: Allows to observe an element via array indexing
span<>: Allows to observe an element via call indexing
span<>: Allows to observe an element via at() [span_FEATURE_MEMBER_AT>0]
span<>: Allows to observe an element via data()
span<>: Allows to observe the first element via front() [span_FEATURE_MEMBER_BACK_FRONT=1]
span<>: Allows to observe the last element via back() [span_FEATURE_MEMBER_BACK_FRONT=1]
span<>: Allows to change an element via array indexing
span<>: Allows to change an element via call indexing
span<>: Allows to change an element via at() [span_FEATURE_MEMBER_AT>0]
span<>: Allows to change an element via data()
span<>: Allows to change the first element via front() [span_FEATURE_MEMBER_BACK_FRONT=1]
span<>: Allows to change the last element via back() [span_FEATURE_MEMBER_BACK_FRONT=1]
span<>: Allows to swap with another span [span_FEATURE_MEMBER_SWAP=1]
span<>: Allows forward iteration
span<>: Allows const forward iteration
span<>: Allows reverse iteration
span<>: Allows const reverse iteration
span<>: Allows to identify if a span is the same as another span [span_FEATURE_SAME=1]
span<>: Allows to compare equal to another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare unequal to another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare less than another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare less than or equal to another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare greater than another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare greater than or equal to another span of the same type [span_FEATURE_COMPARISON=1]
span<>: Allows to compare to another span of the same type and different cv-ness [span_FEATURE_SAME=0]
span<>: Allows to compare empty spans as equal [span_FEATURE_COMPARISON=1]
span<>: Allows to test for empty span via empty(), empty case
span<>: Allows to test for empty span via empty(), non-empty case
span<>: Allows to obtain the number of elements via size()
span<>: Allows to obtain the number of elements via ssize()
span<>: Allows to obtain the number of bytes via size_bytes()
span<>: Allows to view the elements as read-only bytes
span<>: Allows to view and change the elements as writable bytes
make_span() [span_FEATURE_MAKE_SPAN_TO_STD=99]
make_span(): Allows building from two pointers
make_span(): Allows building from two const pointers
make_span(): Allows building from a non-null pointer and a size
make_span(): Allows building from a non-null const pointer and a size
make_span(): Allows building from a C-array
make_span(): Allows building from a const C-array
make_span(): Allows building from a std::initializer_list<> (C++11)
make_span(): Allows building from a std::initializer_list<> as a constant set of values (C++11)
make_span(): Allows building from a std::array<> (C++11)
make_span(): Allows building from a const std::array<> (C++11)
make_span(): Allows building from a container (std::vector<>)
make_span(): Allows building from a const container (std::vector<>)
make_span(): Allows building from a container (with_container_t, std::vector<>)
make_span(): Allows building from a const container (with_container_t, std::vector<>)
byte_span() [span_FEATURE_BYTE_SPAN=1]
byte_span(): Allows building a span of std::byte from a single object (C++17, byte-lite)
byte_span(): Allows building a span of const std::byte from a single const object (C++17, byte-lite)
first(), last(), subspan() [span_FEATURE_NON_MEMBER_FIRST_LAST_SUB=1]
first(): Allows to create a sub span of the first n elements (span, template parameter)
first(): Allows to create a sub span of the first n elements (span, function parameter)
first(): Allows to create a sub span of the first n elements (compatible container, template parameter)
first(): Allows to create a sub span of the first n elements (compatible container, function parameter)
last(): Allows to create a sub span of the last n elements (span, template parameter)
last(): Allows to create a sub span of the last n elements (span, function parameter)
last(): Allows to create a sub span of the last n elements (compatible container, template parameter)
last(): Allows to create a sub span of the last n elements (compatible container, function parameter)
subspan(): Allows to create a sub span starting at a given offset (span, template parameter)
subspan(): Allows to create a sub span starting at a given offset (span, function parameter)
subspan(): Allows to create a sub span starting at a given offset (compatible container, template parameter)
subspan(): Allows to create a sub span starting at a given offset (compatible container, function parameter)
size(): Allows to obtain the number of elements via size()
ssize(): Allows to obtain the number of elements via ssize()
tuple_size<>: Allows to obtain the number of elements via std::tuple_size<> (C++11)
tuple_element<>: Allows to obtain an element via std::tuple_element<> (C++11)
tuple_element<>: Allows to obtain an element via std::tuple_element_t<> (C++11)
get<I>(spn): Allows to access an element via std::get<>()
tweak header: reads tweak header if supported [tweak]
```
</p>
</details>

2162
src/libs/3rdparty/span/span.hpp vendored
View File

File diff suppressed because it is too large Load Diff

17
src/libs/utils/span.h
View File

@@ -3,6 +3,8 @@
#pragma once
#include <qcompilerdetection.h>
#if __cplusplus >= 202002L
#include <span>
@@ -13,6 +15,17 @@ using std::get;
using std::span;
} // namespace Utils
#else
#define TCB_SPAN_NAMESPACE_NAME Utils
#include <3rdparty/span/span.hpp>
QT_WARNING_PUSH
#if defined(Q_CC_MSVC)
#pragma system_header
#elif defined(Q_CC_GNU) || defined(Q_CC_CLANG)
#pragma GCC system_header
#endif
#include <3rdparty/span/span.hpp>
namespace Utils {
using namespace nonstd;
}
QT_WARNING_POP
#endif