+
+
+There was a discussion about whether tuples should be in a separate namespace or directly at the boost namespace.
+The common principle is that domain libraries (like graph, python) should be on a separate subnamespace, while utility like libraries directly in the boost 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 boost namespace.
+
+ +
+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. +
+
+In the original tuple library submission, all names were under the namespace tuples. This brought up the issue of naming subnamespaces.
+The rationale for not using the most natural name 'tuple' was to avoid having an identical name with the tuple template. Namespace names are, however, not generally in plural form in boost libraries. Further, no real trouble was reported for using the same name for a namespace and a class.
+But we found some trouble after all.
+One solution proposed to the dilemma of introducing a subnamespace or not was as follows: use a subnamespace but lift the most common names to the boost namespace with using declarations.
+Both gcc and edg compilers rejected such using declarations if the namespace and class names were identical:
+
+namespace boost {
+ namespace tuple {
+ class cons;
+ class tuple;
+ ...
+ }
+ using tuple::cons; // ok
+ using tuple::tuple; // error
+ ...
+}
+
+using boost::tuple::tuple; // ok;
+
+Tuples are internally represented as cons lists:
+
+tuple<int, int>
+
cons<int, cons<int, null_type> >
+
null_type is the end mark of the list. Original proposition was nil, but the name is used in MacOS, and might have caused problems, so null_type was chosen instead.
+Other names considered were null_t and unit (the empty tuple type in SML).
+
+Note that null_type is the internal representation of an empty tuple: tuple<> inherits from null_type.
+
+Whether to use 0- or 1-based indexing was discussed more than thoroughly, and the following observations were made: + +
bind1st, bind2nd, pair::first, etc.get<N>(a), or a.get<N>() (where a is a tuple and N an index), was considered to be of the first category, hence, the index of the first element in a tuple is 0.
+
+
+
+A suggestion to provide 1-based 'name like' indexing with constants like _1st, _2nd, _3rd, ... was made.
+By suitably chosen constant types, this would allow alternative syntaces:
+
+a.get<0>() == a.get(_1st) == a[_1st] == a(_1st);
+
_1st, ...).
+Let the binding and lambda libraries use these for a better purpose.a[_1st] (or a(_1st)) 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.
+The characters specified with tuple stream manipulators are stored within the space allocated by ios_base::xalloc, which allocates storage for long type objects.
+static_cast is used in casting between long and the stream's character type.
+Streams that have character types not convertible back and forth to long thus fail to compile.
+
+This may be revisited at some point. The two possible solutions are:
+
char types as the tuple delimiters and use widen and narrow 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).ios_base::xalloc.
+Any volunteers?© Copyright Jaakko Järvi 2001. + + + diff --git a/doc/tuple_advanced_interface.html b/doc/tuple_advanced_interface.html new file mode 100644 index 0000000..e578d6c --- /dev/null +++ b/doc/tuple_advanced_interface.html @@ -0,0 +1,114 @@ + + +
+
+
+
+
+
+
+Suppose T is a tuple type, and N is a constant integral expression.
+
+tuple_element<N, T>::type
Nth element in the tuple type T.
+
tuple_length<T>::value
T.
+
+
+
+Tuples are internally represented as cons lists.
+For example, the tuple
+
+tuple<A, B, C, D>
cons<A, cons<B, cons<C, cons<D, null_type> > > >
+
inherited to access the cons list representation. E.g.:
+tuple<A>::inherited is the type cons<A, null_type>.
+
+The internal representation of the empty tuple tuple<> is null_type.
+
+Both tuple template and the cons templates provide the typedefs head_type and tail_type.
+The head_type typedef gives the type of the first element of the tuple (or the cons list).
+The
+tail_type typedef gives the remaining cons list after removing the first element.
+The head element is stored in the member variable head and the tail list in the member variable tail.
+Cons lists provide the member function get_head() for getting a reference to the head of a cons list, and get_tail() for getting a reference to the tail.
+There are const and non-const versions of both functions.
+
+Note that in a one element tuple, tail_type equals null_type and the get_tail() function returns an object of type null_type.
+
+The empty tuple (null_type) has no head or tail, hence the get_head and get_tail functions are not provided.
+
+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): + +
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()); }
++ +
tuple_access_traits
+The template tuple_access_traits defines three type functions. Let T be a type of an element in a tuple:
+
tuple_access_traits<T>::type maps T to the return type of the non-const access functions (nonmeber and member get functions, and the get_head function).tuple_access_traits<T>::const_type maps T to the return type of the const access functions.tuple_access_traits<T>::parameter_type maps T to the parameter type of the tuple constructor.make_tuple_traitsmake_tuple functions are computed with the type function make_tuple_traits.
+The type function call make_tuple_traits<T>::type implements the following type mapping:
+reference_wrapper<T> -> T&
+T -> T
+reference_wrapper are created with the ref and cref functions (see The make_tuple function.)
+
+
+Note, that the reference_wrapper template and the ref and cref functions are defined in a separate hpp-file reference_wrappers.hpp, which can be included without including the rest of the tuple library.
+
© Copyright Jaakko Järvi 2001.
+ + diff --git a/doc/tuple_users_guide.html b/doc/tuple_users_guide.html new file mode 100644 index 0000000..56204da --- /dev/null +++ b/doc/tuple_users_guide.html @@ -0,0 +1,532 @@ + + +
+
++A tuple (or n-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. +
+ +Tuples are convenient in many circumstances. +For instance, tuples make it easy to define functions that return more than one value. +
+ ++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. +
+ ++Advanced features (describes some metafunctions etc.).
++Rationale behind some design/implementation decisions.
+ + +To use the library, just include: + +
#include "boost/tuple/tuple.hpp"Comparison operators can be included with: +
#include "boost/tuple/tuple_comparison.hpp"To use tuple input and output operators, + +
#include "boost/tuple/tuple_io.hpp"libs/tuple/src/tuple.hpp file to your project.
+
+
+Both tuple_io.hpp and tuple_comparison.hpp include tuple.hpp.
+
+All definitions are in namespace boost.
+
+
A tuple type is an instantiation of the tuple template.
+The template parameters specify the types of the tuple elements.
+The current version supports tuples with 0-10 elements.
+If necessary, the upper limit can be increased up to, say, a few dozen elements.
+The data element can be any C++ type, except for a type that cannot be copied, e.g.:
+
+
+For example, the following definitions are valid tuple instantiations (A, B and C are some user defined classes):
+
+
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*>
++The following code shows some invalid tuple instantiations: +
class Y {
+ Y(const Y&);
+public:
+ Y();
+};
+
+tuple<Y> // not allowed, objects of type Y cannot be copied
+tuple<char[10]> // not allowed: arrays cannot be copied
+tuple<Y&> and tuple<char(&)[10]> are valid instantiations.
+
+
+
++The tuple constructor takes the tuple elements as arguments. +For an n-element tuple, the constructor can be invoked with k arguments, where 0 < k <= n. +For example: +
tuple<int, double>()
+tuple<int, double>(1)
+tuple<int, double>(1, 3.14)
++If no initial value for an element is provided, it is default initialized (and hence must be default initializable). +For example. + +
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
+tuple<double&>() // error: reference must be
+ // initialised explicitly
+
+double d = 5;
+tuple<double&>(d) // ok
+
+tuple<double&>(d+3.14) // error: cannot initialise
+ // non-const reference with a temporary
+
+tuple<const double&>(d+3.14) // ok, but dangerous:
+ // the element becomes a dangling reference
+In sum, the tuple construction is semantically just a group of individual elementary constructions. +
+ +make_tuple function
+Tuples can also be constructed using the make_tuple (cf. std::make_pair) helper functions.
+This makes the construction more convenient, saving the programmer from explicitly specifying the element types:
+
tuple<int, int, double> add_multiply_divide(int a, int b) {
+ return make_tuple(a+b, a*b, double(a)/double(b));
+}
++By default, the element types are deduced to the plain nonreference types. E.g: +
void foo(const A& a, B& b) {
+ ...
+ make_tuple(a, b);
+make_tuple invocation results in a tuple of type tuple<A, B>.
+
+
+
+Sometimes the plain nonreference type is not desired, e.g. if the element type cannot be copied.
+Therefore, the programmer can control the type deduction and state that a reference to const or reference to nonconst type should be used as the element type instead.
+This is accomplished with two helper template functions: ref and cref.
+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 ref results in a tuple element with const reference type (see the fifth code line below).
+For example:
+
+
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&>
+
+Array arguments to make_tuple functions are deduced to reference to const types by default; there is no need to wrap them with cref. For example:
+
make_tuple("Donald", "Daisy");
+tuple<const char (&)[5], const char (&)[6]>
+(note that the type of a string literal is an array of const characters, not const char*).
+However, to get make_tuple to create a tuple with an element of a nonconst array type one must use the ref wrapper.
+
+
+
+Function pointers are deduced to the plain nonreference type, that is, to plain function pointer.
+A tuple can also hold a reference to a function,
+but such a tuple cannot be constructed with make_tuple (a const qualified function type would result, which is illegal):
+
void f(int i);
+ ...
+make_tuple(&f); // tuple<void (*)(int)>
+ ...
+tuple<tuple<void (&)(int)> > a(f) // ok
+make_tuple(f); // not ok
++Tuple elements are accessed with the expression: + +
t.get<N>()
+get<N>(t)
+t is a tuple object and N is a constant integral expression specifying the index of the element to be accessed.
+Depending on whether t is const or not, get returns the Nth element as a reference to const or nonconst type.
+The index of the first element is 0 and thus
+N must be between 0 and k-1, where k is the number of elements in the tuple.
+Violations of these constrains are detected at compile time. Examples:
+
+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
++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: + +
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
+char -> int, B* -> A* (derived class pointer to base class pointer), B -> C (a user defined conversion) and D -> C (a user defined conversion).
+
+
+
+Note that assignment is also defined from std::pair types:
+
+
tuple<float, int> a = std::make_pair(1, 'a');
+
+Tuples reduce the operators ==, !=, <, >, <= and >= 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 a and b are defined as:
+
a == b iff for each i: ai == bia != b iff exists i: ai != bi<, >, <= and >= implement a lexicographical ordering.
+
++Note that an attempt to compare two tuples of different lengths results in a compile time error.
+Also, the comparison operators are "short-circuited": elementary comparisons start from the first elements and are performed only until the result is clear. + +Examples: + +
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..."
+
+Tiers are tuples, where all elements are of nonconst reference types.
+They are constructed with a call to the tie function template (cf. make_tuple):
+
+
int i; char c; double d;
+ ...
+tie(i, c, a);
+
+The above tie function creates a tuple of type tuple<int&, char&, double&>.
+The same result could be achieved with the call make_tuple(ref(i), ref(c), ref(a)).
+
+A tuple that contains nonconst references as elements can be used to 'unpack' another tuple into variables. E.g.: + +
int i; char c; double d;
+tie(i, c, d) = make_tuple(1,'a', 5.5);
+std::cout << i << " " << c << " " << d;
+1 a 5.5 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.
+
+
+
+The tying mechanism works with std::pair templates as well:
+
+
int i; char c;
+tie(i, c) = std::make_pair(1, 'a');
+ignore 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:
+
+char c;
+tie(ignore, c) = std::make_pair(1, 'a');
+
+The global operator<< has been overloaded for std::ostream such that tuples are
+output by recursively calling operator<< for each element.
+
+Analogously, the global operator>> has been overloaded to extract tuples from std::istream by recursively calling operator>> for each element.
+
+The default delimiter between the elements is space, and the tuple is enclosed +in parenthesis. +For Example: + +
tuple<float, int, std::string> a(1.0f, 2, std::string("Howdy folks!");
+
+cout << a;
+(1.0 2 Howdy folks!)
+
+
++The library defines three manipulators for changing the default +behaviour: +
set_open(char) defines the character that is output before the first
+element.set_close(char) defines the character that is output after the
+last element.set_delimiter(char) defines the delimiter charcter between
+elements.cout << set_open('[') << set_close(']') << set_delimiter(',') << a;
+a as: [1.0,2,Howdy folks!]
+
+
+The same manipulators work with operator>> and istream as well. Suppose the cin stream contains the following data:
+
+
(1 2 3) [4:5]tuple<int, int, int> i;
+tuple<int, int> j;
+
+cin >> i;
+cin >> set_open('[') >> set_close(']') >> set_delimiter(':');
+cin >> j;
+i and j.
+
+
+
+Note that extracting tuples with std::string or C-style string
+elements does not generally work, since the streamed tuple representation may not be unambiguously parseable.
+
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();
+tuple<A, B, C> t(A(), B(), C());
+t.get<0>(); t.get<1>(); t.get<2>();
+
+Depending on the optimizing ablity of the compiler, the tier mechanism may have a small performance penalty compared to using nonconst reference parameters as a mechanism for returning multiple values from a function.
+For example, suppose that the following functions f1 and f2 have equivalent functionalities:
+
+
void f1(int&, double&);
+tuple<int, double> f2();
+int i; double d;
+ ...
+f1(i,d); // #1
+tie(i,d) = f2(); // #2
+
+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 hand_made_tuple class above.
+However, as a realistic program is likely to contain a lot of code in addition to tuple definitions, the difference is probably unnoticeable.
+Compile time increases between 5 to 10 percentages were measured for programs which used tuples very frequently.
+With the same test programs, memory consumption of compiling increased between 22% to 27%. See
+[1,
+2]
+for details.
+
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: +
+| Compiler | Problems |
| gcc 2.95 | - |
| edg 2.44 | - |
| Borland 5.5 | Can't use function pointers or member pointers as tuple elements |
| Metrowerks 6.2 | Can't use ref and cref wrappers |
| MS Visual C++ | No reference elements (tie still works). Can't use ref and cref wrappers |
+[1] +Järvi J.: Tuples and multiple return values in C++, TUCS Technical Report No 249, 1999 (http://www.tucs.fi/publications). +
+ ++[2] +Järvi J.: ML-Style Tuple Assignment in Standard C++ - Extending the Multiple Return Value Formalism, TUCS Technical Report No 267, 1999 (http://www.tucs.fi/publications). +
+ ++[3] Järvi J.:Tuple Types and Multiple Return Values, C/C++ Users Journal, August 2001. +
+ +Last modified 2001-08-10
+ +© Copyright Jaakko Järvi 2001. + +Permission to copy, use, modify, sell and distribute this software and its documentation is granted provided this copyright notice appears in all copies. +This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +
+ + + + + + diff --git a/src/tuple.cpp b/src/tuple.cpp new file mode 100644 index 0000000..94f0ccc --- /dev/null +++ b/src/tuple.cpp @@ -0,0 +1,33 @@ +// tuple.cpp ----------------------------------------------------- + +// Copyright (C) 1999, 2000, 2001 Jaakko Järvi (jaakko.jarvi@cs.utu.fi) +// Copyright (C) 2001 Gary Powell (gary.powell@sierra.com) +// +// Permission to copy, use, sell and distribute this software is granted +// provided this copyright notice appears in all copies. +// Permission to modify the code and to distribute modified code is granted +// provided this copyright notice appears in all copies, and a notice +// that the code was modified is included with the copyright notice. +// +// This software is provided "as is" without express or implied warranty, +// and with no claim as to its suitability for any purpose. + +// For more information, see http://lambda.cs.utu.fi + +// Revision History + +// 16 02 01 Initial Version (GWP) +// ----------------------------------------------------------------- + +#include "boost/tuple/tuple_io.hpp" + +namespace boost { +namespace detail { +namespace tuples { +const int + format_info::stream_index[number_of_manipulators] + = { std::ios::xalloc(), std::ios::xalloc(), std::ios::xalloc() }; + +} // namespace tuples +} // namespace detail +} // namespace boost diff --git a/test/README b/test/README new file mode 100644 index 0000000..7a5c441 --- /dev/null +++ b/test/README @@ -0,0 +1,14 @@ +To compile the + +libs/tuple/test/*.cpp + +files, you need to set include paths +for boost. +For example, in libs/tuple/test directory you would type (using g++): + +g++ -I../../.. tuple_test_bench.cpp + +If you want to use tuple_io, you need to compile and link src/tuple.cpp: + +g++ -I../../.. ../src/tuple.cpp io_test.cpp + diff --git a/test/another_tuple_test_bench.cpp b/test/another_tuple_test_bench.cpp new file mode 100644 index 0000000..0f58ddf --- /dev/null +++ b/test/another_tuple_test_bench.cpp @@ -0,0 +1,163 @@ +// tuple_test_bench.cpp -------------------------------- +// +// Defining any of E1 to E5 or E7 to E11 opens some illegal code that +// should cause the compliation to fail. + +#define BOOST_INCLUDE_MAIN // for testing, include rather than link +#include