Merge 49371c5f298707209c5f947bec747558bcd955a6 into 2828399820ef4928cc89b65605dca5dc68efca6e

- A macro with the very generic name `BYTE_TYPE` is likely to collide with existing code, so get rid of the macro.
- The new solution is to provide a non-deprecated `byte` in the namespace `gsl::impl`.
  - Users of GSL should use `gsl::byte`, which is still deprecated when mapped to a `std::std::byte`.
  - GSL types and functions need to use `gsl::impl::byte` so they do not trigger the deprecation warning.
- The `gsl::impl::byte` return type in an exported function is not nice, it might mislead users to use that type in their own declarations. But the `BYTE_TYPE` solution is not better in this respect.

Co-authored-by: Werner Henze <w.henze@avm.de>

README.md

@@ -74,12 +74,12 @@ u32string_span                     | ☐   | Deprecated. An alias to `basic
 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
------------------------------------|------------------|------
-gsl::unique_ptr                    | C++11            | Use std::unique_ptr instead.
-gsl::shared_ptr                    | C++11            | Use std::shared_ptr instead.
-gsl::byte                          | C++17            | Use std::byte instead.
-gsl:joining_thread                 | C++20 (Note: Not yet implemented in GSL) | Use std::jthread instead.
+Feature                                                           | Deprecated Since | Notes
+------------------------------------------------------------------|------------------|------
+[unique_ptr](docs/headers.md#user-content-H-pointers-unique_ptr)  | C++11            | Use std::unique_ptr instead.
+[shared_ptr](docs/headers.md#user-content-H-pointers-shared_ptr)  | C++11            | Use std::shared_ptr instead.
+[byte](docs/headers.md#user-content-H-byte-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](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gsl-guidelines-support-library).
 

docs/headers.md

@@ -230,7 +230,7 @@ See [F.23: Use a `not_null<T>` to indicate that “null” is not a valid value]
 using element_type = T;
 ```
 
-The type of the pointed-to object.
+The type of the pointer or smart pointer that is managed by this object.
 
 #### Member functions
 

include/gsl/byte

@@ -74,12 +74,6 @@
 #define byte_may_alias
 #endif // defined __clang__ || defined __GNUC__
 
-#if GSL_USE_STD_BYTE
-#define BYTE_TYPE std::byte
-#else // !GSL_USE_STD_BYTE
-#define BYTE_TYPE byte
-#endif // GSL_USE_STD_BYTE
-
 #if GSL_USE_STD_BYTE
 #include <cstddef>
 #endif
@@ -88,6 +82,12 @@ namespace gsl
 {
 #if GSL_USE_STD_BYTE
 
+namespace impl {
+// impl::byte is used by gsl::as_bytes so our own code does not trigger a deprecation warning as would be the case when we used gsl::byte.
+// Users of GSL should only use gsl::byte, not gsl::impl::byte.
+using byte = std::byte;
+}
+
 using byte GSL_DEPRECATED("Use std::byte instead.") = std::byte;
 
 using std::to_integer;
@@ -100,6 +100,12 @@ enum class byte_may_alias byte : unsigned char
 {
 };
 
+namespace impl {
+// impl::byte is used by gsl::as_bytes so our own code does not trigger a deprecation warning as would be the case when we used gsl::byte.
+// Users of GSL should only use gsl::byte, not gsl::impl::byte.
+using byte = gsl::byte;
+}
+
 template <class IntegerType, std::enable_if_t<std::is_integral<IntegerType>::value, bool> = true>
 constexpr byte& operator<<=(byte& b, IntegerType shift) noexcept
 {
@@ -168,20 +174,20 @@ constexpr IntegerType to_integer(byte b) noexcept
 template <typename T>
 // NOTE: need suppression since c++14 does not allow "return {t}"
 // GSL_SUPPRESS(type.4) // NO-FORMAT: attribute // TODO: suppression does not work
-constexpr BYTE_TYPE to_byte(T t) noexcept
+constexpr gsl::impl::byte to_byte(T t) noexcept
 {
     static_assert(std::is_same<T, unsigned char>::value,
                   "gsl::to_byte(t) must be provided an unsigned char, otherwise data loss may occur. "
                   "If you are calling to_byte with an integer constant use: gsl::to_byte<t>() version.");
-    return BYTE_TYPE(t);
+    return gsl::impl::byte(t);
 }
 
 template <int I>
-constexpr BYTE_TYPE to_byte() noexcept
+constexpr gsl::impl::byte to_byte() noexcept
 {
     static_assert(I >= 0 && I <= 255,
                   "gsl::byte only has 8 bits of storage, values must be in range 0-255");
-    return static_cast<BYTE_TYPE>(I);
+    return static_cast<gsl::impl::byte>(I);
 }
 
 } // namespace gsl

include/gsl/span

@@ -18,7 +18,7 @@
 #define GSL_SPAN_H
 
 #include "./assert"   // for Expects
-#include "./byte"     // for BYTE_TYPE
+#include "./byte"     // for gsl::impl::byte
 #include "./span_ext" // for span specialization of gsl::at and other span-related extensions
 #include "./util"     // for narrow_cast
 
@@ -824,28 +824,28 @@ namespace details
 
 // [span.objectrep], views of object representation
 template <class ElementType, std::size_t Extent>
-span<const BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>
+span<const gsl::impl::byte, details::calculate_byte_size<ElementType, Extent>::value>
 as_bytes(span<ElementType, Extent> s) noexcept
 {
-    using type = span<const BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>;
+    using type = span<const gsl::impl::byte, details::calculate_byte_size<ElementType, Extent>::value>;
 
     // clang-format off
     GSL_SUPPRESS(type.1) // NO-FORMAT: attribute
     // clang-format on
-    return type{reinterpret_cast<const BYTE_TYPE*>(s.data()), s.size_bytes()};
+    return type{reinterpret_cast<const gsl::impl::byte*>(s.data()), s.size_bytes()};
 }
 
 template <class ElementType, std::size_t Extent,
           std::enable_if_t<!std::is_const<ElementType>::value, int> = 0>
-span<BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>
+span<gsl::impl::byte, details::calculate_byte_size<ElementType, Extent>::value>
 as_writable_bytes(span<ElementType, Extent> s) noexcept
 {
-    using type = span<BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>;
+    using type = span<gsl::impl::byte, details::calculate_byte_size<ElementType, Extent>::value>;
 
     // clang-format off
     GSL_SUPPRESS(type.1) // NO-FORMAT: attribute
     // clang-format on
-    return type{reinterpret_cast<BYTE_TYPE*>(s.data()), s.size_bytes()};
+    return type{reinterpret_cast<gsl::impl::byte*>(s.data()), s.size_bytes()};
 }
 
 } // namespace gsl