Sierra Toolkit  Version of the Day
type_traits_eastl.h
1 /*
2 Copyright (C) 2009-2010 Electronic Arts, Inc. All rights reserved.
3 
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions
6 are met:
7 
8 1. Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10 2. Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13 3. Neither the name of Electronic Arts, Inc. ("EA") nor the names of
14  its contributors may be used to endorse or promote products derived
15  from this software without specific prior written permission.
16 
17 THIS SOFTWARE IS PROVIDED BY ELECTRONIC ARTS AND ITS CONTRIBUTORS "AS IS" AND ANY
18 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20 DISCLAIMED. IN NO EVENT SHALL ELECTRONIC ARTS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
21 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28 
30 // EASTL/type_traits.h
31 //
32 // Copyright (c) 2005, Electronic Arts. All rights reserved.
33 // Written and maintained by Paul Pedriana.
35 
36 
38 // Specification
39 //
40 // This file implements C++ type traits as proposed by the emerging C++ update
41 // as of May, 2005. This update is known as "Proposed Draft Technical Report
42 // on C++ Library Extensions" and is document number n1745. It can be found
43 // on the Internet as n1745.pdf and as of this writing it is updated every
44 // couple months to reflect current thinking.
46 
47 
49 // Description
50 //
51 // EASTL includes a fairly serious type traits library that is on par with the
52 // one found in Boost but offers some additional performance-enhancing help as well.
53 // The type_traits library provides information about class types, as opposed to
54 // class instances. For example, the is_integral type trait tells if a type is
55 // one of int, short, long, char, uint64_t, etc.
56 //
57 // There are three primary uses of type traits:
58 // * Allowing for optimized operations on some data types.
59 // * Allowing for different logic pathways based on data types.
60 // * Allowing for compile-type assertions about data type expectations.
61 //
62 // Most of the type traits are automatically detected and implemented by the compiler.
63 // However, EASTL allows for the user to explicitly give the compiler hints about
64 // type traits that the compiler cannot know, via the EASTL_DECLARE declarations.
65 // If the user has a class that is relocatable (i.e. can safely use memcpy to copy values),
66 // the user can use the EASTL_DECLARE_TRIVIAL_RELOCATE declaration to tell the compiler
67 // that the class can be copied via memcpy. This will automatically significantly speed
68 // up some containers and algorithms that use that class.
69 //
70 // Here is an example of using type traits to tell if a value is a floating point
71 // value or not:
72 //
73 // template <typename T>
74 // DoSomething(T t) {
75 // assert(is_floating_point<T>::value);
76 // }
77 //
78 // Here is an example of declaring a class as relocatable and using it in a vector.
79 //
80 // EASTL_DECLARE_TRIVIAL_RELOCATE(Widget); // Usually you put this at the Widget class declaration.
81 // vector<Widget> wVector;
82 // wVector.erase(wVector.begin()); // This operation will be optimized via using memcpy.
83 //
84 // The following is a full list of the currently recognized type traits. Most of these
85 // are implemented as of this writing, but if there is one that is missing, feel free
86 // to contact the maintainer of this library and request that it be completed.
87 //
88 // Trait Description
89 // ------------------------------------------------------------------------------
90 // is_void T is void or a cv-qualified (const/void-qualified) void.
91 // is_integral T is an integral type.
92 // is_floating_point T is a floating point type.
93 // is_arithmetic T is an arithmetic type (integral or floating point).
94 // is_fundamental T is a fundamental type (void, integral, or floating point).
95 // is_const T is const-qualified.
96 // is_volatile T is volatile-qualified.
97 // is_abstract T is an abstract class.
98 // is_signed T is a signed integral type.
99 // is_unsigned T is an unsigned integral type.
100 // is_array T is an array type. The templated array container is not an array type.
101 // is_pointer T is a pointer type. Includes function pointers, but not pointers to (data or function) members.
102 // is_reference T is a reference type. Includes references to functions.
103 // is_member_object_pointer T is a pointer to data member.
104 // is_member_function_pointer T is a pointer to member function.
105 // is_member_pointer T is a pointer to a member or member function.
106 // is_enum T is an enumeration type.
107 // is_union T is a union type.
108 // is_class T is a class type but not a union type.
109 // is_polymorphic T is a polymorphic class.
110 // is_function T is a function type.
111 // is_object T is an object type.
112 // is_scalar T is a scalar type (arithmetic, enum, pointer, member_pointer)
113 // is_compound T is a compound type (anything but fundamental).
114 // is_same T and U name the same type.
115 // is_convertible An imaginary lvalue of type From is implicitly convertible to type To. Special conversions involving string-literals
116 // and null-pointer constants are not considered. No function-parameter adjustments are made to type To when determining
117 // whether From is convertible to To; this implies that if type To is a function type or an array type, then the condition is false.
118 // is_base_of Base is a base class of Derived or Base and Derived name the same type.
119 // is_empty T is an empty class.
120 // is_pod T is a POD type.
121 // *is_aligned Defined as true if the type has alignment requirements greater than default alignment, which is taken to be 8.
122 // has_trivial_constructor The default constructor for T is trivial.
123 // has_trivial_copy The copy constructor for T is trivial.
124 // has_trivial_assign The assignment operator for T is trivial.
125 // has_trivial_destructor The destructor for T is trivial.
126 // *has_trivial_relocate T can be moved to a new location via bitwise copy.
127 // has_nothrow_constructor The default constructor for T has an empty exception specification or can otherwise be deduced never to throw an exception.
128 // has_nothrow_copy The copy constructor for T has an empty exception specification or can otherwise be deduced never to throw an exception.
129 // has_nothrow_assign The assignment operator for T has an empty exception specification or can otherwise be deduced never to throw an exception.
130 // has_virtual_destructor T has a virtual destructor.
131 // alignment_of An integer value representing the number of bytes of the alignment of objects of type T; an object of type T may be allocated
132 // at an address that is a multiple of its alignment.
133 // rank An integer value representing the rank of objects of type T. The term 'rank' here is used to describe the number of dimensions of an array type.
134 // extent An integer value representing the extent (dimension) of the I'th bound of objects of type T. If the type T is not an array
135 // type, has rank of less than I, or if I == 0 and T is of type 'array of unknown bound of U,' then value shall evaluate to zero;
136 // otherwise value shall evaluate to the number of elements in the I'th array bound of T. The term 'extent' here is used to describe
137 // the number of elements in an array type.
138 // remove_const The member typedef type shall be the same as T except that any top level const-qualifier has been removed.
139 // remove_const<const volatile int>::type evaluates to volatile int, whereas remove_const<const int*> is const int*.
140 //
141 // * is_aligned is not found in Boost nor the C++ standard update proposal.
142 //
143 // * has_trivial_relocate is not found in Boost nor the C++ standard update proposal.
144 // However, it is very useful in allowing for the generation of optimized object
145 // moving operations. It is similar to the is_pod type trait, but goes further and
146 // allows non-pod classes to be categorized as relocatable. Such categorization is
147 // something that no compiler can do, as only the user can know if it is such.
148 // Thus EASTL_DECLARE_TRIVIAL_RELOCATE is provided to allow the user to give
149 // the compiler a hint.
150 //
152 
154 // Requirements
155 //
156 // As of this writing (5/2005), type_traits here requires a well-conforming
157 // C++ compiler with respect to template metaprogramming. To use this library
158 // you need to have at least one of the following:
159 // MSVC++ 7.1 (includes Win32, XBox 360, Win64, and WinCE platforms)
160 // GCC 3.2 (includes Playstation 3, and Linux platforms)
161 // Metrowerks 8.0 (incluees Playstation 3, Windows, and other platforms)
162 // SN Systems (not the GCC 2.95-based compilers)
163 // EDG (includes any compiler with EDG as a back-end, such as the Intel compiler)
164 // Comeau (this is a C++ to C generator)
165 //
166 // It may be useful to list the compilers/platforms the current version of
167 // type_traits doesn't support:
168 // Borland C++ (it simply has too many bugs with respect to templates).
169 // GCC 2.96 With a little effort, type_traits can probably be made to work with this compiler.
171 
173 // Implementation
174 //
175 // The implementation here is almost entirely based on template metaprogramming.
176 // This is whereby you use the compiler's template functionality to define types
177 // and values and make compilation decisions based on template declarations.
178 // Many of the algorithms here are similar to those found in books such as
179 // "Modern C++ Design" and C++ libraries such as Boost. The implementations here
180 // are simpler and more straightforward than those found in some libraries, due
181 // largely to our assumption that the compiler is good at donig template programming.
183 
184 
185 
186 #ifndef EASTL_TYPE_TRAITS_H
187 #define EASTL_TYPE_TRAITS_H
188 
189 
190 
191 #include <stk_util/util/config_eastl.h>
192 #include <stddef.h> // Is needed for size_t usage by some traits.
193 
194 
195 
196 namespace eastl
197 {
198 
200  // integral_constant
201  //
202  // This is the base class for various type traits, as defined by the proposed
203  // C++ standard. This is essentially a utility base class for defining properties
204  // as both class constants (value) and as types (type).
205  //
206  template <typename T, T v>
207  struct integral_constant
208  {
209  static const T value = v;
210  typedef T value_type;
211  typedef integral_constant<T, v> type;
212  };
213 
214 
216  // true_type / false_type
217  //
218  // These are commonly used types in the implementation of type_traits.
219  // Other integral constant types can be defined, such as those based on int.
220  //
221  typedef integral_constant<bool, true> true_type;
222  typedef integral_constant<bool, false> false_type;
223 
224 
225 
227  // yes_type / no_type
228  //
229  // These are used as a utility to differentiate between two things.
230  //
231  typedef char yes_type; // sizeof(yes_type) == 1
232  struct no_type { char padding[8]; }; // sizeof(no_type) != 1
233 
234 
235 
237  // type_select
238  //
239  // This is used to declare a type from one of two type options.
240  // The result is based on the condition type. This has certain uses
241  // in template metaprogramming.
242  //
243  // Example usage:
244  // typedef ChosenType = type_select<is_integral<SomeType>::value, ChoiceAType, ChoiceBType>::type;
245  //
246  template <bool bCondition, class ConditionIsTrueType, class ConditionIsFalseType>
247  struct type_select { typedef ConditionIsTrueType type; };
248 
249  template <typename ConditionIsTrueType, class ConditionIsFalseType>
250  struct type_select<false, ConditionIsTrueType, ConditionIsFalseType> { typedef ConditionIsFalseType type; };
251 
252 
253 
255  // type_or
256  //
257  // This is a utility class for creating composite type traits.
258  //
259  template <bool b1, bool b2, bool b3 = false, bool b4 = false, bool b5 = false>
260  struct type_or;
261 
262  template <bool b1, bool b2, bool b3, bool b4, bool b5>
263  struct type_or { static const bool value = true; };
264 
265  template <>
266  struct type_or<false, false, false, false, false> { static const bool value = false; };
267 
268 
269 
271  // type_and
272  //
273  // This is a utility class for creating composite type traits.
274  //
275  template <bool b1, bool b2, bool b3 = true, bool b4 = true, bool b5 = true>
276  struct type_and;
277 
278  template <bool b1, bool b2, bool b3, bool b4, bool b5>
279  struct type_and{ static const bool value = false; };
280 
281  template <>
282  struct type_and<true, true, true, true, true>{ static const bool value = true; };
283 
284 
285 
287  // type_equal
288  //
289  // This is a utility class for creating composite type traits.
290  //
291  template <int b1, int b2>
292  struct type_equal{ static const bool value = (b1 == b2); };
293 
294 
295 
297  // type_not_equal
298  //
299  // This is a utility class for creating composite type traits.
300  //
301  template <int b1, int b2>
302  struct type_not_equal{ static const bool value = (b1 != b2); };
303 
304 
305 
307  // type_not
308  //
309  // This is a utility class for creating composite type traits.
310  //
311  template <bool b>
312  struct type_not{ static const bool value = true; };
313 
314  template <>
315  struct type_not<true>{ static const bool value = false; };
316 
317 
318 
320  // empty
321  //
322  template <typename T>
323  struct empty{ };
324 
325 
326 } // namespace eastl
327 
328 
329 // The following files implement the type traits themselves.
330  #include <stk_util/util/type_fundamental_eastl.h>
331  #include <stk_util/util/type_transformations_eastl.h>
332  #include <stk_util/util/type_properties_eastl.h>
333  #include <stk_util/util/type_compound_eastl.h>
334  #include <stk_util/util/type_pod_eastl.h>
335 
336 
337 #endif // Header include guard
EA Standard Template Library.