From a9ffcf7f6539368a44f121f404f0bcb0bb8b064c Mon Sep 17 00:00:00 2001 From: Krystian Kuzniarek Date: Sun, 15 Sep 2019 16:41:38 +0200 Subject: [PATCH 1/2] add a table of features --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 99a0d34..2e3c055 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,6 @@ The Guidelines Support Library (GSL) contains functions and types that are sugge [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) maintained by the [Standard C++ Foundation](https://isocpp.org). This repo contains Microsoft's implementation of GSL. -The library includes types like `span`, `string_span`, `owner<>` and others. - The entire implementation is provided inline in the headers under the [gsl](./include/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](./include/gsl/span)), @@ -21,6 +19,69 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope # Usage of Third Party Libraries This project makes use of the [Google Test](https://github.com/google/googletest) testing library. Please see the [ThirdPartyNotices.txt](./ThirdPartyNotices.txt) file for details regarding the licensing of Google Test. +# Supported features +GSL implements the following utilities: + +Feature | Supported? | Description +-----------------------------------|:----------:|------------- +[**1. Views**][cg-views] | | +owner | ☑ | an alias for a raw pointer for its better expressiveness +not_null | ☑ | restricts a pointer / smart pointer to hold non-null values +strict_not_null | ☑ | a stricter version of `not_null` with explicit constructors +span | ☑ | spans a range starting from a pointer to pointer + size +span_p | ☐ | spans a range starting from a pointer to the first place for which the predicate is true +multi_span | ☑ | spans a contiguous region of memory, which represents a multidimensional array +strided_span | ☑ | **I HAVE NO IDEA WHAT IT DOES, ANYONE???!!!** +basic_zstring | ☑ | a pointer to a C-string (zero-terminated array) with a templated char type +zstring | ☑ | an alias to `basic_zstring` where the char type is char +wzstring | ☑ | an alias to `basic_zstring` where the char type is wchar_t +czstring | ☑ | like `zstring` but the char type is also const +cwzstring | ☑ | like `wzstring` but the char type is also const +u16zstring | ☑ | an alias to `basic_zstring` where the char type is char16_t +cu16zstring | ☑ | like `u16zstring` but the char type is also const +u32zstring | ☑ | an alias to `basic_zstring` where the char type is char32_t +cu32zstring | ☑ | like `u32zstring` but the char type is also const +basic_string_span | ☑ | like `span` but for strings with a templated string type +string_span | ☑ | an alias to `basic_string_span` where the char type is char +cstring_span | ☑ | like `string_span` but the char type is also const +wstring_span | ☑ | an alias to `basic_string_span` where the char type is wchar_t +cwstring_span | ☑ | like `wstring_span` but the char type is also const +u16string_span | ☑ | an alias to `basic_string_span` where the char type is char16_t +cu16string_span | ☑ | like `u16string_span` but the char type is also const +u32string_span | ☑ | an alias to `basic_string_span` where the char type is char32_t +cu32string_span | ☑ | like `u32string_span` but the char type is also const +[**2. Owners**][cg-owners] | | +unique_ptr | ☑ | an alias to `std::unique_ptr` +shared_ptr | ☑ | an alias to `std::shared_ptr` +stack_array | ☐ | a stack-allocated array +dyn_array | ☐ | a heap-allocated array +[**3. Assertions**][cg-assertions] | | +Expects | ☑ | a precondition assertion; on failure it either terminates or throws `fail_fast` +Ensures | ☑ | a postcondition assertion; on failure it either terminates or throws `fail_fast` +[**4. Utitilies**][cg-utilities] | | +move_owner | ☐ | a helper function that moves one `owner` to the other +release_owner | ☐ | a helper function that releases ownership of the passed `owner` and returns a new `owner` +byte | ☑ | either an alias to std::byte or a byte type +fail_fast | ☑ | a custom exception type thrown by assertions +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 tries to turn it into `[[gsl::suppress(x)]]` +[[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) +joining_thread | ☐ | a RAII style version of `std::thread` that joins +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**][cg-concepts] | ☐ | + +This is based on [CppCoreGuidelines semi-specification](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gsl-guidelines-support-library). + +[cg-views]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views +[cg-owners]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslowner-ownership-pointers +[cg-assertions]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslassert-assertions +[cg-utilities]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslutil-utilities +[cg-concepts]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslconcept-concepts + # Quick Start ## Supported Compilers The GSL officially supports the current and previous major release of MSVC, GCC, Clang, and XCode's Apple-Clang. From dad3d80c2582acc1ff26401f81c4093656eaadeb Mon Sep 17 00:00:00 2001 From: Jordan Maples Date: Wed, 12 Aug 2020 16:22:03 -0700 Subject: [PATCH 2/2] Update README.md Rearranged and updated the table. Added a second table of concepts that exist in the Microsoft GSL that do not exist in the C++ Core Guidelines --- README.md | 56 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 2e3c055..54b3fb5 100644 --- a/README.md +++ b/README.md @@ -20,52 +20,48 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope This project makes use of the [Google Test](https://github.com/google/googletest) testing library. Please see the [ThirdPartyNotices.txt](./ThirdPartyNotices.txt) file for details regarding the licensing of Google Test. # Supported features -GSL implements the following utilities: +## Microsoft GSL implements the following from the C++ Core Guidelines: Feature | Supported? | Description -----------------------------------|:----------:|------------- [**1. Views**][cg-views] | | -owner | ☑ | an alias for a raw pointer for its better expressiveness +owner | ☑ | an alias for a raw pointer not_null | ☑ | restricts a pointer / smart pointer to hold non-null values strict_not_null | ☑ | a stricter version of `not_null` with explicit constructors -span | ☑ | spans a range starting from a pointer to pointer + size +span | ☑ | a view over a contiguous sequence of memory. Based on the standardized verison 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 -multi_span | ☑ | spans a contiguous region of memory, which represents a multidimensional array -strided_span | ☑ | **I HAVE NO IDEA WHAT IT DOES, ANYONE???!!!** basic_zstring | ☑ | a pointer to a C-string (zero-terminated array) with a templated char type -zstring | ☑ | an alias to `basic_zstring` where the char type is char -wzstring | ☑ | an alias to `basic_zstring` where the char type is wchar_t -czstring | ☑ | like `zstring` but the char type is also const -cwzstring | ☑ | like `wzstring` but the char type is also const -u16zstring | ☑ | an alias to `basic_zstring` where the char type is char16_t -cu16zstring | ☑ | like `u16zstring` but the char type is also const -u32zstring | ☑ | an alias to `basic_zstring` where the char type is char32_t -cu32zstring | ☑ | like `u32zstring` but the char type is also const -basic_string_span | ☑ | like `span` but for strings with a templated string type -string_span | ☑ | an alias to `basic_string_span` where the char type is char -cstring_span | ☑ | like `string_span` but the char type is also const -wstring_span | ☑ | an alias to `basic_string_span` where the char type is wchar_t -cwstring_span | ☑ | like `wstring_span` but the char type is also const -u16string_span | ☑ | an alias to `basic_string_span` where the char type is char16_t -cu16string_span | ☑ | like `u16string_span` but the char type is also const -u32string_span | ☑ | an alias to `basic_string_span` where the char type is char32_t -cu32string_span | ☑ | like `u32string_span` but the char type is also const +zstring | ☑ | an alias to `basic_zstring` with a char type of char +czstring | ☑ | an alias to `basic_zstring` with a char type of const char +wzstring | ☑ | an alias to `basic_zstring` with a char type of wchar_t +cwzstring | ☑ | an alias to `basic_zstring` with a char type of const wchar_t +u16zstring | ☑ | an alias to `basic_zstring` with a char type of char16_t +cu16zstring | ☑ | an alias to `basic_zstring` with a char type of const char16_t +u32zstring | ☑ | an alias to `basic_zstring` with a char type of char32_t +cu32zstring | ☑ | an alias to `basic_zstring` with a char type of const char32_t +basic_string_span | ☑ | like `span` but for strings with a templated char type +string_span | ☑ | an alias to `basic_string_span` with a char type of char +cstring_span | ☑ | an alias to `basic_string_span` with a char type of const char +wstring_span | ☑ | an alias to `basic_string_span` with a char type of wchar_t +cwstring_span | ☑ | an alias to `basic_string_span` with a char type of const wchar_t +u16string_span | ☑ | an alias to `basic_string_span` with a char type of char16_t +cu16string_span | ☑ | an alias to `basic_string_span` with a char type of const char16_t +u32string_span | ☑ | an alias to `basic_string_span` with a char type of char32_t +cu32string_span | ☑ | an alias to `basic_string_span` with a char type of const char32_t [**2. Owners**][cg-owners] | | unique_ptr | ☑ | an alias to `std::unique_ptr` shared_ptr | ☑ | an alias to `std::shared_ptr` stack_array | ☐ | a stack-allocated array dyn_array | ☐ | a heap-allocated array [**3. Assertions**][cg-assertions] | | -Expects | ☑ | a precondition assertion; on failure it either terminates or throws `fail_fast` -Ensures | ☑ | a postcondition assertion; on failure it either terminates or throws `fail_fast` +Expects | ☑ | a precondition assertion; on failure it terminates +Ensures | ☑ | a postcondition assertion; on failure it terminates [**4. Utitilies**][cg-utilities] | | move_owner | ☐ | a helper function that moves one `owner` to the other -release_owner | ☐ | a helper function that releases ownership of the passed `owner` and returns a new `owner` byte | ☑ | either an alias to std::byte or a byte type -fail_fast | ☑ | a custom exception type thrown by assertions 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 tries to turn it into `[[gsl::suppress(x)]]` +GSL_SUPPRESS | ☑ | a macro that takes an argument and turns it into `[[gsl::suppress(x)]]` or `[[gsl::suppress("x")]]` [[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) joining_thread | ☐ | a RAII style version of `std::thread` that joins @@ -74,6 +70,12 @@ narrow_cast | ☑ | a narrowing cast for values an narrowing_error | ☑ | a custom exception type thrown by `narrow()` [**5. Concepts**][cg-concepts] | ☐ | +## The following features do not exist in C++ Core Guidelines: +Feature | Supported? | Description +-----------------------------------|:----------:|------------- +multi_span | ☐ | Deprecated. Support for this type has been discontinued. +strided_span | ☐ | Deprecated. Support for this type has been discontinued. + This is based on [CppCoreGuidelines semi-specification](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gsl-guidelines-support-library). [cg-views]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views