diff options
author | Abseil Team <absl-team@google.com> | 2022-01-14 04:25:20 -0800 |
---|---|---|
committer | vslashg <gfalcon@google.com> | 2022-01-14 10:07:25 -0500 |
commit | c59e7e59f5d29619ddc07fcb59be3dcba9585814 (patch) | |
tree | 922b40d92ac5866e69fd328b55aae0e72e19e8a0 /absl/base/casts.h | |
parent | 2a042b082ca6fc8592ec98d800012fc03c965c15 (diff) |
Export of internal Abseil changes
--
0db7f4046f9b59c0f8c3df2f0eb7fd88fc328439 by Abseil Team <absl-team@google.com>:
Revise documentation of bit_cast:
* Removes inappropriate examples (round-tripping pointers, serialization), for which reinterpret_cast is more appropriate.
* Removes mention of "bit representation", which is not an explicit notion in C++. The best we get is "byte representation".
* Removes a circular defition of "bitcast" as itself, and instead explains what it does.
* Removes the mathism "for some values of", which is probably not totally accessible to a general audience, and in any case needless verbiage.
* Fixes comments in the example.
* Replaces some colloquialisms with simpler, more direct language.
PiperOrigin-RevId: 421791786
--
e04e64df55d93c1b9a09c0483b97cc4d8763260d by Derek Mauro <dmauro@google.com>:
Update Docker image to use GCC 11.2, Clang 14 (prerelease),
CMake 3.22.1, and Bazel 4.2.2
PiperOrigin-RevId: 421658559
--
d002bb3dc5cd1fc5b4cbd79a450efc894caa567c by Chris Kennelly <ckennelly@google.com>:
Add a small microbenchmark for absl::bit_width.
PiperOrigin-RevId: 421604852
--
131b057d1b76ecd7170421b48d661bb958ff676b by Evan Brown <ezb@google.com>:
Adds a disabled test for EBO in nested `CompressedTuple`s.
PiperOrigin-RevId: 421413134
--
e34c7876d3a1212d90c73c030ccae6169b682d43 by Jorg Brown <jorg@google.com>:
Show users a better error message if they pass a pointer to absl::Uniform.
PiperOrigin-RevId: 421090472
GitOrigin-RevId: 0db7f4046f9b59c0f8c3df2f0eb7fd88fc328439
Change-Id: I5a004e8d17e974fa4897a09d1466ae8fc65dfdbb
Diffstat (limited to 'absl/base/casts.h')
-rw-r--r-- | absl/base/casts.h | 57 |
1 files changed, 30 insertions, 27 deletions
diff --git a/absl/base/casts.h b/absl/base/casts.h index 83c69126..b16af233 100644 --- a/absl/base/casts.h +++ b/absl/base/casts.h @@ -105,47 +105,50 @@ constexpr To implicit_cast(typename absl::internal::identity_t<To> to) { // bit_cast() // -// Performs a bitwise cast on a type without changing the underlying bit -// representation of that type's value. The two types must be of the same size -// and both types must be trivially copyable. As with most casts, use with -// caution. A `bit_cast()` might be needed when you need to temporarily treat a -// type as some other type, such as in the following cases: -// -// * Serialization (casting temporarily to `char *` for those purposes is -// always allowed by the C++ standard) -// * Managing the individual bits of a type within mathematical operations -// that are not normally accessible through that type -// * Casting non-pointer types to pointer types (casting the other way is -// allowed by `reinterpret_cast()` but round-trips cannot occur the other -// way). -// -// Example: +// Creates a value of the new type `Dest` whose representation is the same as +// that of the argument, which is of (deduced) type `Source` (a "bitwise cast"; +// every bit in the value representation of the result is equal to the +// corresponding bit in the object representation of the source). Source and +// destination types must be of the same size, and both types must be trivially +// copyable. +// +// As with most casts, use with caution. A `bit_cast()` might be needed when you +// need to treat a value as the value of some other type, for example, to access +// the individual bits of an object which are not normally accessible through +// the object's type, such as for working with the binary representation of a +// floating point value: // // float f = 3.14159265358979; // int i = bit_cast<int32_t>(f); // // i = 0x40490fdb // -// Casting non-pointer types to pointer types and then dereferencing them -// traditionally produces undefined behavior. +// Reinterpreting and accessing a value directly as a different type (as shown +// below) usually results in undefined behavior. // // Example: // // // WRONG -// float f = 3.14159265358979; // WRONG -// int i = * reinterpret_cast<int*>(&f); // WRONG +// float f = 3.14159265358979; +// int i = reinterpret_cast<int&>(f); // Wrong +// int j = *reinterpret_cast<int*>(&f); // Equally wrong +// int k = *bit_cast<int*>(&f); // Equally wrong +// +// Reinterpret-casting results in undefined behavior according to the ISO C++ +// specification, section [basic.lval]. Roughly, this section says: if an object +// in memory has one type, and a program accesses it with a different type, the +// result is undefined behavior for most "different type". // -// The address-casting method produces undefined behavior according to the ISO -// C++ specification section [basic.lval]. Roughly, this section says: if an -// object in memory has one type, and a program accesses it with a different -// type, the result is undefined behavior for most values of "different type". +// Using bit_cast on a pointer and then dereferencing it is no better than using +// reinterpret_cast. You should only use bit_cast on the value itself. // // Such casting results in type punning: holding an object in memory of one type // and reading its bits back using a different type. A `bit_cast()` avoids this -// issue by implementing its casts using `memcpy()`, which avoids introducing -// this undefined behavior. +// issue by copying the object representation to a new value, which avoids +// introducing this undefined behavior (since the original value is never +// accessed in the wrong way). // -// NOTE: The requirements here are more strict than the bit_cast of standard -// proposal p0476 due to the need for workarounds and lack of intrinsics. +// NOTE: The requirements here are stricter than the bit_cast of standard +// proposal P0476 due to the need for workarounds and lack of intrinsics. // Specifically, this implementation also requires `Dest` to be // default-constructible. template < |