From 2764718489a2caac5c2237c7bb28d2bf298262c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaakko=20J=C3=A4rvi?= Date: Fri, 14 Sep 2001 07:54:33 +0000 Subject: [PATCH] Reintroduced tuples subnamespace, documents now reflect that change [SVN r11119] --- doc/design_decisions_rationale.html | 55 ++++++++++++++++++++--------- doc/tuple_advanced_interface.html | 20 ++++++----- doc/tuple_users_guide.html | 17 +++++---- 3 files changed, 60 insertions(+), 32 deletions(-) diff --git a/doc/design_decisions_rationale.html b/doc/design_decisions_rationale.html index 7c8ba68..cde921e 100644 --- a/doc/design_decisions_rationale.html +++ b/doc/design_decisions_rationale.html @@ -12,42 +12,63 @@

About namespaces

-There was a discussion about whether tuples should be in a separate namespace or directly at the boost namespace. +There was a discussion about whether tuples should be in a separate namespace or 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. +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. +Tuples were originally under a subnamespace. +As a result of the discussion, tuple definitions were moved directly under the boost 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 ::boost::tuples, and the most common names in the ::boost namespace as well. +This is accomplished with using declarations (suggested by Dave Abrahams): +

namespace boost {
+  namespace tuples {
+      ...      
+    // All library code
+      ...
+  }
+  using tuples::tuple; 
+  using tuples::make_tuple;
+  using tuples::tie;
+  using tuples::get;
+}
+
+With this arrangement, tuple creation with direct constructor calls, make_tuple or tie functions do not need the namespace qualifier. +Further, all functions that manipulate tuples are found with Koenig-lookup. +The only exceptions are the get<N> functions, which are always called with an explicitly qualified template argument, and thus Koenig-lookup does not apply. +Therefore, get is lifted to ::boost namespace with a using declaration. +Hence, the interface for an application programmer is in practice under the namespace ::boost. +

+The other names, forming an interface for library writers (cons lists, metafunctions manipulating cons lists, ...) remain in the subnamespace ::boost::tuples. +Note, that the names ignore, set_open, set_close and set_delimiter are considered to be part of the application programmer's interface, but are still not under boost namespace. +The reason being the danger for name clashes for these common names. +Further, the usage of these features is probably not very frequent. +

For those who are really interested in namespaces

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

namespace boost {
   namespace tuple {
-    class cons;
+    ... tie(...);
     class tuple; 
       ...
   }
-  using tuple::cons; // ok
+  using tuple::tie; // ok
   using tuple::tuple; // error
     ...
 }
- -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: 
 using boost::tuple::tuple; // ok;
diff --git a/doc/tuple_advanced_interface.html b/doc/tuple_advanced_interface.html
index 55b6966..1b9df5a 100644
--- a/doc/tuple_advanced_interface.html
+++ b/doc/tuple_advanced_interface.html
@@ -12,17 +12,18 @@
   
     
Tuple library advanced features

 
+The advanced features described in this document are all under namespace ::boost::tuples
 
 
Metafunctions for tuple types

 

 Suppose T is a tuple type, and N is a constant integral expression. 
 
-
tuple_element<N, T>::type

+
element<N, T>::type

 
 gives the type of the Nth element in the tuple type T.
 

 
-
tuple_length<T>::value

+
length<T>::value

 
 gives the length of the tuple type T.
 

@@ -82,7 +83,7 @@ A cons list can be default constructed provided that all its elements can be def
 

 

 A cons list can be constructed from its head and tail. The prototype of the constructor is:
-
cons(typename tuple_access_traits<head_type>::parameter_type h,
+
cons(typename access_traits<head_type>::parameter_type h,
      const tail_type& t)
 

 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 (null_type) can be om
 
 
Traits classes for tuple element types

 
-
tuple_access_traits

+
access_traits

 

-The template tuple_access_traits defines three type functions. Let T be a type of an element in a tuple:
+The template access_traits defines three type functions. Let T be a type of an element in a tuple:
 
    
-
  1. 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).
    2. 
-
  2. tuple_access_traits<T>::const_type maps T to the return type of the const access functions.
    3. 
-
  3. tuple_access_traits<T>::parameter_type maps T to the parameter type of the tuple constructor.
    4. 
+
  4. 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).
    5. 
+
  5. access_traits<T>::const_type maps T to the return type of the const access functions.
    6. 
+
  6. access_traits<T>::parameter_type maps T to the parameter type of the tuple constructor.
    7. 
 

 
make_tuple_traits

 
@@ -120,7 +121,8 @@ The type function call make_tuple_traits<T>::type implements
 Objects of type 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.
+
Reference wrappers were originally part of the tuple library, but they are now a general utility of boost. 
+The reference_wrapper template and the ref and cref functions are defined in a separate file ref.hpp in the main boost include directory; and directly in the boost namespace.
 

 
 Back to the user's guide
diff --git a/doc/tuple_users_guide.html b/doc/tuple_users_guide.html
index 4d0d4eb..21d396a 100644
--- a/doc/tuple_users_guide.html
+++ b/doc/tuple_users_guide.html
@@ -67,7 +67,7 @@ and add the 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.
+
All definitions are in namespace ::boost::tuples, but the most common names are lifted to namespace ::boost with using declarations. These names are: tuple, make_tuple, tie and get. Further, ref and cref are defined directly under the ::boost namespace.
 
 
Tuple types

 
@@ -252,6 +252,10 @@ A aa = get<3>(t);     // error: index out of bounds
 ++get<0>(t);  // ok, can be used as any variable
 

 
+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 get calls should be qualified as: tuples::get<N>(a_tuple) when writing code that shoud compile with MSVC++ 6.0.
+
 
Copy construction and tuple assignment

 
 

@@ -343,10 +347,10 @@ 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: +The idea is that a function may return a tuple, only part of which you are interested in. For example (note, that ignore is under the tuples subnamespace): 
char c;
-tie(ignore, c) = std::make_pair(1, 'a');
+tie(tuples::ignore, c) = std::make_pair(1, 'a');

Streaming

@@ -382,8 +386,9 @@ last element. elements. +Note, that these manipulators are defined in the tuples subnamespace. For example: -
cout << set_open('[') << set_close(']') << set_delimiter(',') << a; 
+
cout << tuples::set_open('[') << tuples::set_close(']') << tuples::set_delimiter(',') << a; 
 

 outputs the same tuple a as: [1.0,2,Howdy folks!]
 
@@ -397,7 +402,7 @@ The code:
 tuple<int, int> j;
 
 cin >> i;
-cin >> set_open('[') >> set_close(']') >> set_delimiter(':');
+cin >> tuples::set_open('[') >> tuples::set_close(']') >> tules::set_delimiter(':');
 cin >> j;
@@ -506,7 +511,7 @@ Järvi J.: ML-Style Tuple Assignment in Standard C++ - Extending the Mult
-

Last modified 2001-08-10

+

Last modified 2001-09-13

© Copyright Jaakko Järvi 2001.