The Boost Tuple Library

A tuple (or n-tuple) is a fixed size collection of elements.
Pairs, triples, quadruples etc. are tuples.
In a programming language, a tuple is a data object containing other objects as elements.
These element objects may be of different types.

Tuples are convenient in many circumstances.
For instance, tuples make it easy to define functions that return more than one value.

Some programming languages, such as ML, Python and Haskell, have built-in tuple constructs.
Unfortunately C++ does not.
To compensate for this "deficiency", the Boost Tuple Library implements a tuple construct using templates.

All definitions are in namespace ::boost::tuples, but the most common names are lifted to namespace
::boost with using declarations. These names are: tuple, make_tuple, tie and get.
Further, ref and cref are defined directly under the ::boost namespace.

A tuple type is an instantiation of the tuple template.
The template parameters specify the types of the tuple elements.
The current version supports tuples with 0-10 elements.
If necessary, the upper limit can be increased up to, say, a few dozen elements.
The data element can be any C++ type.
Note that void and plain function types are valid
C++ types, but objects of such types cannot exist.
Hence, if a tuple type contains such types as elements, the tuple type
can exist, but not an object of that type.
There are natural limitations for element types that cannot
be copied, or that are not default constructible (see 'Constructing tuples'
below).

For example, the following definitions are valid tuple instantiations (A, B and C are some user defined classes):

It is possible to come up with a tuple type that cannot be constructed.
This occurs if an element that cannot be initialized has a lower
index than an element that requires initialization.
For example: tuple<char[10], int&>.

In sum, the tuple construction is semantically just a group of individual elementary constructions.

Tuples can also be constructed using the make_tuple (cf. std::make_pair) helper functions.
This makes the construction more convenient, saving the programmer from explicitly specifying the element types:

By default, the element types are deduced to the plain non-reference types. E.g.:

void foo(const A& a, B& b) {
...
make_tuple(a, b);

The make_tuple invocation results in a tuple of type tuple<A, B>.

Sometimes the plain non-reference type is not desired, e.g. if the element type cannot be copied.
Therefore, the programmer can control the type deduction and state that a reference to const or reference to
non-const type should be used as the element type instead.
This is accomplished with two helper template functions: ref and cref.
Any argument can be wrapped with these functions to get the desired type.
The mechanism does not compromise const correctness since a const object wrapped with ref results
in a tuple element with const reference type (see the fifth example below).
For example:

Array arguments to make_tuple functions are deduced to reference to const types by default; there is no need to wrap them with cref. For example:

make_tuple("Donald", "Daisy");

This creates an object of type tuple<const char (&)[7], const char (&)[6]>
(note that the type of a string literal is an array of const characters, not const char*).
However, to get make_tuple to create a tuple with an element of a
non-const array type one must use the ref wrapper.

Function pointers are deduced to the plain non-reference type, that is, to plain function pointer.
A tuple can also hold a reference to a function,
but such a tuple cannot be constructed with make_tuple (a const qualified function type would result, which is illegal):

where t is a tuple object and N is a constant integral expression specifying the index of the element to be accessed.
Depending on whether t is const or not, get returns the Nth element as a reference to const or
non-const type.
The index of the first element is 0 and thus
N must be between 0 and k-1, where k is the number of elements in the tuple.
Violations of these constraints are detected at compile time. Examples:

Note! The member get functions are not supported with MS Visual C++ compiler.
Further, the compiler has trouble with finding the non-member get functions without an explicit namespace qualifier.
Hence, all get calls should be qualified as: tuples::get<N>(a_tuple) when writing code that should compile with MSVC++ 6.0.

A tuple can be copy constructed from another tuple, provided that the element types are element-wise copy constructible.
Analogously, a tuple can be assigned to another tuple, provided that the element types are element-wise assignable.
For example:

Tuples reduce the operators ==, !=, <, >, <= and >= to the corresponding elementary operators.
This means, that if any of these operators is defined between all elements of two tuples, then the same operator is defined between the tuples as well.
The equality operators for two tuples a and b are defined as:

a == b iff for each i: ai == bi

a != b iff exists i: ai != bi

The operators <, >, <= and >= implement a lexicographical ordering.

Note that an attempt to compare two tuples of different lengths results in a compile time error.
Also, the comparison operators are "short-circuited": elementary comparisons start from the first elements and are performed only until the result is clear.

This code prints 1 a 5.5 to the standard output stream.
A tuple unpacking operation like this is found for example in ML and Python.
It is convenient when calling functions which return tuples.

The tying mechanism works with std::pair templates as well:

int i; char c;
tie(i, c) = std::make_pair(1, 'a');

Ignore

There is also an object called ignore which allows you to ignore an element assigned by a tuple.
The idea is that a function may return a tuple, only part of which you are interested in. For example (note, that ignore is under the tuples subnamespace):

All tuple access and construction functions are small inlined one-liners.
Therefore, a decent compiler can eliminate any extra cost of using tuples compared to using hand-written tuple like classes.
Particularly, with a decent compiler there is no performance difference between this code:

Note, that there are widely used compilers (e.g. bcc 5.5.1) which fail to optimize this kind of tuple usage.

Depending on the optimizing ability of the compiler, the tier mechanism may have a small performance penalty compared to using
non-const reference parameters as a mechanism for returning multiple values from a function.
For example, suppose that the following functions f1 and f2 have equivalent functionalities:

Effect on Compile Time

Compiling tuples can be slow due to the excessive amount of template instantiations.
Depending on the compiler and the tuple length, it may be more than 10 times slower to compile a tuple construct, compared to compiling an equivalent explicitly written class, such as the hand_made_tuple class above.
However, as a realistic program is likely to contain a lot of code in addition to tuple definitions, the difference is probably unnoticeable.
Compile time increases between 5 and 10 percent were measured for programs which used tuples very frequently.
With the same test programs, memory consumption of compiling increased between 22% to 27%. See
[1,
2]
for details.

Gary Powell has been an indispensable helping hand. In particular, stream manipulators for tuples were his idea. Doug Gregor came up with a working version for MSVC, David Abrahams found a way to get rid of most of the restrictions for compilers not supporting partial specialization. Thanks to Jeremy Siek, William Kempf and Jens Maurer for their help and suggestions.
The comments by Vesa Karvonen, John Max Skaller, Ed Brey, Beman Dawes, David Abrahams and Hartmut Kaiser helped to improve the
library.
The idea for the tie mechanism came from an old usenet article by Ian McCulloch, where he proposed something similar for std::pairs.