Header <boost/type_traits.hpp>

Contents

Introduction
Primary Type Categorisation
Secondary Type Categorisation
Type Properties
Relationships Between Types
Transformations Between Types
Synthesizing Types
Function Traits
Type traits headers
User defined specializations
Example Code

Introduction

The contents of <boost/type_traits.hpp> are declared in namespace boost.

The file <boost/type_traits.hpp> defines three kinds of type trait:

1. The properties of a specific type.
2. The relationship between two types.
3. A transformation from one type to another.

If you are new to this library then the accompanying article provides the background information and motivation.

All of the integral expressions in this library are integral constant expressions, these can sometimes cause compiler problems in use, so there is a related set of coding guidelines to help you write portable code using this library.

Primary Type Categorisation

The following type traits templates identify which type category the type belongs to. For any given type, exactly one of the following expressions will evaluate to true. Note that this means that is_integral<T>::value and is_float<T>::value will only every be true for built-in types; if you want to check for a user-defined type that may behave "as if" it is an integral or floating point type, then use the std::numeric_limits template instead.

Secondary Type Categorisation

The following type categories are made up of the union of one or more primary type categorisations. A type may belong to more than one of these categories, in addition to one of the primary categories.

Type Properties

The following templates identify the properties that a type has.

::boost::has_trivial_constructor<T>::value,
::boost::has_trivial_copy<T>::value,
::boost::has_trivial_destructor<T>::value,
::boost::is_class<T>::value,
::boost::is_empty<T>::value

Relationships Between Types

The following templates determine the whether there is a relationship between two types:

::boost::is_same<T,U>::value

Note that both is_convertible, and is_base_and_derived can produce compiler errors if the convertion is ambiguous:

struct A {};
struct B : A {};
struct C : A {};
struct D : B, C {};
bool const x = boost::is_base_and_derived<A,D>::value;  // error
bool const y = boost::is_convertible<D*,A*>::value;     // error

Transformations Between Types

The following templates transform one type to another, based upon some well-defined rule. Each template has a single member called type that is the result of applying the transformation to the template argument T:

As the table above indicates, support for partial specialization of class templates is required to correctly implement the type transformation templates. On the other hand, practice shows that many of the templates from this category are very useful, and often essential for implementing some generic libraries. Lack of these templates is often one of the major limiting factors in porting those libraries to compilers that do not yet support this language feature. As some of these compilers are going to be around for a while, and at least one of them is very wide-spread, it was decided that the library should provide workarounds where possible. The basic idea behind the workaround is

1. To manually define full specializations of all type transformation templates for all fundamental types, and all their 1st and 2nd rank cv-[un]qualified derivative pointer types, and to
2. Provide a user-level macro that will define such explicit specializations for any user-defined type T.

The first part guarantees the successful compilation of something like this:

BOOST_STATIC_ASSERT((is_same<char, remove_reference<char&>::type>::value));

BOOST_STATIC_ASSERT((is_same<char const, remove_reference<char const&>::type>::value));

BOOST_STATIC_ASSERT((is_same<char volatile, remove_reference<char volatile&>::type>::value));

BOOST_STATIC_ASSERT((is_same<char const volatile, remove_reference<char const volatile&>::type>::value));

BOOST_STATIC_ASSERT((is_same<char*, remove_reference<char*&>::type>::value));

BOOST_STATIC_ASSERT((is_same<char const*, remove_reference<char const*&>::type>::value));

...

BOOST_STATIC_ASSERT((is_same<char const volatile* const volatile* const volatile, remove_reference<char const volatile* const volatile* const volatile&>::type>::value));

and the second part provides library's users with a mechanism to make the above code work not only for 'char', 'int' or other built-in type, but for they own types too:

struct my {};

BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION(my)

BOOST_STATIC_ASSERT((is_same<my, remove_reference<my&>::type>::value));

BOOST_STATIC_ASSERT((is_same<my, remove_const<my const>::type>::value));

// etc.

Note that the macro BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION evaluates to nothing on those compilers that do support partial specialization.

Synthesizing Types

The following template synthesizes a type with the desired properties.

Function Traits

The ::boost::function_traits class template extracts information from function types.

Type Traits Headers

The type traits library is normally included with:

#include <boost/type_traits.hpp>

However the library is actually split up into a number of smaller headers, sometimes it can be convenient to include one of these directly in order to get just those type traits classes you actually need.  The split headers always have the same name as the template you require, and are located in boost/type_traits/.  So if for example some code requires is_class<>, then just include:

<boost/type_traits/is_class.hpp>

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::mpl::true_ or boost::mpl::false_ 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 mpl::true_{};
template<>
struct is_pod<my_union> 
   : public mpl::true_{};
template<>
struct is_union<my_union> 
   : public mpl::true_{};
template<>
struct is_class<my_union> 
   : public mpl::false_{};
}

      

Example code

Type-traits comes with four example programs that illustrate some of the ways in which the type traits templates may be used:

Copy_example.cpp

Demonstrates a version of std::copy that uses memcpy where appropriate to optimise the copy operation;

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

namespace detail{

template<typename I1, typename I2>
I2 copy_imp(I1 first, I1 last, I2 out)
{
   while(first != last)
   {
      *out = *first;
      ++out;
      ++first;
   }
   return out;
}

template <bool b>
struct copier
{
   template<typename I1, typename I2>
   static I2 do_copy(I1 first, I1 last, I2 out)
   { return copy_imp(first, last, out); }
};

template <>
struct copier<true>
{
   template<typename I1, typename I2>
   static I2* do_copy(I1* first, I1* last, I2* out)
   {
      memcpy(out, first, (last-first)*sizeof(I2));
      return out+(last-first);
   }
};


}

template<typename I1, typename I2>
inline I2 copy(I1 first, I1 last, I2 out)
{
   typedef typename boost::remove_cv<typename std::iterator_traits<I1>::value_type>::type v1_t;
   typedef typename boost::remove_cv<typename std::iterator_traits<I2>::value_type>::type v2_t;
   return detail::copier<
      ::boost::type_traits::ice_and<
         ::boost::is_same<v1_t, v2_t>::value,
         ::boost::is_pointer<I1>::value,
         ::boost::is_pointer<I2>::value,
         ::boost::has_trivial_assign<v1_t>::value
      >::value>::do_copy(first, last, out);
}

fill_example.cpp

Demonstrates a version of std::fill that uses memset where appropriate to optimise fill operations. Also uses call_traits to optimise parameter passing, to avoid aliasing issues:

namespace opt{
//
// fill
// same as std::fill, uses memset where appropriate, along with call_traits
// to "optimise" parameter passing.
//
namespace detail{

template <typename I, typename T>
void do_fill_(I first, I last, typename boost::call_traits<T>::param_type val)
{
   while(first != last)
   {
      *first = val;
      ++first;
   }
}

template <bool opt>
struct filler
{
   template <typename I, typename T>
   struct rebind
   {
      static void do_fill(I first, I last, typename boost::call_traits<T>::param_type val)
      { do_fill_<I,T>(first, last, val); }
   };
};

template <>
struct filler<true>
{
   template <typename I, typename T>
   struct rebind
   {
      static void do_fill(I first, I last, T val)
      {
         std::memset(first, val, last-first);
      }
   };
};

}

template <class I, class T>
inline void fill(I first, I last, const T& val)
{
   typedef detail::filler<
      ::boost::type_traits::ice_and<
         ::boost::is_pointer<I>::value,
         ::boost::is_arithmetic<T>::value,
         (sizeof(T) == 1)
      >::value> filler_t;
   typedef typename filler_t:: template rebind<I,T> binder;
   binder::do_fill(first, last, val);
}

};   // namespace opt

iter_swap_example.cpp

Demonstrates a version of std::iter_swap that works with proxying iterators, as well as regular ones; calls std::swap for regular iterators, otherwise does a "slow but safe" swap:

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

template <bool b>
struct swapper
{
   template <typename I>
   static void do_swap(I one, I two)
   {
      typedef typename std::iterator_traits<I>::value_type v_t;
      v_t v = *one;
      *one = *two;
      *two = v;
   }
};

template <>
struct swapper<true>
{
   template <typename I>
   static void do_swap(I one, I two)
   {
      using std::swap;
      swap(*one, *two);
   }
};

}

template <typename I1, typename I2>
inline void iter_swap(I1 one, I2 two)
{
   typedef typename std::iterator_traits<I1>::reference r1_t;
   typedef typename std::iterator_traits<I2>::reference r2_t;
   detail::swapper<
      ::boost::type_traits::ice_and<
         ::boost::is_reference<r1_t>::value, 
         ::boost::is_reference<r2_t>::value,
         ::boost::is_same<r1_t, r2_t>::value
      >::value>::do_swap(one, two);
}

};   // namespace opt

Trivial_destructor_example.cpp

This algorithm is the reverse of std::unitialized_copy; it takes a block of initialized memory and calls destructors on all objects therein. This would typically be used inside container classes that manage their own memory:

namespace opt{
//
// 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 <bool>
struct array_destroyer
{
   template <class T>
   static void destroy_array(T* i, T* j){ do_destroy_array(i, j); }
};

template <>
struct array_destroyer<true>
{
   template <class T>
   static void destroy_array(T*, T*){}
};

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

}; // namespace detail

template <class T>
inline void destroy_array(T* p1, T* p2)
{
   detail::array_destroyer<boost::has_trivial_destructor<T>::value>::destroy_array(p1, p2);
}
} // namespace opt

Revised 22 April 2001

Documentation © Copyright John Maddock 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

The type traits library is based on contributions by Steve Cleary, Beman Dawes, Aleksey Gurtovoy, Howard Hinnant, Jesse Jones, Mat Marcus, John Maddock and Jeremy Siek.

Mat Marcus and Jesse Jones have worked on, and published a paper describing the partial specialisation workarounds used in this library.

The is_convertible template is based on code originally devised by Andrei Alexandrescu, see "Generic<Programming>: Mappings between Types and Values".

Maintained by John Maddock, the latest version of this file can be found at www.boost.org, and the boost discussion list at boost@lists.boost.org (see http://www.boost.org/more/mailing_lists.htm#main).