added cursor feature (including tests) and updated documentation

[SVN r8367]

test/comprehensive.cpp

@@ -10,6 +10,7 @@
 #include <stdio.h> // used for portability on broken compilers
 #include <math.h>  // for pow()
 #include <boost/rational.hpp>
+#include <list>
 
 namespace bpl_test {
 
@@ -1009,6 +1010,15 @@ void init_module(boost::python::module_builder& m)
     // export non-operator function as heterogeneous reverse-argument operator
     int_class.def(&rmul, "__rmul__");
     
+    // wrap an STL conforming container
+    boost::python::class_builder<std::list<Int> > intlist_class(m, "IntList");
+
+    intlist_class.def(boost::python::constructor<>());
+    intlist_class.def((void (std::list<Int>::*)(Int const &))
+                             &std::list<Int>::push_back, "append");
+    
+    // wrap the iterator of an STL conforming container in a cursor
+    m.def_cursor_for(intlist_class);
 
     boost::python::class_builder<EnumOwner> enum_owner(m, "EnumOwner");
     enum_owner.def(boost::python::constructor<EnumOwner::enum_type, const EnumOwner::enum_type&>());

test/comprehensive.py

@@ -1029,6 +1029,30 @@ Test operator export to a subclass
     >>> j.i()
     15
 
+========= Test creation of a cursor for an STL conforming container ==========
+
+    >>> i1 = Int(1)
+    >>> i2 = Int(2)
+    >>> i3 = Int(3)
+    >>> l = IntList()
+    >>> l.append(i1)
+    >>> l.append(i2)
+    >>> l.append(i3)
+    >>> for i in l.cursor():
+    ...     print i.i()
+    1
+    2
+    3
+
+test that cursor keeps a reference to its container
+
+    >>> c = l.cursor()
+    >>> del l
+    >>> for i in c:
+    ...     print i.i()
+    1
+    2
+    3
 
 ========= Prove that the "phantom base class" issue is resolved ==========