From 0d1efb61e23d84f08e1a625c35970ffce1f85074 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sun, 29 Sep 2002 19:06:13 +0000 Subject: [PATCH] doc update [SVN r15556] --- doc/v2/call_method.html | 2 +- doc/v2/copy_const_reference.html | 2 +- doc/v2/copy_non_const_reference.html | 2 +- doc/v2/data_members.html | 2 +- doc/v2/has_back_reference.html | 2 +- doc/v2/implicit.html | 2 +- doc/v2/iterator.html | 407 +++++++++++++++------------ 7 files changed, 226 insertions(+), 193 deletions(-) diff --git a/doc/v2/call_method.html b/doc/v2/call_method.html index 3aae0e35..5323ab07 100644 --- a/doc/v2/call_method.html +++ b/doc/v2/call_method.html @@ -85,7 +85,7 @@ R call_method(PyObject* self, char const* method, A1 const&, A2 const&,

C++ Module Definition

-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/class.hpp>
 #include <boost/utility.hpp>
 #include <cstring>
diff --git a/doc/v2/copy_const_reference.html b/doc/v2/copy_const_reference.html
index e8d02503..41a9b9ab 100644
--- a/doc/v2/copy_const_reference.html
+++ b/doc/v2/copy_const_reference.html
@@ -98,7 +98,7 @@ template <class T> struct apply
 
     
C++ Module Definition

 
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/class.hpp>
 #include <boost/python/copy_const_reference.hpp>
 #include <boost/python/return_value_policy.hpp>
diff --git a/doc/v2/copy_non_const_reference.html b/doc/v2/copy_non_const_reference.html
index 8f427016..0169fff1 100644
--- a/doc/v2/copy_non_const_reference.html
+++ b/doc/v2/copy_non_const_reference.html
@@ -99,7 +99,7 @@ template <class T> struct apply
 
     
C++ code:

 
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/class.hpp>
 #include <boost/python/copy_non_const_reference.hpp>
 #include <boost/python/return_value_policy.hpp>
diff --git a/doc/v2/data_members.html b/doc/v2/data_members.html
index 5ec6ff01..eabf8183 100644
--- a/doc/v2/data_members.html
+++ b/doc/v2/data_members.html
@@ -115,7 +115,7 @@ template <class C, class D, class Policies>
     member as functions:

 
 #include <boost/python/data_members.hpp>
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/class.hpp>
 
 struct X
diff --git a/doc/v2/has_back_reference.html b/doc/v2/has_back_reference.html
index c6d752dc..ed8b0342 100644
--- a/doc/v2/has_back_reference.html
+++ b/doc/v2/has_back_reference.html
@@ -111,7 +111,7 @@ namespace boost { namespace python
     
C++ module definition

 
 #include <boost/python/class.hpp>
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/has_back_reference.hpp>
 #include <boost/python/handle.hpp>
 #include <boost/shared_ptr.hpp>
diff --git a/doc/v2/implicit.html b/doc/v2/implicit.html
index 8b934691..03832566 100644
--- a/doc/v2/implicit.html
+++ b/doc/v2/implicit.html
@@ -103,7 +103,7 @@ void implicitly_convertible();
 
 #include <boost/python/class.hpp>
 #include <boost/python/implicit.hpp>
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 
 using namespace boost::python;
 
diff --git a/doc/v2/iterator.html b/doc/v2/iterator.html
index 1e367cce..3388d913 100644
--- a/doc/v2/iterator.html
+++ b/doc/v2/iterator.html
@@ -1,216 +1,239 @@
 
-    
+
+
+  
+    
     
     
 
     Boost.Python - <boost/python/iterator.hpp>
+  
 
+  
     
+      

       

         
-          
-

+          
C++ Boost

+        		
 
         
           
Boost.Python

 
           
Header <boost/python/iterator.hpp>

+        

     

     

 
     
Contents

 
     

-      
Introduction
+      
Introduction

 
-      
Classes
+      
Classes

 
       

         

-          
Class template iterator
+          
Class template
+          iterator

 
           

             

               
Class
-              iterator synopsis
+              iterator synopsis

 
-              
Class template iterator
-              constructor
+              
Class template
+              iterator constructor

             

-         

+          

+        

 
         

-          
Class template iterators
+          
Class template
+          iterators

 
           

             

               
Class
-              iterators synopsis
-              
Class template
-              iterators nested types
-              
Class template
-              iterators static functions
-            

-        

+              iterators synopsis
 
-      
Functions
+              
Class template
+              iterators nested types

+
+              
Class template
+              iterators static functions

+            
+          
+        
+      
+
+      
Functions

 
       

         

-          
range
+          
range

         

+      

 
-      
Examples
+      
Examples

     
     

 
     
Introduction

 
-    
<boost/python/iterator.hpp> provides types
-    and functions for creating Python
-    iterators from C++
-    Containers and <boost/python/iterator.hpp> provides types and
+    functions for creating Python
+    iterators from C++ Containers and Iterators. Note
     that if your class_ supports random-access iterators,
-    implementing 
-    __getitem__
-    (also known as the Sequence Protocol) may serve you better than
-    using this facility: Python will automatically create an iterator
-    type for you (see iter()),
-    and each access can be range-checked, leaving no possiblity of
-    accessing through an invalidated C++ iterator.
+    implementing __getitem__
+    (also known as the Sequence Protocol) may serve you better than using
+    this facility: Python will automatically create an iterator type for you
+    (see iter()),
+    and each access can be range-checked, leaving no possiblity of accessing
+    through an invalidated C++ iterator.

 
     
Classes

 
     
Class Template iterator

 
-    
Instances of iterator<C,P> hold a reference
-    to a callable Python object which, when invoked from Python,
-    expects a single argument c convertible to
-    C and creates a Python iterator that traverses
-    [c.begin(),
-    c.end()). The optional CallPolicies
-    P can be used to control how elements are returned
-    during iteration.
+    
Instances of iterator<C,P> hold a reference to a
+    callable Python object which, when invoked from Python, expects a single
+    argument c convertible to C and creates a
+    Python iterator that traverses [c.begin(),
+    c.end()). The optional CallPolicies P can be used to
+    control how elements are returned during iteration.

 
-    
In the table below, c is an instance of Container.
+    
In the table below, c is an instance of
+    Container.

 
     
-        
 
-        
 
-        
 
-        
+      
-        
 
-        
 
+        
+      
-        
 
-        
 
-        
 
+        
+      

       
Template Parameter
+        Template ParameterRequirements
+        RequirementsSemantics
+        SemanticsDefault
+        Default

 
       
Container 
+        Container[c.begin(),c.end()) is a valid Iterator
-        range.
-
-        The result will convert its argument to
-        c and call
-        c.begin() and c.end() to acquire
-        iterators. To invoke Container's
-        const begin() and end()
-        functions, make it const.
+        [c.begin(),c.end()) is a valid Iterator range.The result will convert its argument to c and call
+        c.begin() and c.end() to acquire iterators.
+        To invoke Container's const
+        begin() and end() functions, make it
+        const.

 
       
NextPolicies 
+        NextPoliciesA default-constructible model of CallPolicies.
+        A default-constructible model of CallPolicies.Applied to the resulting iterators' next() method.
-
-        An unspecified model of CallPolicies
-        which always makes a copy of the
-        result of deferencing the underlying C++ iterator
+        Applied to the resulting iterators' next()
+        method.An unspecified model of CallPolicies which
+        always makes a copy of the result of deferencing the underlying C++
+        iterator

     

 
-    
Class Template iterator synopsis

+    
Class Template iterator
+    synopsis

 
 namespace boost { namespace python
 {
   template <class Container
              , class NextPolicies = unspecified>
-  struct iterator : reference<PyObject*>
+  struct iterator : object
   {
       iterator();
   };
 }}
 

-    
Class Template
-    iterator constructor

 
+    
Class Template iterator
+    constructor

 
 iterator()
 

 
     

-      
Effects: Initializes its base class with the result
-      of:
+      
Effects:

+
+      

+        Initializes its base class with the result of: 
 
 range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end)
 

+      

 
-      
Postconditions: this->get() points to
-      a Python callable object which creates a Python iterator as
-      described above.
+      
Postconditions: this->get() points to a
+      Python callable object which creates a Python iterator as described
+      above.

 
-      
Rationale: Provides an easy way to create iterators
-      for the common case where a C++ class being wrapped provides
-      begin() and end().
+      
Rationale: Provides an easy way to create iterators for the
+      common case where a C++ class being wrapped provides
+      begin() and end().

     

+    
 
-
+    
Class Template
+    iterators

 
-    
Class Template iterators

+    
A utility class template which provides a way to reliably call its
+    argument's begin() and end() member functions.
+    Note that there is no portable way to take the address of a member
+    function of a C++ standard library container, so
+    iterators<> can be particularly helpful when wrapping
+    them.

 
-    
A utility class template which provides a way to reliably call
-    its argument's begin() and end() member
-    functions. Note that there is no portable way to take the address
-    of a member function of a C++ standard library container, so
-    iterators<> can be particularly helpful when
-    wrapping them.
-    
-
-    
In the table below, x is an instance of C.
+    
In the table below, x is an instance of
+    C.

 
     
-        
 
-        
+      
-        
+
+        
+      
-        
 
+        
+      

       
Required Valid Expression
+        Required Valid ExpressionType
+        Type

 
       
x.begin()
-        
-        Convertible to C::const_iterator if C is a
-        const type; convertible to C::iterator otherwise.
+        x.begin()Convertible to C::const_iterator if C
+        is a const type; convertible to C::iterator
+        otherwise.

 
       
x.end()
-        
-        Convertible to C::const_iterator if C is a
-        const type; convertible to C::iterator otherwise.
+        x.end()Convertible to C::const_iterator if C
+        is a const type; convertible to C::iterator
+        otherwise.

     

 
-    
Class Template iterators synopsis

+    
Class Template iterators
+    synopsis

 
 namespace boost { namespace python
 {
@@ -224,141 +247,151 @@ namespace boost { namespace python
 }}
 
 

-    
Class Template
-    iterators nested types

 
-If C is a const type,
+    
Class Template iterators nested
+    types

+    If C is a const type, 
 
 typedef typename C::const_iterator iterator;
 

-Otherwise:
+    Otherwise: 
 
 typedef typename C::iterator iterator;
 

 
-    
Class Template
-    iterators static functions

-
+    
Class Template iterators static
+    functions

 
 static iterator begin(C&);
 

 
     

-      
Returns: x.begin()
+      
Returns: x.begin()

     

-
 
 static iterator end(C&);
 

 
     

-      
Returns: x.end()
+      
Returns: x.end()

     

-
-
+    
 
     
Functions

 
 template <class NextPolicies, class Target, class Accessor1, class Accessor2>
-reference<PyObject*> range(Accessor1 start, Accessor2 finish);
+object range(Accessor1 start, Accessor2 finish);
 
 template <class NextPolicies, class Accessor1, class Accessor2>
-reference<PyObject*> range(Accessor1 start, Accessor2 finish);
+object range(Accessor1 start, Accessor2 finish);
 
 template <class Accessor1, class Accessor2>
-reference<PyObject*> range(Accessor1 start, Accessor2 finish);
+object range(Accessor1 start, Accessor2 finish);
 

 
     

       
Requires: NextPolicies is a
-        default-constructible model of CallPolicies.
+      default-constructible model of CallPolicies.

 
-      
Effects: 

+      
Effects:

 
-The first form creates a Python callable
-      object which, when invoked, converts its argument to a
-      Target object
-      x, and creates a Python iterator which traverses
-       [bind(start,_1)(x), bind(finish,_1)(x)),
-       applying NextPolicies to the iterator's
-       next() function. 
-

-       
The second form is identical to
-       the first, except that Target is deduced from
-       Accessor1 as follows:
-       
    
-       
  1. If Accessor1 is a function type,
-       Target is the type of its first argument.
-       
  2. If Accessor1 is a data member pointer of the
-       form R (T::*), Target is
-       identical to T.
-       
  3. If Accessor1 is a member function pointer of
-       the form
-       R (T::*)(arguments...) cv-opt,
-       where cv-opt is an optional cv-qualifier,
-       Target is identical to T.
-        

-

+      

+        

+          
The first form creates a Python callable object which, when
+          invoked, converts its argument to a Target object
+          x, and creates a Python iterator which traverses
+          [bind(start,_1)(x), bind(finish,_1)(x)),
+          applying NextPolicies to the iterator's
+          next() function.

 
-       
The third form is identical to the second, except that
-       NextPolicies is an unspecified model of CallPolicies
-        which always makes a copy of the
-        result of deferencing the underlying C++ iterator

-

+          
The second form is identical to the first, except that
+          Target is deduced from Accessor1 as
+          follows:

 
+          

+            
    
+              
  1. If Accessor1 is a function type,
+              Target is the type of its first argument.
    2. 
 
-      
    Rationale: The use of boost::bind() allows
-      C++ iterators to be accessed through functions, member functions
-      or data member pointers. Customization of
-      NextPolicies (e.g. using return_internal_reference) is useful when it is
-      expensive to copy sequence elements of a wrapped class
-      type. Customization of Target is useful when
-      Accessor1 is a function object, or when a base
-      class of the intended target type would otherwise be deduced.
+              
  2. If Accessor1 is a data member pointer of the
+              form R (T::*), Target is
+              identical to T.
    3. 
+
+              
  3. If Accessor1 is a member function pointer of
+              the form
+              R (T::*)(arguments...) 
+              cv-opt, where cv-opt is an optional
+              cv-qualifier, Target is identical to
+              T.
    4. 
+            

+          

+
+          
The third form is identical to the second, except that
+          NextPolicies is an unspecified model of CallPolicies which
+          always makes a copy of the result of deferencing the underlying C++
+          iterator

+        

+      
+
+      
Rationale: The use of boost::bind() allows C++ iterators
+      to be accessed through functions, member functions or data member
+      pointers. Customization of NextPolicies (e.g. using
+      return_internal_reference)
+      is useful when it is expensive to copy sequence elements of a wrapped
+      class type. Customization of Target is useful when
+      Accessor1 is a function object, or when a base class of
+      the intended target type would otherwise be deduced.

     

 
     
Examples

-
 
-#include <boost/python/module.hpp>
+#include <boost/python/module_init.hpp>
 #include <boost/python/class.hpp>
-#include <boost/python/return_internal_reference.hpp>
+
 #include <vector>
 
 using namespace boost::python;
 BOOST_PYTHON_MODULE_INIT(demo)
 {
-   module("demo")
-      .add(
-         class_<std::vector<double> >("dvec")
-            .def("__iter__", iterator<std::vector<double> >())
-            ...
-         )
-      ;
+    class_<std::vector<double> >("dvec")
+        .def("__iter__", iterator<std::vector<double> >())
+        ;
 }
 

+    A more comprehensive example can be found in: 
 
-A more comprehensive example can be found in:
-

-
libs/python/test/iterator.cpp

-
libs/python/test/input_iterator.cpp

-
libs/python/test/input_iterator.py

-
+    

+      
libs/python/test/iterator.cpp

 
-    
Revised 
-    
-     17 May, 2002
-    
+      
libs/python/test/input_iterator.cpp

 
+      
libs/python/test/input_iterator.py

 
-    
© Copyright Dave
-    Abrahams 2002. All Rights Reserved.
+      

+        
Revised 
+        
+         29 September, 2002 
+        
+        

+
+        
© Copyright Dave Abrahams 2002. All
+        Rights Reserved.

+      

+    

+  
+