legacy-libs/grpc/deps/grpc/third_party/abseil-cpp/absl/base/casts.h

   1 //
   2 // Copyright 2017 The Abseil Authors.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the "License");
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //      https://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16 // -----------------------------------------------------------------------------
  17 // File: casts.h
  18 // -----------------------------------------------------------------------------
  19 //
  20 // This header file defines casting templates to fit use cases not covered by
  21 // the standard casts provided in the C++ standard. As with all cast operations,
  22 // use these with caution and only if alternatives do not exist.
  23
  24 #ifndef ABSL_BASE_CASTS_H_
  25 #define ABSL_BASE_CASTS_H_
  26
  27 #include <cstring>
  28 #include <memory>
  29 #include <type_traits>
  30 #include <utility>
  31
  32 #include "absl/base/internal/identity.h"
  33 #include "absl/base/macros.h"
  34 #include "absl/meta/type_traits.h"
  35
  36 namespace absl {
  37
  38 namespace internal_casts {
  39
  40 template <class Dest, class Source>
  41 struct is_bitcastable
  42     : std::integral_constant<
  43           bool,
  44           sizeof(Dest) == sizeof(Source) &&
  45               type_traits_internal::is_trivially_copyable<Source>::value &&
  46               type_traits_internal::is_trivially_copyable<Dest>::value &&
  47               std::is_default_constructible<Dest>::value> {};
  48
  49 }  // namespace internal_casts
  50
  51 // implicit_cast()
  52 //
  53 // Performs an implicit conversion between types following the language
  54 // rules for implicit conversion; if an implicit conversion is otherwise
  55 // allowed by the language in the given context, this function performs such an
  56 // implicit conversion.
  57 //
  58 // Example:
  59 //
  60 //   // If the context allows implicit conversion:
  61 //   From from;
  62 //   To to = from;
  63 //
  64 //   // Such code can be replaced by:
  65 //   implicit_cast<To>(from);
  66 //
  67 // An `implicit_cast()` may also be used to annotate numeric type conversions
  68 // that, although safe, may produce compiler warnings (such as `long` to `int`).
  69 // Additionally, an `implicit_cast()` is also useful within return statements to
  70 // indicate a specific implicit conversion is being undertaken.
  71 //
  72 // Example:
  73 //
  74 //   return implicit_cast<double>(size_in_bytes) / capacity_;
  75 //
  76 // Annotating code with `implicit_cast()` allows you to explicitly select
  77 // particular overloads and template instantiations, while providing a safer
  78 // cast than `reinterpret_cast()` or `static_cast()`.
  79 //
  80 // Additionally, an `implicit_cast()` can be used to allow upcasting within a
  81 // type hierarchy where incorrect use of `static_cast()` could accidentally
  82 // allow downcasting.
  83 //
  84 // Finally, an `implicit_cast()` can be used to perform implicit conversions
  85 // from unrelated types that otherwise couldn't be implicitly cast directly;
  86 // C++ will normally only implicitly cast "one step" in such conversions.
  87 //
  88 // That is, if C is a type which can be implicitly converted to B, with B being
  89 // a type that can be implicitly converted to A, an `implicit_cast()` can be
  90 // used to convert C to B (which the compiler can then implicitly convert to A
  91 // using language rules).
  92 //
  93 // Example:
  94 //
  95 //   // Assume an object C is convertible to B, which is implicitly convertible
  96 //   // to A
  97 //   A a = implicit_cast<B>(C);
  98 //
  99 // Such implicit cast chaining may be useful within template logic.
 100 template <typename To>
 101 constexpr To implicit_cast(typename absl::internal::identity_t<To> to) {
 102   return to;
 103 }
 104
 105 // bit_cast()
 106 //
 107 // Performs a bitwise cast on a type without changing the underlying bit
 108 // representation of that type's value. The two types must be of the same size
 109 // and both types must be trivially copyable. As with most casts, use with
 110 // caution. A `bit_cast()` might be needed when you need to temporarily treat a
 111 // type as some other type, such as in the following cases:
 112 //
 113 //    * Serialization (casting temporarily to `char *` for those purposes is
 114 //      always allowed by the C++ standard)
 115 //    * Managing the individual bits of a type within mathematical operations
 116 //      that are not normally accessible through that type
 117 //    * Casting non-pointer types to pointer types (casting the other way is
 118 //      allowed by `reinterpret_cast()` but round-trips cannot occur the other
 119 //      way).
 120 //
 121 // Example:
 122 //
 123 //   float f = 3.14159265358979;
 124 //   int i = bit_cast<int32_t>(f);
 125 //   // i = 0x40490fdb
 126 //
 127 // Casting non-pointer types to pointer types and then dereferencing them
 128 // traditionally produces undefined behavior.
 129 //
 130 // Example:
 131 //
 132 //   // WRONG
 133 //   float f = 3.14159265358979;            // WRONG
 134 //   int i = * reinterpret_cast<int*>(&f);  // WRONG
 135 //
 136 // The address-casting method produces undefined behavior according to the ISO
 137 // C++ specification section [basic.lval]. Roughly, this section says: if an
 138 // object in memory has one type, and a program accesses it with a different
 139 // type, the result is undefined behavior for most values of "different type".
 140 //
 141 // Such casting results in type punning: holding an object in memory of one type
 142 // and reading its bits back using a different type. A `bit_cast()` avoids this
 143 // issue by implementing its casts using `memcpy()`, which avoids introducing
 144 // this undefined behavior.
 145 //
 146 // NOTE: The requirements here are more strict than the bit_cast of standard
 147 // proposal p0476 due to the need for workarounds and lack of intrinsics.
 148 // Specifically, this implementation also requires `Dest` to be
 149 // default-constructible.
 150 template <
 151     typename Dest, typename Source,
 152     typename std::enable_if<internal_casts::is_bitcastable<Dest, Source>::value,
 153                             int>::type = 0>
 154 inline Dest bit_cast(const Source& source) {
 155   Dest dest;
 156   memcpy(static_cast<void*>(std::addressof(dest)),
 157          static_cast<const void*>(std::addressof(source)), sizeof(dest));
 158   return dest;
 159 }
 160
 161 // NOTE: This overload is only picked if the requirements of bit_cast are not
 162 // met. It is therefore UB, but is provided temporarily as previous versions of
 163 // this function template were unchecked. Do not use this in new code.
 164 template <
 165     typename Dest, typename Source,
 166     typename std::enable_if<
 167         !internal_casts::is_bitcastable<Dest, Source>::value, int>::type = 0>
 168 ABSL_DEPRECATED(
 169     "absl::bit_cast type requirements were violated. Update the types being "
 170     "used such that they are the same size and are both TriviallyCopyable.")
 171 inline Dest bit_cast(const Source& source) {
 172   static_assert(sizeof(Dest) == sizeof(Source),
 173                 "Source and destination types should have equal sizes.");
 174
 175   Dest dest;
 176   memcpy(&dest, &source, sizeof(dest));
 177   return dest;
 178 }
 179
 180 }  // namespace absl
 181
 182 #endif  // ABSL_BASE_CASTS_H_