legacy-libs/grpc-cloned/deps/grpc/third_party/abseil-cpp/absl/utility/utility.h

   1 // Copyright 2017 The Abseil Authors.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 //
  15 // This header file contains C++11 versions of standard <utility> header
  16 // abstractions available within C++14 and C++17, and are designed to be drop-in
  17 // replacement for code compliant with C++14 and C++17.
  18 //
  19 // The following abstractions are defined:
  20 //
  21 //   * integer_sequence<T, Ints...>  == std::integer_sequence<T, Ints...>
  22 //   * index_sequence<Ints...>       == std::index_sequence<Ints...>
  23 //   * make_integer_sequence<T, N>   == std::make_integer_sequence<T, N>
  24 //   * make_index_sequence<N>        == std::make_index_sequence<N>
  25 //   * index_sequence_for<Ts...>     == std::index_sequence_for<Ts...>
  26 //   * apply<Functor, Tuple>         == std::apply<Functor, Tuple>
  27 //   * exchange<T>                   == std::exchange<T>
  28 //   * make_from_tuple<T>            == std::make_from_tuple<T>
  29 //
  30 // This header file also provides the tag types `in_place_t`, `in_place_type_t`,
  31 // and `in_place_index_t`, as well as the constant `in_place`, and
  32 // `constexpr` `std::move()` and `std::forward()` implementations in C++11.
  33 //
  34 // References:
  35 //
  36 //  https://en.cppreference.com/w/cpp/utility/integer_sequence
  37 //  https://en.cppreference.com/w/cpp/utility/apply
  38 //  http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3658.html
  39
  40 #ifndef ABSL_UTILITY_UTILITY_H_
  41 #define ABSL_UTILITY_UTILITY_H_
  42
  43 #include <cstddef>
  44 #include <cstdlib>
  45 #include <tuple>
  46 #include <utility>
  47
  48 #include "absl/base/config.h"
  49 #include "absl/base/internal/inline_variable.h"
  50 #include "absl/base/internal/invoke.h"
  51 #include "absl/meta/type_traits.h"
  52
  53 namespace absl {
  54
  55 // integer_sequence
  56 //
  57 // Class template representing a compile-time integer sequence. An instantiation
  58 // of `integer_sequence<T, Ints...>` has a sequence of integers encoded in its
  59 // type through its template arguments (which is a common need when
  60 // working with C++11 variadic templates). `absl::integer_sequence` is designed
  61 // to be a drop-in replacement for C++14's `std::integer_sequence`.
  62 //
  63 // Example:
  64 //
  65 //   template< class T, T... Ints >
  66 //   void user_function(integer_sequence<T, Ints...>);
  67 //
  68 //   int main()
  69 //   {
  70 //     // user_function's `T` will be deduced to `int` and `Ints...`
  71 //     // will be deduced to `0, 1, 2, 3, 4`.
  72 //     user_function(make_integer_sequence<int, 5>());
  73 //   }
  74 template <typename T, T... Ints>
  75 struct integer_sequence {
  76   using value_type = T;
  77   static constexpr size_t size() noexcept { return sizeof...(Ints); }
  78 };
  79
  80 // index_sequence
  81 //
  82 // A helper template for an `integer_sequence` of `size_t`,
  83 // `absl::index_sequence` is designed to be a drop-in replacement for C++14's
  84 // `std::index_sequence`.
  85 template <size_t... Ints>
  86 using index_sequence = integer_sequence<size_t, Ints...>;
  87
  88 namespace utility_internal {
  89
  90 template <typename Seq, size_t SeqSize, size_t Rem>
  91 struct Extend;
  92
  93 // Note that SeqSize == sizeof...(Ints). It's passed explicitly for efficiency.
  94 template <typename T, T... Ints, size_t SeqSize>
  95 struct Extend<integer_sequence<T, Ints...>, SeqSize, 0> {
  96   using type = integer_sequence<T, Ints..., (Ints + SeqSize)...>;
  97 };
  98
  99 template <typename T, T... Ints, size_t SeqSize>
 100 struct Extend<integer_sequence<T, Ints...>, SeqSize, 1> {
 101   using type = integer_sequence<T, Ints..., (Ints + SeqSize)..., 2 * SeqSize>;
 102 };
 103
 104 // Recursion helper for 'make_integer_sequence<T, N>'.
 105 // 'Gen<T, N>::type' is an alias for 'integer_sequence<T, 0, 1, ... N-1>'.
 106 template <typename T, size_t N>
 107 struct Gen {
 108   using type =
 109       typename Extend<typename Gen<T, N / 2>::type, N / 2, N % 2>::type;
 110 };
 111
 112 template <typename T>
 113 struct Gen<T, 0> {
 114   using type = integer_sequence<T>;
 115 };
 116
 117 template <typename T>
 118 struct InPlaceTypeTag {
 119   explicit InPlaceTypeTag() = delete;
 120   InPlaceTypeTag(const InPlaceTypeTag&) = delete;
 121   InPlaceTypeTag& operator=(const InPlaceTypeTag&) = delete;
 122 };
 123
 124 template <size_t I>
 125 struct InPlaceIndexTag {
 126   explicit InPlaceIndexTag() = delete;
 127   InPlaceIndexTag(const InPlaceIndexTag&) = delete;
 128   InPlaceIndexTag& operator=(const InPlaceIndexTag&) = delete;
 129 };
 130
 131 }  // namespace utility_internal
 132
 133 // Compile-time sequences of integers
 134
 135 // make_integer_sequence
 136 //
 137 // This template alias is equivalent to
 138 // `integer_sequence<int, 0, 1, ..., N-1>`, and is designed to be a drop-in
 139 // replacement for C++14's `std::make_integer_sequence`.
 140 template <typename T, T N>
 141 using make_integer_sequence = typename utility_internal::Gen<T, N>::type;
 142
 143 // make_index_sequence
 144 //
 145 // This template alias is equivalent to `index_sequence<0, 1, ..., N-1>`,
 146 // and is designed to be a drop-in replacement for C++14's
 147 // `std::make_index_sequence`.
 148 template <size_t N>
 149 using make_index_sequence = make_integer_sequence<size_t, N>;
 150
 151 // index_sequence_for
 152 //
 153 // Converts a typename pack into an index sequence of the same length, and
 154 // is designed to be a drop-in replacement for C++14's
 155 // `std::index_sequence_for()`
 156 template <typename... Ts>
 157 using index_sequence_for = make_index_sequence<sizeof...(Ts)>;
 158
 159 // Tag types
 160
 161 #ifdef ABSL_HAVE_STD_OPTIONAL
 162
 163 using std::in_place_t;
 164 using std::in_place;
 165
 166 #else  // ABSL_HAVE_STD_OPTIONAL
 167
 168 // in_place_t
 169 //
 170 // Tag type used to specify in-place construction, such as with
 171 // `absl::optional`, designed to be a drop-in replacement for C++17's
 172 // `std::in_place_t`.
 173 struct in_place_t {};
 174
 175 ABSL_INTERNAL_INLINE_CONSTEXPR(in_place_t, in_place, {});
 176
 177 #endif  // ABSL_HAVE_STD_OPTIONAL
 178
 179 #if defined(ABSL_HAVE_STD_ANY) || defined(ABSL_HAVE_STD_VARIANT)
 180 using std::in_place_type;
 181 using std::in_place_type_t;
 182 #else
 183
 184 // in_place_type_t
 185 //
 186 // Tag type used for in-place construction when the type to construct needs to
 187 // be specified, such as with `absl::any`, designed to be a drop-in replacement
 188 // for C++17's `std::in_place_type_t`.
 189 template <typename T>
 190 using in_place_type_t = void (*)(utility_internal::InPlaceTypeTag<T>);
 191
 192 template <typename T>
 193 void in_place_type(utility_internal::InPlaceTypeTag<T>) {}
 194 #endif  // ABSL_HAVE_STD_ANY || ABSL_HAVE_STD_VARIANT
 195
 196 #ifdef ABSL_HAVE_STD_VARIANT
 197 using std::in_place_index;
 198 using std::in_place_index_t;
 199 #else
 200
 201 // in_place_index_t
 202 //
 203 // Tag type used for in-place construction when the type to construct needs to
 204 // be specified, such as with `absl::any`, designed to be a drop-in replacement
 205 // for C++17's `std::in_place_index_t`.
 206 template <size_t I>
 207 using in_place_index_t = void (*)(utility_internal::InPlaceIndexTag<I>);
 208
 209 template <size_t I>
 210 void in_place_index(utility_internal::InPlaceIndexTag<I>) {}
 211 #endif  // ABSL_HAVE_STD_VARIANT
 212
 213 // Constexpr move and forward
 214
 215 // move()
 216 //
 217 // A constexpr version of `std::move()`, designed to be a drop-in replacement
 218 // for C++14's `std::move()`.
 219 template <typename T>
 220 constexpr absl::remove_reference_t<T>&& move(T&& t) noexcept {
 221   return static_cast<absl::remove_reference_t<T>&&>(t);
 222 }
 223
 224 // forward()
 225 //
 226 // A constexpr version of `std::forward()`, designed to be a drop-in replacement
 227 // for C++14's `std::forward()`.
 228 template <typename T>
 229 constexpr T&& forward(
 230     absl::remove_reference_t<T>& t) noexcept {  // NOLINT(runtime/references)
 231   return static_cast<T&&>(t);
 232 }
 233
 234 namespace utility_internal {
 235 // Helper method for expanding tuple into a called method.
 236 template <typename Functor, typename Tuple, std::size_t... Indexes>
 237 auto apply_helper(Functor&& functor, Tuple&& t, index_sequence<Indexes...>)
 238     -> decltype(absl::base_internal::Invoke(
 239         absl::forward<Functor>(functor),
 240         std::get<Indexes>(absl::forward<Tuple>(t))...)) {
 241   return absl::base_internal::Invoke(
 242       absl::forward<Functor>(functor),
 243       std::get<Indexes>(absl::forward<Tuple>(t))...);
 244 }
 245
 246 }  // namespace utility_internal
 247
 248 // apply
 249 //
 250 // Invokes a Callable using elements of a tuple as its arguments.
 251 // Each element of the tuple corresponds to an argument of the call (in order).
 252 // Both the Callable argument and the tuple argument are perfect-forwarded.
 253 // For member-function Callables, the first tuple element acts as the `this`
 254 // pointer. `absl::apply` is designed to be a drop-in replacement for C++17's
 255 // `std::apply`. Unlike C++17's `std::apply`, this is not currently `constexpr`.
 256 //
 257 // Example:
 258 //
 259 //   class Foo {
 260 //    public:
 261 //     void Bar(int);
 262 //   };
 263 //   void user_function1(int, std::string);
 264 //   void user_function2(std::unique_ptr<Foo>);
 265 //   auto user_lambda = [](int, int) {};
 266 //
 267 //   int main()
 268 //   {
 269 //       std::tuple<int, std::string> tuple1(42, "bar");
 270 //       // Invokes the first user function on int, std::string.
 271 //       absl::apply(&user_function1, tuple1);
 272 //
 273 //       std::tuple<std::unique_ptr<Foo>> tuple2(absl::make_unique<Foo>());
 274 //       // Invokes the user function that takes ownership of the unique
 275 //       // pointer.
 276 //       absl::apply(&user_function2, std::move(tuple2));
 277 //
 278 //       auto foo = absl::make_unique<Foo>();
 279 //       std::tuple<Foo*, int> tuple3(foo.get(), 42);
 280 //       // Invokes the method Bar on foo with one argument, 42.
 281 //       absl::apply(&Foo::Bar, tuple3);
 282 //
 283 //       std::tuple<int, int> tuple4(8, 9);
 284 //       // Invokes a lambda.
 285 //       absl::apply(user_lambda, tuple4);
 286 //   }
 287 template <typename Functor, typename Tuple>
 288 auto apply(Functor&& functor, Tuple&& t)
 289     -> decltype(utility_internal::apply_helper(
 290         absl::forward<Functor>(functor), absl::forward<Tuple>(t),
 291         absl::make_index_sequence<std::tuple_size<
 292             typename std::remove_reference<Tuple>::type>::value>{})) {
 293   return utility_internal::apply_helper(
 294       absl::forward<Functor>(functor), absl::forward<Tuple>(t),
 295       absl::make_index_sequence<std::tuple_size<
 296           typename std::remove_reference<Tuple>::type>::value>{});
 297 }
 298
 299 // exchange
 300 //
 301 // Replaces the value of `obj` with `new_value` and returns the old value of
 302 // `obj`.  `absl::exchange` is designed to be a drop-in replacement for C++14's
 303 // `std::exchange`.
 304 //
 305 // Example:
 306 //
 307 //   Foo& operator=(Foo&& other) {
 308 //     ptr1_ = absl::exchange(other.ptr1_, nullptr);
 309 //     int1_ = absl::exchange(other.int1_, -1);
 310 //     return *this;
 311 //   }
 312 template <typename T, typename U = T>
 313 T exchange(T& obj, U&& new_value) {
 314   T old_value = absl::move(obj);
 315   obj = absl::forward<U>(new_value);
 316   return old_value;
 317 }
 318
 319 namespace utility_internal {
 320 template <typename T, typename Tuple, size_t... I>
 321 T make_from_tuple_impl(Tuple&& tup, absl::index_sequence<I...>) {
 322   return T(std::get<I>(std::forward<Tuple>(tup))...);
 323 }
 324 }  // namespace utility_internal
 325
 326 // make_from_tuple
 327 //
 328 // Given the template parameter type `T` and a tuple of arguments
 329 // `std::tuple(arg0, arg1, ..., argN)` constructs an object of type `T` as if by
 330 // calling `T(arg0, arg1, ..., argN)`.
 331 //
 332 // Example:
 333 //
 334 //   std::tuple<const char*, size_t> args("hello world", 5);
 335 //   auto s = absl::make_from_tuple<std::string>(args);
 336 //   assert(s == "hello");
 337 //
 338 template <typename T, typename Tuple>
 339 constexpr T make_from_tuple(Tuple&& tup) {
 340   return utility_internal::make_from_tuple_impl<T>(
 341       std::forward<Tuple>(tup),
 342       absl::make_index_sequence<
 343           std::tuple_size<absl::decay_t<Tuple>>::value>{});
 344 }
 345
 346 }  // namespace absl
 347
 348 #endif  // ABSL_UTILITY_UTILITY_H_