Document the option to enable a cache + interruptible distance computation

Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_iso_box.h

@@ -76,6 +76,13 @@ Test whether the fuzzy iso box contains `p`.
 */
 bool contains(Point_d p) const;
 
+/*!
+Test whether the fuzzy iso box contains the point whose coordinates are contained in
+the range [`begin`, `end`).
+*/
+template <typename Coord_iterator>
+bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const;
+
 /*!
 Test whether the inner box intersects the rectangle
 associated with a node of a tree.

Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_sphere.h

@@ -78,6 +78,13 @@ less than \f$ r\f$.
 */
 bool contains(const Point_d& p) const;
 
+/*!
+Test whether the fuzzy sphere contains the point whose coordinates are contained in
+the range [`begin`, `end`).
+*/
+template <typename Coord_iterator>
+bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const;
+
 /*!
 Test whether the inner sphere intersects the rectangle
 associated with a node of a tree.

Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h

@@ -14,13 +14,24 @@ It defaults to `Sliding_midpoint<Traits>`.
 \tparam UseExtendedNode must be  `Tag_true`, if the
 tree shall be built with extended nodes, and `Tag_false` otherwise.
 
+\tparam EnablePointsCache can be `Tag_true` or `Tag_false`.
+Not storing the points coordinates inside the tree usually generates a
+lot of cache misses, leading to non-optimal performance. This is the case
+for example when indices are stored inside the tree, or when the points
+coordinates are stored in a dynamically allocated array. When
+`EnablePointsCache` is set to `Tag_true`, the points 
+coordinates will be cached in an optimal way. This will 
+increase memory consumption but provide better search performance.
+See also the `GeneralDistance` and `FuzzyQueryItem` concepts for
+additional requirements when using such a cache.
+
 \sa `CGAL::Kd_tree_node<Traits>`
 \sa `CGAL::Search_traits_2<Kernel>`
 \sa `CGAL::Search_traits_3<Kernel>`
 \sa `CGAL::Search_traits<FT_,Point,CartesianIterator,ConstructCartesianIterator>`
 
 */
-template< typename Traits, typename Splitter, typename UseExtendedNode >
+template< typename Traits, typename Splitter, typename UseExtendedNode, typename EnablePointsCache >
 class Kd_tree {
 public:
 

Spatial_searching/doc/Spatial_searching/Concepts/FuzzyQueryItem.h

@@ -40,6 +40,15 @@ Test whether the query item contains `p`.
 */ 
 bool contains(Point_d p) const; 
 
+/*!
+Optional: must be defined when used with a `Kd_tree` where `EnablePointsCache`
+is set to `Tag_true`.
+Test whether the query item contains the point whose coordinates are contained in
+the range [`begin`, `end`).
+*/
+template <typename Coord_iterator>
+bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const;
+
 /*!
 Test whether the inner approximation of the spatial object intersects a rectangle 
 associated with a node of a tree. 

Spatial_searching/doc/Spatial_searching/Concepts/GeneralDistance.h

@@ -49,6 +49,33 @@ Returns the transformed distance between `q` and `r`.
 */ 
 FT transformed_distance(Query_item q, Point_d r); 
 
+/*!
+Optional: must be defined when used with a `Kd_tree` where `EnablePointsCache`
+is set to `Tag_true`.
+
+Returns the transformed distance between `q` and the point whose coordinates
+are contained in the range [`begin`, `end`).
+*/
+template <typename Coord_iterator>
+FT transformed_distance_from_coordinates(
+  Query_item q, Coord_iterator begin, Coord_iterator end) const;
+
+/*!
+Optional: in most cases (e.g. Euclidean distance), the distance computation
+algorithm knows before its end that the distance will be greater than or equal
+to some given value. In this function, the computation can be stopped when the
+distance is going to be greater than or equal to `stop_if_geq_to_this`. In this case,
+the only requirement of the return value it to be \f$ \geq \f$ `stop_if_geq_to_this`.
+Note that points cache does not have to be activated to enable this optimization.
+
+Returns the transformed distance between `q` and the point whose coordinates
+are contained in the range [`begin`, `end`), or any value \f$ \geq \f$
+`stop_if_geq_to_this` if the transformed distance is \f$ \geq \f$ `stop_if_geq_to_this`.
+*/
+template <typename Coord_iterator>
+FT interruptible_transformed_distance(
+  Query_item q, Coord_iterator begin, Coord_iterator end, FT stop_if_geq_to_this) const;
+
 /*!
 Returns the transformed distance between `q` and 
 the point on the boundary of `r` closest to `q`. 

Spatial_searching/doc/Spatial_searching/Spatial_searching.txt

@@ -498,6 +498,18 @@ instead of the distance itself. For instance for the Euclidean
 distance, to avoid the expensive computation of square roots, squared
 distances are used instead of the Euclidean distance itself.
 
+\cgalModifBegin
+Not storing the points coordinates inside the tree usually generates a
+lot of cache misses, leading to non-optimal performance. This is the case
+for example when indices are stored inside the tree, or when the points
+coordinates are stored in a dynamically allocated array. In this case,
+the `EnablePointsCache` template parameter of the `Kd_tree` class can be
+set to `Tag_true`. The points coordinates will then be cached in an optimal
+way. This will increase memory consumption but provide better search
+performance. See also the `GeneralDistance` and `FuzzyQueryItem` concepts for
+additional requirements when using such a cache.
+\cgalModif
+
 \section Spatial_searchingImplementationHistory Implementation History
 
 The initial implementation of this package was done by Hans Tangelder and