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

Merge [51862], [53211], [53212], and [53218] from the trunk

Browse Source 
[SVN r53872]
This commit is contained in:
Steven Watanabe committed 2009-06-13 18:30:31 +00:00
1 parent 700d64acc8
commit 41ebb2ee6c
8 files changed
+191 -129
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/tuple_users_guide.html
+73 -67
View File
@@ -1,3 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Boost Tuple Library</title>
@@ -53,20 +54,22 @@ To compensate for this &quot;deficiency&quot;, the Boost Tuple Library implement
<h2><a name="using_library">Using the library</a></h2>
<p>To use the library, just include:
<p>To use the library, just include:</p>
<pre><code>#include &quot;boost/tuple/tuple.hpp&quot;</code></pre>
<p>Comparison operators can be included with:
<p>Comparison operators can be included with:</p>
<pre><code>#include &quot;boost/tuple/tuple_comparison.hpp&quot;</code></pre>
<p>To use tuple input and output operators,
<p>To use tuple input and output operators,</p>
<pre><code>#include &quot;boost/tuple/tuple_io.hpp&quot;</code></pre>
Both <code>tuple_io.hpp</code> and <code>tuple_comparison.hpp</code> include <code>tuple.hpp</code>.
<p>Both <code>tuple_io.hpp</code> and <code>tuple_comparison.hpp</code> include <code>tuple.hpp</code>.</p>
<p>All definitions are in namespace <code>::boost::tuples</code>, but the most common names are lifted to namespace <code>::boost</code> with using declarations. These names are: <code>tuple</code>, <code>make_tuple</code>, <code>tie</code> and <code>get</code>. Further, <code>ref</code> and <code>cref</code> are defined directly under the <code>::boost</code> namespace.
<p>All definitions are in namespace <code>::boost::tuples</code>, but the most common names are lifted to namespace
<code>::boost</code> with using declarations. These names are: <code>tuple</code>, <code>make_tuple</code>, <code>tie</code> and <code>get</code>.
Further, <code>ref</code> and <code>cref</code> are defined directly under the <code>::boost</code> namespace.</p>
<h2><a name = "tuple_types">Tuple types</a></h2>
@@ -80,11 +83,11 @@ 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 be copied, or that are not default constructible (see 'Constructing tuples'
below).
be copied, or that are not default constructible (see 'Constructing tuples'
below). </p>
<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):
For example, the following definitions are valid tuple instantiations (<code>A</code>, <code>B</code> and <code>C</code> are some user defined classes):</p>
<pre><code>tuple&lt;int&gt;
tuple&lt;double&amp;, const double&amp;, const double, double*, const double*&gt;
@@ -98,7 +101,7 @@ tuple&lt;A*, tuple&lt;const A*, const B&amp;, C&gt;, bool, void*&gt;
<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:
For example:</p>
<pre><code>tuple&lt;int, double&gt;()
tuple&lt;int, double&gt;(1)
tuple&lt;int, double&gt;(1, 3.14)
@@ -106,7 +109,7 @@ tuple&lt;int, double&gt;(1, 3.14)
<p>
If no initial value for an element is provided, it is default initialized (and hence must be default initializable).
For example.
For example.</p>
<pre><code>class X {
X();
@@ -118,7 +121,7 @@ tuple&lt;X,X,X&gt;() // error: no d
tuple&lt;X,X,X&gt;(string(&quot;Jaba&quot;), string(&quot;Daba&quot;), string(&quot;Duu&quot;)) // ok
</code></pre>
In particular, reference types do not have a default initialization:
<p>In particular, reference types do not have a default initialization: </p>
<pre><code>tuple&lt;double&amp;&gt;() // error: reference must be
// initialized explicitly
@@ -134,7 +137,7 @@ tuple&lt;const double&amp;&gt;(d+3.14) // ok, but dangerous:
</code></pre>
<p>Using an initial value for an element that cannot be copied, is a compile
time error:
time error:</p>
<pre><code>class Y {
Y(const Y&amp;);
@@ -148,15 +151,15 @@ tuple&lt;char[10], Y&gt;(a, Y()); // error, neither arrays nor Y can be copied
tuple&lt;char[10], Y&gt;(); // ok
</code></pre>
Note particularly that the following is perfectly ok:
<code><pre>Y y;
<p>Note particularly that the following is perfectly ok:</p>
<pre><code>Y y;
tuple&lt;char(&amp;)[10], Y&amp;&gt;(a, y);
</code></pre>
It is possible to come up with a tuple type that cannot be constructed.
<p>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: <code>tuple&lt;char[10], int&amp;&gt;</code>.
For example: <code>tuple&lt;char[10], int&amp;&gt;</code>.</p>
<p>In sum, the tuple construction is semantically just a group of individual elementary constructions.
</p>
@@ -165,19 +168,19 @@ For example: <code>tuple&lt;char[10], int&amp;&gt;</code>.
<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:
This makes the construction more convenient, saving the programmer from explicitly specifying the element types:</p>
<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>
By default, the element types are deduced to the plain non-reference types. E.g:
By default, the element types are deduced to the plain non-reference types. E.g.: </p>
<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>The <code>make_tuple</code> invocation results in a tuple of type <code>tuple&lt;A, B&gt;</code>.</p>
<p>
Sometimes the plain non-reference type is not desired, e.g. if the element type cannot be copied.
@@ -185,8 +188,9 @@ Therefore, the programmer can control the type deduction and state that a refere
non-const 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:
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 example below).
For example:</p>
<pre><code>A a; B b; const A ca = a;
make_tuple(cref(a), b); // creates tuple&lt;const A&amp;, B&gt;
@@ -198,19 +202,19 @@ make_tuple(ref(ca)); // creates tuple&lt;const A&amp;&gt;
<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:
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:</p>
<pre><code>make_tuple(&quot;Donald&quot;, &quot;Daisy&quot;);
</code></pre>
This creates an object of type <code>tuple&lt;const char (&amp;)[7], const char (&amp;)[6]&gt;</code>
<p>This creates an object of type <code>tuple&lt;const char (&amp;)[7], 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
non-const array type one must use the <code>ref</code> wrapper.
non-const array type one must use the <code>ref</code> wrapper.</p>
<p>
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 <code>make_tuple</code> (a const qualified function type would result, which is illegal):
but such a tuple cannot be constructed with <code>make_tuple</code> (a const qualified function type would result, which is illegal):</p>
<pre><code>void f(int i);
...
make_tuple(&amp;f); // tuple&lt;void (*)(int)&gt;
@@ -222,19 +226,19 @@ make_tuple(f); // not ok
<h2><a name = "accessing_elements">Accessing tuple elements</a></h2>
<p>
Tuple elements are accessed with the expression:
Tuple elements are accessed with the expression:</p>
<pre><code>t.get&lt;N&gt;()
</code></pre>
or
<p>or</p>
<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.
<p>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
non-const 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:
Violations of these constraints are detected at compile time. Examples:</p>
<pre><code>double d = 2.7; A a;
tuple&lt;int, double&amp;, const A&amp;&gt; t(1, d, a);
@@ -253,16 +257,18 @@ 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>
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 <code>get</code> calls should be qualified as: <code>tuples::get&lt;N&gt;(a_tuple)</code> when writing code that shoud compile with MSVC++ 6.0.
Hence, all <code>get</code> calls should be qualified as: <code>tuples::get&lt;N&gt;(a_tuple)</code> when writing code that should compile with MSVC++ 6.0.
</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:
For example:</p>
<pre><code>class A {};
class B : public A {};
@@ -274,32 +280,32 @@ 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>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:
Note that assignment is also defined from <code>std::pair</code> types:</p>
<pre><code>tuple&lt;float, int&gt; a = std::make_pair(1, 'a');
</code></pre>
<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.
Tuples reduce the operators <code>==, !=, &lt;, &gt;, &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:
The equality operators for two tuples <code>a</code> and <code>b</code> are defined as:</p>
<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>The operators <code>&lt;, &gt;, &lt;=</code> and <code>&gt;=</code> implement a lexicographical ordering.</p>
<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.
Note that an attempt to compare two tuples of different lengths results in a compile time error.
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:
<p>Examples:</p>
<pre><code>tuple&lt;std::string, int, A&gt; t1(std::string(&quot;same?&quot;), 2, A());
tuple&lt;std::string, long, A&gt; t2(std::string(&quot;same?&quot;), 2, A());
@@ -316,7 +322,7 @@ t1 == t3; // false, does not print &quot;All the...&quot;
<p>
<i>Tiers</i> are tuples, where all elements are of non-const reference types.
They are constructed with a call to the <code>tie</code> function template (cf. <code>make_tuple</code>):
They are constructed with a call to the <code>tie</code> function template (cf. <code>make_tuple</code>):</p>
<pre><code>int i; char c; double d;
...
@@ -329,26 +335,26 @@ The same result could be achieved with the call <code>make_tuple(ref(i), ref(c),
</p>
<p>
A tuple that contains non-const references as elements can be used to 'unpack' another tuple into variables. E.g.:
A tuple that contains non-const references as elements can be used to 'unpack' another tuple into variables. E.g.:</p>
<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; &quot; &quot; &lt;&lt; c &lt;&lt; &quot; &quot; &lt;&lt; d;
</code></pre>
This code prints <code>1 a 5.5</code> to the standard output stream.
<p>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.
It is convenient when calling functions which return tuples.</p>
<p>
The tying mechanism works with <code>std::pair</code> templates as well:
The tying mechanism works with <code>std::pair</code> templates as well:</p>
<pre><code>int i; char c;
tie(i, c) = std::make_pair(1, 'a');
</code></pre>
<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 (note, that <code>ignore</code> is under the <code>tuples</code> subnamespace):
<p>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 (note, that <code>ignore</code> is under the <code>tuples</code> subnamespace):</p>
<pre><code>char c;
tie(tuples::ignore, c) = std::make_pair(1, 'a');
@@ -374,10 +380,10 @@ For Example:
cout &lt;&lt; a;
</code></pre>
outputs the tuple as: <code>(1.0 2 Howdy folks!)</code>
<p>outputs the tuple as: <code>(1.0 2 Howdy folks!)</code></p>
<p>
The library defines three <i>manipulators</i> for changing the default behavior:
The library defines three <i>manipulators</i> for changing the default behavior:</p>
<ul>
<li><code>set_open(char)</code> defines the character that is output before the first
element.</li>
@@ -387,27 +393,27 @@ last element.</li>
elements.</li>
</ul>
Note, that these manipulators are defined in the <code>tuples</code> subnamespace.
For example:
<code><pre>cout &lt;&lt; tuples::set_open('[') &lt;&lt; tuples::set_close(']') &lt;&lt; tuples::set_delimiter(',') &lt;&lt; a;
<p>Note, that these manipulators are defined in the <code>tuples</code> subnamespace.
For example:</p>
<pre><code>cout &lt;&lt; tuples::set_open('[') &lt;&lt; tuples::set_close(']') &lt;&lt; tuples::set_delimiter(',') &lt;&lt; a;
</code></pre>
outputs the same tuple <code>a</code> as: <code>[1.0,2,Howdy folks!]</code>
<p>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:
<p>The code:</p>
<code><pre>tuple&lt;int, int, int&gt; i;
<pre><code>tuple&lt;int, int, int&gt; i;
tuple&lt;int, int&gt; j;
cin &gt;&gt; i;
cin &gt;&gt; tuples::set_open('[') &gt;&gt; tuples::set_close(']') &gt;&gt; tules::set_delimiter(':');
cin &gt;&gt; tuples::set_open('[') &gt;&gt; tuples::set_close(']') &gt;&gt; tuples::set_delimiter(':');
cin &gt;&gt; j;
</code></pre>
reads the data into the tuples <code>i</code> and <code>j</code>.
<p>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
@@ -417,9 +423,9 @@ parseable.
<h2><a name = "performance">Performance</a></h2>
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:
<p>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:</p>
<pre><code>class hand_made_tuple {
A a; B b; C c;
@@ -435,7 +441,7 @@ hand_made_tuple hmt(A(), B(), C());
hmt.getA(); hmt.getB(); hmt.getC();
</code></pre>
and this code:
<p>and this code:</p>
<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;();
@@ -446,23 +452,23 @@ t.get&lt;0&gt;(); t.get&lt;1&gt;(); t.get&lt;2&gt;();
<p>
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 <code>f1</code> and <code>f2</code> have equivalent functionalities:
For example, suppose that the following functions <code>f1</code> and <code>f2</code> have equivalent functionalities:</p>
<pre><code>void f1(int&amp;, double&amp;);
tuple&lt;int, double&gt; f2();
</code></pre>
Then, the call #1 may be slightly faster than #2 in the code below:
<p>Then, the call #1 may be slightly faster than #2 in the code below:</p>
<pre><code>int i; double d;
...
f1(i,d); // #1
tie(i,d) = f2(); // #2
</code></pre>
See
<p>See
[<a href="#publ_1">1</a>,
<a href="#publ_2">2</a>]
for more in-depth discussions about efficiency.
for more in-depth discussions about efficiency.</p>
<h4>Effect on Compile Time</h4>
@@ -470,7 +476,7 @@ See
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.
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
[<a href="#publ_1">1</a>,
<a href="#publ_2">2</a>]
@@ -492,10 +498,10 @@ Below is a list of compilers and known problems with each compiler:
</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, 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.
<p>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.
The idea for the tie mechanism came from an old usenet article by Ian McCulloch, where he proposed something similar for std::pairs.</p>
<h2><a name = "references">References</a></h2>
<p>