C++ Boost

Tuple library advanced features

The advanced features described in this document are all under namespace ::boost::tuples

Metafunctions for tuple types

Suppose T is a tuple type, and N is a constant integral expression.

element<N, T>::type
gives the type of the Nth element in the tuple type T. If T is const, the resulting type is const qualified as well. Note that the constness of T does not affect reference type elements.

length<T>::value
gives the length of the tuple type T.

Cons lists

Tuples are internally represented as cons lists. For example, the tuple

tuple<A, B, C, D>
inherits from the type
cons<A, cons<B, cons<C, cons<D, null_type> > > >
The tuple template provides the typedef inherited to access the cons list representation. E.g.: tuple<A>::inherited is the type cons<A, null_type>.

Empty tuple

The internal representation of the empty tuple tuple<> is null_type.

Head and tail

Both tuple template and the cons templates provide the typedefs head_type and tail_type. The head_type typedef gives the type of the first element of the tuple (or the cons list). The tail_type typedef gives the remaining cons list after removing the first element. The head element is stored in the member variable head and the tail list in the member variable tail. Cons lists provide the member function get_head() for getting a reference to the head of a cons list, and get_tail() for getting a reference to the tail. There are const and non-const versions of both functions.

Note that in a one element tuple, tail_type equals null_type and the get_tail() function returns an object of type null_type.

The empty tuple (null_type) has no head or tail, hence the get_head and get_tail functions are not provided.

Treating tuples as cons lists gives a convenient means to define generic functions to manipulate tuples. For example, the following pair of function templates assign 0 to each element of a tuple (obviously, the assignments must be valid operations for the element types):

inline void set_to_zero(const null_type&) {};

template <class H, class T>
inline void set_to_zero(cons<H, T>& x) { x.get_head() = 0; set_to_zero(x.get_tail()); }

Constructing cons lists

A cons list can be default constructed provided that all its elements can be default constructed.

A cons list can be constructed from its head and tail. The prototype of the constructor is:

cons(typename access_traits<head_type>::parameter_type h,
     const tail_type& t)
The traits template for the head parameter selects correct parameter types for different kinds of element types (for reference elements the parameter type equals the element type, for non-reference types the parameter type is a reference to const non-volatile element type).

For a one-element cons list the tail argument (null_type) can be omitted.

Traits classes for tuple element types

access_traits

The template access_traits defines three type functions. Let T be a type of an element in a tuple:

  1. access_traits<T>::type maps T to the return type of the non-const access functions (nonmeber and member get functions, and the get_head function).
  2. access_traits<T>::const_type maps T to the return type of the const access functions.
  3. access_traits<T>::parameter_type maps T to the parameter type of the tuple constructor.

make_tuple_traits

The element types of the tuples that are created with the make_tuple functions are computed with the type function make_tuple_traits. The type function call make_tuple_traits<T>::type implements the following type mapping: Objects of type reference_wrapper are created with the ref and cref functions (see The make_tuple function.)

Reference wrappers were originally part of the tuple library, but they are now a general utility of boost. The reference_wrapper template and the ref and cref functions are defined in a separate file ref.hpp in the main boost include directory; and directly in the boost namespace.

Back to the user's guide

© Copyright Jaakko Järvi 2001.