major cleanup of Polyline_constraint_hierarchy_2

- remove all mentions of `Edge` and `Constraint`
- `Subconstraint_iterator` is renamed `Subconstraint_and_contexts_iterator` (because of its value type)
- a new `Subconstraint_iterator`, with value type `Subconstraint`
- a few unused/untested and uncompilable functions are removed from the code
- a lot of internal renamings

== Breaking changes ==

For `Constrained_triangulation_plus_2`, there are a few breaking changes...

- The value type of `subconstraints_begin()`, `subconstraints_end()`, of the range `subconstraints()` has changed to `Subconstraint` (a simple `std::pair` of vertex handles). That is actually a kind of bug-fix, because it was documented as such in the user manual.
- The new member functions `subconstraints_and_contexts_begin()`, `subconstraints_and_contexts_end()`, `subconstraints_and_contexts()` are created get the old value type (`std::pair<const Subconstraint, std::list<Context>*>`).
- A few range types have changed from `CGAL::Iterator_range<It>` to `unspecified_type`, for efficiency reasons.
- Doc fixes.

== Determinism ==

Even if it was not documented, the range `subconstraints()` is deterministic (used by Mesh_2), and `subconstraints_and_contexts()` is not.

Mesh_2/include/CGAL/Mesh_2/Clusters.h

@@ -160,15 +160,14 @@ class Clusters
   void create_clusters(Tag_true) {
     cluster_map.clear();
     Unique_hash_map<Vertex_handle,bool> created(false);
-    for(typename Tr::Subconstraint_iterator it = tr.subconstraints_begin();
-        it != tr.subconstraints_end(); ++it) {
-      Vertex_handle vh = it->first.first;
+    for(const auto& sc : tr.subconstraints()) {
+      Vertex_handle vh = sc.first;
       if(!created[vh]){
         created[vh] = true;
         create_clusters_of_vertex(vh);
       }
 
-      vh = it->first.second;
+      vh = sc.second;
       if(!created[vh]){
         created[vh] = true;
         create_clusters_of_vertex(vh);

Mesh_2/include/CGAL/Mesh_2/Refine_edges.h

@@ -344,7 +344,7 @@ class Refine_edges_base :
 
   void scan_triangulation_impl(Tag_true)
   {
-    for(const auto& [v1, v2] : tr.hierarchy_ref().edges())
+    for(const auto& [v1, v2] : tr.subconstraints())
     {
       if(!is_locally_conform(tr, v1, v2) ){
         add_constrained_edge_to_be_conformed(v1, v2);

Mesh_2/test/Mesh_2/conform_plus.cpp

@@ -18,15 +18,7 @@ int main()
 
  std::pair<Vertex_handle,Vertex_handle> p;
 
-  for(CDT::Subconstraint_iterator sit = cdt.subconstraints_begin();
-      sit != cdt.subconstraints_end();
-      ++sit){
-
-    p = (*sit).first;
-
-    Vertex_handle vh1 = p.first;
-    Vertex_handle vh2 = p.second;
-
+  for(const auto& [vh1, vh2] : cdt.subconstraints()) {
     std::cerr << "subconstraint: " << vh1->point() << " -- " << vh2->point() << std::endl;
   }
 
@@ -36,15 +28,8 @@ int main()
 
   int counter = 0;
 
-  for(CDT::Subconstraint_iterator sit = cdt.subconstraints_begin();
-      sit != cdt.subconstraints_end();
-      ++sit){
+  for(const auto& [vh1, vh2] : cdt.subconstraints()) {
     ++counter;
-    p = (*sit).first;
-
-    Vertex_handle vh1 = p.first;
-    Vertex_handle vh2 = p.second;
-
     std::cerr << "subconstraint: " << vh1->point() << " -- " << vh2->point() << std::endl;
   }
 

Triangulation_2/doc/Triangulation_2/CGAL/Constrained_triangulation_plus_2.h

@@ -84,9 +84,10 @@ The value type of this iterator is `Constraint_id`.
 typedef unspecified_type Constraint_iterator;
 
 /*!
-A range type for iterating over all constraints.
+A range type for iterating over all constraints. The iterator type of
+the range is `Constraint_iterator`.
 */
-typedef Iterator_range<Constraint_iterator> Constraints;
+typedef unspecified_type Constraints;
 
 
 /*!
@@ -95,19 +96,30 @@ A subconstraint is a pair of vertices that correspond to an `Edge`.
 typedef std::pair<Vertex_handle, Vertex_handle> Subconstraint;
 
 /*!
-An iterator
-to visit all the subconstraints of the triangulation.
+An iterator to visit all the subconstraints of the triangulation.
 The order of visit is undefined.
-The value type of this iterator is `std::pair<Subconstraint,std::list<Context>*>`
-corresponding to the vertices of the
-subconstraint.
+The value type of this iterator is `Subconstraint`.
 */
 typedef unspecified_type Subconstraint_iterator;
 
 /*!
-A range type for iterating over all subconstraints.
+A range type for iterating over all subconstraints. The iterator type of
+the range is `Subconstraint_iterator`.
 */
-typedef Iterator_range<Subconstraint_iterator> Subconstraints;
+typedef unspecified_type Subconstraints;
+
+/*!
+An iterator to visit all the subconstraints of the triangulation and the
+contexts of their enclosing constraints. The order of visit is undefined.
+The value type of this iterator is `std::pair<const Subconstraint, std::list<Context>*>`.
+*/
+typedef unspecified_type Subconstraint_and_contexts_iterator;
+
+/*!
+A range type for iterating over all subconstraints. The iterator type of
+the range is `Subconstraint_and_contexts_iterator`.
+*/
+typedef unspecified_type Subconstraints_and_contexts;
 
 /*!
 An iterator on the
@@ -381,6 +393,22 @@ returns a range of subconstraints.
 */
 Subconstraints subconstraints() const;
 
+/*!
+returns a `Subconstraint_and_contexts_iterator` pointing at the first
+subconstraint of the triangulation.
+*/
+Subconstraint_and_contexts_iterator subconstraints_and_contexts_begin() const;
+
+/*!
+returns the past-the-end iterator of the subconstraints of the triangulation.
+*/
+Subconstraint_and_contexts_iterator subconstraints_and_contexts_end() const;
+
+/*!
+returns a range of subconstraints with the contexts of their enclosing constraints.
+*/
+Subconstraints_and_contexts subconstraints_and_contexts() const;
+
 /*!
 returns the number of constraints enclosing the subconstraint
 `(va,vb)`.

Triangulation_2/examples/Triangulation_2/constrained_hierarchy_plus.cpp

@@ -30,15 +30,15 @@ main( )
     cdt.insert_constraint( Point(j,0), Point(j,6));
 
   int count = 0;
-  for (Triangulation::Subconstraint_iterator scit = cdt.subconstraints_begin();
-       scit != cdt.subconstraints_end();
-       ++scit)  ++count;
+  for (const Triangulation::Subconstraint& sc :  cdt.subconstraints()) {
+    ++count;
+  }
   std::cout << "The number of resulting constrained edges is  ";
   std::cout <<  count << std::endl;
 
   //verbose mode of is_valid ; shows the number of vertices at each  level
   std::cout << "The number of vertices at successive levels" << std::endl;
-  assert(cdt.is_valid(true));
+  bool valid = cdt.is_valid(true);
 
-  return 0;
+  return valid ? 0 : 1;
 }

Triangulation_2/examples/Triangulation_2/polylines_triangulation.cpp

@@ -28,13 +28,14 @@ print(const CDTP& cdtp, Cid cid)
 void
 contexts(const CDTP& cdtp)
 {
-  for(auto sc : cdtp.subconstraints()){
-    Vertex_handle vp = sc.first.first, vq = sc.first.second;
+  for(const auto& sc_and_contexts : cdtp.subconstraints_and_contexts()) {
+    const auto& [subconstraint, contexts_list_ptr] = sc_and_contexts;
+    Vertex_handle vp = subconstraint.first, vq = subconstraint.second;
 
     if(cdtp.number_of_enclosing_constraints(vp, vq) == 2){
       std::cout << "subconstraint " << vp->point() << " " << vq->point()
                 << " is on constraints starting at:\n";
-      for(const CDTP::Context& c : cdtp.contexts(vp,vq)){
+      for(const CDTP::Context& c : *contexts_list_ptr) {
         std::cout << (*(c.vertices_begin()))->point() << std::endl;
       }
     }

Triangulation_2/include/CGAL/Constrained_triangulation_plus_2.h

@@ -165,11 +165,14 @@ class Constrained_triangulation_plus_2
   typedef typename Constraint_hierarchy::Context_iterator Context_iterator;
   typedef Iterator_range<Context_iterator>                Contexts;
 
-  typedef typename Constraint_hierarchy::C_iterator   Constraint_iterator;
-  typedef Iterator_range<Constraint_iterator> Constraints;
+  typedef typename Constraint_hierarchy::Constraint_iterator   Constraint_iterator;
+  typedef typename Constraint_hierarchy::Constraints           Constraints;
 
-  typedef typename Constraint_hierarchy::Subconstraint_iterator  Subconstraint_iterator;
-  typedef Iterator_range<Subconstraint_iterator> Subconstraints;
+  typedef typename Constraint_hierarchy::Subconstraint_iterator Subconstraint_iterator;
+  typedef typename Constraint_hierarchy::Subconstraints         Subconstraints;
+
+  typedef typename Constraint_hierarchy::Subconstraint_and_contexts_iterator Subconstraint_and_contexts_iterator;
+  typedef typename Constraint_hierarchy::Subconstraints_and_contexts         Subconstraints_and_contexts;
 
   typedef typename Constraint_hierarchy::Constraint_id Constraint_id;
 
@@ -768,18 +771,15 @@ class Constrained_triangulation_plus_2
   // Query of the constraint hierarchy
   Constraint_iterator constraints_begin() const;
   Constraint_iterator constraints_end()   const;
-  Constraints constraints() const
-  {
-    return Constraints(constraints_begin(),constraints_end());
-  }
+  Constraints constraints() const;
 
   Subconstraint_iterator subconstraints_begin() const;
   Subconstraint_iterator subconstraints_end() const;
+  Subconstraints subconstraints() const;
 
-  Subconstraints subconstraints() const
-  {
-    return Subconstraints(subconstraints_begin(),subconstraints_end());
-  }
+  Subconstraint_and_contexts_iterator subconstraints_and_contexts_begin() const;
+  Subconstraint_and_contexts_iterator subconstraints_and_contexts_end() const;
+  Subconstraints_and_contexts subconstraints_and_contexts() const;
 
   Context   context(Vertex_handle va, Vertex_handle vb); //AF: const;
 
@@ -1266,7 +1266,7 @@ Constrained_triangulation_plus_2<Tr>::Constraint_iterator
 Constrained_triangulation_plus_2<Tr>::
 constraints_begin() const
 {
-  return hierarchy.c_begin();
+  return hierarchy.constraints_begin();
 }
 
 template <class Tr>
@@ -1276,7 +1276,17 @@ Constrained_triangulation_plus_2<Tr>::Constraint_iterator
 Constrained_triangulation_plus_2<Tr>::
 constraints_end() const
 {
-  return hierarchy.c_end();
+  return hierarchy.constraints_end();
+}
+
+template <class Tr>
+inline
+typename
+Constrained_triangulation_plus_2<Tr>::Constraints
+Constrained_triangulation_plus_2<Tr>::
+constraints() const
+{
+  return hierarchy.constraints();
 }
 
 template <class Tr>
@@ -1286,7 +1296,7 @@ Constrained_triangulation_plus_2<Tr>::Subconstraint_iterator
 Constrained_triangulation_plus_2<Tr>::
 subconstraints_begin() const
 {
-  return hierarchy.subconstraint_begin();
+  return hierarchy.subconstraints_begin();
 }
 
 template <class Tr>
@@ -1296,9 +1306,48 @@ Constrained_triangulation_plus_2<Tr>::Subconstraint_iterator
 Constrained_triangulation_plus_2<Tr>::
 subconstraints_end() const
 {
-  return hierarchy.subconstraint_end();
+  return hierarchy.subconstraints_end();
+}
+
+template <class Tr>
+inline
+typename
+Constrained_triangulation_plus_2<Tr>::Subconstraints
+Constrained_triangulation_plus_2<Tr>::
+subconstraints() const
+{
+  return hierarchy.subconstraints();
 }
 
+template <class Tr>
+inline
+typename
+Constrained_triangulation_plus_2<Tr>::Subconstraint_and_contexts_iterator
+Constrained_triangulation_plus_2<Tr>::
+subconstraints_and_contexts_begin() const
+{
+  return hierarchy.subconstraints_and_contexts_begin();
+}
+
+template <class Tr>
+inline
+typename
+Constrained_triangulation_plus_2<Tr>::Subconstraint_and_contexts_iterator
+Constrained_triangulation_plus_2<Tr>::
+subconstraints_and_contexts_end() const
+{
+  return hierarchy.subconstraints_and_contexts_end();
+}
+
+template <class Tr>
+inline
+typename
+Constrained_triangulation_plus_2<Tr>::Subconstraints_and_contexts
+Constrained_triangulation_plus_2<Tr>::
+subconstraints_and_contexts() const
+{
+  return hierarchy.subconstraints_and_contexts();
+}
 
 template <class Tr>
 inline
@@ -1325,7 +1374,7 @@ inline bool
 Constrained_triangulation_plus_2<Tr>::
 is_subconstraint(Vertex_handle va, Vertex_handle vb)
 {
- return hierarchy.is_subconstrained_edge(va,vb);
+ return hierarchy.is_subconstraint(va,vb);
 }