diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2013-06-25 22:59:01 +0000 |
|---|---|---|
| committer | <> | 2013-09-27 11:49:28 +0000 |
| commit | 8c4528713d907ee2cfd3bfcbbad272c749867f84 (patch) | |
| tree | c09e2ce80f47b90c85cc720f5139089ad9c8cfff /libs/tuple | |
| download | boost-tarball-8c4528713d907ee2cfd3bfcbbad272c749867f84.tar.gz | |
Imported from /home/lorry/working-area/delta_boost-tarball/boost_1_54_0.tar.bz2.boost_1_54_0baserock/morph
Diffstat (limited to 'libs/tuple')
| -rw-r--r-- | libs/tuple/doc/design_decisions_rationale.html | 155 | ||||
| -rw-r--r-- | libs/tuple/doc/tuple_advanced_interface.html | 134 | ||||
| -rw-r--r-- | libs/tuple/doc/tuple_users_guide.html | 535 | ||||
| -rw-r--r-- | libs/tuple/index.html | 13 | ||||
| -rw-r--r-- | libs/tuple/test/Jamfile | 8 | ||||
| -rw-r--r-- | libs/tuple/test/README | 16 | ||||
| -rw-r--r-- | libs/tuple/test/another_tuple_test_bench.cpp | 163 | ||||
| -rw-r--r-- | libs/tuple/test/io_test.cpp | 143 | ||||
| -rw-r--r-- | libs/tuple/test/tuple_test_bench.cpp | 497 |
9 files changed, 1664 insertions, 0 deletions
diff --git a/libs/tuple/doc/design_decisions_rationale.html b/libs/tuple/doc/design_decisions_rationale.html new file mode 100644 index 000000000..21f7457da --- /dev/null +++ b/libs/tuple/doc/design_decisions_rationale.html @@ -0,0 +1,155 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + +<title>Design decisions rationale for Boost Tuple Library</title> + +<body bgcolor="#FFFFFF" text="#000000"> + +<IMG SRC="../../../boost.png" + 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 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 +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. +Tuples were originally under a subnamespace. +As a result of the discussion, tuple definitions were moved directly under the <code>boost</code> namespace. +As a result of a continued discussion, the subnamespace was reintroduced. +The final (I truly hope so) solution is now to have all definitions in namespace <code>::boost::tuples</code>, and the most common names in the <code>::boost</code> namespace as well. +This is accomplished with using declarations (suggested by Dave Abrahams):</p> +<pre><code>namespace boost { + namespace tuples { + ... + // All library code + ... + } + using tuples::tuple; + using tuples::make_tuple; + using tuples::tie; + using tuples::get; +} +</code></pre> +<p>With this arrangement, tuple creation with direct constructor calls, <code>make_tuple</code> or <code>tie</code> functions do not need the namespace qualifier. +Further, all functions that manipulate tuples are found with Koenig-lookup. +The only exceptions are the <code>get<N></code> functions, which are always called with an explicitly qualified template argument, and thus Koenig-lookup does not apply. +Therefore, get is lifted to <code>::boost</code> namespace with a using declaration. +Hence, the interface for an application programmer is in practice under the namespace <code>::boost</code>. +</p> +<p> +The other names, forming an interface for library writers (cons lists, metafunctions manipulating cons lists, ...) remain in the subnamespace <code>::boost::tuples</code>. +Note, that the names <code>ignore</code>, <code>set_open</code>, <code>set_close</code> and <code>set_delimiter</code> are considered to be part of the application programmer's interface, but are still not under <code>boost</code> namespace. +The reason being the danger for name clashes for these common names. +Further, the usage of these features is probably not very frequent. +</p> + +<h4>For those who are really interested in namespaces</h4> + +<p> +The subnamespace name <i>tuples</i> raised some discussion. +The rationale for not using the most natural name 'tuple' is to avoid having an identical name with the tuple template. +Namespace names are, however, not generally in plural form in boost libraries. +First, no real trouble was reported for using the same name for a namespace and a class and we considered changing the name 'tuples' to 'tuple'. +But we found some trouble after all. +Both gcc and edg compilers reject using declarations where the namespace and class names are identical:</p> + +<pre><code>namespace boost { + namespace tuple { + ... tie(...); + class tuple; + ... + } + using tuple::tie; // ok + using tuple::tuple; // error + ... +} +</code></pre> + +<p>Note, however, that a corresponding using declaration in the global namespace seems to be ok:</p> + +<pre><code> +using boost::tuple::tuple; // ok; +</code></pre> + + +<h2>The end mark of the cons list (nil, null_type, ...)</h2> + +<p> +Tuples are internally represented as <code>cons</code> lists: + +<pre><code>tuple<int, int> +</code></pre> +<p>inherits from</p> +<pre><code>cons<int, cons<int, null_type> > +</code></pre> + +<p> +<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<></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:</p> + +<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> +<p>Tuple access with the syntax <code>get<N>(a)</code>, or <code>a.get<N>()</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 syntaxes: + +<pre><code>a.get<0>() == a.get(_1st) == a[_1st] == a(_1st); +</code></pre> + +<p>We chose not to provide more than one indexing method for the following reasons:</p> +<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> + +<p>The comparison operator implements lexicographical order. +Other orderings were considered, mainly dominance (<i>a < 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.</p> + +<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.</p> + +<p>This may be revisited at some point. The two possible solutions are:</p> +<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 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> + +<A href="tuple_users_guide.html">Back to the user's guide</A> +<hr><p>© Copyright Jaakko Järvi 2001. +</body> +</html> + diff --git a/libs/tuple/doc/tuple_advanced_interface.html b/libs/tuple/doc/tuple_advanced_interface.html new file mode 100644 index 000000000..c783f0285 --- /dev/null +++ b/libs/tuple/doc/tuple_advanced_interface.html @@ -0,0 +1,134 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Tuple library advanced features</title> + </head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<IMG SRC="../../../boost.png" + ALT="C++ Boost" width="277" height="86"> + + <h1>Tuple library advanced features</h1> + +The advanced features described in this document are all under namespace <code>::boost::tuples</code> + +<h2>Metafunctions for tuple types</h2> +<p> +Suppose <code>T</code> is a tuple type, and <code>N</code> is a constant integral expression.</p> + +<pre><code>element<N, T>::type</code></pre> + +<p>gives the type of the <code>N</code>th element in the tuple type <code>T</code>. If <code>T</code> is const, the resulting type is const qualified as well. +Note that the constness of <code>T</code> does not affect reference type +elements. +</p> + +<pre><code>length<T>::value</code></pre> + +<p>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 </p> + +<pre><code>tuple<A, B, C, D></code></pre> + +<p>inherits from the type</p> +<pre><code>cons<A, cons<B, cons<C, cons<D, null_type> > > > +</code></pre> + +<p>The tuple template provides the typedef <code>inherited</code> to access the cons list representation. E.g.: +<code>tuple<A>::inherited</code> is the type <code>cons<A, null_type></code>. +</p> + +<h4>Empty tuple</h4> +<p> +The internal representation of the empty tuple <code>tuple<></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&) {}; + +template <class H, class T> +inline void set_to_zero(cons<H, T>& x) { x.get_head() = 0; set_to_zero(x.get_tail()); } +</code></pre> +<p> + +<h4>Constructing cons lists</h4> + +<p> +A cons list can be default constructed provided that all its elements can be default constructed. +</p> +<p> +A cons list can be constructed from its head and tail. The prototype of the constructor is:</p> +<pre><code>cons(typename access_traits<head_type>::parameter_type h, + const tail_type& t) +</code></pre> +<p>The traits template for the head parameter selects correct parameter types for different kinds of element types (for reference elements the parameter type equals the element type, for non-reference types the parameter type is a reference to const non-volatile element type). +</p> +<p> +For a one-element cons list the tail argument (<code>null_type</code>) can be omitted. +</p> + + +<h2>Traits classes for tuple element types</h2> + +<h4><code>access_traits</code></h4> +<p> +The template <code>access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:</p> +<ol> +<li><code>access_traits<T>::non_const_type</code> maps <code>T</code> to the return type of the non-const access functions (nonmember and member <code>get</code> functions, and the <code>get_head</code> function).</li> +<li><code>access_traits<T>::const_type</code> maps <code>T</code> to the return type of the const access functions.</li> +<li><code>access_traits<T>::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li> +</ol> +<h4><code>make_tuple_traits</code></h4> + +<p>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<T>::type</code> implements the following type mapping:</p> +<ul> +<li><i>any reference type</i> -> <i>compile time error</i> +</li> +<li><i>any array type</i> -> <i>constant reference to the array type</i> +</li> +<li><code>reference_wrapper<T></code> -> <code>T&</code> +</li> +<li><code>T</code> -> <code>T</code> +</li> +</ul> + +<p>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>Reference wrappers were originally part of the tuple library, but they are now a general utility of boost. +The <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate file <code>ref.hpp</code> in the main boost include directory; and directly in the <code>boost</code> namespace. +</p> + +<A href="tuple_users_guide.html">Back to the user's guide</A> +<hr> + +<p>© Copyright Jaakko Järvi 2001.</p> + </body> +</html> diff --git a/libs/tuple/doc/tuple_users_guide.html b/libs/tuple/doc/tuple_users_guide.html new file mode 100644 index 000000000..c68edfc7f --- /dev/null +++ b/libs/tuple/doc/tuple_users_guide.html @@ -0,0 +1,535 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<title>The Boost Tuple Library</title> +</head> +<body bgcolor="#FFFFFF" text="#000000"> + +<IMG SRC="../../../boost.png" + 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 "deficiency", 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:</p> + +<pre><code>#include "boost/tuple/tuple.hpp"</code></pre> + +<p>Comparison operators can be included with:</p> +<pre><code>#include "boost/tuple/tuple_comparison.hpp"</code></pre> + +<p>To use tuple input and output operators,</p> + +<pre><code>#include "boost/tuple/tuple_io.hpp"</code></pre> + +<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> + +<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. +Note that <code>void</code> and plain function types are valid +C++ types, but objects of such types cannot exist. +Hence, if a tuple type contains such types as elements, the tuple type +can exist, but not an object of that type. +There are natural limitations for element types that cannot +be copied, or that are not default constructible (see 'Constructing tuples' + below). </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):</p> + +<pre><code>tuple<int> +tuple<double&, const double&, const double, double*, const double*> +tuple<A, int(*)(char, int), B(A::*)(C&), C> +tuple<std::string, std::pair<A, B> > +tuple<A*, tuple<const A*, const B&, C>, bool, void*> +</code></pre> + +<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 <= <i>k</i> <= <i>n</i>. +For example:</p> +<pre><code>tuple<int, double>() +tuple<int, double>(1) +tuple<int, double>(1, 3.14) +</code></pre> + +<p> +If no initial value for an element is provided, it is default initialized (and hence must be default initializable). +For example.</p> + +<pre><code>class X { + X(); +public: + X(std::string); +}; + +tuple<X,X,X>() // error: no default constructor for X +tuple<X,X,X>(string("Jaba"), string("Daba"), string("Duu")) // ok +</code></pre> + +<p>In particular, reference types do not have a default initialization: </p> + +<pre><code>tuple<double&>() // error: reference must be + // initialized explicitly + +double d = 5; +tuple<double&>(d) // ok + +tuple<double&>(d+3.14) // error: cannot initialize + // non-const reference with a temporary + +tuple<const double&>(d+3.14) // ok, but dangerous: + // the element becomes a dangling reference +</code></pre> + +<p>Using an initial value for an element that cannot be copied, is a compile +time error:</p> + +<pre><code>class Y { + Y(const Y&); +public: + Y(); +}; + +char a[10]; + +tuple<char[10], Y>(a, Y()); // error, neither arrays nor Y can be copied +tuple<char[10], Y>(); // ok +</code></pre> + +<p>Note particularly that the following is perfectly ok:</p> +<pre><code>Y y; +tuple<char(&)[10], Y&>(a, y); +</code></pre> + +<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<char[10], int&></code>.</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:</p> +<pre><code>tuple<int, int, double> 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.: </p> +<pre><code>void foo(const A& a, B& b) { + ... + make_tuple(a, b); +</code></pre> +<p>The <code>make_tuple</code> invocation results in a tuple of type <code>tuple<A, B></code>.</p> + +<p> +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 example below). +For example:</p> + +<pre><code>A a; B b; const A ca = a; +make_tuple(cref(a), b); // creates tuple<const A&, B> +make_tuple(ref(a), b); // creates tuple<A&, B> +make_tuple(ref(a), cref(b)); // creates tuple<A&, const B&> +make_tuple(cref(ca)); // creates tuple<const A&> +make_tuple(ref(ca)); // creates tuple<const A&> +</code></pre> + + +<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:</p> +<pre><code>make_tuple("Donald", "Daisy"); +</code></pre> + +<p>This creates an object of type <code>tuple<const char (&)[7], const char (&)[6]></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.</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):</p> +<pre><code>void f(int i); + ... +make_tuple(&f); // tuple<void (*)(int)> + ... +tuple<tuple<void (&)(int)> > a(f) // ok +make_tuple(f); // not ok +</code></pre> + +<h2><a name = "accessing_elements">Accessing tuple elements</a></h2> + +<p> +Tuple elements are accessed with the expression:</p> + +<pre><code>t.get<N>() +</code></pre> +<p>or</p> +<pre><code>get<N>(t) +</code></pre> +<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 constraints are detected at compile time. Examples:</p> + +<pre><code>double d = 2.7; A a; +tuple<int, double&, const A&> t(1, d, a); +const tuple<int, double&, const A&> ct = t; + ... +int i = get<0>(t); i = t.get<0>(); // ok +int j = get<0>(ct); // ok +get<0>(t) = 5; // ok +get<0>(ct) = 5; // error, can't assign to const + ... +double e = get<1>(t); // ok +get<1>(t) = 3.14; // ok +get<2>(t) = A(); // error, can't assign to const +A aa = get<3>(t); // error: index out of bounds + ... +++get<0>(t); // ok, can be used as any variable +</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<N>(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:</p> + +<pre><code>class A {}; +class B : public A {}; +struct C { C(); C(const B&); }; +struct D { operator C() const; }; +tuple<char, B*, B, D> t; + ... +tuple<int, A*, C, C> a(t); // ok +a = t; // ok +</code></pre> + +<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:</p> + +<pre><code>tuple<float, int> a = std::make_pair(1, 'a'); +</code></pre> + +<h2><a name = "relational_operators">Relational operators</a></h2> +<p> +Tuples reduce the operators <code>==, !=, <, >, <=</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:</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> + +<p>The operators <code><, >, <=</code> and <code>>=</code> implement a lexicographical ordering.</p> + +<p> +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> + +<pre><code>tuple<std::string, int, A> t1(std::string("same?"), 2, A()); +tuple<std::string, long, A> t2(std::string("same?"), 2, A()); +tuple<std::string, long, A> t3(std::string("different"), 3, A()); + +bool operator==(A, A) { std::cout << "All the same to me..."; return true; } + +t1 == t2; // true +t1 == t3; // false, does not print "All the..." +</code></pre> + + +<h2><a name = "tiers">Tiers</a></h2> + +<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>):</p> + +<pre><code>int i; char c; double d; + ... +tie(i, c, a); +</code></pre> + +<p> +The above <code>tie</code> function creates a tuple of type <code>tuple<int&, char&, double&></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 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 << i << " " << c << " " << d; +</code></pre> +<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.</p> + +<p> +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> +<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'); +</code></pre> + +<h2><a name = "streaming">Streaming</a></h2> + +<p> +The global <code>operator<<</code> has been overloaded for <code>std::ostream</code> such that tuples are +output by recursively calling <code>operator<<</code> for each element. +</p> + +<p> +Analogously, the global <code>operator>></code> has been overloaded to extract tuples from <code>std::istream</code> by recursively calling <code>operator>></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<float, int, std::string> a(1.0f, 2, std::string("Howdy folks!"); + +cout << a; +</code></pre> +<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:</p> +<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 character between +elements.</li> +</ul> + +<p>Note, that these manipulators are defined in the <code>tuples</code> subnamespace. +For example:</p> +<pre><code>cout << tuples::set_open('[') << tuples::set_close(']') << tuples::set_delimiter(',') << a; +</code></pre> +<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>></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> + +<p>The code:</p> + +<pre><code>tuple<int, int, int> i; +tuple<int, int> j; + +cin >> i; +cin >> tuples::set_open('[') >> tuples::set_close(']') >> tuples::set_delimiter(':'); +cin >> j; +</code></pre> + +<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 +elements does not generally work, since the streamed tuple representation may not be unambiguously +parseable. +</p> + +<h2><a name = "performance">Performance</a></h2> + +<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; +public: + hand_made_tuple(const A& aa, const B& bb, const C& cc) + : a(aa), b(bb), c(cc) {}; + A& getA() { return a; }; + B& getB() { return b; }; + C& getC() { return c; }; +}; + +hand_made_tuple hmt(A(), B(), C()); +hmt.getA(); hmt.getB(); hmt.getC(); +</code></pre> + +<p>and this code:</p> + +<pre><code>tuple<A, B, C> t(A(), B(), C()); +t.get<0>(); t.get<1>(); t.get<2>(); +</code></pre> + +<p>Note, that there are widely used compilers (e.g. bcc 5.5.1) which fail to optimize this kind of tuple usage. +</p> +<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:</p> + +<pre><code>void f1(int&, double&); +tuple<int, double> f2(); +</code></pre> + +<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> +<p>See +[<a href="#publ_1">1</a>, +<a href="#publ_2">2</a>] + for more in-depth discussions about efficiency.</p> + +<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 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>] +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> +<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.</p> +<h2><a name = "references">References</a></h2> + +<p> +<a name="publ_1"></a>[1] +Jä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ä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ärvi J.:<i>Tuple Types and Multiple Return Values</i>, C/C++ Users Journal, August 2001. +</p> + +<hr> + +<p>Last modified 2003-09-07</p> + +<p>© Copyright <a href="http://www.boost.org/people/jaakko_jarvi.htm"> Jaakko Jä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. +</p> +</body> +</html> + + + + diff --git a/libs/tuple/index.html b/libs/tuple/index.html new file mode 100644 index 000000000..d8c1cf895 --- /dev/null +++ b/libs/tuple/index.html @@ -0,0 +1,13 @@ +<html> +<head> +<meta http-equiv="refresh" content="0; URL=doc/tuple_users_guide.html"> +</head> +<body> +Automatic redirection failed, please go to <a href="doc/tuple_users_guide.html">doc/tuple_users_guide.html</a> + <hr> +<p>© Copyright Beman Dawes, 2001</p> +<p>Distributed under the Boost Software License, Version 1.0. (See accompanying +file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy +at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p> +</body> +</html> diff --git a/libs/tuple/test/Jamfile b/libs/tuple/test/Jamfile new file mode 100644 index 000000000..66574f691 --- /dev/null +++ b/libs/tuple/test/Jamfile @@ -0,0 +1,8 @@ + +project : requirements <library>/boost/test//boost_test_exec_monitor ; + +test-suite tuple : + [ run tuple_test_bench.cpp ] + [ run io_test.cpp ] + [ run another_tuple_test_bench.cpp ] + ;
\ No newline at end of file diff --git a/libs/tuple/test/README b/libs/tuple/test/README new file mode 100644 index 000000000..6047c49aa --- /dev/null +++ b/libs/tuple/test/README @@ -0,0 +1,16 @@ +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 + +The following is not true anymore: + + If you want to use tuple_io, you need to compile and link src/tuple.cpp: + g++ -I../../.. ../src/tuple.cpp io_test.cpp + +Thanks to Hartmut Kaiser's suggestion, the tuple.cpp is not needed anymore. diff --git a/libs/tuple/test/another_tuple_test_bench.cpp b/libs/tuple/test/another_tuple_test_bench.cpp new file mode 100644 index 000000000..15074daf0 --- /dev/null +++ b/libs/tuple/test/another_tuple_test_bench.cpp @@ -0,0 +1,163 @@ +// Copyright (C) 1999, 2000 Jaakko Jarvi (jaakko.jarvi@cs.utu.fi) +// +// Distributed under the Boost Software License, Version 1.0. (See +// accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) + +// For more information, see http://www.boost.org + + +// another_test_bench.cpp -------------------------------- + +// This file has various tests to see that things that shouldn't +// compile, don't compile. + +// 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 <string> +#include <utility> + +using namespace boost; +using namespace boost::tuples; + + +template<class T> void dummy(const T&) {} + +class A {}; class B {}; class C {}; + +// A non-copyable class +class no_copy { + no_copy(const no_copy&) {} +public: + no_copy() {}; +}; + +no_copy y; + +#ifdef E1 +tuple<no_copy> v1; // should faild +#endif + + +#ifdef E2 +char cs[10]; +tuple<char[10]> v3; // should fail, arrays must be stored as references +#endif + +// 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 +} + +void foo2() { +// testing default values +#ifdef E4 + dummy(tuple<double&>()); // should fail, not defaults for references + dummy(tuple<const double&>()); // likewise +#endif + +#ifdef E5 + double dd = 5; + dummy(tuple<double&>(dd+3.14)); // should fail, temporary to non-const reference +#endif +} + + + +// make_tuple ------------------------------------------ + + + void foo3() { +#ifdef E7 + std::make_pair("Doesn't","Work"); // fails +#endif + // make_tuple("Does", "Work"); // this should work +} + + + +// - testing element access + +void foo4() +{ + double d = 2.7; + A a; + tuple<int, double&, const A&> t(1, d, a); + const tuple<int, double&, const A> ct = t; + (void)ct; +#ifdef E8 + get<0>(ct) = 5; // can't assign to const +#endif + +#ifdef E9 + get<4>(t) = A(); // can't assign to const +#endif +#ifdef E10 + dummy(get<5>(ct)); // illegal index +#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; + (void)t; + tuple<char, char> aaa; + tuple<int, int> bbb(aaa); + (void)bbb; + // tuple<int, AA*, CC, CC> a = t; + // a = t; + } + + +// testing tie +// testing assignment from std::pair +void foo7() { + + tuple<int, int, float> a; +#ifdef E11 + a = std::make_pair(1, 2); // should fail, tuple is of length 3, not 2 +#endif + + dummy(a); +} + + + +// -------------------------------- +// ---------------------------- +int test_main(int, char *[]) { + + foo1(); + foo2(); + foo3(); + foo4(); + foo5(); + + foo7(); + + return 0; +} diff --git a/libs/tuple/test/io_test.cpp b/libs/tuple/test/io_test.cpp new file mode 100644 index 000000000..382f8cc51 --- /dev/null +++ b/libs/tuple/test/io_test.cpp @@ -0,0 +1,143 @@ +// Copyright (C) 1999, 2000 Jaakko Jarvi (jaakko.jarvi@cs.utu.fi) +// +// Distributed under the Boost Software License, Version 1.0. (See +// accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) + +// For more information, see http://www.boost.org + +// -- 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> +#include <iomanip> + +#if defined BOOST_NO_STRINGSTREAM +#include <strstream> +#else +#include <sstream> +#endif + +using namespace boost; + +#if defined BOOST_NO_STRINGSTREAM +typedef std::ostrstream useThisOStringStream; +typedef std::istrstream useThisIStringStream; +#else +typedef std::ostringstream useThisOStringStream; +typedef std::istringstream useThisIStringStream; +#endif + +int test_main(int argc, char * argv[] ) { + (void)argc; + (void)argv; + using boost::tuples::set_close; + using boost::tuples::set_open; + using boost::tuples::set_delimiter; + + 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_CHECK (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_CHECK (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_CHECK (os1.str() == std::string("[1,2,3][1,2,3]") ); + + // check empty tuple. + useThisOStringStream os3; + os3 << make_tuple(); + BOOST_CHECK (os3.str() == std::string("()") ); + os3 << set_open('['); + os3 << set_close(']'); + os3 << make_tuple(); + BOOST_CHECK (os3.str() == std::string("()[]") ); + + // check width + useThisOStringStream os4; + os4 << std::setw(10) << make_tuple(1, 2, 3); + BOOST_CHECK (os4.str() == std::string(" (1 2 3)") ); + + std::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) << std::endl; + + tmp.close(); + + // When teading tuples from a stream, manipulators must be set correctly: + std::ifstream tmp3("temp.tmp"); + tuple<std::string, std::string, int> j; + +#if !defined (BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION) + tmp3 >> j; + BOOST_CHECK (tmp3.good() ); +#endif + + tmp3 >> set_delimiter(':'); + tuple<int, int, int> i; + tmp3 >> i; + BOOST_CHECK (tmp3.good() ); + + tmp3.close(); + + + // reading tuple<int, int, int> in format (a b c); + useThisIStringStream is1("(100 200 300)"); + + tuple<int, int, int> ti1; + BOOST_CHECK(bool(is1 >> ti1)); + BOOST_CHECK(ti1 == make_tuple(100, 200, 300)); + + useThisIStringStream is2("()"); + tuple<> ti2; + BOOST_CHECK(bool(is2 >> ti2)); + useThisIStringStream is3("[]"); + is3 >> set_open('['); + is3 >> set_close(']'); + BOOST_CHECK(bool(is3 >> ti2)); + + // Make sure that whitespace between elements + // is skipped. + useThisIStringStream is4("(100 200 300)"); + + BOOST_CHECK(bool(is4 >> std::noskipws >> ti1)); + BOOST_CHECK(ti1 == 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; +} + diff --git a/libs/tuple/test/tuple_test_bench.cpp b/libs/tuple/test/tuple_test_bench.cpp new file mode 100644 index 000000000..8bf756f9b --- /dev/null +++ b/libs/tuple/test/tuple_test_bench.cpp @@ -0,0 +1,497 @@ +// Copyright (C) 1999, 2000 Jaakko Jarvi (jaakko.jarvi@cs.utu.fi) +// +// Distributed under the Boost Software License, Version 1.0. (See +// accompanying file LICENSE_1_0.txt or copy at +// http://www.boost.org/LICENSE_1_0.txt) + +// For more information, see http://www.boost.org + +// tuple_test_bench.cpp -------------------------------- + +#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 "boost/type_traits/is_const.hpp" + +#include "boost/ref.hpp" +#include <string> +#include <utility> + +using namespace boost; + +// ---------------------------------------------------------------------------- +// helpers +// ---------------------------------------------------------------------------- + +class A {}; +class B {}; +class C {}; + +// classes with different kinds of conversions +class AA {}; +class BB : public AA {}; +struct CC { CC() {} CC(const BB&) {} }; +struct DD { operator CC() const { return CC(); }; }; + +// something to prevent warnings for unused variables +template<class T> void dummy(const T&) {} + +// no public default constructor +class foo { +public: + explicit foo(int v) : val(v) {} + + bool operator==(const foo& other) const { + return val == other.val; + } + +private: + foo() {} + int val; +}; + +// another class without a public default constructor +class no_def_constructor { + no_def_constructor() {} +public: + no_def_constructor(std::string) {} +}; + +// A non-copyable class +class no_copy { + no_copy(const no_copy&) {} +public: + no_copy() {}; +}; + + +// ---------------------------------------------------------------------------- +// Testing different element types -------------------------------------------- +// ---------------------------------------------------------------------------- + + +typedef tuple<int> t1; + +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 + +// ----------------------------------------------------------------------- +// -tuple construction tests --------------------------------------------- +// ----------------------------------------------------------------------- + + +no_copy y; +tuple<no_copy&> x = tuple<no_copy&>(y); // ok + +char cs[10]; +tuple<char(&)[10]> v2(cs); // ok + +void +construction_test() +{ + + // Note, the get function can be called without the tuples:: qualifier, + // as it is lifted to namespace boost with a "using tuples::get" but + // MSVC 6.0 just cannot find get without the namespace qualifier + + tuple<int> t1; + BOOST_CHECK(get<0>(t1) == int()); + + tuple<float> t2(5.5f); + BOOST_CHECK(get<0>(t2) > 5.4f && get<0>(t2) < 5.6f); + + tuple<foo> t3(foo(12)); + BOOST_CHECK(get<0>(t3) == foo(12)); + + tuple<double> t4(t2); + BOOST_CHECK(get<0>(t4) > 5.4 && get<0>(t4) < 5.6); + + tuple<int, float> t5; + BOOST_CHECK(get<0>(t5) == int()); + BOOST_CHECK(get<1>(t5) == float()); + + tuple<int, float> t6(12, 5.5f); + BOOST_CHECK(get<0>(t6) == 12); + BOOST_CHECK(get<1>(t6) > 5.4f && get<1>(t6) < 5.6f); + + tuple<int, float> t7(t6); + BOOST_CHECK(get<0>(t7) == 12); + BOOST_CHECK(get<1>(t7) > 5.4f && get<1>(t7) < 5.6f); + + tuple<long, double> t8(t6); + BOOST_CHECK(get<0>(t8) == 12); + BOOST_CHECK(get<1>(t8) > 5.4f && get<1>(t8) < 5.6f); + + 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") + ) + ); + +// testing default values + dummy(tuple<int, double>()); + dummy(tuple<int, double>(1)); + dummy(tuple<int, double>(1,3.14)); + + + // dummy(tuple<double&>()); // should fail, not defaults for references + // dummy(tuple<const double&>()); // likewise + + double dd = 5; + dummy(tuple<double&>(dd)); // ok + + dummy(tuple<const double&>(dd+3.14)); // ok, but dangerous + + // dummy(tuple<double&>(dd+3.14)); // should fail, + // // temporary to non-const reference +} + + +// ---------------------------------------------------------------------------- +// - testing element access --------------------------------------------------- +// ---------------------------------------------------------------------------- + +void element_access_test() +{ + double d = 2.7; + A a; + tuple<int, double&, const A&, int> t(1, d, a, 2); + const tuple<int, double&, const A, int> ct = t; + + int i = get<0>(t); + int i2 = get<3>(t); + + BOOST_CHECK(i == 1 && i2 == 2); + + int j = get<0>(ct); + BOOST_CHECK(j == 1); + + get<0>(t) = 5; + BOOST_CHECK(t.head == 5); + + // get<0>(ct) = 5; // can't assign to const + + double e = get<1>(t); + BOOST_CHECK(e > 2.69 && e < 2.71); + + get<1>(t) = 3.14+i; + BOOST_CHECK(get<1>(t) > 4.13 && get<1>(t) < 4.15); + + // get<4>(t) = A(); // can't assign to const + // dummy(get<5>(ct)); // illegal index + + ++get<0>(t); + BOOST_CHECK(get<0>(t) == 6); + + BOOST_STATIC_ASSERT((boost::is_const<boost::tuples::element<0, tuple<int, float> >::type>::value != true)); +#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION + BOOST_STATIC_ASSERT((boost::is_const<boost::tuples::element<0, const tuple<int, float> >::type>::value)); +#endif + + BOOST_STATIC_ASSERT((boost::is_const<boost::tuples::element<1, tuple<int, float> >::type>::value != true)); +#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION + BOOST_STATIC_ASSERT((boost::is_const<boost::tuples::element<1, const tuple<int, float> >::type>::value)); +#endif + + + dummy(i); dummy(i2); dummy(j); dummy(e); // avoid warns for unused variables +} + + +// ---------------------------------------------------------------------------- +// - copying tuples ----------------------------------------------------------- +// ---------------------------------------------------------------------------- + + + +void +copy_test() +{ + tuple<int, char> t1(4, 'a'); + tuple<int, char> t2(5, 'b'); + t2 = t1; + BOOST_CHECK(get<0>(t1) == get<0>(t2)); + BOOST_CHECK(get<1>(t1) == get<1>(t2)); + + tuple<long, std::string> t3(2, "a"); + t3 = t1; + BOOST_CHECK((double)get<0>(t1) == get<0>(t3)); + BOOST_CHECK(get<1>(t1) == get<1>(t3)[0]); + +// testing copy and assignment with implicit conversions between elements +// testing tie + + tuple<char, BB*, BB, DD> t; + tuple<int, AA*, CC, CC> a(t); + a = t; + + int i; char c; double d; + tie(i, c, d) = make_tuple(1, 'a', 5.5); + + BOOST_CHECK(i==1); + BOOST_CHECK(c=='a'); + BOOST_CHECK(d>5.4 && d<5.6); +} + +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_CHECK(get<0>(t1) == 6); + BOOST_CHECK(get<1>(t1) > 2.1f && get<1>(t1) < 2.3f); + BOOST_CHECK(get<2>(t1) == false); + BOOST_CHECK(get<3>(t1) == foo(5)); +} + +// ---------------------------------------------------------------------------- +// make_tuple tests ----------------------------------------------------------- +// ---------------------------------------------------------------------------- + +void +make_tuple_test() +{ + tuple<int, char> t1 = make_tuple(5, 'a'); + BOOST_CHECK(get<0>(t1) == 5); + BOOST_CHECK(get<1>(t1) == 'a'); + + tuple<int, std::string> t2; + t2 = boost::make_tuple((short int)2, std::string("Hi")); + BOOST_CHECK(get<0>(t2) == 2); + BOOST_CHECK(get<1>(t2) == "Hi"); + + + A a = A(); B b; + const A ca = a; + make_tuple(boost::cref(a), b); + make_tuple(boost::ref(a), b); + make_tuple(boost::ref(a), boost::cref(b)); + + make_tuple(boost::ref(ca)); + +// the result of make_tuple is assignable: + BOOST_CHECK(make_tuple(2, 4, 6) == + (make_tuple(1, 2, 3) = make_tuple(2, 4, 6))); + +#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION + make_tuple("Donald", "Daisy"); // should work; +#endif + // std::make_pair("Doesn't","Work"); // fails + +// You can store a reference to a function in a tuple + tuple<void(&)()> adf(make_tuple_test); + + dummy(adf); // avoid warning for unused variable + +// But make_tuple doesn't work +// with function references, since it creates a const qualified function type + +// make_tuple(make_tuple_test); + +// With function pointers, make_tuple works just fine + +#if !defined(__BORLANDC__) || __BORLAND__ > 0x0551 + make_tuple(&make_tuple_test); +#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 (&func_t) (void); +// func_t fref = static_cast<func_t>(ref(make_tuple_test)); // works fine +// func_t fref = ref(make_tuple_test); // error + +// This is probably not a very common situation, so currently +// I don't know how which compiler is right (JJ) +} + +void +tie_test() +{ + int a; + char b; + foo c(5); + + tie(a, b, c) = make_tuple(2, 'a', foo(3)); + BOOST_CHECK(a == 2); + BOOST_CHECK(b == 'a'); + BOOST_CHECK(c == foo(3)); + + tie(a, tuples::ignore, c) = make_tuple((short int)5, false, foo(5)); + BOOST_CHECK(a == 5); + BOOST_CHECK(b == 'a'); + BOOST_CHECK(c == foo(5)); + +// testing assignment from std::pair + int i, j; + tie (i, j) = std::make_pair(1, 2); + BOOST_CHECK(i == 1 && j == 2); + + tuple<int, int, float> ta; +#ifdef E11 + ta = std::make_pair(1, 2); // should fail, tuple is of length 3, not 2 +#endif + + dummy(ta); +} + + +// ---------------------------------------------------------------------------- +// - testing tuple equality ------------------------------------------------- +// ---------------------------------------------------------------------------- + +void +equality_test() +{ + tuple<int, char> t1(5, 'a'); + tuple<int, char> t2(5, 'a'); + BOOST_CHECK(t1 == t2); + + tuple<int, char> t3(5, 'b'); + tuple<int, char> t4(2, 'a'); + BOOST_CHECK(t1 != t3); + BOOST_CHECK(t1 != t4); + BOOST_CHECK(!(t1 != t2)); +} + + +// ---------------------------------------------------------------------------- +// - testing tuple comparisons ----------------------------------------------- +// ---------------------------------------------------------------------------- + +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_CHECK(t1 < t2); + BOOST_CHECK(t1 <= t2); + BOOST_CHECK(t2 > t1); + BOOST_CHECK(t2 >= t1); + BOOST_CHECK(t2 < t3); + BOOST_CHECK(t2 <= t3); + BOOST_CHECK(t3 > t2); + BOOST_CHECK(t3 >= t2); + +} + + +// ---------------------------------------------------------------------------- +// - testing cons lists ------------------------------------------------------- +// ---------------------------------------------------------------------------- +void cons_test() +{ + using tuples::cons; + using tuples::null_type; + + cons<volatile float, null_type> a(1, null_type()); + cons<const int, cons<volatile float, null_type> > b(2,a); + int i = 3; + cons<int&, cons<const int, cons<volatile float, null_type> > > c(i, b); + BOOST_CHECK(make_tuple(3,2,1)==c); + + cons<char, cons<int, cons<float, null_type> > > x; + dummy(x); +} + +// ---------------------------------------------------------------------------- +// - testing const tuples ----------------------------------------------------- +// ---------------------------------------------------------------------------- +void const_tuple_test() +{ + const tuple<int, float> t1(5, 3.3f); + BOOST_CHECK(get<0>(t1) == 5); + BOOST_CHECK(get<1>(t1) == 3.3f); +} + +// ---------------------------------------------------------------------------- +// - testing length ----------------------------------------------------------- +// ---------------------------------------------------------------------------- +void tuple_length_test() +{ + typedef tuple<int, float, double> t1; + using tuples::cons; + typedef cons<int, cons< float, cons <double, tuples::null_type> > > t1_cons; + typedef tuple<> t2; + typedef tuples::null_type t3; + + BOOST_STATIC_ASSERT(tuples::length<t1>::value == 3); + BOOST_STATIC_ASSERT(tuples::length<t1_cons>::value == 3); + BOOST_STATIC_ASSERT(tuples::length<t2>::value == 0); + BOOST_STATIC_ASSERT(tuples::length<t3>::value == 0); + +} + +// ---------------------------------------------------------------------------- +// - testing swap ----------------------------------------------------------- +// ---------------------------------------------------------------------------- +void tuple_swap_test() +{ + tuple<int, float, double> t1(1, 2.0f, 3.0), t2(4, 5.0f, 6.0); + swap(t1, t2); + BOOST_CHECK(get<0>(t1) == 4); + BOOST_CHECK(get<1>(t1) == 5.0f); + BOOST_CHECK(get<2>(t1) == 6.0); + BOOST_CHECK(get<0>(t2) == 1); + BOOST_CHECK(get<1>(t2) == 2.0f); + BOOST_CHECK(get<2>(t2) == 3.0); + + int i = 1,j = 2; + boost::tuple<int&> t3(i), t4(j); + swap(t3, t4); + BOOST_CHECK(i == 2); + BOOST_CHECK(j == 1); +} + + + +// ---------------------------------------------------------------------------- +// - main --------------------------------------------------------------------- +// ---------------------------------------------------------------------------- + +int test_main(int, char *[]) { + + construction_test(); + element_access_test(); + copy_test(); + mutate_test(); + make_tuple_test(); + tie_test(); + equality_test(); + ordering_test(); + cons_test(); + const_tuple_test(); + tuple_length_test(); + tuple_swap_test(); + return 0; +} + + + + + + + |