feedc0de/boost_tuple
1
0
Fork 0
forked from boostorg/tuple
Code Pull Requests Activity

Adding the tuple library files

Browse Source 
[SVN r10829]
This commit is contained in:
Jaakko Järvi
2001-08-10 11:48:57 +00:00
parent adeeed1f6d
commit c80a1d86d8
8 changed files with 1369 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
doc/design_decisions_rationale.html Normal file
View File

@ -0,0 +1,130 @@
<html>
<title>Design decisions rationale for Boost Tuple Library</title>
<body bgcolor="#FFFFFF" text="#000000">
<IMG SRC="../../../c++boost.gif"
ALT="C++ Boost" width="277" height="86">
<h1>Tuple Library : design decisions rationale</h1>
<h2>About namespaces</h2>
<p>
There was a discussion about whether tuples should be in a separate namespace or directly at the <code>boost</code> namespace.
The common principle is that domain libraries (like <i>graph</i>, <i>python</i>) should be on a separate subnamespace, while utility like libraries directly in the <code>boost</code> namespace.
Tuples are somewhere in between, as the tuple template is clearly a general utility, but the library introduces quite a lot of names in addition to just the tuple template.
As a result of the discussion, tuple definitions are now directly under the <code>boost</code> namespace.
<p>
<h4>For those who are really interested in namespaces</h4>
<p>
Note! The following discussion is not relevant for the Tuple library, as the 'no subnamespace' decision was taken, but it may be useful for other library writers.
</p>
<p>
In the original tuple library submission, all names were under the namespace <code>tuples</code>. This brought up the issue of naming subnamespaces.
The rationale for not using the most natural name 'tuple' was to avoid having an identical name with the tuple template. Namespace names are, however, not generally in plural form in boost libraries. Further, no real trouble was reported for using the same name for a namespace and a class.
But we found some trouble after all.
One solution proposed to the dilemma of introducing a subnamespace or not was as follows: use a subnamespace but lift the most common names to the <code>boost</code> namespace with using declarations.
Both gcc and edg compilers rejected such using declarations if the namespace and class names were identical:
<code><pre>namespace boost {
namespace tuple {
class cons;
class tuple;
<EFBFBD> ...
}
using tuple::cons; // ok
using tuple::tuple; // error
...
}
</pre></code>
Note, however, that a corresponding using declaration in the global namespace seemed to be ok:
<code><pre>
using boost::tuple::tuple; // ok;
</pre></code>
<h2>The endmark of the cons list (nil, null_type, ...)</h2>
<p>
Tuples are internally represented as <code>cons</code> lists:
<code><pre>tuple&lt;int, int&gt;
</pre></code>
inherits from
<code><pre>cons&lt;int, cons&lt;int, null_type&gt; &gt;
</code></pre>
<code>null_type</code> is the end mark of the list. Original proposition was <code>nil</code>, but the name is used in MacOS, and might have caused problems, so <code>null_type</code> was chosen instead.
Other names considered were <i>null_t</i> and <i>unit</i> (the empty tuple type in SML).
</p>
<p>
Note that <code>null_type</code> is the internal representation of an empty tuple: <code>tuple&lt;&gt;</code> inherits from <code>null_type</code>.
</p>
<h2>Element indexing</h2>
<p>
Whether to use 0- or 1-based indexing was discussed more than thoroughly, and the following observations were made:
<ul>
<li> 0-based indexing is 'the C++ way' and used with arrays etc.</li>
<li> 1-based 'name like' indexing exists as well, eg. <code>bind1st</code>, <code>bind2nd</code>, <code>pair::first</code>, etc.</li>
</ul>
Tuple access with the syntax <code>get&lt;N&gt;(a)</code>, or <code>a.get&lt;N&gt;()</code> (where <code>a</code> is a tuple and <code>N</code> an index), was considered to be of the first category, hence, the index of the first element in a tuple is 0.
</p>
<p>
A suggestion to provide 1-based 'name like' indexing with constants like <code>_1st</code>, <code>_2nd</code>, <code>_3rd</code>, ... was made.
By suitably chosen constant types, this would allow alternative syntaces:
<code><pre>a.get&lt;0&gt;() == a.get(_1st) == a[_1st] == a(_1st);
</pre></code>
We chose not to provide more than one indexing method for the following reasons:
<ul>
<li>0-based indexing might not please everyone, but once its fixed, it is less confusing than having two different methods (would anyone want such constants for arrays?).</li>
<li>Adding the other indexing scheme doesn't really provide anything new (like a new feature) to the user of the library.</li>
<li>C++ variable and constant naming rules don't give many possibilities for defining short and nice index constants (like <code>_1st</code>, ...).
Let the binding and lambda libraries use these for a better purpose.</li>
<li>The access syntax <code>a[_1st]</code> (or <code>a(_1st)</code>) is appealing, and almost made us add the index constants after all. However, 0-based subscripting is so deep in C++, that we had a fear for confusion.</li>
<li>
Such constants are easy to add.
</li>
</ul>
<h2>Tuple comparison</h2>
The comparison operator implements lexicographical order.
Other orderings were considered, mainly dominance (<i>a &lt; b iff for each i a(i) < b(i)</i>).
Our belief is, that lexicographical ordering, though not mathematically the most natural one, is the most frequently needed ordering in everyday programming.
<h2>Streaming</h2>
<p>
The characters specified with tuple stream manipulators are stored within the space allocated by <code>ios_base::xalloc</code>, which allocates storage for <code>long</code> type objects.
<code>static_cast</code> is used in casting between <code>long</code> and the stream's character type.
Streams that have character types not convertible back and forth to long thus fail to compile.
This may be revisited at some point. The two possible solutions are:
<ul>
<li>Allow only plain <code>char</code> types as the tuple delimiters and use <code>widen</code> and <code>narrow</code> to convert between the real character type of the stream.
This would always compile, but some calls to set manipulators might result in a differnt character than expected (some default charcter).</li>
<li>Allocate enought space to hold the real character type of the stream.
This means memory for holding the delimiter characters must be allocated separately, and that pointers to this memory are stored in the space allocated with <code>ios_base::xalloc</code>.
Any volunteers?</li>
</ul>
</p>
<A href="tuple_users_guide.html">Back to the user's guide</A>
<hr><p>&copy; Copyright Jaakko J&auml;rvi 2001.
</body>
</html>

114
doc/tuple_advanced_interface.html Normal file
View File

@ -0,0 +1,114 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Tuple library advanced features</title>
<body bgcolor="#FFFFFF" text="#000000">
<IMG SRC="../../../c++boost.gif"
ALT="C++ Boost" width="277" height="86">
</head>
<body>
<h1>Tuple library advanced features</h1>
<h2>Metafunctions for tuple types</h2>
<p>
Suppose <code>T</code> is a tuple type, and <code>N</code> is a constant integral expression.
<code><pre>tuple_element&lt;N, T&gt;::type</pre></code>
gives the type of the <code>N</code>th element in the tuple type <code>T</code>.
</p>
<code><pre>tuple_length&lt;T&gt;::value</pre></code>
gives the length of the tuple type <code>T</code>.
</p>
<h2>Cons lists</h2>
<p>
Tuples are internally represented as <i>cons lists</i>.
For example, the tuple
<code><pre>tuple&lt;A, B, C, D&gt;</pre></code>
inherits from the type
<code><pre>cons&lt;A, cons&lt;B, cons&lt;C, cons&lt;D, null_type&gt; &gt; &gt; &gt;
</pre></code>
The tuple template provides the typedef <code>inherited</code> to access the cons list representation. E.g.:
<code>tuple&lt;A&gt;::inherited</code> is the type <code>cons&lt;A, null_type&gt;</code>.
</p>
<h4>Empty tuple</h4>
<p>
The internal representation of the empty tuple <code>tuple&lt;&gt</code> is <code>null_type</code>.
</p>
<h4>Head and tail</h4>
<p>
Both tuple template and the cons templates provide the typedefs <code>head_type</code> and <code>tail_type</code>.
The <code>head_type</code> typedef gives the type of the first element of the tuple (or the cons list).
The
<code>tail_type</code> typedef gives the remaining cons list after removing the first element.
The head element is stored in the member variable <code>head</code> and the tail list in the member variable <code>tail</code>.
Cons lists provide the member function <code>get_head()</code> for getting a reference to the head of a cons list, and <code>get_tail()</code> for getting a reference to the tail.
There are const and non-const versions of both functions.
</p>
<p>
Note that in a one element tuple, <code>tail_type</code> equals <code>null_type</code> and the <code>get_tail()</code> function returns an object of type <code>null_type</code>.
</p>
<p>
The empty tuple (<code>null_type</code>) has no head or tail, hence the <code>get_head</code> and <code>get_tail</code> functions are not provided.
</p>
<p>
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):
<pre><code>inline void set_to_zero(const null_type&amp;) {};
template &lt;class H, class T&gt;
inline void set_to_zero(cons&lt;H, T&gt;&amp; x) { x.get_head() = 0; set_to_zero(x.get_tail()); }
</code></pre>
<p>
<h2>Traits classes for tuple element types</h2>
<h4><code>tuple_access_traits</code></h4>
<p>
The template <code>tuple_access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:
<ol>
<li><code>tuple_access_traits&lt;T&gt;::type</code> maps <code>T</code> to the return type of the non-const access functions (nonmeber and member <code>get</code> functions, and the <code>get_head</code> function).</li>
<li><code>tuple_access_traits&lt;T&gt;::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
<li><code>tuple_access_traits&lt;T&gt;::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
</ol>
<h4><code>make_tuple_traits</code></h4>
The element types of the tuples that are created with the <code>make_tuple</code> functions are computed with the type function <code>make_tuple_traits</code>.
The type function call <code>make_tuple_traits&lt;T&gt;::type</code> implements the following type mapping:
<ul>
<li><i>any reference type</i> -&gt; <i>compile time error</i>
</li>
<li><i>any array type</i> -&gt; <i>constant reference to the array type</i>
</li>
<li><code>reference_wrapper&lt;T&gt;</code> -&gt; <code>T&amp;</code>
</li>
<li><code>T</code> -&gt; <code>T</code>
</li>
</ul>
Objects of type <code>reference_wrapper</code> are created with the <code>ref</code> and <code>cref</code> functions (see <A href="tuple_users_guide.html#make_tuple">The <code>make_tuple</code> function</A>.)
</p>
<p>Note, that the <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate hpp-file <code>reference_wrappers.hpp</code>, which can be included without including the rest of the tuple library.
</p>
<A href="tuple_users_guide.html">Back to the user's guide</A>
<hr>
<p>&copy; Copyright Jaakko J&auml;rvi 2001.</p>
</body>
</html>

532
doc/tuple_users_guide.html Normal file
View File

@ -0,0 +1,532 @@
<html>
<head>
<title>The Boost Tuple Library</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<IMG SRC="../../../c++boost.gif"
ALT="C++ Boost" width="277" height="86">
<h1>The Boost Tuple Library</h1>
<p>
A tuple (or <i>n</i>-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.
</p>
<p>Tuples are convenient in many circumstances.
For instance, tuples make it easy to define functions that return more than one value.
</p>
<p>
Some programming languages, such as ML, Python and Haskell, have built-in tuple constructs.
Unfortunately C++ does not.
To compensate for this &quot;deficiency&quot;, the Boost Tuple Library implements a tuple construct using templates.
</p>
<h2>Table of Contents</h2>
<ol>
<li><a href = "#using_library">Using the library</a></li>
<li><a href = "#tuple_types">Tuple types</a></li>
<li><a href = "#constructing_tuples">Constructing tuples</a></li>
<li><a href = "#accessing_elements">Accessing tuple elements</a></li>
<li><a href = "#construction_and_assignment">Copy construction and tuple assignment</a></li>
<li><a href = "#relational_operators">Relational operators</a></li>
<li><a href = "#tiers">Tiers</a></li>
<li><a href = "#streaming">Streaming</a></li>
<li><a href = "#performance">Performance</a></li>
<li><a href = "#portability">Portability</a></li>
<li><a href = "#thanks">Acknowledgements</a></li>
<li><a href = "#references">References</a></li>
</ol>
<h4>More details</h4>
<p>
<a href = "tuple_advanced_interface.html">Advanced features</a> (describes some metafunctions etc.).</p>
<p>
<a href = "design_decisions_rationale.html">Rationale behind some design/implementation decisions.</a></p>
<h2><a name="using_library">Using the library</a></h2>
<p>To use the library, just include:
<pre><code>#include "boost/tuple/tuple.hpp"</code></pre>
</p>
<p>Comparison operators can be included with:
<pre><code>#include "boost/tuple/tuple_comparison.hpp"</code></pre>
</p>
<p>To use tuple input and output operators,
<pre><code>#include "boost/tuple/tuple_io.hpp"</code></pre>
and add the <code>libs/tuple/src/tuple.hpp</code> file to your project.
</p>
Both <code>tuple_io.hpp</code> and <code>tuple_comparison.hpp</code> include <code>tuple.hpp</code>.
<p>All definitions are in namespace <code>boost</code>.
<h2><a name = "tuple_types">Tuple types</a></h2>
<p>A tuple type is an instantiation of the <code>tuple</code> 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, except for a type that cannot be copied, e.g.:
<ul>
<li>classes that do not have a public copy constructor</li>
<li>arrays</li>
</ul>
However, a reference to a non-copyable type is a valid element type.
<p>
For example, the following definitions are valid tuple instantiations (<code>A</code>, <code>B</code> and <code>C</code> are some user defined classes):
<pre><code>tuple&lt;int&gt;
tuple&lt;double&amp;, const double&amp;, const double, double*, const double*&gt;
tuple&lt;A, int(*)(char, int), B(A::*)(C&), C&gt;
tuple&lt;std::string, std::pair&lt;A, B&gt; &gt;
tuple&lt;A*, tuple&lt;const A*, const B&amp;, C&gt;, bool, void*&gt;
</code></pre>
</p>
<p>
The following code shows some invalid tuple instantiations:
<pre><code>class Y {
Y(const Y&amp;);
public:
Y();
};
tuple&lt;Y&gt; // not allowed, objects of type Y cannot be copied
tuple&lt;char[10]&gt; // not allowed: arrays cannot be copied
</code></pre>
Note however that <code>tuple&lt;Y&amp;&gt;</code> and <code>tuple&lt;char(&)[10]&gt;</code> are valid instantiations.
</p>
<h2><a name = "constructing_tuples">Constructing tuples</a></h2>
<p>
The tuple constructor takes the tuple elements as arguments.
For an <i>n</i>-element tuple, the constructor can be invoked with <i>k</i> arguments, where 0 &lt; <i>k</i> &lt;= <i>n</i>.
For example:
<pre><code>tuple&lt;int, double&gt;()
tuple&lt;int, double&gt;(1)
tuple&lt;int, double&gt;(1, 3.14)
</code></pre>
</p>
<p>
If no initial value for an element is provided, it is default initialized (and hence must be default initializable).
For example.
<pre><code>class X {
X();
public:
X(std::string);
};
tuple&lt;X,X,X&gt;() // error: no default constructor for X
tuple&lt;X,X,X&gt;(string("Jaba"), string("Daba"), string("Duu")) // ok
</code></pre>
In particular, reference types do not have a default initialisation:
<pre><code>tuple&lt;double&amp;&gt;() // error: reference must be
// initialised explicitly
double d = 5;
tuple&lt;double&amp;&gt;(d) // ok
tuple&lt;double&amp;&gt;(d+3.14) // error: cannot initialise
// non-const reference with a temporary
tuple&lt;const double&amp;&gt;(d+3.14) // ok, but dangerous:
// the element becomes a dangling reference
</code></pre>
</p>
<p>In sum, the tuple construction is semantically just a group of individual elementary constructions.
</p>
<h4><a name="make_tuple">The <code>make_tuple</code> function</a></h4>
<p>
Tuples can also be constructed using the <code>make_tuple</code> (cf. <code>std::make_pair</code>) helper functions.
This makes the construction more convenient, saving the programmer from explicitly specifying the element types:
<pre><code>tuple&lt;int, int, double&gt; add_multiply_divide(int a, int b) {
return make_tuple(a+b, a*b, double(a)/double(b));
}
</code></pre>
</p>
<p>
By default, the element types are deduced to the plain nonreference types. E.g:
<pre><code>void foo(const A&amp; a, B&amp; b) {
...
make_tuple(a, b);
</code></pre>
The <code>make_tuple</code> invocation results in a tuple of type <code>tuple&lt;A, B&gt;</code>.
</p>
<p>
Sometimes the plain nonreference 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 nonconst type should be used as the element type instead.
This is accomplished with two helper template functions: <code>ref</code> and <code>cref</code>.
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 <code>ref</code> results in a tuple element with const reference type (see the fifth code line below).
For example:
<pre><code>A a; B b; const A ca = a;
make_tuple(cref(a), b); // creates tuple&lt;const A&amp;, B&gt;
make_tuple(ref(a), b); // creates tuple&lt;A&amp;, B&gt;
make_tuple(ref(a), cref(b)); // creates tuple&lt;A&amp;, const B&amp;&gt;
make_tuple(cref(ca)); // creates tuple&lt;const A&amp;&gt;
make_tuple(ref(ca)); // creates tuple&lt;const A&amp;&gt;
</code></pre>
</p>
<p>
Array arguments to <code>make_tuple</code> functions are deduced to reference to const types by default; there is no need to wrap them with <code>cref</code>. For example:
<pre><code>make_tuple("Donald", "Daisy");
</code></pre>
This creates an object of type <code>tuple&lt;const char (&amp;)[5], const char (&amp;)[6]&gt;</code>
(note that the type of a string literal is an array of const characters, not <code>const char*</code>).
However, to get <code>make_tuple</code> to create a tuple with an element of a nonconst array type one must use the <code>ref</code> wrapper.
</p>
<p>
Function pointers are deduced to the plain nonreference 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 <code>make_tuple</code> (a const qualified function type would result, which is illegal):
<pre><code>void f(int i);
...
make_tuple(&f); // tuple&lt;void (*)(int)&gt;
...
tuple&lt;tuple&lt;void (&amp;)(int)&gt; &gt; a(f) // ok
make_tuple(f); // not ok
</code></pre>
</p>
<h2><a name = "accessing_elements">Accessing tuple elements</a></h2>
<p>
Tuple elements are accessed with the expression:
<pre><code>t.get&lt;N&gt;()
</code></pre>
or
<pre><code>get&lt;N&gt;(t)
</code></pre>
where <code>t</code> is a tuple object and <code>N</code> is a constant integral expression specifying the index of the element to be accessed.
Depending on whether <code>t</code> is const or not, <code>get</code> returns the <code>N</code>th element as a reference to const or nonconst type.
The index of the first element is 0 and thus<code>
N</code> must be between 0 and <code>k-1</code>, where <code>k</code> is the number of elements in the tuple.
Violations of these constrains are detected at compile time. Examples:
<pre><code>double d = 2.7; A a;
tuple&lt;int, double&amp;, const A&amp;&gt; t(1, d, a);
const tuple&lt;int, double&amp;, const A&amp;&gt; ct = t;
...
int i = get&lt;0&gt;(t); i = t.get&lt;0&gt;(); // ok
int j = get&lt;0&gt;(ct); // ok
get&lt;0&gt;(t) = 5; // ok
get&lt;0&gt;(ct) = 5; // error, can't assign to const
...
double e = get&lt;1&gt;(t); // ok
get&lt;1&gt;(t) = 3.14; // ok
get&lt;2&gt;(t) = A(); // error, can't assign to const
A aa = get&lt;3&gt;(t); // error: index out of bounds
...
++get&lt;0&gt;(t); // ok, can be used as any variable
</code></pre>
</p>
<h2><a name = "construction_and_assignment">Copy construction and tuple assignment</a></h2>
<p>
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:
<pre><code>class A;
class B : public A {};
struct C { C(); C(const B&amp;); }
struct D { operator C() const; }
tuple&lt;char, B*, B, D&gt; t;
...
tuple&lt;int, A*, C, C&gt; a(t); // ok
a = t; // ok
</code></pre>
In both cases, the conversions performed are: <code>char -> int</code>, <code>B* -> A*</code> (derived class pointer to base class pointer), <code>B -> C</code> (a user defined conversion) and <code>D -> C</code> (a user defined conversion).
</p>
<p>
Note that assignment is also defined from <code>std::pair</code> types:
<pre><code>tuple&lt;float, int&gt; a = std::make_pair(1, 'a');
</code></pre>
</p>
<h2><a name = "relational_operators">Relational operators</a></h2>
<p>
Tuples reduce the operators <code>==, !=, &lt;, >, &lt;=</code> and <code>>=</code> 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 <code>a</code> and <code>b</code> are defined as:
<ul>
<li><code>a == b</code> iff for each <code>i</code>: <code>a<sub>i</sub> == b<sub>i</sub></code></li>
<li><code>a != b</code> iff exists <code>i</code>: <code>a<sub>i</sub> != b<sub>i</sub></code></li>
</ul>
The operators <code>&lt;, >, &lt;=</code> and <code>>=</code> implement a lexicographical ordering.
<p>
Note that an attempt to compare two tuples of different lengths results in a compile time error.</p>
Also, the comparison operators are <i>"short-circuited"</i>: elementary comparisons start from the first elements and are performed only until the result is clear.</p>
<p>Examples:
<pre><code>tuple&lt;std::string, int, A&gt; t1(std::string("same?"), 2, A());
tuple&lt;std::string, long, A&gt; t2(std::string("same?"), 2, A());
tuple&lt;std::string, long, A&gt; 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..."
</code></pre>
</p>
<h2><a name = "tiers">Tiers</a></h2>
<p>
<i>Tiers</i> are tuples, where all elements are of nonconst reference types.
They are constructed with a call to the <code>tie</code> function template (cf. <code>make_tuple</code>):
<pre><code>int i; char c; double d;
...
tie(i, c, a);
</code></pre>
</p>
<p>
The above <code>tie</code> function creates a tuple of type <code>tuple&lt;int&amp;, char&amp;, double&amp;&gt;</code>.
The same result could be achieved with the call <code>make_tuple(ref(i), ref(c), ref(a))</code>.
</p>
<p>
A tuple that contains nonconst references as elements can be used to 'unpack' another tuple into variables. E.g.:
<pre><code>int i; char c; double d;
tie(i, c, d) = make_tuple(1,'a', 5.5);
std::cout &lt;&lt; i &lt;&lt; " " &lt;&lt; c &lt;&lt; " " &lt;&lt; d;
</code></pre>
This code prints <code>1 a 5.5</code> 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.
</p>
<p>
The tying mechanism works with <code>std::pair</code> templates as well:
<pre><code>int i; char c;
tie(i, c) = std::make_pair(1, 'a');
</code></pre>
</p>
<h4>Ignore</h4>
There is also an object called <code>ignore</code> 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:
<pre><code>char c;
tie(ignore, c) = std::make_pair(1, 'a');
</code></pre>
<h2><a name = "streaming">Streaming</a></h2>
<p>
The global <code>operator&lt;&lt;</code> has been overloaded for <code>std::ostream</code> such that tuples are
output by recursively calling <code>operator&lt;&lt;</code> for each element.
</p>
<p>
Analogously, the global <code>operator&gt;&gt;</code> has been overloaded to extract tuples from <code>std::istream</code> by recursively calling <code>operator&gt;&gt;</code> for each element.
</p>
<p>
The default delimiter between the elements is space, and the tuple is enclosed
in parenthesis.
For Example:
<pre><code>tuple&lt;float, int, std::string&gt; a(1.0f, 2, std::string("Howdy folks!");
cout << a;
</code></pre>
outputs the tuple as: <code>(1.0 2 Howdy folks!)</code>
</p>
<p>
The library defines three <i>manipulators</i> for changing the default
behaviour:
<ul>
<li><code>set_open(char)</code> defines the character that is output before the first
element.</li>
<li><code>set_close(char)</code> defines the character that is output after the
last element.</li>
<li><code>set_delimiter(char)</code> defines the delimiter charcter between
elements.</li>
</ul>
For example:
<code><pre>cout << set_open('[') << set_close(']') << set_delimiter(',') << a;
</code></pre>
outputs the same tuple <code>a</code> as: <code>[1.0,2,Howdy folks!]</code>
</p>
<p>The same manipulators work with <code>operator&gt;&gt;</code> and <code>istream</code> as well. Suppose the <code>cin</code> stream contains the following data:
<pre><code>(1 2 3) [4:5]</code></pre>
The code:
<code><pre>tuple&lt;int, int, int&gt; i;
tuple&lt;int, int&gt; j;
cin >> i;
cin >> set_open('[') >> set_close(']') >> set_delimiter(':');
cin >> j;
</code></pre>
reads the data into the tuples <code>i</code> and <code>j</code>.
</p>
<p>
Note that extracting tuples with <code>std::string</code> or C-style string
elements does not generally work, since the streamed tuple representation may not be unambiguously parseable.
</p>
<h2><a name = "performance">Performance</a></h2>
Tuples are efficient. All functions are small inlined one-liners and a decent compiler will eliminate any extra cost.
Particularly, there is no performance difference between this code:
<pre><code>class hand_made_tuple {
A a; B b; C c;
public:
hand_made_tuple(const A&amp; aa, const B&amp; bb, const C&amp; cc)
: a(aa), b(bb), c(cc) {};
A&amp; getA() { return a; };
B&amp; getB() { return b; };
C&amp; getC() { return c; };
};
hand_made_tuple hmt(A(), B(), C());
hmt.getA(); hmt.getB(); hmt.getC();
</code></pre>
and this code:
<pre><code>tuple&lt;A, B, C&gt; t(A(), B(), C());
t.get&lt;0&gt;(); t.get&lt;1&gt;(); t.get&lt;2&gt;();
</code></pre>
</p>
<p>
Depending on the optimizing ablity of the compiler, the tier mechanism may have a small performance penalty compared to using nonconst reference parameters as a mechanism for returning multiple values from a function.
For example, suppose that the following functions <code>f1</code> and <code>f2</code> have equivalent functionalities:
<pre><code>void f1(int&amp;, double&);
tuple&lt;int, double&gt; f2();
</code></pre>
Then, the call #1 may be slightly faster than #2 in the code below:
<pre><code>int i; double d;
...
f1(i,d); // #1
tie(i,d) = f2(); // #2
</code></pre>
See
[<a href=#publ_1>1</a>,
<a href=#publ_2>2</a>]
for more in-depth discussions about efficiency.
<h4>Effect on Compile Time</h4>
<p>
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 <code>hand_made_tuple</code> 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 to 10 percentages were measured for programs which used tuples very frequently.
With the same test programs, memory consumption of compiling increased between 22% to 27%. See
[<a href=#publ_1>1</a>,
<a href=#publ_2>2</a>]
for details.
</p>
<h2><a name = "portability">Portability</a></h2>
<p>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:
</p>
<table>
<tr><td><u>Compiler</u></td><td><u>Problems</u></td></tr>
<tr><td>gcc 2.95</td><td>-</td></tr>
<tr><td>edg 2.44</td><td>-</td></tr>
<tr><td>Borland 5.5</td><td>Can't use function pointers or member pointers as tuple elements</td></tr>
<tr><td>Metrowerks 6.2</td><td>Can't use <code>ref</code> and <code>cref</code> wrappers</td></tr>
<tr><td>MS Visual C++</td><td>No reference elements (<code>tie</code> still works). Can't use <code>ref</code> and <code>cref</code> wrappers</td></tr>
</table>
<h2><a name = "thanks">Acknowledgements</a></h2>
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. Thanks to Jeremy Siek, William Kempf, Jens Maurer for their help and suggestions.
The comments by Vesa Karvonen, John Max Skaller, Ed Brey, Beman Davis and David Abrahams helped to improve the libray.
The idea for the tie mechanism came from an old usenet article by Ian McCulloch, where he proposed something similar for std::pairs.
<h2><a name = "references">References</a></h2>
<p>
<a name="publ_1"></a>[1]
J&auml;rvi J.: <i>Tuples and multiple return values in C++</i>, TUCS Technical Report No 249, 1999 (<a href="http://www.tucs.fi/publications">http://www.tucs.fi/publications</a>).
</p>
<p>
<a name="publ_2"></a>[2]
J&auml;rvi J.: <i>ML-Style Tuple Assignment in Standard C++ - Extending the Multiple Return Value Formalism</i>, TUCS Technical Report No 267, 1999 (<a href="http://www.tucs.fi/publications">http://www.tucs.fi/publications</a>).
</p>
<p>
[3] J&auml;rvi J.:<i>Tuple Types and Multiple Return Values</i>, C/C++ Users Journal, August 2001.
</p>
<hr>
<p>Last modified 2001-08-10</p>
<p>&copy; Copyright Jaakko J&auml;rvi 2001.
Permission to copy, use, modify, sell and distribute this software and its documentation is granted provided this copyright notice appears in all copies.
This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.
</p>
</body>
</html>

33
src/tuple.cpp Normal file
View File

@ -0,0 +1,33 @@
// tuple.cpp -----------------------------------------------------
// Copyright (C) 1999, 2000, 2001 Jaakko J<>rvi (jaakko.jarvi@cs.utu.fi)
// Copyright (C) 2001 Gary Powell (gary.powell@sierra.com)
//
// Permission to copy, use, sell and distribute this software is granted
// provided this copyright notice appears in all copies.
// Permission to modify the code and to distribute modified code is granted
// provided this copyright notice appears in all copies, and a notice
// that the code was modified is included with the copyright notice.
//
// This software is provided "as is" without express or implied warranty,
// and with no claim as to its suitability for any purpose.
// For more information, see http://lambda.cs.utu.fi
// Revision History
// 16 02 01 Initial Version (GWP)
// -----------------------------------------------------------------
#include "boost/tuple/tuple_io.hpp"
namespace boost {
namespace detail {
namespace tuples {
const int
format_info::stream_index[number_of_manipulators]
= { std::ios::xalloc(), std::ios::xalloc(), std::ios::xalloc() };
} // namespace tuples
} // namespace detail
} // namespace boost

14
test/README Normal file
View File

@ -0,0 +1,14 @@
To compile the
libs/tuple/test/*.cpp
files, you need to set include paths
for boost.
For example, in libs/tuple/test directory you would type (using g++):
g++ -I../../.. tuple_test_bench.cpp
If you want to use tuple_io, you need to compile and link src/tuple.cpp:
g++ -I../../.. ../src/tuple.cpp io_test.cpp

163
test/another_tuple_test_bench.cpp Normal file
View File

@ -0,0 +1,163 @@
// tuple_test_bench.cpp --------------------------------
//
// Defining any of E1 to E5 or E7 to E11 opens some illegal code that
// should cause the compliation to fail.
#define BOOST_INCLUDE_MAIN // for testing, include rather than link
#include <boost/test/test_tools.hpp> // see "Header Implementation Option"
#include "boost/tuple/tuple.hpp"
#include "boost/tuple/tuple_comparison.hpp"
using namespace std;
using namespace boost;
class foo
{
public:
explicit foo(int v) : val(v) {}
bool operator==(const foo& other) const
{
return val == other.val;
}
private:
foo() {}
int val;
};
void
construction_test()
{
tuple<int> t1;
BOOST_TEST(get<0>(t1) == int());
tuple<float> t2(5.5f);
BOOST_TEST(get<0>(t2) == 5.5f);
tuple<foo> t3(foo(12));
BOOST_TEST(get<0>(t3) == foo(12));
tuple<double> t4(t2);
BOOST_TEST(get<0>(t4) == 5.5);
tuple<int, float> t5;
BOOST_TEST(get<0>(t5) == int());
BOOST_TEST(get<1>(t5) == float());
tuple<int, float> t6(12, 5.5f);
BOOST_TEST(get<0>(t6) == 12);
BOOST_TEST(get<1>(t6) == 5.5f);
tuple<long, double> t7(t6);
BOOST_TEST(get<0>(t7) == 12);
BOOST_TEST(get<1>(t7) == 5.5f);
}
void
copy_test()
{
tuple<int, float> t1(4, 12.5f);
tuple<int, float> t2(5, 2.2f);
t2 = t1;
BOOST_TEST(get<0>(t1) == get<0>(t2));
BOOST_TEST(get<1>(t1) == get<1>(t2));
tuple<long, double> t3(2, 3.3);
t3 = t1;
BOOST_TEST((double)get<0>(t1) == get<0>(t3));
BOOST_TEST((double)get<1>(t1) == get<1>(t3));
}
void
mutate_test()
{
tuple<int, float, bool, foo> t1(5, 12.2f, true, foo(4));
get<0>(t1) = 6;
get<1>(t1) = 2.2f;
get<2>(t1) = false;
get<3>(t1) = foo(5);
BOOST_TEST(get<0>(t1) == 6);
BOOST_TEST(get<1>(t1) == 2.2f);
BOOST_TEST(get<2>(t1) == false);
BOOST_TEST(get<3>(t1) == foo(5));
}
void
make_tuple_test()
{
tuple<int, float> t1 = make_tuple(5, 2.25f);
BOOST_TEST(get<0>(t1) == 5);
BOOST_TEST(get<1>(t1) == 2.25f);
tuple<int, double> t2;
t2 = make_tuple((short int)2, 2.25);
BOOST_TEST(get<0>(t2) == 2);
BOOST_TEST(get<1>(t2) == 2.25);
}
void
tie_test()
{
int a;
float b;
foo c(5);
tie(a, b, c) = make_tuple(2, 5.5f, foo(3));
BOOST_TEST(a == 2);
BOOST_TEST(b == 5.5f);
BOOST_TEST(c == foo(3));
tie(a, ignore, c) = make_tuple((short int)5, false, foo(5));
BOOST_TEST(a == 5);
BOOST_TEST(b == 5.5f);
BOOST_TEST(c == foo(5));
}
void
equality_test()
{
tuple<int, float> t1(5, 3.3f);
tuple<int, float> t2(5, 3.3f);
BOOST_TEST(t1 == t2);
tuple<int, float> t3(5, 2.2f);
tuple<int, float> t4(2, 3.3f);
BOOST_TEST(t1 != t3);
BOOST_TEST(t1 != t4);
}
void
ordering_test()
{
tuple<int, float> t1(4, 3.3f);
tuple<short, float> t2(5, 3.3f);
tuple<long, double> t3(5, 4.4);
BOOST_TEST(t1 < t2);
BOOST_TEST(t1 <= t2);
BOOST_TEST(t2 > t1);
BOOST_TEST(t2 >= t1);
BOOST_TEST(t2 < t3);
BOOST_TEST(t2 <= t3);
BOOST_TEST(t3 > t2);
BOOST_TEST(t3 >= t2);
}
int
test_main(int, char *[])
{
construction_test();
copy_test();
mutate_test();
make_tuple_test();
tie_test();
equality_test();
ordering_test();
return 0;
}

104
test/io_test.cpp Normal file
View File

@ -0,0 +1,104 @@
// -- io_test.cpp -----------------------------------------------
//
// Testing the I/O facilities of tuples
#define BOOST_INCLUDE_MAIN // for testing, include rather than link
#include "boost/test/test_tools.hpp" // see "Header Implementation Option"
#include "boost/tuple/tuple_io.hpp"
#include "boost/tuple/tuple_comparison.hpp"
#include <fstream>
#include <iterator>
#include <algorithm>
#include <string>
#if defined BOOST_NO_STRINGSTREAM
#include <strstream>
#else
#include <sstream>
#endif
#include "boost/config.hpp"
using namespace std;
using namespace boost;
#if defined BOOST_NO_STRINGSTREAM
typedef ostrstream useThisOStringStream;
typedef istrstream useThisIStringStream;
#else
typedef ostringstream useThisOStringStream;
typedef istringstream useThisIStringStream;
#endif
int test_main(int argc, char * argv[] ) {
useThisOStringStream os1;
// Set format [a, b, c] for os1
os1 << set_open('[');
os1 << set_close(']');
os1 << set_delimiter(',');
os1 << make_tuple(1, 2, 3);
BOOST_TEST (os1.str() == std::string("[1,2,3]") );
{
useThisOStringStream os2;
// Set format (a:b:c) for os2;
os2 << set_open('(');
os2 << set_close(')');
os2 << set_delimiter(':');
#if !defined (BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
os2 << make_tuple("TUPU", "HUPU", "LUPU", 4.5);
BOOST_TEST (os2.str() == std::string("(TUPU:HUPU:LUPU:4.5)") );
#endif
}
// The format is still [a, b, c] for os1
os1 << make_tuple(1, 2, 3);
BOOST_TEST (os1.str() == std::string("[1,2,3][1,2,3]") );
ofstream tmp("temp.tmp");
#if !defined (BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
tmp << make_tuple("One", "Two", 3);
#endif
tmp << set_delimiter(':');
tmp << make_tuple(1000, 2000, 3000) << endl;
tmp.close();
// When teading tuples from a stream, manipulators must be set correctly:
ifstream tmp3("temp.tmp");
tuple<string, string, int> j;
#if !defined (BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
tmp3 >> j;
BOOST_TEST (tmp3.good() );
#endif
tmp3 >> set_delimiter(':');
tuple<int, int, int> i;
tmp3 >> i;
BOOST_TEST (tmp3.good() );
tmp3.close();
// reading tuple<int, int, int> in format (a b c);
useThisIStringStream is("(100 200 300)");
tuple<int, int, int> ti;
BOOST_TEST(is >> ti);
BOOST_TEST(ti == make_tuple(100, 200, 300));
// Note that strings are problematic:
// writing a tuple on a stream and reading it back doesn't work in
// general. If this is wanted, some kind of a parseable string class
// should be used.
return 0;
}

279
test/tuple_test_bench.cpp Normal file
View File

@ -0,0 +1,279 @@
// tuple_test_bench.cpp --------------------------------
// Defining any of E1 to E5 or E7 to E11 opens some illegal code that
// should cause the compliation to fail.
#define BOOST_INCLUDE_MAIN // for testing, include rather than link
#include <boost/test/test_tools.hpp> // see "Header Implementation Option"
#include "boost/tuple/tuple.hpp"
#include "boost/tuple/tuple_comparison.hpp"
#include <string>
#include <utility>
#include <vector>
#include <algorithm>
#include <functional>
#include <iostream>
using namespace std;
using namespace boost;
template<class T> void dummy(const T& t) {}
class A {}; class B {}; class C {};
typedef int(t)(float);
// some arbitrary tuple definitions
typedef tuple<int> t1;
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
typedef tuple<double&, const double&, const double, double*, const double*> t2;
typedef tuple<A, int(*)(char, int), C> t3;
typedef tuple<std::string, std::pair<A, B> > t4;
typedef tuple<A*, tuple<const A*, const B&, C>, bool, void*> t5;
typedef tuple<volatile int, const volatile char&, int(&)(float) > t6;
# if !defined(__BORLANDC__) || __BORLAND__ > 0x0551
typedef tuple<B(A::*)(C&), A&> t7;
#endif
#endif
// A non-copyable class
class no_copy {
no_copy(const no_copy&) {}
public:
no_copy() {};
};
no_copy y;
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
tuple<no_copy&> x = tuple<no_copy&>(y); // ok
#endif
#ifdef E1
tuple<no_copy> v1; // should faild
#endif
char cs[10];
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
tuple<char(&)[10]> v2(cs); // ok
#endif
#ifdef E2
tuple<char[10]> v3; // should fail, arrays must be stored as references
#endif
// -tuple construction tests ------------------------------------
// a class without a public default constructor
class no_def_constructor {
no_def_constructor() {}
public:
no_def_constructor(std::string) {} // can be constructed with a string
};
void foo1() {
#ifdef E3
dummy(tuple<no_def_constructor, no_def_constructor, no_def_constructor>());
// should fail
#endif
dummy( tuple<no_def_constructor, no_def_constructor, no_def_constructor>(
std::string("Jaba"), // ok, since the default
std::string("Daba"), // constructor is not used
std::string("Doo")));
}
void foo2() {
// testing default values
dummy(tuple<int, double>());
dummy(tuple<int, double>(1));
dummy(tuple<int, double>(1,3.14));
#ifdef E4
dummy(tuple<double&>()); // should fail, not defaults for references
dummy(tuple<const double&>()); // likewise
#endif
double dd = 5;
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
dummy(tuple<double&>(dd)); // ok
#endif
#ifdef E5
dummy(tuple<double&>(dd+3.14)); // should fail, temporary to non-const reference
#endif
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
dummy(tuple<const double&>(dd+3.14)); // ok, but potentially dangerous
#endif
}
// make_tuple ------------------------------------------
void foo3() {
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
A a; B b;
const A ca = a;
make_tuple(cref(a), b);
make_tuple(ref(a), b);
make_tuple(ref(a), cref(b));
make_tuple(ref(ca));
#endif
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
make_tuple("Donald", "Daisy"); // should work;
#endif
#ifdef E7
std::make_pair("Doesn't","Work"); // fails
#endif
// You can store a reference to a function in a tuple
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
tuple<void(&)()> adf(foo3);
dummy(adf); // avoid warning for unused variable
#endif
// But make_tuple doesn't work
// with function references, since it creates a const qualified function type
// make_tuple(foo3);
// With function pointers, make_tuple works just fine
#if !defined(__BORLANDC__) || __BORLAND__ > 0x0551
make_tuple(&foo3);
#endif
// NOTE:
//
// wrapping it the function reference with ref helps on gcc 2.95.2.
// on edg 2.43. it results in a catastrophic error?
// make_tuple(ref(foo3));
// It seems that edg can't use implicitly the ref's conversion operator, e.g.:
// typedef void (&foo3type) (void);
// foo3type foo3ref = static_cast<foo3type>(ref(foo3)); // works fine
// foo3type foo3ref = ref(foo3); // error
// This is probably not a very common situation, so currently
// I don't know how which compiler is right (JJ)
}
// - testing element access
void foo4()
{
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
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);
int j = get<0>(ct);
BOOST_TEST(i == 1 && j == 1);
get<0>(t) = 5;
BOOST_TEST(t.head == 5);
#ifdef E8
get<0>(ct) = 5; // can't assign to const
#endif
double e = get<1>(t);
BOOST_TEST(e > 2.69 && e < 2.71);
get<1>(t) = 3.14+i;
BOOST_TEST(get<1>(t) > 4.13 && get<1>(t) < 4.15);
#ifdef E9
get<4>(t) = A(); // can't assign to const
#endif
#ifdef E10
dummy(get<5>(ct)); // illegal index
#endif
++get<0>(t);
BOOST_TEST(get<0>(t) == 6);
dummy(i); dummy(j); dummy(e); // avoid warns for unused variables
#endif
}
// testing copy and assignment with implicit conversions between elements
// testing tie
class AA {};
class BB : public AA {};
struct CC { CC() {} CC(const BB& b) {} };
struct DD { operator CC() const { return CC(); }; };
void foo5() {
tuple<char, BB*, BB, DD> t;
tuple<int, AA*, CC, CC> a(t);
a = t;
}
void foo6() {
int i; char c; double d;
tie(i, c, d) = make_tuple(1, 'a', 5.5);
BOOST_TEST(i==1);
BOOST_TEST(c=='a');
BOOST_TEST(d==5.5);
}
// testing tie
// testing assignment from std::pair
void foo7() {
#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
int i, j;
tie (i, j) = std::make_pair(1, 2);
BOOST_TEST(i == 1 && j == 2);
#endif
tuple<int, int, float> a;
#ifdef E11
a = std::make_pair(1, 2); // should fail, tuple is of length 3, not 2
#endif
// the result of make_tuple is assignable:
BOOST_TEST(make_tuple(2, 4, 6) ==
(make_tuple(1, 2, 3) = make_tuple(2, 4, 6)));
dummy(a);
}
// --------------------------------
// ----------------------------
int test_main(int, char *[]) {
foo1();
foo2();
foo3();
foo4();
foo5();
foo6();
foo7();
return 0;
}