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.