deprecate features adopted into C++ (#1198)

* deprecated features adopted into C++

1) Mark the following GSL features as deprecated:
 - gsl::unique_ptr (always)
 - gsl::shared_ptr (always)
 - gsl::byte (since c++17)
 - gsl::joining_thread (never implemented)
2) Refactor existing deprecations to use the new GSL_DEPRECATED(msg) macro.
3) Create a section in the README for deprecated features in the
   standard.

* do not deprecate gsl::to_integer because we never claim to implement it.

* do not use gsl::byte if it is deprecated

README.md

@@ -40,8 +40,6 @@ span_p                                                                   | &#x26
 [u32zstring](docs/headers.md#user-content-H-zstring)                     | ☑   | An alias to `basic_zstring` with dynamic extent and a char type of `char32_t`
 [cu32zstring](docs/headers.md#user-content-H-zstring)                    | ☑   | An alias to `basic_zstring` with dynamic extent and a char type of `const char32_t`
 [**2. Owners**][cg-owners]                                               |            |
-[unique_ptr](docs/headers.md#user-content-H-pointers-unique_ptr)         | ☑   | An alias to `std::unique_ptr`
-[shared_ptr](docs/headers.md#user-content-H-pointers-shared_ptr)         | ☑   | An alias to `std::shared_ptr`
 stack_array                                                              | ☐   | A stack-allocated array
 dyn_array                                                                | ☐   | A heap-allocated array
 [**3. Assertions**][cg-assertions]                                       |            |
@@ -49,13 +47,11 @@ dyn_array                                                                | &#x26
 [Ensures](docs/headers.md#user-content-H-assert-ensures)                 | ☑   | A postcondition assertion; on failure it terminates
 [**4. Utilities**][cg-utilities]                                         |            |
 move_owner                                                               | ☐   | A helper function that moves one `owner` to the other
-[byte](docs/headers.md#user-content-H-byte-byte)                         | ☑   | Either an alias to `std::byte` or a byte type
 [final_action](docs/headers.md#user-content-H-util-final_action)         | ☑   | A RAII style class that invokes a functor on its destruction
 [finally](docs/headers.md#user-content-H-util-finally)                   | ☑   | A helper function instantiating [final_action](docs/headers.md#user-content-H-util-final_action)
 [GSL_SUPPRESS](docs/headers.md#user-content-H-assert-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](docs/headers.md#user-content-H-util-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](docs/headers.md#user-content-H-narrow-narrow)                   | ☑   | A checked version of `narrow_cast`; it can throw [narrowing_error](docs/headers.md#user-content-H-narrow-narrowing_error)
 [narrow_cast](docs/headers.md#user-content-H-util-narrow_cast)           | ☑   | A narrowing cast for values and a synonym for `static_cast`
 [narrowing_error](docs/headers.md#user-content-H-narrow-narrowing_error) | ☑   | A custom exception type thrown by [narrow](docs/headers.md#user-content-H-narrow-narrow)
@@ -77,6 +73,14 @@ cu16string_span                    | ☐   | Deprecated. An alias to `basic
 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
+-----------------------------------|------------------|------
+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.
+
 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

include/gsl/byte

@@ -17,6 +17,8 @@
 #ifndef GSL_BYTE_H
 #define GSL_BYTE_H
 
+#include "./util" // for GSL_DEPRECATED
+
 #include <type_traits>
 
 #ifdef _MSC_VER
@@ -72,6 +74,12 @@
 #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
@@ -80,7 +88,8 @@ namespace gsl
 {
 #if GSL_USE_STD_BYTE
 
-using std::byte;
+using byte GSL_DEPRECATED("Use std::byte instead.") = std::byte;
+
 using std::to_integer;
 
 #else // GSL_USE_STD_BYTE
@@ -155,23 +164,24 @@ constexpr IntegerType to_integer(byte b) noexcept
 
 #endif // GSL_USE_STD_BYTE
 
+
 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 to_byte(T t) noexcept
+constexpr BYTE_TYPE 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(t);
+    return BYTE_TYPE(t);
 }
 
 template <int I>
-constexpr byte to_byte() noexcept
+constexpr BYTE_TYPE 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>(I);
+    return static_cast<BYTE_TYPE>(I);
 }
 
 } // namespace gsl

include/gsl/pointers

@@ -18,6 +18,7 @@
 #define GSL_POINTERS_H
 
 #include "./assert" // for Ensures, Expects
+#include "./util" // for GSL_DEPRECATED
 
 #include <cstddef>      // for ptrdiff_t, nullptr_t, size_t
 #include <functional>   // for less, greater
@@ -62,8 +63,11 @@ namespace details
 //
 // GSL.owner: ownership pointers
 //
-using std::shared_ptr;
-using std::unique_ptr;
+template <typename... Ts>
+using shared_ptr GSL_DEPRECATED("Use std::shared_ptr instead") = std::shared_ptr<Ts...>;
+
+template <typename... Ts>
+using unique_ptr GSL_DEPRECATED("Use std::unique_ptr instead") = std::unique_ptr<Ts...>;
 
 //
 // owner

include/gsl/span

@@ -18,7 +18,7 @@
 #define GSL_SPAN_H
 
 #include "./assert"   // for Expects
-#include "./byte"     // for byte
+#include "./byte"     // for BYTE_TYPE
 #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, details::calculate_byte_size<ElementType, Extent>::value>
+span<const BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>
 as_bytes(span<ElementType, Extent> s) noexcept
 {
-    using type = span<const byte, details::calculate_byte_size<ElementType, Extent>::value>;
+    using type = span<const BYTE_TYPE, 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*>(s.data()), s.size_bytes()};
+    return type{reinterpret_cast<const BYTE_TYPE*>(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, details::calculate_byte_size<ElementType, Extent>::value>
+span<BYTE_TYPE, details::calculate_byte_size<ElementType, Extent>::value>
 as_writable_bytes(span<ElementType, Extent> s) noexcept
 {
-    using type = span<byte, details::calculate_byte_size<ElementType, Extent>::value>;
+    using type = span<BYTE_TYPE, 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*>(s.data()), s.size_bytes()};
+    return type{reinterpret_cast<BYTE_TYPE*>(s.data()), s.size_bytes()};
 }
 
 } // namespace gsl

include/gsl/span_ext

@@ -123,14 +123,14 @@ constexpr span<const typename Container::value_type> make_span(const Container&
 }
 
 template <class Ptr>
-[[deprecated("This function is deprecated. See GSL issue #1092.")]]
+GSL_DEPRECATED("This function is deprecated. See GSL issue #1092.")
 constexpr span<typename Ptr::element_type> make_span(Ptr& cont, std::size_t count)
 {
     return span<typename Ptr::element_type>(cont, count);
 }
 
 template <class Ptr>
-[[deprecated("This function is deprecated. See GSL issue #1092.")]]
+GSL_DEPRECATED("This function is deprecated. See GSL issue #1092.")
 constexpr span<typename Ptr::element_type> make_span(Ptr& cont)
 {
     return span<typename Ptr::element_type>(cont);

include/gsl/util

@@ -60,6 +60,32 @@
 #define GSL_INLINE
 #endif
 
+#if defined(__has_cpp_attribute)
+#if __has_cpp_attribute(deprecated)
+#define GSL_DEPRECATED(msg) [[deprecated(msg)]]
+#endif // __has_cpp_attribute(deprecated)
+#endif // defined(__has_cpp_attribute)
+
+#if !defined(GSL_DEPRECATED)
+#if defined(__cplusplus)
+#if __cplusplus >= 201309L
+#define GSL_DEPRECATED(msg) [[deprecated(msg)]]
+#endif // __cplusplus >= 201309L
+#endif // defined(__cplusplus)
+#endif // !defined(GSL_DEPRECATED)
+
+#if !defined(GSL_DEPRECATED)
+#if defined(_MSC_VER)
+#define GSL_DEPRECATED(msg) __declspec(deprecated(msg))
+#elif defined(__GNUC__)
+#define GSL_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#endif // defined(_MSC_VER)
+#endif // !defined(GSL_DEPRECATED)
+
+#if !defined(GSL_DEPRECATED)
+#define GSL_DEPRECATED(msg)
+#endif // !defined(GSL_DEPRECATED)
+
 namespace gsl
 {
 //