cleanup

BGL/doc/BGL/PackageDescription.txt

@@ -119,17 +119,23 @@ user might encounter.
 - `CGAL::HalfedgeDS_face_max_base_with_id`
 - `CGAL::Polyhedron_items_with_id_3`
 
-## Iterators and Circulators ##
+## Iterators ##
 - `CGAL::Halfedge_around_source_iterator`
 - `CGAL::Halfedge_around_target_iterator`
 - `CGAL::Halfedge_around_face_iterator`
-- `CGAL::Halfedge_around_source_circulator`
-- `CGAL::Halfedge_around_target_circulator`
-- `CGAL::Halfedge_around_face_circulator`
+- `CGAL::Vertex_around_target_iterator`
+- `CGAL::Face_around_target_iterator`
 - `CGAL::halfedges_around_source`
 - `CGAL::halfedges_around_target`
 - `CGAL::halfedges_around_face`
 
+## Circulators ##
+- `CGAL::Halfedge_around_source_circulator`
+- `CGAL::Halfedge_around_target_circulator`
+- `CGAL::Halfedge_around_face_circulator`
+- `CGAL::Vertex_around_target_circulator`
+- `CGAL::Face_around_target_circulator`
+
 ## Euler Operations ##
 
 - `CGAL::Euler::join_vertex()`

BGL/include/CGAL/boost/graph/iterator.h

@@ -25,7 +25,7 @@
 #include <boost/graph/graph_traits.hpp>
 #include <boost/iterator/transform_iterator.hpp>
 
-#include <CGAL/Range.h>
+#include <CGAL/iterator_range.h>
 #include <CGAL/assertions.h>
 #include <CGAL/circulator_bases.h>
 #include <CGAL/boost/graph/internal/helpers.h>
@@ -782,7 +782,7 @@ private:
  * returns an iterator range over all halfedges with vertex `source(h,g)` as source.
  */
 template<typename Graph>
-Range<Halfedge_around_source_iterator<Graph> >
+iterator_range<Halfedge_around_source_iterator<Graph> >
 halfedges_around_source(typename boost::graph_traits<Graph>::halfedge_descriptor h, Graph& g)
 {
   typedef Halfedge_around_source_iterator<Graph> I;
@@ -794,7 +794,7 @@ halfedges_around_source(typename boost::graph_traits<Graph>::halfedge_descriptor
  * returns an iterator range over all halfedges with vertex `v` as source.
  */
 template<typename Graph>
-Range<Halfedge_around_source_iterator<Graph> >
+iterator_range<Halfedge_around_source_iterator<Graph> >
 halfedges_around_source(typename boost::graph_traits<Graph>::vertex_descriptor v, Graph& g)
 {
   return halfedges_around_source(opposite(halfedge(v,g),g),g);
@@ -805,7 +805,7 @@ halfedges_around_source(typename boost::graph_traits<Graph>::vertex_descriptor v
  * returns an iterator range over all halfedges with vertex `target(h,g)` as target. 
  */
 template<typename Graph>
-Range<Halfedge_around_target_iterator<Graph> >
+iterator_range<Halfedge_around_target_iterator<Graph> >
 halfedges_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Halfedge_around_target_iterator<Graph> I;
@@ -817,7 +817,7 @@ halfedges_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor
  * returns an iterator range over all halfedges with vertex `v` as target. 
  */
 template<typename Graph>
-Range<Halfedge_around_target_iterator<Graph> >
+iterator_range<Halfedge_around_target_iterator<Graph> >
 halfedges_around_target(typename boost::graph_traits<Graph>::vertex_descriptor v, Graph& g)
 {
   return halfedges_around_target(halfedge(v,g),g);
@@ -828,7 +828,7 @@ halfedges_around_target(typename boost::graph_traits<Graph>::vertex_descriptor v
  * returns an iterator range over all halfedges incident to the same face as `h`. 
  */
 template<typename Graph>
-Range<Halfedge_around_face_iterator<Graph> >
+iterator_range<Halfedge_around_face_iterator<Graph> >
 halfedges_around_face(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Halfedge_around_face_iterator<Graph> I;
@@ -902,7 +902,7 @@ public:
  * returns an iterator range over all faces around  vertex `target(h,g)`. 
  */
 template<typename Graph>
-Range<Face_around_target_iterator<Graph> >
+iterator_range<Face_around_target_iterator<Graph> >
 faces_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Face_around_target_iterator<Graph> I;
@@ -914,7 +914,7 @@ faces_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor h,
  * returns an iterator range over all faces adjacent to the same face `face(h,g)`. 
  */
 template<typename Graph>
-Range<Face_around_face_iterator<Graph> >
+iterator_range<Face_around_face_iterator<Graph> >
 faces_around_face(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Face_around_face_iterator<Graph> I;
@@ -1090,7 +1090,7 @@ public:
 
 
 template <typename Graph>
-Range<Vertex_around_target_iterator<Graph> >
+iterator_range<Vertex_around_target_iterator<Graph> >
 adjacent_vertices(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Vertex_around_face_iterator<Graph> I;
@@ -1099,7 +1099,7 @@ adjacent_vertices(typename boost::graph_traits<Graph>::halfedge_descriptor h, co
 
 
 template <typename Graph>
-Range<Vertex_around_target_iterator<Graph> >
+iterator_range<Vertex_around_target_iterator<Graph> >
 adjacent_vertices(typename boost::graph_traits<Graph>::vertex_descriptor v, const Graph& g)
 {
   typedef Vertex_around_face_iterator<Graph> I;
@@ -1111,7 +1111,7 @@ adjacent_vertices(typename boost::graph_traits<Graph>::vertex_descriptor v, cons
  * returns an iterator range over all vertices adjacent to the vertex `target(h,g)`. 
  */
 template <typename Graph>
-Range<Vertex_around_target_iterator<Graph> >
+iterator_range<Vertex_around_target_iterator<Graph> >
 vertices_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Vertex_around_target_iterator<Graph> I;
@@ -1119,7 +1119,7 @@ vertices_around_target(typename boost::graph_traits<Graph>::halfedge_descriptor
 }
 
 template <typename Graph>
-Range<Vertex_around_target_iterator<Graph> >
+iterator_range<Vertex_around_target_iterator<Graph> >
 vertices_around_target(typename boost::graph_traits<Graph>::vertex_descriptor v, const Graph& g)
 {
   typedef Vertex_around_target_iterator<Graph> I;
@@ -1130,7 +1130,7 @@ vertices_around_target(typename boost::graph_traits<Graph>::vertex_descriptor v,
  * returns an iterator range over all vertices adjacent to the face `face(h,g)`. 
  */
 template <typename Graph>
-Range<Vertex_around_face_iterator<Graph> >
+iterator_range<Vertex_around_face_iterator<Graph> >
 vertices_around_face(typename boost::graph_traits<Graph>::halfedge_descriptor h, const Graph& g)
 {
   typedef Vertex_around_face_iterator<Graph> I;

STL_Extension/doc/STL_Extension/PackageDescription.txt

@@ -63,6 +63,9 @@
 - `CGAL::Random_access_adaptor<IC>`
 - `CGAL::Random_access_value_adaptor<IC,T>`
 
+## Ranges ##
+- `CGAL::iterator_range`
+
 ## Projection Function Objects ##
 - `CGAL::Identity<Value>`
 - `CGAL::Dereference<Value>`

STL_Extension/include/CGAL/iterator_range.h

@@ -25,6 +25,10 @@
 
 namespace CGAL {
 
+  /*!
+\ingroup PkgStlExtension
+  /// `CGAL::iterator_range` is a...
+  */
   template <typename I>
   class iterator_range
     : public std::pair<I,I>{

Surface_mesh/doc/Surface_mesh/Surface_mesh.txt

@@ -56,7 +56,7 @@ m.add_face(u, v, w);
 \endcode
 
 As `Surface_mesh` is index-based `Vertex_index`, `Face_index`, 
-`Halfedge_index` and `Edge_descriptor`
+`Halfedge_index` and `Edge_index`
 don't have member functions to access connectivity or properties.
 The functions of the `Surface_mesh` instance they were
 created from needs to be used to obtain that information.
@@ -76,7 +76,7 @@ in a surface mesh:  `Surface_mesh::opposite()`, `Surface_mesh::next()`,
 `Surface_mesh::prev()`, `Surface_mesh::target()`, and 
 `Surface_mesh::face()`.  What is not illustrated are the
 functions `Surface_mesh::halfedge()` overloaded for 
-`Surface_mesh::Vertex_descriptor` and `Surface_mesh::Face_descriptor`.
+`Surface_mesh::Vertex_index` and `Surface_mesh::Face_index`.
 Alternatively, one may use the free functions with the same names
 defined in the package \ref PkgBGLSummary.
 
@@ -102,30 +102,29 @@ returning ranges of elements which are compatible with the
 <a href="http://www.boost.org/libs/range/doc/html/index.html">Boost.Range</a>
 library. 
 
-It further provides circulators around faces and around vertices.
+Circulators around faces and around vertices are provided as class templates 
+in the package \ref PkgBGLSummary.
+
 Circulators around faces basically call `Surface_mesh::next()`
 in order to go from halfedge to halfedge counterclockwise around the face, and 
 when dereferenced return the halfedge or the incident vertex or the opposite face.
 
-- `Surface_mesh::Halfedge_around_face_circulator`
-- `Surface_mesh::Vertex_around_face_circulator`
-- `Surface_mesh::Face_around_face_circulator`
+- `CGAL::Halfedge_around_face_circulator<Mesh>`
+- `CGAL::Vertex_around_face_circulator<Mesh>`
+- `CGAL::Face_around_face_circulator<Mesh>`
 
 Circulators around the target vertex of an edge basically
 call `Surface_mesh::opposite(Surface_mesh::next())` in order
 to go from halfedge to halfedge clockwise around the same target vertex.
 
-- `Surface_mesh::Halfedge_around_target_circulator`
-- `Surface_mesh::Vertex_around_target_circulator`
-- `Surface_mesh::Face_around_target_circulator`
+- `CGAL::Halfedge_around_target_circulator<Mesh>`
+- `CGAL::Vertex_around_target_circulator<Mesh>`
+- `CGAL::Face_around_target_circulator<Mesh>`
 
 All circulators model `BidirectionalCirculator`. In addition to that
 they also support a conversion to `bool` for more convenient checking
 of emptiness.
 
-For all these circulators exist corresponding iterators. 
-These circulators and iterators around faces and vertices 
-are implemented as class templates  in the package \ref PkgBGLSummary.
 
 \subsection iterators_example Example
 
@@ -151,7 +150,7 @@ One property is maintained by default, namely \c "v:point". The value of
 this property has to be supplied when adding a new point to the data
 structure via `Surface_mesh::add_vertex()`. The property can be
 directly accessed using `Surface_mesh::points()` or
-`Surface_mesh::point(Surface_mesh::Vertex_descriptor v)`.
+`Surface_mesh::point(Surface_mesh::Vertex_index v)`.
 
 \subsection properties_example Example
 
@@ -165,13 +164,13 @@ A halfedge `h` is on the border, if it has no associated face, that is if
 `sm.face(h) == Surface_mesh::null_face()`.  An edge is on the border,
 if any of its halfedges is on the border.  A vertex is on the border,
 if any of its incident halfedges is on the border. In order to make 
-`Surface_mesh::is_border(Vertex_descriptor v)` a constant time 
+`Surface_mesh::is_border(Vertex_index v)` a constant time 
 operation, this function only checks if the halfedge associated to `v`
 is a border halfedge. The user is in charge to correctly set the halfedge
 associated to a vertex after having applied an operation that might invalidate 
 this property.
-The functions `Surface_mesh::fix_constant_border_property(Vertex_descriptor v)`,
-`Surface_mesh::fix_constant_border_property(Halfedge_descriptor h)`, and 
+The functions `Surface_mesh::fix_constant_border_property(Vertex_index v)`,
+`Surface_mesh::fix_constant_border_property(Halfedge_index h)`, and 
  `Surface_mesh::fix_constant_border_property()` allow to restore this property 
 for a single vertex `v`, for all vertices on the boundary of the
 face of `h`, and for all vertices of the surface mesh, respectively.
@@ -207,7 +206,7 @@ Again, there are similar types and functions:
 
 | BGL   | %Surface_mesh |
 | :---- | :----        |
-| `boost::graph_traits<G>::halfedge_descriptor` | `Surface_mesh::Halfedge_descriptor` |
+| `boost::graph_traits<G>::halfedge_descriptor` | `Surface_mesh::Halfedge_index` |
 | `hd = next(hd, g)` | `hd = sm.next(hd)` |
 | `hd = opposite(hd,g)` | `hd = sm.opposite(hd)` |
 | `hd = halfedge(vd,g)` | `hd = sm.halfedge(vd)` |

Surface_mesh/doc/Surface_mesh/examples.txt

@@ -1,11 +1,11 @@
 /*!
-\example Surface_mesh/iterators_and_circulators.cpp
-\example Surface_mesh/properties.cpp
-\example Surface_mesh/memory.cpp
-\example Surface_mesh/bgl.cpp
-\example Surface_mesh/kruskal.cpp
+\example Surface_mesh/sm_iterators_and_circulators.cpp
+\example Surface_mesh/sm_properties.cpp
+\example Surface_mesh/sm_memory.cpp
+\example Surface_mesh/sm_bgl.cpp
+\example Surface_mesh/sm_kruskal.cpp
 @cond 
-\example Surface_mesh/do_intersect.cpp
-\example Surface_mesh/aabbtree.cpp
+\example Surface_mesh/sm_do_intersect.cpp
+\example Surface_mesh/sm_aabbtree.cpp
 @endcond
 */

Surface_mesh/examples/Surface_mesh/sm_iterators_and_circulators.cpp

@@ -46,17 +46,17 @@ int main()
 
   {
     std::cout << "vertices around vertex " << v << std::endl;
-    Mesh::Vertex_around_target_circulator vbegin(m.halfedge(v),m), vend(vbegin);
+    CGAL::Vertex_around_target_circulator<Mesh> vbegin(m.halfedge(v),m), done(vbegin);
 
     do {
       std::cout << *vbegin++ << std::endl;
-    } while(vbegin != vend);
+    } while(vbegin != done);
   }
    
   { 
     std::cout << "vertices around face " << f << std::endl;
-    Mesh::Vertex_around_face_iterator vbegin, vend;
-    for(boost::tie(vbegin, vend) = m.vertices_around_face(m.halfedge(f));
+    CGAL::Vertex_around_face_iterator<Mesh> vbegin, vend;
+    for(boost::tie(vbegin, vend) = vertices_around_face(m.halfedge(f), m);
         vbegin != vend; 
         ++vbegin){
       std::cout << *vbegin << std::endl;

Surface_mesh/include/CGAL/Surface_mesh/Surface_mesh.h

@@ -801,6 +801,10 @@ private: //------------------------------------------------------ iterator types
 public:
     /// \name Range Types
     ///
+    /// Each range `R` in this section has a nested type `R::iterator`, 
+    /// is convertible to `std:pair<R::iterator,R::iterator`, so that one can use `boost::tie()`,
+    /// and can be used with `BOOST_FOREACH()`, as well as with the Cxx11 `for(..)` loop for ranges.
+
     ///@{
 
 #ifndef DOXYGEN_RUNNING
@@ -815,7 +819,7 @@ public:
 #ifdef DOXYGEN_RUNNING
     typedef unspecified_type Vertex_range;
 #else
-    typedef Range<Vertex_iterator> Vertex_range;
+    typedef iterator_range<Vertex_iterator> Vertex_range;
 #endif
 
 #ifndef DOXYGEN_RUNNING
@@ -830,7 +834,7 @@ public:
 #ifdef DOXYGEN_RUNNING
     typedef unspecified_type Halfedge_range;
 #else
-    typedef Range<Halfedge_iterator> Halfedge_range;
+    typedef iterator_range<Halfedge_iterator> Halfedge_range;
 #endif
 
 #ifndef DOXYGEN_RUNNING
@@ -845,7 +849,7 @@ public:
 #ifdef DOXYGEN_RUNNING
     typedef unspecified_type Edge_range;
 #else
-    typedef Range<Edge_iterator> Edge_range;
+    typedef iterator_range<Edge_iterator> Edge_range;
 #endif
 
 
@@ -861,39 +865,28 @@ public:
  #ifdef DOXYGEN_RUNNING
     typedef unspecified_type Face_range;
 #else
-   typedef Range<Face_iterator> Face_range;
+   typedef iterator_range<Face_iterator> Face_range;
 #endif
 
-#ifdef DOXYGEN_RUNNING 
-  typedef unspecified_type Vertex_around_target_range;
+#ifndef DOXYGEN_RUNNING 
 
-  typedef unspecified_type Halfedge_around_target_range;
-
-  typedef unspecified_type Face_around_target_range;
-
-  typedef unspecified_type Vertex_around_face_range;
-
-  typedef unspecified_type Halfedge_around_face_range;
-
-  typedef unspecified_type Face_around_face_range;
-#else
   typedef CGAL::Vertex_around_target_iterator<Surface_mesh> Vertex_around_target_iterator;
-  typedef Range<Vertex_around_target_iterator> Vertex_around_target_range;
+  typedef iterator_range<Vertex_around_target_iterator> Vertex_around_target_range;
 
   typedef CGAL::Halfedge_around_target_iterator<Surface_mesh>  Halfedge_around_target_iterator;
-  typedef Range<Halfedge_around_target_iterator> Halfedge_around_target_range;
+  typedef iterator_range<Halfedge_around_target_iterator> Halfedge_around_target_range;
 
   typedef CGAL::Face_around_target_iterator<Surface_mesh>  Face_around_target_iterator;
-  typedef Range<Face_around_target_iterator> Face_around_target_range;
+  typedef iterator_range<Face_around_target_iterator> Face_around_target_range;
 
   typedef CGAL::Vertex_around_face_iterator<Surface_mesh>  Vertex_around_face_iterator;
-  typedef Range<Vertex_around_face_iterator> Vertex_around_face_range;
+  typedef iterator_range<Vertex_around_face_iterator> Vertex_around_face_range;
 
   typedef CGAL::Halfedge_around_face_iterator<Surface_mesh>  Halfedge_around_face_iterator;
-  typedef Range<Halfedge_around_face_iterator> Halfedge_around_face_range;
+  typedef iterator_range<Halfedge_around_face_iterator> Halfedge_around_face_range;
 
   typedef CGAL::Face_around_face_iterator<Surface_mesh>  Face_around_face_iterator;
-  typedef Range<Face_around_face_iterator> Face_around_face_range;
+  typedef iterator_range<Face_around_face_iterator> Face_around_face_range;
 #endif
 
     /// @cond CGAL_BEGIN_END
@@ -979,6 +972,7 @@ public:
       return make_range(faces_begin(), faces_end());
     }
 
+#ifndef DOXYGEN_RUNNING
     /// returns the iterator range for vertices around vertex `target(h)`, starting at `source(h)`.
     Vertex_around_target_range vertices_around_target(Halfedge_index h) const
     {
@@ -1015,6 +1009,8 @@ public:
        return CGAL::faces_around_face(h,*this);
     }
 
+#endif
+
     ///@}
 
 
@@ -1341,8 +1337,8 @@ public:
     /// used and removed elements, and to collect garbage.
     /// The number of used and removed elements is
     /// an upperbound on the index, and is needed
-    /// for algorithms that temporarily store a 
-    /// property in a vector of the right size.
+    /// by algorithms that temporarily store a 
+    /// property in a vector of the appropriate size.
 
     ///@{
    /// returns the number of used and removed vertices in the mesh.
@@ -1461,8 +1457,8 @@ public:
     /// \name Validity Checks
     ///
     /// Functions in this group perform checks for structural
-    /// consistency of the object. They are expensive and should only
-    /// be used in debug configurations.
+    /// consistency of a complete surface mesh, or an individual element. 
+    /// They are expensive and should only be used in debug configurations.
 
     ///@{