boostorg/tuple
1
0
Fork 1
mirror of https://github.com/boostorg/tuple.git synced 2025-07-29 20:27:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Minor spelling fixes, add author link

Browse Source 
[SVN r10834]
This commit is contained in:
Beman Dawes
2001-08-10 16:03:01 +00:00
parent c80a1d86d8
commit 00688f9a4a
2 changed files with 59 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
doc/tuple_users_guide.html
View File

@ -55,18 +55,15 @@ To compensate for this "deficiency", the Boost Tuple Library implement
<p>To use the library, just include:
<pre><code>#include "boost/tuple/tuple.hpp"</code></pre>
</p>
<pre><code>#include &quot;boost/tuple/tuple.hpp&quot;</code></pre>
<p>Comparison operators can be included with:
<pre><code>#include "boost/tuple/tuple_comparison.hpp"</code></pre>
</p>
<pre><code>#include &quot;boost/tuple/tuple_comparison.hpp&quot;</code></pre>
<p>To use tuple input and output operators,
<pre><code>#include "boost/tuple/tuple_io.hpp"</code></pre>
<pre><code>#include &quot;boost/tuple/tuple_io.hpp&quot;</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>.
@ -91,13 +88,11 @@ For example, the following definitions are valid tuple instantiations (<code>A</
<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;A, int(*)(char, int), B(A::*)(C&amp;), 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 {
@ -111,7 +106,6 @@ 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>
@ -124,7 +118,6 @@ For example:
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).
@ -137,24 +130,23 @@ public:
};
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
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 initialisation:
In particular, reference types do not have a default initialization:
<pre><code>tuple&lt;double&amp;&gt;() // error: reference must be
// initialised explicitly
// initialized explicitly
double d = 5;
tuple&lt;double&amp;&gt;(d) // ok
tuple&lt;double&amp;&gt;(d+3.14) // error: cannot initialise
tuple&lt;double&amp;&gt;(d+3.14) // error: cannot initialize
// 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>
@ -168,20 +160,19 @@ This makes the construction more convenient, saving the programmer from explicit
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:
By default, the element types are deduced to the plain non-reference 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.
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: <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).
@ -194,33 +185,30 @@ 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");
<pre><code>make_tuple(&quot;Donald&quot;, &quot;Daisy&quot;);
</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>
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.
<p>
Function pointers are deduced to the plain nonreference type, that is, to plain function pointer.
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):
<pre><code>void f(int i);
...
make_tuple(&f); // tuple&lt;void (*)(int)&gt;
make_tuple(&amp;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>
@ -232,7 +220,8 @@ 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.
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:
@ -253,7 +242,6 @@ 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>
@ -272,15 +260,13 @@ 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>
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>
@ -297,33 +283,31 @@ The operators <code>&lt;, >, &lt;=</code> and <code>>=</code> implement a lexico
<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>
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>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());
<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());
tuple&lt;std::string, long, A&gt; t3(std::string(&quot;different&quot;), 3, A());
bool operator==(A, A) { std::cout << "All the same to me..."; return true; }
bool operator==(A, A) { std::cout &lt;&lt; &quot;All the same to me...&quot;; return true; }
t1 == t2; // true
t1 == t3; // false, does not print "All the..."
t1 == t3; // false, does not print &quot;All the...&quot;
</code></pre>
</p>
<h2><a name = "tiers">Tiers</a></h2>
<p>
<i>Tiers</i> are tuples, where all elements are of nonconst reference types.
<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>):
<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>.
@ -331,17 +315,16 @@ The same result could be achieved with the call <code>make_tuple(ref(i), ref(c),
</p>
<p>
A tuple that contains nonconst 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.:
<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;
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.
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:
@ -349,7 +332,6 @@ 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:
@ -374,30 +356,27 @@ 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!");
<pre><code>tuple&lt;float, int, std::string&gt; a(1.0f, 2, std::string(&quot;Howdy folks!&quot;);
cout << a;
cout &lt;&lt; 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:
The library defines three <i>manipulators</i> for changing the default behavior:
<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
<li><code>set_delimiter(char)</code> defines the delimiter character between
elements.</li>
</ul>
For example:
<code><pre>cout << set_open('[') << set_close(']') << set_delimiter(',') << a;
<code><pre>cout &lt;&lt; set_open('[') &lt;&lt; set_close(']') &lt;&lt; set_delimiter(',') &lt;&lt; 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:
@ -408,17 +387,17 @@ 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;
cin &gt;&gt; i;
cin &gt;&gt; set_open('[') &gt;&gt; set_close(']') &gt;&gt; set_delimiter(':');
cin &gt;&gt; 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.
elements does not generally work, since the streamed tuple representation may not be unambiguously
parseable.
</p>
<h2><a name = "performance">Performance</a></h2>
@ -445,13 +424,13 @@ 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.
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:
<pre><code>void f1(int&amp;, double&);
<pre><code>void f1(int&amp;, double&amp;);
tuple&lt;int, double&gt; f2();
</code></pre>
@ -496,7 +475,8 @@ Below is a list of compilers and known problems with each compiler:
<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 comments by Vesa Karvonen, John Max Skaller, Ed Brey, Beman Dawes and David Abrahams 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.
<h2><a name = "references">References</a></h2>
@ -519,7 +499,7 @@ J&auml;rvi J.: <i>ML-Style Tuple Assignment in Standard C++ - Extending the Mult
<p>Last modified 2001-08-10</p>
<p>&copy; Copyright Jaakko J&auml;rvi 2001.
<p>&copy; Copyright <a href="../../../people/jaakko_jarvi.htm"> Jaakko J&auml;rvi</a> 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.