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 (see 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 can not be used with array types (although it can be
used to solve the reference to reference problem).

Existing practice

call_traits equivalent

Description

Notes

T
(return by value)

call_traits<T>::value_type

Defines a type that
represents the "value" of type T. Use this for
functions that return by value, or possibly for stored
values of type T.

2

T&
(return value)

call_traits<T>::reference

Defines a type that
represents a reference to type T. Use for functions that
would normally return a T&.

1

const
T&
(return value)

call_traits<T>::const_reference

Defines a type that
represents a constant reference to type T. Use for
functions that would normally return a const T&.

1

const
T&
(function parameter)

call_traits<T>::param_type

Defines a type that
represents the "best" way to pass a parameter
of type T to a function.

1,3

Notes:

If T is already reference type, then call_traits is
defined such that references to
references do not occur (requires partial
specialization).

If 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!).

If 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).

Copy constructibility

The following table defines which call_traits types can always
be copy-constructed from which other types, those entries marked
with a '?' are true only if and only if T is copy constructible:

To:

From:

T

value_type

reference

const_reference

param_type

T

?

?

Y

Y

Y

value_type

?

?

N

N

Y

reference

?

?

Y

Y

Y

const_reference

?

N

N

Y

Y

param_type

?

?

N

N

Y

If T is an assignable type the following assignments are
possible:

To:

From:

T

value_type

reference

const_reference

param_type

T

Y

Y

-

-

-

value_type

Y

Y

-

-

-

reference

Y

Y

-

-

-

const_reference

Y

Y

-

-

-

param_type

Y

Y

-

-

-

Examples

The following table shows the effect that call_traits has on
various types, the table assumes that the compiler supports
partial specialization: if it doesn't then all types behave in
the same way as the entry for "myclass", and
call_traits can not be used with reference or array types.

Call_traits type:

Original type T

value_type

reference

const_reference

param_type

Applies to:

myclass

myclass

myclass&

const
myclass&

myclass
const&

All user
defined types.

int

int

int&

const
int&

int const

All small
built-in types.

int*

int*

int*&

int*const&

int* const

All
pointer types.

int&

int&

int&

const
int&

int&

All
reference types.

const int&

const
int&

const
int&

const
int&

const
int&

All
constant-references.

int[3]

const int*

int(&)[3]

const int(&)[3]

const int*
const

All array
types.

const int[3]

const int*

const int(&)[3]

const int(&)[3]

const int*
const

All
constant-array types.

Example 1:

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:

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:

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.

Example 3 (the make_pair problem):

If we pass the name of an array as one (or both) arguments to std::make_pair,
then template argument deduction deduces the passed parameter as
"const reference to array of T", 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 make_pair to pointers, but call_traits provides a
better (i.e. automatic) solution (and one that works safely even
in generic code where the cast might do the wrong thing):

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
make_pair are not expressed in terms of call_traits: doing so
would prevent template argument deduction from functioning.

Example 4 (optimising fill):

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++ implemention is
used, but with the passed parameter "optimized" using
call_traits:

Footnote: 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.

Rationale

The following notes are intended to briefly describe the
rational 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 [3.9.1]) 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 rational as small built-in types.

For reference types the rational 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 it's actual type is const int*,
if we try to use the type T within the function body, then there
is a strong likelyhood that our code will not compile:

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 don't 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).