Reintroduced tuples subnamespace, documents now reflect that change

[SVN r11119]

doc/design_decisions_rationale.html

@@ -12,42 +12,63 @@
 <h2>About namespaces</h2>
 
 <p>
-There was a discussion about whether tuples should be in a separate namespace or directly at the <code>boost</code> namespace.
+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
-sub-namespace, while utility like libraries directly in the <code>boost</code> namespace.
+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. 
-As a result of the discussion, tuple definitions are now directly under the <code>boost</code> namespace.
+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):
+<code><pre>namespace boost {
+  namespace tuples {
+      ...      
+    // All library code
+      ...
+  }
+  using tuples::tuple; 
+  using tuples::make_tuple;
+  using tuples::tie;
+  using tuples::get;
+}
+</pre></code>
+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&lt;N&gt;</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>
-Note! The following discussion is not relevant for the Tuple library, as the 'no
-sub-namespace' decision was taken, but it may be useful for other library writers.
-</p>
-<p>
-In the original tuple library submission, all names were under the namespace <code>tuples</code>. This brought up the issue of naming
-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. 
+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.
-One solution proposed to the dilemma of introducing a sub-namespace or not was as follows: use a
-sub-namespace but lift the most common names to the <code>boost</code> namespace with using declarations. 
-Both gcc and edg compilers rejected such using declarations if the namespace and class names were identical:
+Both gcc and edg compilers reject using declarations where the namespace and class names are identical:
 
 <code><pre>namespace boost {
   namespace tuple {
-    class cons;
+    ... tie(...);
     class tuple; 
 &nbsp;     ...
   }
-  using tuple::cons; // ok
+  using tuple::tie; // ok
   using tuple::tuple; // error
     ...
 }
 </pre></code>
 
-
-Note, however, that a corresponding using declaration in the global namespace seemed to be ok: 
+Note, however, that a corresponding using declaration in the global namespace seems to be ok: 
 
 <code><pre>
 using boost::tuple::tuple; // ok;

doc/tuple_advanced_interface.html

@@ -12,17 +12,18 @@
   <body>
     <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. 
 
-<code><pre>tuple_element&lt;N, T&gt;::type</pre></code>
+<code><pre>element&lt;N, T&gt;::type</pre></code>
 
 gives the type of the <code>N</code>th element in the tuple type <code>T</code>.
 </p>
 
-<code><pre>tuple_length&lt;T&gt;::value</pre></code>
+<code><pre>length&lt;T&gt;::value</pre></code>
 
 gives the length of the tuple type <code>T</code>.
 </p>
@@ -82,7 +83,7 @@ A cons list can be default constructed provided that all its elements can be def
 </p>
 <p>
 A cons list can be constructed from its head and tail. The prototype of the constructor is:
-<pre><code>cons(typename tuple_access_traits&lt;head_type&gt;::parameter_type h,
+<pre><code>cons(typename access_traits&lt;head_type&gt;::parameter_type h,
      const tail_type&amp; t)
 </code></pre>
 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).
@@ -94,13 +95,13 @@ For a one-element cons list the tail argument (<code>null_type</code>) can be om
 
 <h2>Traits classes for tuple element types</h2>
 
-<h4><code>tuple_access_traits</code></h4>
+<h4><code>access_traits</code></h4>
 <p>
-The template <code>tuple_access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:
+The template <code>access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:
 <ol>
-<li><code>tuple_access_traits&lt;T&gt;::type</code> maps <code>T</code> to the return type of the non-const access functions (nonmeber and member <code>get</code> functions, and the <code>get_head</code> function).</li>
-<li><code>tuple_access_traits&lt;T&gt;::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
-<li><code>tuple_access_traits&lt;T&gt;::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
+<li><code>access_traits&lt;T&gt;::type</code> maps <code>T</code> to the return type of the non-const access functions (nonmeber and member <code>get</code> functions, and the <code>get_head</code> function).</li>
+<li><code>access_traits&lt;T&gt;::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
+<li><code>access_traits&lt;T&gt;::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
 </ol>
 <h4><code>make_tuple_traits</code></h4>
 
@@ -120,7 +121,8 @@ The type function call <code>make_tuple_traits&lt;T&gt;::type</code> implements
 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>Note, that the <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate hpp-file <code>reference_wrappers.hpp</code>, which can be included without including the rest of the tuple library.
+<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>

doc/tuple_users_guide.html

@@ -67,7 +67,7 @@ and add the <code>libs/tuple/src/tuple.hpp</code> file to your project.
 
 Both <code>tuple_io.hpp</code> and <code>tuple_comparison.hpp</code> include <code>tuple.hpp</code>.
 
-<p>All definitions are in namespace <code>boost</code>.
+<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.
 
 <h2><a name = "tuple_types">Tuple types</a></h2>
 
@@ -252,6 +252,10 @@ A aa = get&lt;3&gt;(t);     // error: index out of bounds
 ++get&lt;0&gt;(t);  // ok, can be used as any variable
 </code></pre>
 
+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&lt;N&gt;(a_tuple)</code> when writing code that shoud compile with MSVC++ 6.0.
+
 <h2><a name = "construction_and_assignment">Copy construction and tuple assignment</a></h2>
 
 <p>
@@ -343,10 +347,10 @@ tie(i, c) = std::make_pair(1, 'a');
 </code></pre>
 <h4>Ignore</h4>
 There is also an object called <code>ignore</code> which allows you to ignore an element assigned by a tuple.
-The idea is that a function may return a tuple, only part of which you are interested in. For example:
+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):
 
 <pre><code>char c;
-tie(ignore, c) = std::make_pair(1, 'a');
+tie(tuples::ignore, c) = std::make_pair(1, 'a');
 </code></pre>
 
 <h2><a name = "streaming">Streaming</a></h2>
@@ -382,8 +386,9 @@ last element.</li>
 elements.</li>
 </ul>
 
+Note, that these manipulators are defined in the <code>tuples</code> subnamespace. 
 For example:
-<code><pre>cout &lt;&lt; set_open('[') &lt;&lt; set_close(']') &lt;&lt; set_delimiter(',') &lt;&lt; a; 
+<code><pre>cout &lt;&lt; tuples::set_open('[') &lt;&lt; tuples::set_close(']') &lt;&lt; tuples::set_delimiter(',') &lt;&lt; a; 
 </code></pre>
 outputs the same tuple <code>a</code> as: <code>[1.0,2,Howdy folks!]</code>
 
@@ -397,7 +402,7 @@ The code:
 tuple&lt;int, int&gt; j;
 
 cin &gt;&gt; i;
-cin &gt;&gt; set_open('[') &gt;&gt; set_close(']') &gt;&gt; set_delimiter(':');
+cin &gt;&gt; tuples::set_open('[') &gt;&gt; tuples::set_close(']') &gt;&gt; tules::set_delimiter(':');
 cin &gt;&gt; j;
 </code></pre>
 
@@ -506,7 +511,7 @@ J&auml;rvi J.: <i>ML-Style Tuple Assignment in Standard C++ - Extending the Mult
 
 <hr>
 
-<p>Last modified 2001-08-10</p>
+<p>Last modified 2001-09-13</p>
 
 <p>&copy; Copyright <a href="../../../people/jaakko_jarvi.htm"> Jaakko J&auml;rvi</a> 2001.