feedc0de/boost_tuple
1
0
Fork 0
forked from boostorg/tuple
Code Pull Requests 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

26
doc/design_decisions_rationale.html
View File

@ -13,7 +13,8 @@
<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.
The common principle is that domain libraries (like <i>graph</i>, <i>python</i>) should be on a separate
sub-namespace, 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>
@ -21,20 +22,23 @@ As a result of the discussion, tuple definitions are now directly under the <cod
<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.
Note! The following discussion is not relevant for the Tuple library, as the 'no
sub-namespace' 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.
In the original tuple library submission, all names were under the namespace <code>tuples</code>. This brought up the issue of naming
sub-namespaces.
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.
One solution proposed to the dilemma of introducing a sub-namespace or not was as follows: use a
sub-namespace 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> ...
&nbsp; ...
}
using tuple::cons; // ok
using tuple::tuple; // error
@ -50,7 +54,7 @@ using boost::tuple::tuple; // ok;
</pre></code>
<h2>The endmark of the cons list (nil, null_type, ...)</h2>
<h2>The end mark of the cons list (nil, null_type, ...)</h2>
<p>
Tuples are internally represented as <code>cons</code> lists:
@ -63,7 +67,6 @@ inherits from
<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>
@ -78,11 +81,10 @@ Whether to use 0- or 1-based indexing was discussed more than thoroughly, and th
<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:
By suitably chosen constant types, this would allow alternative syntaxes:
<code><pre>a.get&lt;0&gt;() == a.get(_1st) == a[_1st] == a(_1st);
</pre></code>
@ -116,12 +118,12 @@ Streams that have character types not convertible back and forth to long thus fa
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 would always compile, but some calls to set manipulators might result in a different
character than expected (some default character).</li>
<li>Allocate enough 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.

110
doc/tuple_users_guide.html
View File

@ -55,18 +55,15 @@ To compensate for this &quot;deficiency&quot;, 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.