| Home | Libraries | People | FAQ | More

## Tuple library advanced features

Copyright © 2001 Jaakko Järvi

Distributed under the Boost Software License, Version 1.0.

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 `N`-th 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:

- `access_traits<T>::non_const_type` maps `T` to the return type of the no n-const access functions (nonmember and member `get` functions, and the `get_head` function).
- `access_traits<T>::const_type` maps `T` to the return type of the const access functions.
- `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:

- any reference type -> compile time error
- any array type -> constant reference to the array type
- `reference_wrapper<T>` -> `T&`
- `T` -> `T`

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.