From 00688f9a4ac8ec3c5f679f9b216a9c3c3a6e840b Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Fri, 10 Aug 2001 16:03:01 +0000 Subject: [PATCH] Minor spelling fixes, add author link [SVN r10834] --- doc/design_decisions_rationale.html | 26 ++++--- doc/tuple_users_guide.html | 110 ++++++++++++---------------- 2 files changed, 59 insertions(+), 77 deletions(-) diff --git a/doc/design_decisions_rationale.html b/doc/design_decisions_rationale.html index 8fbab7a..7c8ba68 100644 --- a/doc/design_decisions_rationale.html +++ b/doc/design_decisions_rationale.html @@ -13,7 +13,8 @@

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. +The common principle is that domain libraries (like graph, python) should be on a separate +sub-namespace, 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.

@@ -21,20 +22,23 @@ As a result of the discussion, tuple definitions are now directly under the For those who are really interested in namespaces

-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.

-In the original tuple library submission, all names were under the namespace tuples. This brought up the issue of naming subnamespaces. +In the original tuple library submission, all names were under the namespace tuples. 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 boost 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 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
@@ -50,7 +54,7 @@ using boost::tuple::tuple; // ok;
-

The endmark of the cons list (nil, null_type, ...)

+

The end mark of the cons list (nil, null_type, ...)

Tuples are internally represented as cons lists: @@ -63,7 +67,6 @@ inherits from 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.

@@ -78,11 +81,10 @@ Whether to use 0- or 1-based indexing was discussed more than thoroughly, and th
  • 1-based 'name like' indexing exists as well, eg. bind1st, bind2nd, pair::first, etc.
    • Tuple access with the syntax 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: +By suitably chosen constant types, this would allow alternative syntaxes: 

    a.get<0>() == a.get(_1st) == a[_1st] == a(_1st);
    @@ -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: -

    Back to the user's guide

    © Copyright Jaakko Järvi 2001. diff --git a/doc/tuple_users_guide.html b/doc/tuple_users_guide.html index 56204da..87f2983 100644 --- a/doc/tuple_users_guide.html +++ b/doc/tuple_users_guide.html @@ -55,18 +55,15 @@ To compensate for this "deficiency", the Boost Tuple Library implement

    To use the library, just include: -

    #include "boost/tuple/tuple.hpp"
    -

    +
    #include "boost/tuple/tuple.hpp"

    Comparison operators can be included with: -

    #include "boost/tuple/tuple_comparison.hpp"
    -

    +
    #include "boost/tuple/tuple_comparison.hpp"

    To use tuple input and output operators, -

    #include "boost/tuple/tuple_io.hpp"
    +
    #include "boost/tuple/tuple_io.hpp"
    and add the libs/tuple/src/tuple.hpp file to your project. -

    Both tuple_io.hpp and tuple_comparison.hpp include tuple.hpp. @@ -91,13 +88,11 @@ For example, the following definitions are valid tuple instantiations (Atuple<int> tuple<double&, const double&, const double, double*, const double*> -tuple<A, int(*)(char, int), B(A::*)(C&), C> +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 { 
@@ -111,7 +106,6 @@ tuple<char[10]> // not allowed: arrays cannot be copied
    Note however that tuple<Y&> and tuple<char(&)[10]> are valid instantiations. -

    Constructing tuples

    @@ -124,7 +118,6 @@ For example: 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). @@ -137,24 +130,23 @@ public: }; tuple<X,X,X>() // error: no default constructor for X -tuple<X,X,X>(string("Jaba"), string("Daba"), string("Duu")) // ok +tuple<X,X,X>(string("Jaba"), string("Daba"), string("Duu")) // ok -In particular, reference types do not have a default initialisation: +In particular, reference types do not have a default initialization: 

    tuple<double&>()                // error: reference must be 
-                                // initialised explicitly
+                                // initialized explicitly
 
 double d = 5; 
 tuple<double&>(d)               // ok
 
-tuple<double&>(d+3.14)          // error: cannot initialise 
+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
    -

    In sum, the tuple construction is semantically just a group of individual elementary constructions.

    @@ -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)); } -

    -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: 

    void foo(const A& a, B& b) { 
   ...
   make_tuple(a, b);
    The 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. +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: 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). @@ -194,33 +185,30 @@ 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");
+
    make_tuple("Donald", "Daisy");
 
    
 
 This creates an object of type 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.
-
    
+However, to get make_tuple to create a tuple with an element of a
+non-const array type one must use the ref wrapper.
 
 
    
-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 make_tuple (a const qualified function type would result, which is illegal):
 
    void f(int i);
   ...
-make_tuple(&f); // tuple<void (*)(int)>
+make_tuple(&f); // tuple<void (*)(int)>
   ...
 tuple<tuple<void (&)(int)> > a(f) // ok
 make_tuple(f);                    // not ok
 
    
 
-
    
-
 
    Accessing tuple elements
    
 
 
    
@@ -232,7 +220,8 @@ or
 
    get<N>(t)
 
    
 where 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.
+Depending on whether t is const or not, get returns the Nth element as a reference to const or
+non-const 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:
@@ -253,7 +242,6 @@ A aa = get<3>(t);     // error: index out of bounds
   ...
 ++get<0>(t);  // ok, can be used as any variable
    -

    Copy construction and tuple assignment

    @@ -272,15 +260,13 @@ tuple<int, A*, C, C> a(t); // ok a = t; // ok -In both cases, the conversions performed are: char -> int, B* -> A* (derived class pointer to base class pointer), B -> C (a user defined conversion) and D -> C (a user defined conversion). -

    +In both cases, the conversions performed are: 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');
    -

    Relational operators

    @@ -297,33 +283,31 @@ The operators <, >, <= and >= implement a lexico

    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.

    +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());
+
    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; }
+bool operator==(A, A) { std::cout << "All the same to me..."; return true; }
 
 t1 == t2; 		// true
-t1 == t3;               // false, does not print "All the..."
+t1 == t3;               // false, does not print "All the..."
 
    
-
    
 
 
 
    Tiers
    
 
 
    
-Tiers are tuples, where all elements are of nonconst reference types.
+Tiers are tuples, where all elements are of non-const 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&>. 
@@ -331,17 +315,16 @@ The same result could be achieved with the call make_tuple(ref(i), ref(c),
 
    
 
 
    
-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.:
 
 
    int i; char c; double d; 
 tie(i, c, d) = make_tuple(1,'a', 5.5);
-std::cout << i << " " <<  c << " " << d;
+std::cout << i << " " <<  c << " " << d;
 
    
 This code prints 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:
@@ -349,7 +332,6 @@ The tying mechanism works with std::pair templates as well:
 
    int i; char c;
 tie(i, c) = std::make_pair(1, 'a');
 
    
-
    
 
    Ignore
    
 There is also an object called 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:
@@ -374,30 +356,27 @@ 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!");
+
    tuple<float, int, std::string> a(1.0f,  2, std::string("Howdy folks!");
 
-cout << a; 
+cout << a; 
 
    
 outputs the tuple as: (1.0 2 Howdy folks!)
-
    
 
 
    
-The library defines three manipulators for changing the default
-behaviour:
+The library defines three manipulators for changing the default behavior:
 
      
 
    • 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
+
    • set_delimiter(char) defines the delimiter character between
 elements.
      • 
 
    
 
 For example:
-
    cout << set_open('[') << set_close(']') << set_delimiter(',') << a; 
+
    cout << set_open('[') << set_close(']') << set_delimiter(',') << a; 
 
    
 outputs the same tuple 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:
 
@@ -408,17 +387,17 @@ The code:
 
    tuple<int, int, int> i;
 tuple<int, int> j;
 
-cin >> i;
-cin >> set_open('[') >> set_close(']') >> set_delimiter(':');
-cin >> j;
+cin >> i;
+cin >> set_open('[') >> set_close(']') >> set_delimiter(':');
+cin >> j;
 
    
 
 reads the data into the tuples 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.
+elements does not generally work, since the streamed tuple representation may not be unambiguously
+parseable.
 
    
 
 
    Performance
    
@@ -445,13 +424,13 @@ and this code:
 
    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. 
+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 f1 and f2 have equivalent functionalities:
 
-
    void f1(int&, double&);
+
    void f1(int&, double&);
 tuple<int, double> f2();
 
    
 
@@ -496,7 +475,8 @@ Below is a list of compilers and known problems with each compiler:
 
 
    Acknowledgements
    
 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.
 
 
    References
    
@@ -519,7 +499,7 @@ Järvi J.: ML-Style Tuple Assignment in Standard C++ - Extending the Mult
 
 
    Last modified 2001-08-10
    
 
-
    © Copyright Jaakko Järvi 2001. 
+
    © 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.