...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Copyright © 2001 Jaakko Järvi
Distributed under the Boost Software License, Version 1.0.
Table of Contents
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.
To use the library, just include:
#include "boost/tuple/tuple.hpp"
Comparison operators can be included with:
#include "boost/tuple/tuple_comparison.hpp"
To use tuple input and output operators,
#include "boost/tuple/tuple_io.hpp"
Both tuple_io.hpp
and tuple_comparison.hpp
include
tuple.hpp
.
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):
tuple<int> tuple<double&, const double&, const double, double*, const double*> tuple<A, int(*)(char, int), B(A::*)(C&), C> tuple<std::string, std::pair<A, B> > tuple<A*, tuple<const A*, const B&, C>, bool, void*>
The tuple constructor takes the tuple elements as arguments. For an n-
element tuple, the constructor can be invoked with k arguments,
where 0
<= k
<= n. For example:
tuple<int, double>() tuple<int, double>(1) tuple<int, double>(1, 3.14)
If no initial value for an element is provided, it is default initialized (and hence must be default initializable). For example:
class X { X(); public: X(std::string); }; tuple<X,X,X>() // error: no default constructor for X tuple<X,X,X>(string("Jaba"), string("Daba"), string("Duu")) // ok
In particular, reference types do not have a default initialization:
tuple<double&>() // error: reference must be // initialized explicitly double d = 5; tuple<double&>(d) // ok tuple<double&>(d+3.14) // error: cannot initialize // non-const reference with a temporary tuple<const double&>(d+3.14) // ok, but dangerous: // the element becomes a dangling reference
Using an initial value for an element that cannot be copied, is a compile time error:
class Y { Y(const Y&); public: Y(); }; char a[10]; tuple<char[10], Y>(a, Y()); // error, neither arrays nor Y can be copied tuple<char[10], Y>(); // ok
Note particularly that the following is perfectly ok:
Y y; tuple<char(&)[10], Y&>(a, y);
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:
tuple<int, int, double> add_multiply_divide(int a, int b) { return make_tuple(a+b, a*b, double(a)/double(b)); }
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: boost::ref
and boost::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:
A a; B b; const A ca = a; make_tuple(cref(a), b); // creates tuple<const A&, B> make_tuple(ref(a), b); // creates tuple<A&, B> make_tuple(ref(a), cref(b)); // creates tuple<A&, const B&> make_tuple(cref(ca)); // creates tuple<const A&> make_tuple(ref(ca)); // creates tuple<const A&>
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):
void f(int i); ... make_tuple(&f); // tuple<void (*)(int)> ... tuple<tuple<void (&)(int)> > a(f) // ok make_tuple(f); // not ok
Tuple elements are accessed with the expression:
t.get<N>()
or
get<N>(t)
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 N
-th 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:
double d = 2.7; A a; tuple<int, double&, const A&> t(1, d, a); const tuple<int, double&, const A&> ct = t; ... int i = get<0>(t); i = t.get<0>(); // ok int j = get<0>(ct); // ok get<0>(t) = 5; // ok get<0>(ct) = 5; // error, can't assign to const ... double e = get<1>(t); // ok get<1>(t) = 3.14; // ok get<2>(t) = A(); // error, can't assign to const A aa = get<3>(t); // error: index out of bounds ... ++get<0>(t); // ok, can be used as any variable
[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:
class A {}; class B : public A {}; struct C { C(); C(const B&); }; struct D { operator C() const; }; tuple<char, B*, B, D> t; ... tuple<int, A*, C, C> a(t); // ok a = t; // ok
In both cases, the conversions performed are:
char ->
int
,
B*
-> A*
(derived class pointer to base class pointer),
B ->
C
(a user defined conversion),
and
D ->
C
(a user defined conversion).
Note that assignment is also defined from std::pair
types:
tuple<float, int> a = std::make_pair(1, 'a');
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
: a
i
== b
i
a !=
b
iff exists i
:
a
i !=
b
i
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.
Examples:
tuple<std::string, int, A> t1(std::string("same?"), 2, A()); tuple<std::string, long, A> t2(std::string("same?"), 2, A()); tuple<std::string, long, A> t3(std::string("different"), 3, A()); bool operator==(A, A) { std::cout << "All the same to me..."; return true; } t1 == t2; // true t1 == t3; // false, does not print "All the..."
Tiers are tuples, where all elements are of non-const
reference types. They are constructed with a call to the tie
function template (cf. make_tuple
):
int i; char c; double d; ... tie(i, c, a);
The above tie
function creates
a tuple of type tuple<int&, char&, double&>
. The same result could be achieved
with the call make_tuple(ref(i), ref(c), ref(a))
.
A tuple that contains non-const references as elements can be used to 'unpack' another tuple into variables. E.g.:
int i; char c; double d; tie(i, c, d) = make_tuple(1,'a', 5.5); std::cout << i << " " << c << " " << d;
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');
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):
char c; tie(tuples::ignore, c) = std::make_pair(1, 'a');
The global operator<<
has been overloaded for std::ostream
such that tuples are output by recursively calling operator<<
for each element.
Analogously, the global operator>>
has been overloaded to extract tuples
from std::istream
by recursively calling operator>>
for each element.
The default delimiter between the elements is space, and the tuple is enclosed in parenthesis. For Example:
tuple<float, int, std::string> a(1.0f, 2, std::string("Howdy folks!"); cout << a;
outputs the tuple as: (1.0
2 Howdy
folks!)
The library defines three manipulators for changing the default behavior:
set_open(char)
defines
the character that is output before the first element.
set_close(char)
defines
the character that is output after the last element.
set_delimiter(char)
defines
the delimiter character between elements.
Note, that these manipulators are defined in the tuples subnamespace. For example:
cout << tuples::set_open('[') << tuples::set_close(']') << tuples::set_delimiter(',') << a;
outputs the same tuple a
as:
[1.0,2,Howdy folks!]
The same manipulators work with operator>>
and istream
as well. Suppose the cin
stream
contains the following data:
(1 2 3) [4:5]
The code:
tuple<int, int, int> i; tuple<int, int> j; cin >> i; cin >> tuples::set_open('[') >> tuples::set_close(']') >> tuples::set_delimiter(':'); cin >> j;
reads the data into the tuples i
and j
.
Note that extracting tuples with std::string
or C-style string elements does not generally work, since the streamed tuple
representation may not be unambiguously parseable.
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:
class hand_made_tuple { A a; B b; C c; public: hand_made_tuple(const A& aa, const B& bb, const C& cc) : a(aa), b(bb), c(cc) {}; A& getA() { return a; }; B& getB() { return b; }; C& getC() { return c; }; }; hand_made_tuple hmt(A(), B(), C()); hmt.getA(); hmt.getB(); hmt.getC();
and this code:
tuple<A, B, C> t(A(), B(), C()); t.get<0>(); t.get<1>(); t.get<2>();
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:
void f1(int&, double&); tuple<int, double> f2();
Then, the call #1 may be slightly faster than #2 in the code below:
int i; double d; ... f1(i,d); // #1 tie(i,d) = f2(); // #2
See [1, 2] for more in-depth discussions about efficiency.
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.
The library code is(?) standard C++ and thus the library works with a standard conforming compiler. Below is a list of compilers and known problems with each compiler:
Compiler |
Problems |
---|---|
gcc 2.95 |
- |
edg 2.44 |
- |
Borland 5.5 |
Can't use function pointers or member pointers as tuple elements |
Metrowerks 6.2 |
Can't use |
MS Visual C++ |
No reference elements ( |
Advanced features (describes some metafunctions etc.).
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::pair
s.
[1] Järvi J.: Tuples and multiple return values in C++, TUCS Technical Report No 249, 1999.
[2] Järvi J.: ML-Style Tuple Assignment in Standard C++ - Extending the Multiple Return Value Formalism, TUCS Technical Report No 267, 1999.
[3] Järvi J.: Tuple Types and Multiple Return Values, C/C++ Users Journal, August 2001.
Last revised: December 05, 2018 at 20:01:52 GMT |