type_traits.qbk

C++的一个好库。。。现在很流行

[endsect]

[section:alignment Synthesizing Types with Specific Alignments]

Some low level memory management routines need to synthesize a POD type with
specific alignment properties.  The template `__type_with_alignment` finds the smallest
type with a specified alignment, while template `__aligned_storage` creates a type 
with a specific size and alignment.

[*Synopsis]

   template <std::size_t Align>
   struct __type_with_alignment;
   
   template <std::size_t Size, std::size_t Align>
   struct __aligned_storage;

[endsect]

[section:function Decomposing Function Types]

The class template __function_traits extracts information from function types
(see also __is_function).  This traits class allows you to tell how many arguments
a function takes, what those argument types are, and what the return type is.

[*Synopsis]

   template <std::size_t Align>
   struct __function_traits;

[endsect]

[endsect]

[section:user_defined User Defined Specializations]

Occationally the end user may need to provide their own specialization 
for one of the type traits - typically where intrinsic compiler support 
is required to implement a specific trait fully.  
These specializations should derive from boost::__true_type or boost::__false_type 
as appropriate:

   #include <boost/type_traits/is_pod.hpp>
   #include <boost/type_traits/is_class.hpp>
   #include <boost/type_traits/is_union.hpp>

   struct my_pod{};
   struct my_union
   {
      char c;
      int i;
   };

   namespace boost
   {
      template<>
      struct __is_pod<my_pod> : public __true_type{};
         
      template<>
      struct __is_pod<my_union> : public __true_type{};
      
      template<>
      struct __is_union<my_union> : public __true_type{};
      
      template<>
      struct __is_class<my_union> : public __false_type{};
   }

[endsect]

[section:intrinsics Support for Compiler Intrinsics]

There are some traits that can not be implemented within the current C++ language:
to make these traits "just work" with user defined types, some kind of additional
help from the compiler is required.  Currently (May 2005) MWCW 9 and Visual C++ 8
provide the necessary intrinsics, and other compilers will no doubt follow in due 
course.  

The Following traits classes always need compiler support to do the right thing 
for all types 
(but all have safe fallback positions if this support is unavailable):

* __is_union
* __is_pod
* __has_trivial_constructor
* __has_trivial_copy
* __has_trivial_assign
* __has_trivial_destructor
* __has_nothrow_constructor
* __has_nothrow_copy
* __has_nothrow_assign
* __has_virtual_destructor

The following traits classes can't be portably implemented in the C++ language, 
although in practice, the implementations do in fact do the right thing on all
the compilers we know about:

* __is_empty
* __is_polymorphic

The following traits classes are dependent on one or more of the above:

* __is_class
* __is_stateless

The hooks for compiler-intrinsic support are defined in 
[@../../boost/type_traits/intrinsics.hpp boost/type_traits/intrinsics.hpp], adding support for new compilers is simply
a matter of defining one of more of the following macros:

[table Macros for Compiler Intrinsics
   [[BOOST_IS_UNION(T)][Should evaluate to true if T is a union type]]
   [[BOOST_IS_POD(T)][Should evaluate to true if T is a POD type]]
   [[BOOST_IS_EMPTY(T)][Should evaluate to true if T is an empty struct or union]]
   [[BOOST_HAS_TRIVIAL_CONSTRUCTOR(T)][Should evaluate to true if the default constructor for T is trivial (i.e. has no effect)]]
   [[BOOST_HAS_TRIVIAL_COPY(T)][Should evaluate to true if T has a trivial copy constructor (and can therefore be replaced by a call to memcpy)]]
   [[BOOST_HAS_TRIVIAL_ASSIGN(T)][Should evaluate to true if T has a trivial assignment operator (and can therefore be replaced by a call to memcpy)]]
   [[BOOST_HAS_TRIVIAL_DESTRUCTOR(T)][Should evaluate to true if T has a trivial destructor (i.e. ~T() has no effect)]]
   [[BOOST_HAS_NOTHROW_CONSTRUCTOR(T)][Should evaluate to true if `T x;` can not throw]]
   [[BOOST_HAS_NOTHROW_COPY(T)][Should evaluate to true if `T(t)` can not throw]]
   [[BOOST_HAS_NOTHROW_ASSIGN(T)][Should evaluate to true if `T t, u; t = u` can not throw]]
   [[BOOST_HAS_VIRTUAL_DESTRUCTOR(T)][Should evaluate to true T has a virtual destructor]]
]

[endsect]

[section:mpl MPL Interoperability]

All the value based traits in this library conform to MPL's requirements
for an [@../../libs/mpl/doc/refmanual/integral-constant.html Integral Constant type]: that includes a number of rather intrusive
workarounds for broken compilers.  

Purely as an implementation detail, this
means that `__true_type` inherits from [@../../libs/mpl/doc/refmanual/bool.html `boost::mpl::true_`], `__false_type` inherits
from [@../../libs/mpl/doc/refmanual/bool.html `boost::mpl::false_`], and `__integral_constant<T, v>` inherits from
[@../../libs/mpl/doc/refmanual/integral-c.html `boost::mpl::integral_c<T,v>`] (provided `T` is not `bool`)

[endsect]

[section:examples Examples]

[section:copy An Optimized Version of std::copy]

Demonstrates a version of `std::copy` that uses `__has_trivial_assign` to
determine whether to use `memcpy` to optimise the copy operation 
(see [@../../libs/type_traits/examples/copy_example.cpp copy_example.cpp]):

   //
   // opt::copy
   // same semantics as std::copy
   // calls memcpy where appropriate.
   //

   namespace detail{

   template<typename I1, typename I2, bool b>
   I2 copy_imp(I1 first, I1 last, I2 out, const boost::__integral_constant<bool, b>&)
   {
      while(first != last)
      {
         *out = *first;
         ++out;
         ++first;
      }
      return out;
   }

   template<typename T>
   T* copy_imp(const T* first, const T* last, T* out, const boost::__true_type&)
   {
      memcpy(out, first, (last-first)*sizeof(T));
      return out+(last-first);
   }


   }

   template<typename I1, typename I2>
   inline I2 copy(I1 first, I1 last, I2 out)
   {
      //
      // We can copy with memcpy if T has a trivial assignment operator,
      // and if the iterator arguments are actually pointers (this last
      // requirement we detect with overload resolution):
      //
      typedef typename std::iterator_traits<I1>::value_type value_type;
      return detail::copy_imp(first, last, out, boost::__has_trivial_assign<value_type>());
   }


[endsect]

[section:fill An Optimised Version of std::fill]

Demonstrates a version of `std::fill` that uses `__has_trivial_assign` to
determine whether to use `memset` to optimise the fill operation 
(see [@../../libs/type_traits/examples/fill_example.cpp fill_example.cpp]):

   //
   // fill
   // same as std::fill, but uses memset where appropriate
   //
   namespace detail{

   template <typename I, typename T, bool b>
   void do_fill(I first, I last, const T& val, const boost::__integral_constant<bool, b>&)
   {
      while(first != last)
      {
         *first = val;
         ++first;
      }
   }

   template <typename T>
   void do_fill(T* first, T* last, const T& val, const boost::__true_type&)
   {
      std::memset(first, val, last-first);
   }

   }

   template <class I, class T>
   inline void fill(I first, I last, const T& val)
   {
      //
      // We can do an optimised fill if T has a trivial assignment 
      // operator and if it's size is one:
      //
      typedef boost::__integral_constant<bool, 
         ::boost::__has_trivial_assign<T>::value && (sizeof(T) == 1)> truth_type;
      detail::do_fill(first, last, val, truth_type());
   }


[endsect]

[section:destruct An Example that Omits Destructor Calls For Types with Trivial Destructors]

Demonstrates a simple algorithm that uses `__has_trivial_destruct` to
determine whether to destructors need to be called 
(see [@../../libs/type_traits/examples/trivial_destructor_example.cpp trivial_destructor_example.cpp]):

   //
   // algorithm destroy_array:
   // The reverse of std::unitialized_copy, takes a block of
   // initialized memory and calls destructors on all objects therein.
   //

   namespace detail{

   template <class T>
   void do_destroy_array(T* first, T* last, const boost::__false_type&)
   {
      while(first != last)
      {
         first->~T();
         ++first;
      }
   }

   template <class T>
   inline void do_destroy_array(T* first, T* last, const boost::__true_type&)
   {
   }

   } // namespace detail

   template <class T>
   inline void destroy_array(T* p1, T* p2)
   {
      detail::do_destroy_array(p1, p2, ::boost::__has_trivial_destructor<T>());
   }


[endsect]

[section:iter An improved Version of std::iter_swap]

Demonstrates a version of `std::iter_swap` that use type traits to
determine whether an it's arguments are proxying iterators or not,
if they're not then it just does a `std::swap` of it's dereferenced 
arguments (the
same as `std::iter_swap` does), however if they are proxying iterators
then takes special care over the swap to ensure that the algorithm
works correctly for both proxying iterators, and even iterators of
different types 
(see [@../../libs/type_traits/examples/iter_swap_example.cpp iter_swap_example.cpp]):

   //
   // iter_swap:
   // tests whether iterator is a proxying iterator or not, and
   // uses optimal form accordingly:
   //
   namespace detail{

   template <typename I>
   static void do_swap(I one, I two, const boost::__false_type&)
   {
      typedef typename std::iterator_traits<I>::value_type v_t;
      v_t v = *one;
      *one = *two;
      *two = v;
   }
   template <typename I>
   static void do_swap(I one, I two, const boost::__true_type&)
   {
      using std::swap;
      swap(*one, *two);
   }

   }

   template <typename I1, typename I2>
   inline void iter_swap(I1 one, I2 two)
   {
      //
      // See is both arguments are non-proxying iterators, 
      // and if both iterator the same type:
      //
      typedef typename std::iterator_traits<I1>::reference r1_t;
      typedef typename std::iterator_traits<I2>::reference r2_t;

      typedef boost::__integral_constant<bool,
         ::boost::__is_reference<r1_t>::value
         && ::boost::__is_reference<r2_t>::value
         && ::boost::__is_same<r1_t, r2_t>::value> truth_type;

      detail::do_swap(one, two, truth_type());
   }


[endsect]

[endsect]

[section:reference Alphabetical Reference]

[section:add_const add_const]

   template <class T>
   struct add_const
   {
      typedef __below type;