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
36namespace absl {
37
38namespace internal_casts {
39
40template <class Dest, class Source>
41struct 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.
100template <typename To>
101constexpr 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.
150template <
151 typename Dest, typename Source,
152 typename std::enable_if<internal_casts::is_bitcastable<Dest, Source>::value,
153 int>::type = 0>
154inline 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.
164template <
165 typename Dest, typename Source,
166 typename std::enable_if<
167 !internal_casts::is_bitcastable<Dest, Source>::value, int>::type = 0>
168ABSL_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.")
171inline 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_
183