Add some locate() and insert() convenient overloads, taking the start hint as a

Vertex_handle (instead of the Cell_handle currently).

Triangulation_3/doc_tex/Triangulation_3_ref/Delaunay_triangulation_3.tex

@@ -90,6 +90,9 @@ scheme~\cite{cgal:dt-pvr3d-03}.
 addition the empty sphere property of all the created faces.
 The optional argument \ccc{start} is used as a starting place for the search.}
 
+\ccMethod{Vertex_handle insert(const Point & p, Vertex_handle hint);}
+{ Same as above but uses \ccc{hint} as a starting place for the search. }
+
 \ccMethod{Vertex_handle insert(const Point & p, Locate_type lt,
                                Cell_handle loc, int li, int lj);}
 {Inserts point \ccc{p} in the triangulation and returns the corresponding

Triangulation_3/doc_tex/Triangulation_3_ref/Regular_triangulation_3.tex

@@ -106,6 +106,9 @@ Otherwise if \ccc{p} does not appear as a vertex of the triangulation,
 then it is stored as a hidden point and this method returns the default 
 constructed handle.}
 
+\ccMethod{Vertex_handle insert(const Weighted_point & p, Vertex_handle hint);}
+{ Same as above but uses \ccc{hint} as a starting place for the search. }
+
 \ccMethod{Vertex_handle insert(const Weighted_point & p, Locate_type lt,
                                Cell_handle loc, int li, int lj);}
 {Inserts weighted point \ccc{p} in the triangulation and returns the corresponding

Triangulation_3/doc_tex/Triangulation_3_ref/Triangulation_3.tex

@@ -419,6 +419,10 @@ the facet (resp. edge, vertex) containing the query point. \\
 The optional argument \ccc{start} is used as a starting place for the search.
 }
 
+\ccMethod{Cell_handle
+          locate(const Point & query, Vertex_handle hint) const;}
+{ Same as above but uses \ccc{hint} as the starting place for the search.  }
+
 \ccMethod{Cell_handle
           locate(const Point & query, Locate_type & lt,
                  int & li, int & lj, Cell_handle start = Cell_handle() ) const;}
@@ -447,6 +451,11 @@ triangulation, \ccc{lt} is set to \ccc{OUTSIDE_AFFINE_HULL} and
 The optional argument \ccc{start} is used as a starting place for the search.
 }
 
+\ccMethod{Cell_handle
+          locate(const Point & query, Locate_type & lt,
+                 int & li, int & lj, Vertex_handle hint) const;}
+{ Same as above but uses \ccc{hint} as the starting place for the search. }
+
 \ccMethod{Bounded_side
           side_of_cell(const Point & p,
 			Cell_handle c,
@@ -608,6 +617,9 @@ triangulate the new infinite face. See
 Figure~\ref{Triangulation3-fig-insert_outside_affine_hull}.
 The optional argument \ccc{start} is used as a starting place for the search.}
 
+\ccMethod{Vertex_handle insert(const Point & p, Vertex_handle hint);}
+{ Same as above but uses \ccc{hint} as the starting place for the search. }
+
 \ccMethod{Vertex_handle insert(const Point & p, Locate_type lt,
                                Cell_handle loc, int li, int lj);}
 {Inserts point \ccc{p} in the triangulation and returns the corresponding

Triangulation_3/include/CGAL/Delaunay_triangulation_3.h

@@ -195,14 +195,19 @@ public:
     std::random_shuffle (points.begin(), points.end());
     spatial_sort (points.begin(), points.end(), geom_traits());
 
-    Cell_handle hint;
+    Vertex_handle hint;
     for (typename std::vector<Point>::const_iterator p = points.begin(), end = points.end();
             p != end; ++p)
-        hint = insert (*p, hint)->cell();
+        hint = insert(*p, hint);
 
     return number_of_vertices() - n;
   }
 
+  Vertex_handle insert(const Point & p, Vertex_handle hint)
+  {
+    return insert(p, hint == Vertex_handle() ? this->infinite_cell() : hint->cell());
+  }
+
   Vertex_handle insert(const Point & p, Cell_handle start = Cell_handle());
 
   Vertex_handle insert(const Point & p, Locate_type lt,

Triangulation_3/include/CGAL/Regular_triangulation_3.h

@@ -156,6 +156,11 @@ public:
     return number_of_vertices() - n;
   }
 
+  Vertex_handle insert(const Weighted_point & p, Vertex_handle hint)
+  {
+    return insert(p, hint == Vertex_handle() ? this->infinite_cell() : hint->cell());
+  }
+
   Vertex_handle insert(const Weighted_point & p,
 	               Cell_handle start = Cell_handle());
 

Triangulation_3/include/CGAL/Triangulation_3.h

@@ -464,6 +464,19 @@ public:
       return locate( p, lt, li, lj, start);
   }
 
+  Cell_handle
+  locate(const Point & p,
+	 Locate_type & lt, int & li, int & lj, Vertex_handle hint) const
+  {
+      return locate(p, lt, li, lj, hint == Vertex_handle() ? infinite_cell() : hint->cell());
+  }
+
+  Cell_handle
+  locate(const Point & p, Vertex_handle hint) const
+  {
+      return locate(p, hint == Vertex_handle() ? infinite_cell() : hint->cell());
+  }
+
   // PREDICATES ON POINTS ``TEMPLATED'' by the geom traits
 
   Bounded_side
@@ -553,6 +566,10 @@ public:
 
   //INSERTION 
 
+  Vertex_handle insert(const Point & p, Vertex_handle hint)
+  {
+    return insert(p, hint == Vertex_handle() ? infinite_cell() : hint->cell());
+  }
   Vertex_handle insert(const Point & p, Cell_handle start = Cell_handle());
   Vertex_handle insert(const Point & p, Locate_type lt, Cell_handle c,
 	               int li, int lj);
@@ -572,10 +589,10 @@ public:
       std::random_shuffle (points.begin(), points.end());
       spatial_sort (points.begin(), points.end(), geom_traits());
 
-      Cell_handle hint;
+      Vertex_handle hint;
       for (typename std::vector<Point>::const_iterator p = points.begin(), end = points.end();
               p != end; ++p)
-          hint = insert (*p, hint)->cell();
+          hint = insert(*p, hint);
 
       return number_of_vertices() - n;
     }

Triangulation_3/include/CGAL/Triangulation_hierarchy_3.h

@@ -90,6 +90,10 @@ public:
   bool is_valid(bool verbose = false, int level = 0) const;
 
   // INSERT REMOVE
+  Vertex_handle insert(const Point &p, Vertex_handle hint)
+  {
+    return insert(p, hint == Vertex_handle() ? this->infinite_cell() : hint->cell());
+  }
   Vertex_handle insert(const Point &p, Cell_handle start = Cell_handle ());
   Vertex_handle insert(const Point &p, Locate_type lt, Cell_handle loc,
       int li, int lj);
@@ -103,24 +107,20 @@ public:
       std::random_shuffle (points.begin(), points.end());
       spatial_sort (points.begin(), points.end(), geom_traits());
 
-      // hints[i] is the cell of the previously inserted point in level i.
+      // hints[i] is the vertex of the previously inserted point in level i.
       // Thanks to spatial sort, they are better hints than what the hierarchy
       // would give us.
-      Cell_handle hints[maxlevel];
+      Vertex_handle hints[maxlevel];
       for (typename std::vector<Point>::const_iterator p = points.begin(), end = points.end();
               p != end; ++p)
       {
           int vertex_level = random_level();
 
-          Vertex_handle v = hierarchy[0]->insert (*p, hints[0]);
+          Vertex_handle v = hints[0] = hierarchy[0]->insert (*p, hints[0]);
-          hints[0] = v->cell();
-
           Vertex_handle prev = v;
 
           for (int level = 1; level <= vertex_level; ++level) {
-              v = hierarchy[level]->insert (*p, hints[level]);
+              v = hints[level] = hierarchy[level]->insert (*p, hints[level]);
-              hints[level] = v->cell();
-
               v->set_down (prev);
               prev->set_up (v);
               prev = v;
@@ -147,6 +147,16 @@ public:
   Vertex_handle move_point(Vertex_handle v, const Point & p);
 
   //LOCATE
+  Cell_handle locate(const Point& p, Locate_type& lt, int& li, int& lj,
+                     Vertex_handle hint) const
+  {
+    return locate(p, lt, li, lj, hint == Vertex_handle() ? this->infinite_cell() : hint->cell());
+  }
+  Cell_handle locate(const Point& p, Vertex_handle hint) const
+  {
+    return locate(p, hint == Vertex_handle() ? this->infinite_cell() : hint->cell());
+  }
+
   Cell_handle locate(const Point& p, Locate_type& lt, int& li, int& lj,
           Cell_handle start = Cell_handle ()) const;
   Cell_handle locate(const Point& p, Cell_handle start = Cell_handle ()) const;
@@ -165,11 +175,6 @@ private:
   void locate(const Point& p, Locate_type& lt, int& li, int& lj,
 	      locs pos[maxlevel], Cell_handle start = Cell_handle ()) const;
   int random_level();
-
-  // added to make the test program of usual triangulations work
-  // undocumented
-public:
-
 };
 
 

Triangulation_3/test/Triangulation_3/include/CGAL/_test_cls_delaunay_3.h

@@ -817,8 +817,8 @@ _test_cls_delaunay_3(const Triangulation &)
   Cls T4;
   v0 = T4.insert(q0);
   Vertex_handle v1 = T4.insert(q1);
-  Vertex_handle v2 = T4.insert(q2);
+  Vertex_handle v2 = T4.insert(q2, v1);         // testing with the hint
-  Vertex_handle v3 = T4.insert(q3);
+  Vertex_handle v3 = T4.insert(q3, v2->cell()); // testing with the hint
   Cell_handle c;
   int j,k,l;
   assert(T4.is_facet(v0,v1,v2,c,j,k,l));

Triangulation_3/test/Triangulation_3/include/CGAL/_test_cls_triangulation_3.h

@@ -480,8 +480,8 @@ _test_cls_triangulation_3(const Triangulation &)
   v0=T3_5.insert(p115);
   v0=T3_5.insert(p116);
   v0=T3_5.insert(p117);
-  v0=T3_5.insert(p118);
+  v0=T3_5.insert(p118, v0->cell()); // testing with the hint
-  v0=T3_5.insert(p119);
+  v0=T3_5.insert(p119, v0);         // testing with the hint
   
   assert(T3_5.is_valid());
   assert(T3_5.number_of_vertices()==10);
@@ -552,6 +552,11 @@ _test_cls_triangulation_3(const Triangulation &)
   assert(lt==Cls::VERTEX);
   i2=li;
 
+  // testing the locate with hint.
+  Cell_handle ccc = Ti.locate(Point(100,100,0),c);
+  assert(c == ccc);
+  ccc = Ti.locate(Point(100,100,0),c->vertex(0));
+
   Point p22(50,50,0);
   v0=Ti.insert_in_edge(p22,Ti.locate(Point(50,40,1)),i1,i2);
   assert(Ti.is_valid());