1// Copyright 2009 Google Inc. All Rights Reserved.
2//
3// Various Google-specific casting templates.
4//
5// This code is compiled directly on many platforms, including client
6// platforms like Windows, Mac, and embedded systems. Before making
7// any changes here, make sure that you're not breaking any platforms.
8//
9
10#ifndef BASE_CASTS_H_
11#define BASE_CASTS_H_
12
13#include <assert.h> // for use with down_cast<>
14#include <string.h> // for memcpy
15#include <limits.h> // for enumeration casts and tests
16#include <typeinfo> // for enumeration casts and tests
17
18#include "base/macros.h"
19
20
21// Use implicit_cast as a safe version of static_cast or const_cast
22// for upcasting in the type hierarchy (i.e. casting a pointer to Foo
23// to a pointer to SuperclassOfFoo or casting a pointer to Foo to
24// a const pointer to Foo).
25// When you use implicit_cast, the compiler checks that the cast is safe.
26// Such explicit implicit_casts are necessary in surprisingly many
27// situations where C++ demands an exact type match instead of an
28// argument type convertable to a target type.
29//
30// The From type can be inferred, so the preferred syntax for using
31// implicit_cast is the same as for static_cast etc.:
32//
33// implicit_cast<ToType>(expr)
34//
35// implicit_cast would have been part of the C++ standard library,
36// but the proposal was submitted too late. It will probably make
37// its way into the language in the future.
38template<typename To, typename From>
39inline To implicit_cast(From const &f) {
40 return f;
41}
42
43
44// When you upcast (that is, cast a pointer from type Foo to type
45// SuperclassOfFoo), it's fine to use implicit_cast<>, since upcasts
46// always succeed. When you downcast (that is, cast a pointer from
47// type Foo to type SubclassOfFoo), static_cast<> isn't safe, because
48// how do you know the pointer is really of type SubclassOfFoo? It
49// could be a bare Foo, or of type DifferentSubclassOfFoo. Thus,
50// when you downcast, you should use this macro. In debug mode, we
51// use dynamic_cast<> to double-check the downcast is legal (we die
52// if it's not). In normal mode, we do the efficient static_cast<>
53// instead. Thus, it's important to test in debug mode to make sure
54// the cast is legal!
55// This is the only place in the code we should use dynamic_cast<>.
56// In particular, you SHOULDN'T be using dynamic_cast<> in order to
57// do RTTI (eg code like this:
58// if (dynamic_cast<Subclass1>(foo)) HandleASubclass1Object(foo);
59// if (dynamic_cast<Subclass2>(foo)) HandleASubclass2Object(foo);
60// You should design the code some other way not to need this.
61
62template<typename To, typename From> // use like this: down_cast<T*>(foo);
63inline To down_cast(From* f) { // so we only accept pointers
64 // Ensures that To is a sub-type of From *. This test is here only
65 // for compile-time type checking, and has no overhead in an
66 // optimized build at run-time, as it will be optimized away
67 // completely.
68
69 // TODO(user): This should use COMPILE_ASSERT.
70 if (false) {
71 implicit_cast<From*, To>(0);
72 }
73
74 // uses RTTI in dbg and fastbuild. asserts are disabled in opt builds.
75 assert(f == NULL || dynamic_cast<To>(f) != NULL);
76 return static_cast<To>(f);
77}
78
79// Overload of down_cast for references. Use like this: down_cast<T&>(foo).
80// The code is slightly convoluted because we're still using the pointer
81// form of dynamic cast. (The reference form throws an exception if it
82// fails.)
83//
84// There's no need for a special const overload either for the pointer
85// or the reference form. If you call down_cast with a const T&, the
86// compiler will just bind From to const T.
87template<typename To, typename From>
88inline To down_cast(From& f) {
89 COMPILE_ASSERT(base::is_reference<To>::value, target_type_not_a_reference);
90 typedef typename base::remove_reference<To>::type* ToAsPointer;
91 if (false) {
92 // Compile-time check that To inherits from From. See above for details.
93 implicit_cast<From*, ToAsPointer>(0);
94 }
95
96 assert(dynamic_cast<ToAsPointer>(&f) != NULL); // RTTI: debug mode only
97 return static_cast<To>(f);
98}
99
100// bit_cast<Dest,Source> is a template function that implements the
101// equivalent of "*reinterpret_cast<Dest*>(&source)". We need this in
102// very low-level functions like the protobuf library and fast math
103// support.
104//
105// float f = 3.14159265358979;
106// int i = bit_cast<int32>(f);
107// // i = 0x40490fdb
108//
109// The classical address-casting method is:
110//
111// // WRONG
112// float f = 3.14159265358979; // WRONG
113// int i = * reinterpret_cast<int*>(&f); // WRONG
114//
115// The address-casting method actually produces undefined behavior
116// according to ISO C++ specification section 3.10 -15 -. Roughly, this
117// section says: if an object in memory has one type, and a program
118// accesses it with a different type, then the result is undefined
119// behavior for most values of "different type".
120//
121// This is true for any cast syntax, either *(int*)&f or
122// *reinterpret_cast<int*>(&f). And it is particularly true for
123// conversions betweeen integral lvalues and floating-point lvalues.
124//
125// The purpose of 3.10 -15- is to allow optimizing compilers to assume
126// that expressions with different types refer to different memory. gcc
127// 4.0.1 has an optimizer that takes advantage of this. So a
128// non-conforming program quietly produces wildly incorrect output.
129//
130// The problem is not the use of reinterpret_cast. The problem is type
131// punning: holding an object in memory of one type and reading its bits
132// back using a different type.
133//
134// The C++ standard is more subtle and complex than this, but that
135// is the basic idea.
136//
137// Anyways ...
138//
139// bit_cast<> calls memcpy() which is blessed by the standard,
140// especially by the example in section 3.9 . Also, of course,
141// bit_cast<> wraps up the nasty logic in one place.
142//
143// Fortunately memcpy() is very fast. In optimized mode, with a
144// constant size, gcc 2.95.3, gcc 4.0.1, and msvc 7.1 produce inline
145// code with the minimal amount of data movement. On a 32-bit system,
146// memcpy(d,s,4) compiles to one load and one store, and memcpy(d,s,8)
147// compiles to two loads and two stores.
148//
149// I tested this code with gcc 2.95.3, gcc 4.0.1, icc 8.1, and msvc 7.1.
150//
151// WARNING: if Dest or Source is a non-POD type, the result of the memcpy
152// is likely to surprise you.
153//
154// Props to Bill Gibbons for the compile time assertion technique and
155// Art Komninos and Igor Tandetnik for the msvc experiments.
156//
157// -- mec 2005-10-17
158
159template <class Dest, class Source>
160inline Dest bit_cast(const Source& source) {
161 // Compile time assertion: sizeof(Dest) == sizeof(Source)
162 // A compile error here means your Dest and Source have different sizes.
163 typedef char VerifySizesAreEqual [sizeof(Dest) == sizeof(Source) ? 1 : -1];
164
165 Dest dest;
166 memcpy(&dest, &source, sizeof(dest));
167 return dest;
168}
169
170
171// **** Enumeration Casts and Tests
172//
173// C++ requires that the value of an integer that is converted to an
174// enumeration be within the value bounds of the enumeration. Modern
175// compilers can and do take advantage of this requirement to optimize
176// programs. So, using a raw static_cast with enums can be bad. See
177//
178// The following templates and macros enable casting from an int to an enum
179// with checking against the appropriate bounds. First, when defining an
180// enumeration, identify the limits of the values of its enumerators.
181//
182// enum A { A_min = -18, A_max = 33 };
183// MAKE_ENUM_LIMITS(A, A_min, A_max)
184//
185// Convert an enum to an int in one of two ways. The prefered way is a
186// tight conversion, which ensures that A_min <= value <= A_max.
187//
188// A var = tight_enum_cast<A>(3);
189//
190// However, the C++ language defines the set of possible values for an
191// enumeration to be essentially the range of a bitfield that can represent
192// all the enumerators, i.e. those within the nearest containing power
193// of two. In the example above, the nearest positive power of two is 64,
194// and so the upper bound is 63. The nearest negative power of two is
195// -32 and so the lower bound is -32 (two's complement), which is upgraded
196// to match the upper bound, becoming -64. The values within this range
197// of -64 to 63 are valid, according to the C++ standard. You can cast
198// values within this range as follows.
199//
200// A var = loose_enum_cast<A>(45);
201//
202// These casts will log a message if the value does not reside within the
203// specified range, and will be fatal when in debug mode.
204//
205// For those times when an assert too strong, there are test functions.
206//
207// bool var = tight_enum_test<A>(3);
208// bool var = loose_enum_test<A>(45);
209//
210// For code that needs to use the enumeration value if and only if
211// it is good, there is a function that both tests and casts.
212//
213// int i = ....;
214// A var;
215// if (tight_enum_test_cast<A>(i, &var))
216// .... // use valid var with value as indicated by i
217// else
218// .... // handle invalid enum cast
219//
220// The enum test/cast facility is currently limited to enumerations that
221// fit within an int. It is also limited to two's complement ints.
222
223// ** Implementation Description
224//
225// The enum_limits template class captures the minimum and maximum
226// enumerator. All uses of this template are intended to be of
227// specializations, so the generic has a field to identify itself as
228// not specialized. The test/cast templates assert specialization.
229
230template <typename Enum>
231class enum_limits {
232 public:
233 static const Enum min_enumerator = 0;
234 static const Enum max_enumerator = 0;
235 static const bool is_specialized = false;
236};
237
238// Now we define the macro to define the specialization for enum_limits.
239// The specialization checks that the enumerators fit within an int.
240// This checking relies on integral promotion.
241
242#define MAKE_ENUM_LIMITS(ENUM_TYPE, ENUM_MIN, ENUM_MAX) \
243template <> \
244class enum_limits<ENUM_TYPE> { \
245public: \
246 static const ENUM_TYPE min_enumerator = ENUM_MIN; \
247 static const ENUM_TYPE max_enumerator = ENUM_MAX; \
248 static const bool is_specialized = true; \
249 COMPILE_ASSERT(ENUM_MIN >= INT_MIN, enumerator_too_negative_for_int); \
250 COMPILE_ASSERT(ENUM_MAX <= INT_MAX, enumerator_too_positive_for_int); \
251};
252
253// The loose enum test/cast is actually the more complicated one,
254// because of the problem of finding the bounds.
255//
256// The unary upper bound, ub, on a positive number is its positive
257// saturation, i.e. for a value v within pow(2,k-1) <= v < pow(2,k),
258// the upper bound is pow(2,k)-1.
259//
260// The unary lower bound, lb, on a negative number is its negative
261// saturation, i.e. for a value v within -pow(2,k) <= v < -pow(2,k-1),
262// the lower bound is -pow(2,k).
263//
264// The actual bounds are (1) the binary upper bound over the maximum
265// enumerator and the one's complement of a negative minimum enumerator
266// and (2) the binary lower bound over the minimum enumerator and the
267// one's complement of the positive maximum enumerator, except that if no
268// enumerators are negative, the lower bound is zero.
269//
270// The algorithm relies heavily on the observation that
271//
272// a,b>0 then ub(a,b) == ub(a) | ub(b) == ub(a|b)
273// a,b<0 then lb(a,b) == lb(a) & lb(b) == lb(a&b)
274//
275// Note that the compiler will boil most of this code away
276// because of value propagation on the constant enumerator bounds.
277
278template <typename Enum>
279inline bool loose_enum_test(int e_val) {
280 COMPILE_ASSERT(enum_limits<Enum>::is_specialized, missing_MAKE_ENUM_LIMITS);
281 const Enum e_min = enum_limits<Enum>::min_enumerator;
282 const Enum e_max = enum_limits<Enum>::max_enumerator;
283 COMPILE_ASSERT(sizeof(e_val) == 4 || sizeof(e_val) == 8, unexpected_int_size);
284
285 // Find the unary bounding negative number of e_min and e_max.
286
287 // Find the unary bounding negative number of e_max.
288 // This would be b_min = e_max < 0 ? e_max : ~e_max,
289 // but we want to avoid branches to help the compiler.
290 int e_max_sign = e_max >> (sizeof(e_val)*8 - 1);
291 int b_min = ~e_max_sign ^ e_max;
292
293 // Find the binary bounding negative of both e_min and e_max.
294 b_min &= e_min;
295
296 // However, if e_min is postive, the result will be positive.
297 // Now clear all bits right of the most significant clear bit,
298 // which is a negative saturation for negative numbers.
299 // In the case of positive numbers, this is flush to zero.
300 b_min &= b_min >> 1;
301 b_min &= b_min >> 2;
302 b_min &= b_min >> 4;
303 b_min &= b_min >> 8;
304 b_min &= b_min >> 16;
305#if INT_MAX > 2147483647
306 b_min &= b_min >> 32;
307#endif
308
309 // Find the unary bounding positive number of e_max.
310 int b_max = e_max_sign ^ e_max;
311
312 // Find the binary bounding postive number of that
313 // and the unary bounding positive number of e_min.
314 int e_min_sign = e_min >> (sizeof(e_val)*8 - 1);
315 b_max |= e_min_sign ^ e_min;
316
317 // Now set all bits right of the most significant set bit,
318 // which is a postive saturation for positive numbers.
319 b_max |= b_max >> 1;
320 b_max |= b_max >> 2;
321 b_max |= b_max >> 4;
322 b_max |= b_max >> 8;
323 b_max |= b_max >> 16;
324#if INT_MAX > 2147483647
325 b_max |= b_max >> 32;
326#endif
327
328 // Finally test the bounds.
329 return b_min <= e_val && e_val <= b_max;
330}
331
332template <typename Enum>
333inline bool tight_enum_test(int e_val) {
334 COMPILE_ASSERT(enum_limits<Enum>::is_specialized, missing_MAKE_ENUM_LIMITS);
335 const Enum e_min = enum_limits<Enum>::min_enumerator;
336 const Enum e_max = enum_limits<Enum>::max_enumerator;
337 return e_min <= e_val && e_val <= e_max;
338}
339
340template <typename Enum>
341inline bool loose_enum_test_cast(int e_val, Enum* e_var) {
342 if (loose_enum_test<Enum>(e_val)) {
343 *e_var = static_cast<Enum>(e_val);
344 return true;
345 } else {
346 return false;
347 }
348}
349
350template <typename Enum>
351inline bool tight_enum_test_cast(int e_val, Enum* e_var) {
352 if (tight_enum_test<Enum>(e_val)) {
353 *e_var = static_cast<Enum>(e_val);
354 return true;
355 } else {
356 return false;
357 }
358}
359
360// The plain casts require logging, and we get header recursion if
361// it is done directly. So, we do it indirectly.
362// The following function is defined in logging.cc.
363
364namespace logging {
365
366void WarnEnumCastError(const char* name_of_type, int value_of_int);
367
368} // namespace logging
369
370template <typename Enum>
371inline Enum loose_enum_cast(int e_val) {
372 if (!loose_enum_test<Enum>(e_val)) {
373#if __GNUC__ && !__GXX_RTTI
374 // Gcc and -fno-rtti; can't issue a warning with enum name.
375 assert(false);
376#else
377 logging::WarnEnumCastError(typeid(Enum).name(), e_val);
378#endif
379 }
380 return static_cast<Enum>(e_val);
381}
382
383template <typename Enum>
384inline Enum tight_enum_cast(int e_val) {
385 if (!tight_enum_test<Enum>(e_val)) {
386#if __GNUC__ && !__GXX_RTTI
387 // Gcc and -fno-rtti; can't issue a warning with enum name.
388 assert(false);
389#else
390 logging::WarnEnumCastError(typeid(Enum).name(), e_val);
391#endif
392 }
393 return static_cast<Enum>(e_val);
394}
395
396#endif // BASE_CASTS_H_
397