GSL: Guidelines Support Library

The Guidelines Support Library (GSL) contains functions and types that are suggested for use by the C++ Core Guidelines maintained by the Standard C++ Foundation. This repo contains Microsoft's implementation of GSL.

The entire implementation is provided inline in the headers under the gsl directory. The implementation generally assumes a platform that implements C++14 support.

While some types have been broken out into their own headers (e.g. gsl/span), it is simplest to just include gsl/gsl and gain access to the entire library.

NOTE: We encourage contributions that improve or refine any of the types in this library as well as ports to other platforms. Please see CONTRIBUTING.md for more information about contributing.

Project Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Usage of Third Party Libraries

This project makes use of the Google Test testing library. Please see the ThirdPartyNotices.txt file for details regarding the licensing of Google Test.

Supported features

Microsoft GSL implements the following from the C++ Core Guidelines:

Feature | Supported? | Description -------------------------------------------------------------------------|:----------:|------------- 1. Views | | owner | ☑ | An alias for a raw pointer not_null | ☑ | Restricts a pointer/smart pointer to hold non-null values span | ☑ | A view over a contiguous sequence of memory. Based on the standardized version of std::span, however gsl::span enforces bounds checking. span_p | ☐ | Spans a range starting from a pointer to the first place for which the predicate is true basic_zstring | ☑ | A pointer to a C-string (zero-terminated array) with a templated char type zstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of char czstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of const char wzstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of wchar_t cwzstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of const wchar_t u16zstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of char16_t cu16zstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of const char16_t u32zstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of char32_t cu32zstring | ☑ | An alias to basic_zstring with dynamic extent and a char type of const char32_t 2. Owners | | stack_array | ☐ | A stack-allocated array dyn_array | ☐ | A heap-allocated array 3. Assertions | | Expects | ☑ | A precondition assertion; on failure it terminates Ensures | ☑ | A postcondition assertion; on failure it terminates 4. Utilities | | move_owner | ☐ | A helper function that moves one owner to the other final_action | ☑ | A RAII style class that invokes a functor on its destruction finally | ☑ | A helper function instantiating final_action GSL_SUPPRESS | ☑ | A macro that takes an argument and turns it into [[gsl::suppress(x)]] or [[gsl::suppress("x")]] depending on the compiler. [[implicit]] | ☐ | A "marker" to put on single-argument constructors to explicitly make them non-explicit index | ☑ | A type to use for all container and array indexing (currently an alias for std::ptrdiff_t) narrow | ☑ | A checked version of narrow_cast; it can throw narrowing_error narrow_cast | ☑ | A narrowing cast for values and a synonym for static_cast narrowing_error | ☑ | A custom exception type thrown by narrow 5. Concepts | ☐ |

The following features do not exist in or have been removed from the C++ Core Guidelines:

Feature | Supported? | Description -----------------------------------|:----------:|------------- strict_not_null | ☑ | A stricter version of not_null with explicit constructors multi_span | ☐ | Deprecated. Multi-dimensional span. strided_span | ☐ | Deprecated. Support for this type has been discontinued. basic_string_span | ☐ | Deprecated. Like span but for strings with a templated char type string_span | ☐ | Deprecated. An alias to basic_string_span with a char type of char cstring_span | ☐ | Deprecated. An alias to basic_string_span with a char type of const char wstring_span | ☐ | Deprecated. An alias to basic_string_span with a char type of wchar_t cwstring_span | ☐ | Deprecated. An alias to basic_string_span with a char type of const wchar_t u16string_span | ☐ | Deprecated. An alias to basic_string_span with a char type of char16_t cu16string_span | ☐ | Deprecated. An alias to basic_string_span with a char type of const char16_t u32string_span | ☐ | Deprecated. An alias to basic_string_span with a char type of char32_t cu32string_span | ☐ | Deprecated. An alias to basic_string_span with a char type of const char32_t

The following features have been adopted by WG21. They are deprecated in GSL.

Feature | Deprecated Since | Notes ------------------------------------------------------------------|------------------|------ unique_ptr | C++11 | Use std::unique_ptr instead. shared_ptr | C++11 | Use std::shared_ptr instead. byte | C++17 | Use std::byte instead. joining_thread | C++20 (Note: Not yet implemented in GSL) | Use std::jthread instead.

This is based on CppCoreGuidelines semi-specification.