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. |
38 | template<typename To, typename From> |
39 | inline 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 | |
62 | template<typename To, typename From> // use like this: down_cast<T*>(foo); |
63 | inline 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. |
87 | template<typename To, typename From> |
88 | inline 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 | |
159 | template <class Dest, class Source> |
160 | inline 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 | |
230 | template <typename Enum> |
231 | class 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) \ |
243 | template <> \ |
244 | class enum_limits<ENUM_TYPE> { \ |
245 | public: \ |
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 | |
278 | template <typename Enum> |
279 | inline 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 | |
332 | template <typename Enum> |
333 | inline 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 | |
340 | template <typename Enum> |
341 | inline 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 | |
350 | template <typename Enum> |
351 | inline 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 | |
364 | namespace logging { |
365 | |
366 | void WarnEnumCastError(const char* name_of_type, int value_of_int); |
367 | |
368 | } // namespace logging |
369 | |
370 | template <typename Enum> |
371 | inline 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 | |
383 | template <typename Enum> |
384 | inline 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 | |