/README.md
https://github.com/martinmoene/gsl-lite · Markdown · 1183 lines · 945 code · 238 blank · 0 comment · 0 complexity · ef3cf7eab8ffd6389a24b00f72e5f084 MD5 · raw file
Large files are truncated click here to view the full file
- # *gsl-lite*: Guidelines Support Library for C++98, C++11 up
- | metadata | build | packages | try online |
- | -------- | ------ | -------- | ---------- |
- | [](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) <br> [](https://opensource.org/licenses/MIT) <br> [](https://github.com/gsl-lite/gsl-lite/releases) | [](https://dev.azure.com/gsl-lite/gsl-lite/_build/latest?definitionId=1&branchName=master) <br> [](https://travis-ci.com/gsl-lite/gsl-lite) <br> [](https://ci.appveyor.com/project/gsl-lite/gsl-lite) | [](https://github.com/microsoft/vcpkg/tree/master/ports/gsl-lite) <br> [](https://bintray.com/conan/conan-center/gsl-lite%3A_/_latestVersion) <br> [](https://raw.githubusercontent.com/gsl-lite/gsl-lite/master/include/gsl/gsl-lite.hpp) | [](https://gcc.godbolt.org/z/JVtM2c) <br> [](https://wandbox.org/permlink/p9YnfiUTOYEQx0QL) |
- *gsl-lite* is an implementation of the [C++ Core Guidelines Support Library](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl) originally based on [Microsoft GSL](https://github.com/microsoft/gsl).
- **Contents**
- - [Example usage](#example-usage)
- - [In a nutshell](#in-a-nutshell)
- - [License](#license)
- - [Dependencies](#dependencies)
- - [Installation and use](#installation-and-use)
- - [Version semantics](#version-semantics)
- - [Using *gsl-lite* in libraries](#using-gsl-lite-in-libraries)
- - [Configuration options](#configuration-options)
- - [Features](#features)
- - [Deprecation](#deprecation)
- - [Reported to work with](#reported-to-work-with)
- - [Building the tests](#building-the-tests)
- - [Other GSL implementations](#other-gsl-implementations)
- - [Notes and references](#notes-and-references)
- - [Appendix](#appendix)
- Example usage
- -------------
- ```Cpp
- #include <gsl/gsl-lite.hpp>
- int * use( gsl::not_null<int *> p )
- {
- // use p knowing it's not nullptr, NULL or 0.
- return p;
- }
- struct Widget
- {
- Widget() : owned_ptr_( new int(42) ) {}
- ~Widget() { delete owned_ptr_; }
- void work() { non_owned_ptr_ = use( owned_ptr_ ); }
-
- gsl::owner<int *> owned_ptr_; // if alias template support
- int * non_owned_ptr_;
- };
- int main()
- {
- Widget w;
- w.work();
- }
- ```
- ### Compile and run
- ```
- prompt> g++ -std=c++03 -Wall -I../include -o 01-basic.exe 01-basic.cpp && 01-basic.exe
- ```
- In a nutshell
- -------------
- **gsl-lite** is a single-file header-only implementation of the [C++ Core Guidelines Support Library](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl) originally based on [Microsoft GSL](https://github.com/microsoft/gsl) and adapted for C++98, C++03. It also works when compiled as C++11, C++14, C++17, C++20.
- The Guidelines Support Library (GSL) contains functions and types that are suggested for use by the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) maintained by the [Standard C++ Foundation](https://isocpp.org/). The library includes types like `owner<>`, `not_null<>`, `span<>`, `string_span` and [others](#features).
- *gsl-lite* recognizes when it is compiled for the CUDA platform and decorates some functions with `__host__` and `__device__`. See also section [API macro](#api-macro).
- License
- -------
- *gsl-lite* uses the [MIT](LICENSE) license.
-
- Dependencies
- ------------
- *gsl-lite* has no other dependencies than the [C++ standard library](http://en.cppreference.com/w/cpp/header).
- Installation and use
- --------------------
- ### As CMake package
- The recommended way to consume *gsl-lite* in your CMake project is to use `find_package()` and `target_link_libraries()`:
- ```CMake
- cmake_minimum_required( VERSION 3.15 FATAL_ERROR )
-
- find_package( gsl-lite 0.37 REQUIRED )
-
- project( my-program LANGUAGES CXX )
-
- add_executable( my-program main.cpp )
- target_link_libraries( my-program PRIVATE gsl::gsl-lite )
- ```
- There are various ways to make the `gsl-lite` package available to your project:
- <details>
- <summary>Using Vcpkg</summary>
- <p>
- 1. For the [Vcpkg package manager](https://github.com/microsoft/vcpkg/), simply run Vcpkg's install command:
- vcpkg install gsl-lite
- 2. Now, configure your project passing the Vcpkg toolchain file as a parameter:
- cd <my-program-source-dir>
- mkdir build
- cd build
- cmake -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake ..
- cmake --build ../build
- </p></details>
- <details>
- <summary>Using an exported build directory</summary>
- <p>
- 1. Clone the *gsl-lite* repository and configure a build directory with CMake:
- git clone git@github.com:gsl-lite/gsl-lite.git <gsl-lite-source-dir>
- cd <gsl-lite-source-dir>
- mkdir build
- cd build
- cmake ..
- 2. Now, configure your project passing the CMake build directory as a parameter:
- cd <my-program-source-dir>
- mkdir build
- cd build
- cmake -Dgsl-lite_DIR:PATH=<gsl-lite-source-dir>/build ..
- cmake --build ../build
- See [example/cmake-pkg/Readme.md](example/cmake-pkg/Readme.md) for a complete example.
- </p></details>
- <details>
- <summary>Using Conan</summary>
- <p>
- For the [Conan package manager](https://www.conan.io/), follow these steps:
- 1. Add Conan Center to the conan remotes:
- conan remote add center https://api.bintray.com/conan/conan/conan-center
- 2. Add a reference to *gsl-lite* to the *requires* section of your project's `conanfile.txt` file:
- [requires]
- gsl-lite/0.37@center/stable
- 3. Run conan's install command:
- conan install gsl-lite
- Now *gsl-lite* can be consumed as a Conan package. (TODO: elaborate!)
- </p></details>
- <details>
- <summary>Using Conda</summary>
- <p>
- 1. For the [conda package manager](https://conda.io), first use **one of these options** to install `gsl-lite` from the [`conda-forge`](https://conda-forge.org/) channel:
- * Install it in the current environment:
- conda install -c conda-forge gsl-lite
- * Install it in a different environment (named `env_name` in this example):
- conda install -n env_name -c conda-forge gsl-lite
- * Create a new environment containing *gsl-lite* (and possibly other packages, appended at the end of the command):
- conda create -n env_name -c conda-forge gsl-lite cmake
- * Add it to an already existing [`environment.yml`](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file) file, and update the environment using:
- conda env update
- 2. Then activate the environment using `conda activate env_name` (if not already activated) and proceed using the instructions from step 2 of ["As CMake package"](#as-cmake-package). Note that it's also useful to have the `cmake` package in the same environment, and explicitly passing `-DCMAKE_INSTALL_PREFIX` is not necessary.
- </p></details>
- ### Other options
- <details>
- <summary>As external Git project</summary>
- <p>
- TODO: this section needs updating
- Another approach is to automatically fetch the entire *gsl-lite* repository from GitHub and configure it as an external project.
- ```CMake
- cmake_minimum_required( VERSION 3.15 FATAL_ERROR )
- project( use-gsl-lite LANGUAGES CXX )
- # Set default ExternalProject root directory and add gsl-lite:
- set( GSL_LITE_URL https://github.com/gsl-lite/gsl-lite.git )
- include( ExternalProject )
- find_package( Git REQUIRED )
- set_directory_properties( PROPERTIES EP_PREFIX ${CMAKE_BINARY_DIR}/3rd_party )
- ExternalProject_Add(
- gsl-extern
- GIT_REPOSITORY ${GSL_LITE_URL}
- TIMEOUT 10
- UPDATE_COMMAND ${GIT_EXECUTABLE} pull
- CONFIGURE_COMMAND ""
- BUILD_COMMAND ""
- INSTALL_COMMAND ""
- LOG_DOWNLOAD ON
- )
- # Provide #include access to gsl-lite as <gsl/gsl-lite.hpp>:
- ExternalProject_Get_Property( gsl-extern SOURCE_DIR )
- set( GSL_LITE_INCLUDE_DIR ${SOURCE_DIR}/include CACHE INTERNAL "Include folder for gsl-lite" )
- add_library( gsl INTERFACE )
- target_include_directories( gsl INTERFACE ${GSL_LITE_INCLUDE_DIR} )
- # Build program from src:
- add_subdirectory( src )
- ```
- In folder src:
- ```CMake
- cmake_minimum_required( VERSION 3.15 FATAL_ERROR )
- project( program-using-gsl-lite LANGUAGES CXX )
- # Make program executable:
- add_executable( program main.cpp )
- target_link_libraries( program PRIVATE gsl::gsl-lite )
- ```
- This setup brings in more than you need, but also makes it easy to update *gsl-lite* to the latest version. See [example/cmake-extern](example/cmake-extern) for a complete example.
- </p></details>
- <details>
- <summary>As copied header</summary>
- <p>
- Put a copy of [`gsl-lite.hpp`](include/gsl/gsl-lite.hpp) located in folder [include/gsl](include/gsl) directly into the project source tree or somewhere reachable from your project, for example in *project-root*/include/gsl. A minimal CMake setup using this header might look as follows.
- In project root folder:
- ```CMake
- cmake_minimum_required( VERSION 3.15 FATAL_ERROR )
- project( use-gsl-lite LANGUAGES CXX )
- # Provide #include access to gsl-lite as 'gsl/gsl-lite.hpp':
- add_library( gsl-lite INTERFACE )
- target_include_directories( gsl-lite INTERFACE include ) # adapt as necessary
- # Build program from src:
- add_subdirectory( src )
- ```
- In folder src:
- ```CMake
- cmake_minimum_required( VERSION 3.15 FATAL_ERROR )
- project( program-using-gsl-lite LANGUAGES CXX )
- # Make program executable:
- add_executable( program main.cpp )
- target_link_libraries( program PRIVATE gsl-lite )
- ```
- </p></details>
- Version semantics
- -----------------
- *gsl-lite* strives to follow [Semantic Versioning](https://semver.org/) guidelines. Although we are still in the "initial development" stage (version 0\.*), we generally maintain
- [API](https://en.wikipedia.org/wiki/Application_programming_interface) and [ABI](https://en.wikipedia.org/wiki/Application_binary_interface) compatibility and avoid breaking changes in minor and patch releases.
- Development of *gsl-lite* happens in the `master` branch. Versioning semantics apply only to tagged releases: there is no stability guarantee between individual commits in the `master` branch, i.e. anything
- added since the last tagged release may be renamed, removed, have the semantics changed, etc. without further notice.
- A minor-version release will be compatible (in both ABI and API) with the previous minor-version release (with [rare exceptions](https://github.com/gsl-lite/gsl-lite/issues/156) while we're still in version 0.\*).
- Thus, once a change is released, it becomes part of the API.
- Some of the [configuration options](#configuration-options) affect the API and ABI of *gsl-lite*. Most configuration options exist because a change we wanted to make would have broken backward compatibility,
- so many recent changes and improvements are currently opt-in. The current plan is to toggle the default values of these configuration options for the next major version release.
- To simplify migration to the next major version, *gsl-lite* 0.36 introduces the notion of *versioned defaults*. By setting the configuration option `gsl_CONFIG_DEFAULTS_VERSION=0` or `gsl_CONFIG_DEFAULTS_VERSION=1`,
- a set of version-specific default options can be selected. Alternatively, when consuming *gsl-lite* [as a CMake package](#as-cmake-package), versioned defaults can be selected by linking to the target
- `gsl::gsl-lite-v0` or `gsl::gsl-lite-v1` rather than `gsl::gsl-lite`.
- The following table gives an overview of the configuration options affected by versioned defaults:
- Macro | v0 default | v1 default | |
- ------------------------------------------------------------------------------------:|:---------------------------------------------------------|-------------------|-|
- [`gsl_FEATURE_OWNER_MACRO`](#gsl_feature_owner_macro1) | 1 | 0 | an unprefixed macro `Owner()` may interfere with user code |
- [`gsl_FEATURE_GSL_LITE_NAMESPACE`](#gsl_feature_gsl_lite_namespace0) | 0 | 1 | cf. [Using *gsl-lite* in libraries](#using-gsl-lite-in-libraries) |
- [`gsl_CONFIG_DEPRECATE_TO_LEVEL`](#gsl_config_deprecate_to_level0) | 0 | 6 | |
- [`gsl_CONFIG_INDEX_TYPE`](#gsl_config_index_typegsl_config_span_index_type) | `gsl_CONFIG_SPAN_INDEX_TYPE` (defaults to `std::size_t`) | `std::ptrdiff_t` | the GSL specifies `gsl::index` to be a signed type, and M-GSL also uses `std::ptrdiff_t` |
- [`gsl_CONFIG_ALLOWS_SPAN_COMPARISON`](#gsl_config_allows_span_comparison1) | 1 | 0 | C++20 `std::span<>` does not support comparison because semantics (deep vs. shallow) are unclear |
- [`gsl_CONFIG_NOT_NULL_EXPLICIT_CTOR`](#gsl_config_not_null_explicit_ctor0) | 0 | 1 | cf. reasoning in [M-GSL/#395](https://github.com/Microsoft/GSL/issues/395) (note that `not_null<>` in M-GSL has an implicit constructor, cf. [M-GSL/#699](https://github.com/Microsoft/GSL/issues/699)) |
- [`gsl_CONFIG_TRANSPARENT_NOT_NULL`](#gsl_config_transparent_not_null0) | 0 | 1 | enables conformant behavior for `not_null<>::get()` |
- [`gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION`](#gsl_config_narrow_throws_on_truncation0) | 0 | 1 | enables conformant behavior for `narrow<>()` (cf. [#52](https://github.com/gsl-lite/gsl-lite/issues/52)) |
- Note that the v1 defaults are not yet stable; future 0.\* releases may introduce more configuration switches with different version-specific defaults.
- Using *gsl-lite* in libraries
- -----------------------------
- Many features of *gsl-lite* are very useful for defining library interfaces, e.g. spans, precondition checks, or `gsl::not_null<>`. As such, we encourage using *gsl-lite* in your libraries.
- However, please mind the following considerations:
- - *gsl-lite* is an implementation of the [Guidelines Support Library](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl), which is not a library but a non-formal specification.
- There are other libraries implementing the GSL, most notably the [Microsoft GSL](https://github.com/microsoft/GSL/) (herein often referred to as "M-GSL"). Both libraries live in different headers and consist
- of unrelated implementations. There is considerable API compatibility between M-GSL and *gsl-lite*, but some differences are inevitable because the GSL specification is rather loose and informal, and because
- both implementations take some liberties at interpreting and extending the specification (cf. e.g. [#6](https://github.com/gsl-lite/gsl-lite/issues/6), [#52](https://github.com/gsl-lite/gsl-lite/issues/52),
- [#153](https://github.com/gsl-lite/gsl-lite/issues/153)). Also, the ABIs of *gsl-lite* and M-GSL are generally incompatible.
- - It is not clear whether the GSL specification envisions that multiple implementations of the specification should coexist (cf. [CppCoreGuidelines/#1519](https://github.com/isocpp/CppCoreGuidelines/issues/1519)),
- but because all existing implementations currently live in the same `namespace gsl`, using more than one GSL implementation in the same target will usually fail with compile/link errors. This is clearly
- an impediment for using either in a library because the library would thereby force its consumers to pick the same GSL implementation.
- - The API and ABI of *gsl-lite* can be altered by some of the [configuration options](#configuration-options). We consider the availability of these options a strength of *gsl-lite*, but the lack
- of an option-invariant API and ABI is another burden for libraries, which may or may not depend on a particular choice of configuration settings and implicitly force these upon their users.
- Our goal is to make *gsl-lite* suitable for use in libraries; we want to address all of these concerns in the next major version. But if you want to use *gsl-lite* in a library today, we recommend to
- - use version-1 defaults (cf. [Version semantics](#version-semantics))
- - include the new header \<gsl-lite/gsl-lite.hpp\> rather than \<gsl/gsl-lite.hpp\>
- - refer to the new `namespace gsl_lite` instead of `namespace gsl` (or define a `namespace gsl = ::gsl_lite;` alias in your own namespace)
- - use the prefixed contract checking macros `gsl_Expects()`/`gsl_Ensures()` rather than the unprefixed `Expects()`/`Ensures()`
- (M-GSL prefixes its macros with uppercase `GSL_`; we traditionally consider lowercase `gsl_` the realm of *gsl-lite*)
- - avoid any changes to the configuration options
- Example:
- ```cmake
- # my-statistics-lib/CMakeLists.txt
- find_package( gsl-lite 0.37 REQUIRED )
- add_library( my-statistics-lib STATIC mean.cpp )
- target_link_libraries( my-statistics-lib PUBLIC gsl::gsl-lite-v1 )
- ```
- ```c++
- // my-statistics-lib/include/my-statistics-lib/mean.hpp
- #include <gsl-lite/gsl-lite.hpp> // instead of <gsl/gsl-lite.hpp>
- namespace my_statistics_lib {
- namespace gsl = ::gsl_lite; // convenience alias
- double mean( gsl::span<double const> elements )
- {
- gsl_Expects( !elements.empty() ); // instead of Expects()
- ...
- }
- } // namespace my_statistics_lib
- ```
- The idea is that *gsl-lite* will move all its definitions to `namespace gsl_lite` in the next major version, and provide a `namespace gsl` with aliases only if the traditional header \<gsl/gsl-lite.hpp\> is
- included. This way, any code that only uses the new header \<gsl-lite/gsl-lite.hpp\> will not risk collision with M-GSL.
- Configuration options
- ---------------------
- **Contents**
- - [API macro](#api-macro)
- - [Standard selection macro](#standard-selection-macro)
- - [Feature selection macros](#feature-selection-macros)
- - [Contract checking configuration macros](#contract-checking-configuration-macros)
- - [Microsoft GSL compatibility macros](#microsoft-gsl-compatibility-macros)
- - [Other configuration macros](#other-configuration-macros)
- ### API macro
- #### `gsl_api`
- Functions in *gsl-lite* are decorated with `gsl_api` where appropriate. **By default `gsl_api` is defined empty for non-CUDA platforms and `__host__ __device__` for the CUDA platform.** Define this macro to specify your own function decoration.
- ### Standard selection macro
- #### `gsl_CPLUSPLUS`
- Define this macro to override the auto-detection of the supported C++ standard if your compiler does not set the `__cplusplus` macro correctly.
- ### Feature selection macros
- #### `gsl_FEATURE_WITH_CONTAINER_TO_STD=99`
- Define this to the highest C++ standard (98, 3, 11, 14, 17, 20) you want to include tagged-construction via `with_container`. **Default is 99 for inclusion with any standard.**
- #### `gsl_FEATURE_MAKE_SPAN_TO_STD=99`
- Define this to the highest C++ standard (98, 3, 11, 14, 17, 20) you want to include `make_span()` creator functions. **Default is 99 for inclusion with any standard.**
- #### `gsl_FEATURE_BYTE_SPAN_TO_STD=99`
- Define this to the highest C++ standard (98, 3, 11, 14, 17, 20) you want to include `byte_span()` creator functions. **Default is 99 for inclusion with any standard.**
- #### `gsl_FEATURE_IMPLICIT_MACRO=0`
- Define this macro to 1 to provide the `implicit` macro. **Default is 0.**
- #### `gsl_FEATURE_OWNER_MACRO=1`
- At default macro `Owner()` is defined for all C++ versions. This may be useful to transition from a compiler that doesn't provide alias templates to one that does. Define this macro to 0 to omit the `Owner()` macro. **Default is 1.**
- #### `gsl_FEATURE_EXPERIMENTAL_RETURN_GUARD=0`
- Provide experimental types `final_action_return` and `final_action_error` and convenience functions `on_return()` and `on_error()`. **Default is 0.**
- #### `gsl_FEATURE_GSL_LITE_NAMESPACE=0`
- Define this to additionally define a `namespace gsl_lite` with most of the *gsl-lite* API available, cf. [Using *gsl-lite* in libraries](#using-gsl-lite-in-libraries). **Default is 0.**
- ### Contract checking configuration macros
- *gsl-lite* provides contract violation response control as originally suggested in proposal [N4415](http://wg21.link/n4415), with some refinements inspired by [P1710](http://wg21.link/P1710)/[P1730](http://wg21.link/P1730).
- There are four macros for expressing pre- and postconditions:
- - `gsl_Expects()` for simple preconditions
- - `gsl_Ensures()` for simple postconditions
- - `gsl_ExpectsAudit()` for preconditions that are expensive or include potentially opaque function calls
- - `gsl_EnsuresAudit()` for postconditions that are expensive or include potentially opaque function calls
- The macros `Expects()` and `Ensures()` are also provided as aliases for `gsl_Expects()` and `gsl_Ensures()`.
- The following macros control whether contracts are checked at runtime:
- - **`gsl_CONFIG_CONTRACT_CHECKING_AUDIT`**
- Define this macro to have all contracts checked at runtime.
- - **`gsl_CONFIG_CONTRACT_CHECKING_ON` (default)**
- Define this macro to have contracts expressed with `gsl_Expects()` and `gsl_Ensures()` checked at runtime, and contracts expressed with `gsl_ExpectsAudit()` and `gsl_EnsuresAudit()` not checked and not evaluated at runtime. **This is the default.**
-
- - **`gsl_CONFIG_CONTRACT_CHECKING_OFF`**
- Define this macro to disable all runtime checking of contracts.
- The following macros can be used to selectively disable checking for a particular kind of contract:
- - **`gsl_CONFIG_CONTRACT_CHECKING_EXPECTS_OFF`**
- Define this macro to disable runtime checking of precondition contracts expressed with `gsl_Expects()` and `gsl_ExpectsAudit()`.
- - **`gsl_CONFIG_CONTRACT_CHECKING_ENSURES_OFF`**
- Define this macro to disable runtime checking of precondition contracts expressed with `gsl_Ensures()` and `gsl_EnsuresAudit()`.
- The following macros control the handling of runtime contract violations:
- - **`gsl_CONFIG_CONTRACT_VIOLATION_TERMINATES` (default)**
- Define this macro to call `std::terminate()` on a GSL contract violation in `gsl_Expects()`, `gsl_ExpectsAudit()`, `gsl_Ensures()`, and `gsl_EnsuresAudit()`. **This is the default.**
- - **`gsl_CONFIG_CONTRACT_VIOLATION_THROWS`**
- Define this macro to throw a std::runtime_exception-derived exception `gsl::fail_fast` instead of calling `std::terminate()` on a GSL contract violation in `gsl_Expects()`, `gsl_ExpectsAudit()`, `gsl_Ensures()`, and `gsl_EnsuresAudit()`.
- - **`gsl_CONFIG_CONTRACT_VIOLATION_CALLS_HANDLER`**
- Define this macro to call a user-defined handler function `gsl::fail_fast_assert_handler()` instead of calling `std::terminate()` on a GSL contract violation in `gsl_Expects()`, `gsl_ExpectsAudit()`, `gsl_Ensures()`, and `gsl_EnsuresAudit()`. The user must provide a definition of the following function:
- ```c++
- namespace gsl {
- gsl_api void fail_fast_assert_handler(
- char const * const expression, char const * const message,
- char const * const file, int line );
- }
- ```
- The following macros control what happens with contract checks not enforced at runtime:
-
- - **`gsl_CONFIG_UNENFORCED_CONTRACTS_ELIDE` (default)**
- Define this macro to disable all runtime checking and evaluation of contracts. **This is the default.**
- - **`gsl_CONFIG_UNENFORCED_CONTRACTS_ASSUME`**
- Define this macro to let the compiler assume that contracts expressed with `gsl_Expects()` and `gsl_Ensures()` always hold true, and to have contracts expressed with `gsl_ExpectsAudit()` and `gsl_EnsuresAudit()` not checked and not evaluated at runtime. With this setting, contract violations lead to undefined behavior, which gives the compiler more opportunities for optimization but can be dangerous if the code is not prepared for it.
- Note that the distinction between regular and audit-level contracts is subtly different from the C++2a Contracts proposals. When `gsl_CONFIG_UNENFORCED_CONTRACTS_ASSUME` is defined, the compiler is instructed that the
- condition expressed by regular contracts can be assumed to hold true. This is meant to be an aid for the optimizer; runtime evaluation of the condition is not desired. However, because the GSL implements contract checks
- with macros rather than as a language feature, it cannot reliably suppress runtime evaluation of a condition for all compilers. If the contract comprises a function call which is opaque to the compiler, many compilers will
- generate the runtime function call.
- Therefore, `gsl_Expects()` and `gsl_Ensures()` should be used only for conditions that can be proven side-effect-free by the compiler, and `gsl_ExpectsAudit()` and `gsl_EnsuresAudit()` for everything else. In practice, this implies that
- `gsl_Expects()` and `gsl_Ensures()` should only be used for simple comparisons of scalar values, for simple inlineable getters, and for comparisons of class objects with trivially inlineable comparison operators.
- Example:
- ```c++
- template< class RandomIt >
- auto median( RandomIt first, RandomIt last )
- {
- // Comparing iterators for equality boils down to a comparison of pointers. An optimizing
- // compiler will inline the comparison operator and understand that the comparison is free
- // of side-effects, and hence generate no code in gsl_CONFIG_UNENFORCED_CONTRACTS_ASSUME mode.
- gsl_Expects( first != last );
- // Verifying that a range of elements is sorted may be an expensive operation, and we
- // cannot trust the compiler to understand that it is free of side-effects, so we use an
- // audit-level contract check.
- gsl_ExpectsAudit( std::is_sorted( first, last ) );
- auto count = last - first;
- return count % 2 != 0
- ? first[ count / 2 ]
- : std::midpoint( first[ count / 2 ], first[ count / 2 + 1 ] );
- }
- ```
- ### Microsoft GSL compatibility macros
- #### `GSL_UNENFORCED_ON_CONTRACT_VIOLATION`
- Equivalent to defining `gsl_CONFIG_CONTRACT_CHECKING_OFF`.
- #### `GSL_TERMINATE_ON_CONTRACT_VIOLATION`
- Equivalent to defining `gsl_CONFIG_CONTRACT_VIOLATION_TERMINATES`.
- #### `GSL_THROW_ON_CONTRACT_VIOLATION`
- Equivalent to defining `gsl_CONFIG_CONTRACT_VIOLATION_THROWS`.
- ### Other configuration macros
- #### `gsl_CONFIG_DEPRECATE_TO_LEVEL=0`
- Define this to and including the level you want deprecation; see table [Deprecation](#deprecation) below. **Default is 0 for no deprecation.**
- #### `gsl_CONFIG_SPAN_INDEX_TYPE=std::size_t`
- Define this macro to the type to use for indices in `span<>` and `basic_string_span<>`. Microsoft GSL uses `std::ptrdiff_t`. **Default for *gsl-lite* is `std::size_t`.**
- #### `gsl_CONFIG_INDEX_TYPE=gsl_CONFIG_SPAN_INDEX_TYPE`
- Define this macro to the type to use for `gsl::index`. Microsoft's GSL uses `std::ptrdiff_t`. **Default for *gsl-lite* is `std::size_t`.**
- #### `gsl_CONFIG_NOT_NULL_EXPLICIT_CTOR=0`
- Define this macro to 1 to make `not_null<>`'s constructor explicit. **Default is 0.** Note that in Microsoft's GSL the constructor is explicit. For implicit construction you can also use the *gsl-lite*-specific `not_null<>`-derived class `not_null_ic<>`.
- #### `gsl_CONFIG_TRANSPARENT_NOT_NULL=0`
- Define this macro to 1 to have `not_null<>` support typical member functions of the underlying smart pointer transparently (currently `get()`), while adding precondition checks. This is conformant behavior but may be incompatible with older code which expects that `not_null<>::get()` returns the underlying pointer itself. **Default is 0.**
- #### `gsl_CONFIG_NOT_NULL_GET_BY_CONST_REF=0`
- Define this macro to 1 to have the legacy non-transparent version of `not_null<>::get()` return `T const &` instead of `T`. This may improve performance with types that have an expensive copy-constructor. This macro may not be defined if `gsl_CONFIG_TRANSPARENT_NOT_NULL` is 1. **Default is 0 for `T`.**
- #### `gsl_CONFIG_ALLOWS_SPAN_COMPARISON=1`
- Define this macro to 0 to omit the ability to compare spans. C++20 `std::span<>` does not support comparison because semantics (deep vs. shallow) are unclear. **Default is 1.**
- #### `gsl_CONFIG_ALLOWS_NONSTRICT_SPAN_COMPARISON=1`
- Define this macro to 0 to omit the ability to compare spans of different types, e.g. of different const-volatile-ness. To be able to compare a string_span with a cstring_span, non-strict span comparison must be available. **Default is 1.**
- #### `gsl_CONFIG_ALLOWS_UNCONSTRAINED_SPAN_CONTAINER_CTOR=0`
- Define this macro to 1 to add the unconstrained span constructor for containers for pre-C++11 compilers that cannot constrain the constructor. This constructor may prove too greedy and interfere with other constructors. **Default is 0.**
- Note: an alternative is to use the constructor tagged `with_container`: `span<V> s(gsl::with_container, cont)`.
- #### `gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION=0`
- Define this macro to 1 to have `narrow<>()` always throw a `narrowing_error` exception if the narrowing conversion loses information due to truncation. If `gsl_CONFIG_NARROW_THROWS_ON_TRUNCATION` is 0 and `gsl_CONFIG_CONTRACT_VIOLATION_THROWS` is not defined, `narrow<>()` instead calls `std::terminate()` on information loss. **Default is 0.**
- #### `gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS=0`
- Define this macro to 1 to experience the by-design compile-time errors of the GSL components in the test suite. **Default is 0.**
- Features
- --------
- See also section [GSL: Guidelines Support Library](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-gsl) of the C++ Core Guidelines [9].
- Feature / library | GSL | M-GSL | *gsl-lite* | Notes |
- ----------------------------|:-------:|:-------:|:----------:|:------|
- **1.Lifetime safety** | | | | |
- **1.1 Indirection** | | | | |
- `not_null<>` | ✓ | ✓ | ✓ | Wrap any indirection and enforce non-null,<br>see also [Other configuration macros](#other-configuration-macros) |
- `not_null_ic<>` | - | - | ✓ | not_null with implicit constructor, allowing [copy-initialization](https://en.cppreference.com/w/cpp/language/copy_initialization) |
- **1.2 Ownership** | | | | |
- `owner<>` | ✓ | ✓ | ≥ C++11 | Owned raw pointers |
- `Owner()` | - | - | ✓ | Macro for pre-C++11;<br>see also [Feature selection macros](#feature-selection-macros) |
- `unique_ptr<>` | ✓ | ✓ | ≥ C++11 | `std::unique_ptr<>` |
- `unique_ptr<>` | - | - | < C++11 | VC10, VC11 |
- `shared_ptr<>` | ✓ | ✓ | ≥ C++11 | `std::shared_ptr<>` |
- `shared_ptr<>` | - | - | < C++11 | VC10, VC11 |
- `stack_array<>` | ✓ | - | - | A stack-allocated array, fixed size |
- `dyn_array<>` | ? | - | - | A heap-allocated array, fixed size |
- **2.Bounds safety** | | | | |
- **2.1 Tag Types** | | | | |
- `zstring` | ✓ | ✓ | ✓ | a `char*` (C-style string) |
- `wzstring` | - | ✓ | ✓ | a `wchar_t*` (C-style string) |
- `czstring` | ✓ | ✓ | ✓ | a `const char*` (C-style string) |
- `cwzstring` | - | ✓ | ✓ | a `const wchar_t*` (C-style string) |
- `**2.2 Views** | | | | |
- `span<>` | ✓ | ✓ | 1D views | A view of contiguous T's, replace (*,len),<br>see also proposal [p0122](http://wg21.link/p0122) |
- `span_p<>` | ✓ | - | - | A view of contiguous T's that ends at the first element for which predicate(*p) is true |
- `make_span()` | - | ✓ | ✓ | Create a span |
- `byte_span()` | - | - | ✓ | Create a span of bytes from a single object |
- `as_bytes()` | - | ✓ | ✓ | A span as bytes |
- `as_writable_bytes` | - | ✓ | ✓ | A span as writable bytes |
- `basic_string_span<>` | - | ✓ | ✓ | See also proposal [p0123](http://wg21.link/p0123) |
- `string_span` | ✓ | ✓ | ✓ | `basic_string_span< char >` |
- `wstring_span` | - | ✓ | ✓ | `basic_string_span< wchar_t >` |
- `cstring_span` | ✓ | ✓ | ✓ | `basic_string_span< const char >` |
- `cwstring_span` | - | ✓ | ✓ | `basic_string_span< const wchar_t >` |
- `zstring_span` | - | ✓ | ✓ | `basic_zstring_span< char >` |
- `wzstring_span` | - | ✓ | ✓ | `basic_zstring_span< wchar_t >` |
- `czstring_span` | - | ✓ | ✓ | `basic_zstring_span< const char >` |
- `cwzstring_span` | - | ✓ | ✓ | `basic_zstring_span< const wchar_t >` |
- `ensure_z()` | - | ✓ | ✓ | Create a `cstring_span` or `cwstring_span` |
- `to_string()` | - | ✓ | ✓ | Convert a `string_span` to `std::string` or `std::wstring` |
- **2.3 Indexing** | | | | |
- `at()` | ✓ | ✓ | ≥ C++11 | Bounds-checked way of accessing<br>static arrays, `std::array<>`, `std::vector<>` |
- `at()` | - | - | < C++11 | static arrays, `std::vector<>`<br>`std::array<>` : VC11 |
- **3. Assertions** | | | | |
- `Expects()` | ✓ | ✓ | ✓ | Precondition assertion |
- `Ensures()` | ✓ | ✓ | ✓ | Postcondition assertion |
- `gsl_Expects()` | - | - | ✓ | Precondition assertion |
- `gsl_Ensures()` | - | - | ✓ | Postcondition assertion |
- `gsl_ExpectsAudit()` | - | - | ✓ | Audit-level precondition assertion |
- `gsl_EnsuresAudit()` | - | - | ✓ | Audit-level postcondition assertion |
- **4. Utilities** | | | | |
- `index` | ✓ | ✓ | ✓ | type for container indexes and subscripts, <br>see [Other configuration macros](#other-configuration-macros) |
- `dim` | - | - | ✓ | type for container sizes |
- `stride` | - | - | ✓ | type for index strides |
- `diff` | - | - | ✓ | type for index differences |
- `byte` | - | ✓ | ✓ | byte type, see also proposal [p0298](http://wg21.link/p0298) |
- `final_action<>` | ✓ | ✓ | ≥ C++11 | Action at the end of a scope |
- `final_action` | - | - | < C++11 | Currently only `void(*)()` |
- `finally()` | ✓ | ✓ | ≥ C++11 | Make a `final_action<>` |
- `finally()` | - | - | < C++11 | Make a `final_action` |
- `final_action_return` | - | - | < C++11 | Currently only `void(*)()`, [experimental](#feature-selection-macros) |
- `on_return()` | - | - | ≥ C++11 | Make a `final_action_return<>, [experimental](#feature-selection-macros) |
- `on_return()` | - | - | < C++11 | Make a `final_action_return, [experimental](#feature-selection-macros) |
- `final_action_error` | - | - | < C++11 | Currently only `void(*)()`, [experimental](#feature-selection-macros) |
- `on_error()` | - | - | ≥ C++11 | Make a `final_action_error<>`, [experimental](#feature-selection-macros) |
- `on_error()` | - | - | < C++11 | Make a `final_action_error`, [experimental](#feature-selection-macros) |
- `narrow_cast<>` | ✓ | ✓ | ✓ | Searchable narrowing casts of values |
- `narrow<>()` | ✓ | ✓ | ✓ | Checked narrowing cast |
- `narrow_failfast<>()` | - | - | ✓ | Fail-fast narrowing cast |
- `[[implicit]]` | ✓ | - | C++?? | Symmetric with explicit |
- `implicit` | - | - | ✓ | Macro, see [Feature selection macros](#feature-selection-macros) |
- `move_owner` | ? | - | - | ... |
- **5. Algorithms** | | | | |
- `copy()` | | | | Copy from source span to destination span |
- `size()` | | | | Size of span, unsigned |
- `ssize()` | | | | Size of span, signed |
- **6. Concepts** | | | | |
- ... | | | | |
- Note: *gsl-lite* treats VC12 (VS2013) and VC14 (VS2015) as C++11 (`gsl_CPP11_OR_GREATER`: 1).
- Deprecation
- -----------
- The following features are deprecated since the indicated version. See macro [`gsl_CONFIG_DEPRECATE_TO_LEVEL`](#other-configuration-macros) on how to control deprecation using the indicated level.
- Version | Level | Feature / Notes |
- -------:|:-----:|:----------------|
- 0.37.0 | 6 | `as_writeable_bytes()`, call indexing for spans, and `span::at()` |
- | | `as_writable_bytes()`, subscript indexing is used |
- 0.35.0 | - | `gsl_CONFIG_CONTRACT_LEVEL_ON`, `gsl_CONFIG_CONTRACT_LEVEL_OFF`, `gsl_CONFIG_CONTRACT_LEVEL_EXPECTS_ONLY` and `gsl_CONFIG_CONTRACT_LEVEL_ENSURES_ONLY` |
- | | Use `gsl_CONFIG_CONTRACT_CHECKING_ON`, `gsl_CONFIG_CONTRACT_CHECKING_OFF`, `gsl_CONFIG_CONTRACT_CHECKING_ENSURES_OFF`, `gsl_CONFIG_CONTRACT_CHECKING_EXPECTS_OFF` |
- 0.31.0 | 5 | `span( std::nullptr_t, index_type )` |
- | | `span( pointer, index_type )` is used |
- 0.31.0 | 5 | `span( U *, index_type size )` |
- | | `span( pointer, index_type )` is used |
- 0.31.0 | 5 | `span( U (&arr)[N] )` |
- | | `span( element_type (&arr)[N] )` is used |
- 0.31.0 | 5 | `span( std::array< U, N > [const] & arr )` |
- | | `span( std::array< value_type, N > [const] & arr )` is used |
- 0.29.0 | 4 | `span( std::shared_ptr<T> const & p )` |
- | | — |
- 0.29.0 | 4 | `span( std::unique_ptr<T> const & p )` |
- | | — |
- 0.29.0 | 3 | `span<>::length()` |
- | | Use `span<>::size()` |
- 0.29.0 | 3 | `span<>::length_bytes()` |
- | | Use `span<>::size_bytes()` |
- 0.17.0 | 2 | member `span<>::as_bytes()`, `span<>::as_writeable_bytes()` |
- | | — |
- 0.7.0 | - | `gsl_CONFIG_ALLOWS_SPAN_CONTAINER_CTOR` |
- | | Use `gsl_CONFIG_ALLOWS_UNCONSTRAINED_SPAN_CONTAINER_CTOR`,<br>or consider `span(with_container, cont)`. |
- Reported to work with
- ---------------------
- The table below mentions the compiler versions and platforms *gsl-lite* is reported to work with.
- Compiler | OS | Platforms | Versions | CI |
- --------------------:|:----------------|-----------|------------------:|----|
- GCC | Linux | x64 | 4.7 and newer | [4.7, 4.8, 4.9, 5](https://travis-ci.com/gsl-lite/gsl-lite/), [6, 7, 8, 9, 10](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- GCC (MinGW) | Windows | x86, x64 | 4.8.4 and newer | |
- GCC (DJGPP) | DOSBox, FreeDOS | x86 | 7.2 | |
- GCC | MacOS | x64 | 6 and newer | [6, 7, 8, 9, 10](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- Clang | Linux | x64 | 3.5 and newer | [3.5, 3.6, 3.7, 3.8, 3.9](https://travis-ci.com/gsl-lite/gsl-lite/), [4, 5, 6, 7, 8, 9, 10](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- Clang | Windows | x64 | 9 and newer | [9, 10](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- MSVC (Visual Studio) | Windows | x86, x64 | VS 2010 and newer | VS [2010, 2012, 2013, 2015](https://ci.appveyor.com/project/gsl-lite/gsl-lite), [2017, 2019](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- AppleClang (Xcode) | MacOS | x64 | 7.3 and newer | [7.3, 8, 8.1, 9](https://travis-ci.com/gsl-lite/gsl-lite/), [9.1, 10, 10.0.1, 11, 11.0.3](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- NVCC (CUDA Toolkit) | Linux, Windows | x64 | 10.2 and newer | [10.2, 11.0](https://dev.azure.com/gsl-lite/gsl-lite/_build?definitionId=1) |
- Building the tests
- ------------------
- To build the tests:
- - [CMake](http://cmake.org), version 3.15 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 [*gsl-lite* source code](https://github.com/gsl-lite/gsl-lite) has been cloned into a directory named `C:\gsl-lite`.
- 1. Create a directory for the build outputs.
- Here we use `C:\gsl-lite\build`.
- cd C:\gsl-lite
- mkdir build
- cd build
- 2. Configure the build directory with CMake:
- cmake -DGSL_LITE_OPT_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug ..
- 3. Build the test suite:
- cmake --build . --config Debug
- 4. Run the test suite:
- ctest -V -C Debug
- All tests should pass, indicating your platform is supported and you are ready to use *gsl-lite*. See the table with [supported types and functions](#features).
- Other GSL implementations
- -------------------------
- - Microsoft. [Guidelines Support Library (GSL)](https://github.com/microsoft/GSL).
- - Vicente J. Botet Escriba. [Guidelines Support Library (GSL)](https://github.com/viboes/GSL).
- Notes and references
- --------------------
- ### Proposals, specification
- [1] [`std::span<>` on cppreference](https://en.cppreference.com/w/cpp/container/span).
- [2] [`std::span<>` in C++20 Working Draft](http://eel.is/c++draft/views).
- [3] [P0091 - Template argument deduction for class templates](http://wg21.link/p0091).
- [4] [P0122 - span: bounds-safe views for sequences of objects](http://wg21.link/p0122).
- [5] [P0123 - string_span: bounds-safe views for sequences of characters](http://wg21.link/p0123).
- [6] [P0298 - A byte type definition](http://wg21.link/p0298).
- [7] [P0805 - Comparing Containers](http://wg21.link/p0805).
- ### Articles
- [8] [Standard C++ Foundation](https://isocpp.org/).
- [9] Standard C++ Foundation. [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines).
- [10] Microsoft. [Guidelines Support Library (GSL)](https://github.com/microsoft/gsl).
- [11] Bjarne Stroustrup. [Writing good C++14 (PDF)](https://github.com/isocpp/CppCoreGuidelines/raw/master/talks/Stroustrup%20-%20CppCon%202015%20keynote.pdf) — [Video](https://www.youtube.com/watch?t=9&v=1OEu9C51K2A). CppCon 2015.
- [12] Herb Sutter. [Writing good C++14… By default (PDF)](https://github.com/isocpp/CppCoreGuidelines/raw/master/talks/Sutter%20-%20CppCon%202015%20day%202%20plenary%20.pdf) — [Video](https://www.youtube.com/watch?v=hEx5DNLWGgA). CppCon 2015.
- [13] Gabriel Dos Reis. [Contracts for Dependable C++ (PDF)](https://github.com/isocpp/CppCoreGuidelines/raw/master/talks/Contracts-for-Dependable-C%2B%2B.pdf) — Video. CppCon 2015.
- [14] Bjarne Stroustrup et al. [A brief introduction to C++’s model for type- and resource-safety](https://github.com/isocpp/CppCoreGuidelines/raw/master/docs/Introduction%20to%20type%20and%20resource%20safety.pdf).
- [15] Herb Sutter and Neil MacIntosh. [Lifetime Safety: Preventing Leaks and Dangling](https://github.com/isocpp/CppCoreGuidelines/raw/master/docs/Lifetimes%20I%20and%20II%20-%20v0.9.1.pdf). 21 Sep 2015.
- ### Compiler feature testing
- [16] cppreference.com. [Feature testing](https://en.cppreference.com/w/cpp/feature_test).
- ### C++ features in various compilers
- [17] cppreference.com. [C++ compiler support](https://en.cppreference.com/w/cpp/compiler_support).
- Appendix
- --------
- <a id="a1"></a>
- ### A.1 Compile-time information
- In the test runner, the version of *gsl-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 id="a2"></a>
- ### A.2 *gsl-lite* test specification
- <details>
- <summary>click to expand</summary>
- <p>
- ```
- gsl_Expects(): Allows a true expression
- gsl_Ensures(): Allows a true expression
- gsl_Expects(): Terminates on a false expression
- gsl_Ensures(): Terminates on a false expression
- gsl_ExpectsAudit(): Allows a true expression
- gsl_EnsuresAudit(): Allows a true expression
- gsl_ExpectsAudit(): Terminates on a false expression in AUDIT mode
- gsl_EnsuresAudit(): Terminates on a false expression in AUDIT mode
- at(): Terminates access to non-existing C-array elements
- at(): Terminates access to non-existing std::array elements (C++11)
- at(): Terminates access to non-existing std::vector elements
- at(): Terminates access to non-existing std::initializer_list elements (C++11)
- at(): Terminates access to non-existing gsl::span elements
- at(): Allows to access existing C-array elements
- at(): Allows to access existing std::array elements (C++11)
- at(): Allows to access existing std::vector elements
- at(): Allows to access std::initializer_list elements (C++11)
- at(): Allows to access gsl::span elements
- byte: Allows to construct from integral via static cast (C++17)
- byte: Allows to construct from integral via byte() (C++17)
- byte: Allows to construct from integral via to_byte()
- byte: Allows to convert to integral via to_integer()
- byte: Allows comparison operations
- byte: Allows bitwise or operation
- byte: Allows bitwise and operation
- byte: Allows bitwise x-or operation
- byte: Allows bitwise or assignment
- byte: Allows bitwise and assignment
- byte: Allows bitwise x-or assignment
- byte: Allows shift-left operation
- byte: Allows shift-right operation
- byte: Allows shift-left assignment
- byte: Allows shift-right assignment
- byte: Provides constexpr non-assignment operations (C++11)
- byte: Provides constexpr assignment operations (C++14)
- byte: Provides hash support (C++11)
- conjunction<> and disjunction<>: Short-circuiting is handled correctly
- conjunction<> and disjunction<>: First suitable type is chosen as base
- span<>: free comparation functions fail for different const-ness [issue #32]
- span<>: constrained container constructor suffers hard failure for arguments with reference-returning data() function [issue #242]
- byte: aliasing rules lead to undefined behaviour when using enum class [issue #34](GSL issue #313, PR #390)
- string_span<>: must not include terminating '\0' [issue #53]
- string_span<>: to_string triggers SFINAE errors on basic_string_span's move & copy constructor with Clang-3.9 (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS) [issue #53a]
- narrow<>(): Allows narrowing double to float without MSVC level 4 warning C4127: conditional expression is constant [issue #115]
- detail::is_compatible_container<>: Not a proper type trait [PR #238]
- not_null<>: Disallows default construction (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
- not_null<>: Disallows construction from nullptr_t, NULL or 0 (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
- not_null<>: Disallows construction from a unique pointer to underlying type (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
- not_null<>: Layout is compatible to underlying type
- not_null<>: Convertibility is correctly reported by type traits
- not_null<>: Copyability and assignability are correctly reported by type traits
- not_null<>: Disallows assignment from unrelated pointers (define gsl_CONFIG_CONFIRMS_COMPILATION_ERRORS)
- not_null<>: Terminates construction from a null pointer value (raw pointer)
- not_null<>: Terminates construction from related pointer types for null pointer value (raw pointer)
- not_null<>: Terminates assignment from a null pointer value (raw pointer)
- not_null<>: Terminates assignment from related pointer types for null pointer value (raw pointer)
- not_null<>: Allows to construct from a non-null underlying pointer (raw pointer)
- not_null<>: Returns underlying pointer with get() (raw point…