|  | Home | Libraries | People | FAQ | More | 
          All of the contents of <boost/call_traits.hpp> are defined inside namespace boost.
        
          The template class call_traits<T> encapsulates the "best"
          method to pass a parameter of some type T
          to or from a function, and consists of a collection of typedefs
          defined as in the table below. The purpose of call_traits is to ensure that
          problems like "references to references"
          never occur, and that parameters are passed in the most efficient manner
          possible, as in the examples. In each
          case, if your existing practice is to use the type defined on the left,
          then replace it with the call_traits defined type on the
          right.
        
          Note that for compilers that do not support either partial specialization
          or member templates, no benefit will occur from using call_traits: the call_traits defined types will
          always be the same as the existing practice in this case. In addition if
          only member templates and not partial template specialisation is support
          by the compiler (for example Visual C++ 6) then call_traits cannot be used with
          array types, although it can still be used to solve the reference to reference
          problem.
        
Table 1.2. call_traits
          types
| Existing practice | 
                     | Description | Notes | 
|---|---|---|---|
| 
                     (return by value) | 
                     | 
                    Defines a type that represents the "value" of type
                     
                    Use this for functions that return by value, or possibly for
                    stored values of type  | 2 | 
| 
                     (return value) | 
                     | 
                    Defines a type that represents a reference to type  
                    Use for functions that would normally return a  | 1 | 
| 
                     (return value) | 
                     | 
                    Defines a type that represents a constant reference to type
                     
                    Use for functions that would normally return a  | 1 | 
| 
                     (function parameter) | 
                     | 
                    Defines a type that represents the "best" way to pass
                    a parameter of type  | 1,3 | 
Notes:
T is already reference
              type, then call_traits
              is defined such that "references to references"
              do not occur (requires partial specialization).
            T is an array type,
              then call_traits
              defines value_type
              as a "constant pointer to type" rather than an "array
              of type" (requires partial specialization). Note that if you are
              using value_type as
              a stored value then this will result in storing a "constant pointer
              to an array" rather than the array itself. This may or may not
              be a good thing depending upon what you actually need (in other words
              take care!).
            T is a small built
              in type or a pointer, then param_type
              is defined as T const,
              instead of T const&. This can improve the ability
              of the compiler to optimize loops in the body of the function if they
              depend upon the passed parameter, the semantics of the passed parameter
              is otherwise unchanged (requires partial specialization).
            
          The following table defines which call_traits types can always be
          copy-constructed from which other types:
        
Table 1.3. Which call_traits
          types can always be copy-constructed from which other types
| 
                    To  | 
                    To  | 
                    To  | 
                    To  | 
                    To  | |
|---|---|---|---|---|---|
| 
                    From  | 
                    iff  | 
                    iff  | Yes | Yes | Yes | 
| 
                    From  | 
                    iff  | 
                    iff  | No | No | Yes | 
| 
                    From  | 
                    iff  | 
                    iff  | Yes | Yes | Yes | 
| 
                    From  | 
                    iff  | No | No | Yes | Yes | 
| 
                    From  | 
                    iff  | 
                    iff  | No | No | Yes | 
          If T is an assignable type
          the following assignments are possible:
        
Table 1.4. Which call_traits
          types are assignable from which other types
| 
                    To  | 
                    To  | 
                    To  | 
                    To  | 
                    To  | |
|---|---|---|---|---|---|
| 
                    From  | Yes | Yes | - | - | - | 
| 
                    From  | Yes | Yes | - | - | - | 
| 
                    From  | Yes | Yes | - | - | - | 
| 
                    From  | Yes | Yes | - | - | - | 
| 
                    From  | Yes | Yes | - | - | - | 
          The following table shows the effect that call_traits has on various types.
        
Table 1.5. Examples of call_traits
          types
| 
                     | 
                     | 
                     | 
                     | Applies to: | |
|---|---|---|---|---|---|
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All user-defined types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All small built-in types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All pointer types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All reference types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All constant reference types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All array types | 
| 
                    From  | 
                     | 
                     | 
                     | 
                     | All constant array types | 
          The table assumes the compiler supports partial specialization: if it does
          not then all types behave in the same way as the entry for "my_class", and call_traits can not be used with
          reference or array types.
        
            The following class is a trivial class that stores some type T by value (see the call_traits_test.cpp file). The aim is to illustrate
            how each of the available call_traits typedefs
            may be used:
          
template <class T> struct contained { // define our typedefs first, arrays are stored by value // so value_type is not the same as result_type: typedef typenameboost::call_traits<T>::param_type param_type; typedef typenameboost::call_traits<T>::reference reference; typedef typenameboost::call_traits<T>::const_reference const_reference; typedef T value_type; typedef typenameboost::call_traits<T>::value_type result_type; // stored value: value_type v_; // constructors: contained() {} contained(param_type p) : v_(p){} // return byval: result_type value() { return v_; } // return by_ref: reference get() { return v_; } const_reference const_get()const { return v_; } // pass value: void call(param_type p){} };
            Consider the definition of std::binder1st:
          
template <class Operation>
class binder1st :
   public std::unary_function<typename Operation::second_argument_type, typename Operation::result_type>
{
protected:
   Operation op;
   typename Operation::first_argument_type value;
public:
   binder1st(const Operation& x, const typename Operation::first_argument_type& y);
   typename Operation::result_type operator()(const typename Operation::second_argument_type& x) const;
};
            Now consider what happens in the relatively common case that the functor
            takes its second argument as a reference, that implies that Operation::second_argument_type is a reference
            type, operator()
            will now end up taking a reference to a reference as an argument, and
            that is not currently legal. The solution here is to modify operator()
            to use call_traits:
          
typename Operation::result_type operator()(typename call_traits<typename Operation::second_argument_type>::param_type x) const;
            Now in the case that Operation::second_argument_type
            is a reference type, the argument is passed as a reference, and the no
            "reference to reference" occurs.
          
            If we pass the name of an array as one (or both) arguments to std::make_pairT",
            this also applies to string literals (which are really array literals).
            Consequently instead of returning a pair of pointers, it tries to return
            a pair of arrays, and since an array type is not copy-constructible the
            code fails to compile. One solution is to explicitly cast the arguments
            to std::make_pair to pointers, but
            call_traits
            provides a better automatic solution that works safely even in generic
            code where the cast might do the wrong thing:
          
template <class T1, class T2>std::pair< typenameboost::call_traits<T1>::value_type, typenameboost::call_traits<T2>::value_type> make_pair(const T1& t1, const T2& t2) { returnstd::pair< typenameboost::call_traits<T1>::value_type, typenameboost::call_traits<T2>::value_type>(t1, t2); }
            Here, the deduced argument types will be automatically degraded to pointers
            if the deduced types are arrays, similar situations occur in the standard
            binders and adapters: in principle in any function that "wraps"
            a temporary whose type is deduced. Note that the function arguments to
            std::make_pair are not expressed
            in terms of call_traits:
            doing so would prevent template argument deduction from functioning.
          
            The call_traits
            template will "optimize" the passing of a small built-in type
            as a function parameter. This mainly has an effect when the parameter
            is used within a loop body.
          
            In the following example (see fill_example.cpp), a version of std::fill is optimized in two ways:
            if the type passed is a single byte built-in type then std::memset is used to effect the
            fill, otherwise a conventional C++ implementation is used, but with the
            passed parameter "optimized" using call_traits:
          
template <bool opt> struct filler { template <typename I, typename T> static void do_fill(I first, I last, typenameboost::call_traits<T>::param_type val) { while(first != last) { *first = val; ++first; } } }; template <> struct filler<true> { template <typename I, typename T> 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) { enum { can_opt = boost::is_pointer<I>::value && boost::is_arithmetic<T>::value && (sizeof(T) == 1) }; typedef filler<can_opt> filler_t; filler_t::template do_fill<I,T>(first, last, val); }
            The reason that this is "optimal" for small built-in types
            is that with the value passed as T
            const instead of const T& the compiler is able to tell both
            that the value is constant and that it is free of aliases. With this
            information the compiler is able to cache the passed value in a register,
            unroll the loop, or use explicitly parallel instructions: if any of these
            are supported. Exactly how much mileage you will get from this depends
            upon your compiler - we could really use some accurate benchmarking software
            as part of boost for cases like this.
          
            Note that the function arguments to fill are not expressed in terms of
            call_traits:
            doing so would prevent template argument deduction from functioning.
            Instead fill acts as a "thin wrapper" that is there to perform
            template argument deduction, the compiler will optimise away the call
            to fill all together, replacing it with the call to filler<>::do_fill,
            which does use call_traits.
          
          The following notes are intended to briefly describe the rationale behind
          choices made in call_traits.
        
All user-defined types follow "existing practice" and need no comment.
          Small built-in types, what the standard calls fundamental
          types, differ from existing practice only in the param_type typedef.
          In this case passing T const is compatible with existing practice,
          but may improve performance in some cases (see Example
          4). In any case this should never be any worse than existing practice.
        
Pointers follow the same rationale as small built-in types.
          For reference types the rationale follows Example
          2 - references to references are not allowed, so the call_traits members must be defined
          such that these problems do not occur. There is a proposal to modify the
          language such that "a reference to a reference is a reference"
          (issue #106, submitted by Bjarne Stroustrup). call_traits<T>::value_type
          and call_traits<T>::param_type both provide the same effect
          as that proposal, without the need for a language change. In other words,
          it's a workaround.
        
For array types, a function that takes an array as an argument will degrade the array type to a pointer type: this means that the type of the actual parameter is different from its declared type, something that can cause endless problems in template code that relies on the declared type of a parameter.
For example:
template <class T> struct A { void foo(T t); };
          In this case if we instantiate A<int[2]>
          then the declared type of the parameter passed to member function foo is int[2],
          but its actual type is const int*. If
          we try to use the type T
          within the function body, then there is a strong likelihood that our code
          will not compile:
        
template <class T> void A<T>::foo(T t) { T dup(t); // doesn't compile for case that T is an array. }
          By using call_traits
          the degradation from array to pointer is explicit, and the type of the
          parameter is the same as it's declared type:
        
template <class T> struct A { void foo(typenamecall_traits<T>::value_type t); }; template <class T> void A<T>::foo(typenamecall_traits<T>::value_type t) { typenamecall_traits<T>::value_type dup(t); // OK even if T is an array type. }
          For value_type (return
          by value), again only a pointer may be returned, not a copy of the whole
          array, and again call_traits
          makes the degradation explicit. The value_type
          member is useful whenever an array must be explicitly degraded to a pointer
          - Example 3 provides the test case.
        
          Footnote: the array specialisation for call_traits is the least well
          understood of all the call_traits
          specialisations. If the given semantics cause specific problems for you,
          or does not solve a particular array-related problem, then I would be interested
          to hear about it. Most people though will probably never need to use this
          specialisation.