casts.h
Go to the documentation of this file.
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 
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>
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>
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,
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<
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_
Dest bit_cast(const Source &source)
Definition: casts.h:154
Definition: algorithm.h:29
constexpr To implicit_cast(typename absl::internal::identity_t< To > to)
Definition: casts.h:101
size_t to
size_t value
ABSL_DEPRECATED("absl::bit_cast type requirements were violated. Update the types being ""used such that they are the same size and are both TriviallyCopyable.") inline Dest bit_cast(const Source &source)
Definition: casts.h:168
typename identity< T >::type identity_t
Definition: identity.h:28


abseil_cpp
Author(s):
autogenerated on Tue Jun 18 2019 19:44:35