[Boost-commit] svn:boost r85637 - in trunk: boost/geometry/index libs/geometry/doc/index/rtree

Subject: [Boost-commit] svn:boost r85637 - in trunk: boost/geometry/index libs/geometry/doc/index/rtree
From: adam.wulkiewicz_at_[hidden]
Date: 2013-09-10 07:54:35

Author: awulkiew
Date: 2013-09-10 07:54:34 EDT (Tue, 10 Sep 2013)
New Revision: 85637
URL: http://svn.boost.org/trac/boost/changeset/85637

Log:
[geometry] query iterators described in docs + some fixes of the chapter describing queries.

Text files modified: 
   trunk/boost/geometry/index/rtree.hpp          |     6 +--                                     
   trunk/libs/geometry/doc/index/rtree/query.qbk |    74 ++++++++++++++++++++++----------------- 
   2 files changed, 43 insertions(+), 37 deletions(-)

Modified: trunk/boost/geometry/index/rtree.hpp
==============================================================================
--- trunk/boost/geometry/index/rtree.hpp	Tue Sep 10 01:54:53 2013	(r85636)
+++ trunk/boost/geometry/index/rtree.hpp	2013-09-10 07:54:34 EDT (Tue, 10 Sep 2013)	(r85637)
@@ -773,8 +773,7 @@
     about the predicates which may be passed to this method see query().
     
     \par Example
-    \verbatim
-    
+    \verbatim    
     for ( Rtree::const_query_iterator it = tree.qbegin(bgi::nearest(pt, 10000)) ;
           it != tree.qend() ; ++it )
     {
@@ -804,8 +803,7 @@
     This method returns the iterator which may be used to check if the query has ended.
     
     \par Example
-    \verbatim
-    
+    \verbatim    
     for ( Rtree::const_query_iterator it = tree.qbegin(bgi::nearest(pt, 10000)) ;
           it != tree.qend() ; ++it )
     {

Modified: trunk/libs/geometry/doc/index/rtree/query.qbk
==============================================================================
--- trunk/libs/geometry/doc/index/rtree/query.qbk	Tue Sep 10 01:54:53 2013	(r85636)
+++ trunk/libs/geometry/doc/index/rtree/query.qbk	2013-09-10 07:54:34 EDT (Tue, 10 Sep 2013)	(r85637)
@@ -24,32 +24,44 @@
 
 [h4 Performing a query]
 
-There are three ways to perform a query presented below. All of them returns `__value__`s intersecting some
-region defined as a `__box__`.
+There are various ways to perform a query. They are presented below.
+All of them returns `__value__`s intersecting some region defined as a `__box__`.
 
-Method call
+Member function call
 
  std::vector<__value__> returned_values;
  __box__ box_region(...);
  rt.query(bgi::intersects(box_region), std::back_inserter(returned_values));
 
-Function call
+Free function call
 
  std::vector<__value__> returned_values;
  __box__ box_region(...);
- index::query(rt, bgi::intersects(box_region), std::back_inserter(returned_values));
+ bgi::query(rt, bgi::intersects(box_region), std::back_inserter(returned_values));
 
-Use of pipe operator generating a range
+Range generated by `operator|`
 
  __box__ box_region(...);
- BOOST_FOREACH(__value__ & v, rt | index::adaptors::queried(bgi::intersects(box_region)))
+ BOOST_FOREACH(__value__ & v, rt | bgi::adaptors::queried(bgi::intersects(box_region)))
    ; // do something with v
 
+Query iterators returned by member functions
+
+ std::vector<__value__> returned_values;
+ __box__ box_region(...);
+ std::copy(rt.qbegin(bgi::intersects(box_region)), rt.qend(), std::back_inserter(returned_values));
+
+Query iterators returned by free functions
+
+ std::vector<__value__> returned_values;
+ __box__ box_region(...);
+ std::copy(bgi::qbegin(rt, bgi::intersects(box_region)), bgi::qend(rt), std::back_inserter(returned_values));
+
 [h4 Spatial predicates]
 
 Queries using spatial predicates returns `__value__`s which are related somehow to some Geometry - box, polygon, etc.
-Names of spatial predicates correspond to names of __boost_geometry__ algorithms. Examples of some
-basic queries may be found in tables below. The query region and result `Value`s are orange.
+Names of spatial predicates correspond to names of __boost_geometry__ algorithms (boolean operations).
+Examples of some basic queries may be found in the tables below. The query region and result `Value`s are orange.
 
 [table
 [[intersects(Box)] [covered_by(Box)] [disjoint(Box)] [overlaps(Box)] [within(Box)]]
@@ -61,7 +73,7 @@
 [[[$img/index/rtree/intersects_ring.png]] [[$img/index/rtree/intersects_poly.png]] [[$img/index/rtree/intersects_mpoly.png]] [[$img/index/rtree/intersects_segment.png]] [[$img/index/rtree/intersects_linestring.png]]]
 ]
 
-To use a spatial predicate one may use one of the functions defined in `boost::geometry::index` namespace.
+Spatial predicates are generated by functions defined in `boost::geometry::index` namespace.
 
  rt.query(index::contains(box), std::back_inserter(result));
  rt.query(index::covered_by(box), std::back_inserter(result));
@@ -77,38 +89,21 @@
  // the same as
  rt.query(index::disjoint(box), std::back_inserter(result));
 
-[h4 Distance predicates]
-
-[h5 Nearest neighbours queries]
+[h4 Nearest neighbours queries]
 
 Nearest neighbours queries returns `__value__`s which are closest to some point in space.
 The example of knn query is presented below. 5 `__value__`s nearest to the point are orange.
 
 [$img/index/rtree/knn.png]
 
-[h5 k nearest neighbours]
-
-There are three ways of performing knn queries. Following queries returns
-`k` `__value__`s closest to some point in space. For `__box__`es
-`__indexable__`s the distance to the nearest point is calculated by default.
-
-Method call
-
- std::vector<__value__> returned_values;
- __point__ pt(...);
- rt.query(index::nearest(pt, k), std::back_inserter(returned_values));
-
-Function call
+To perform the knn query one must pass the nearest predicate generated by the
+`nearest()` function defined in `boost::geometry::index` namespace.
+The following query returns `k` `__value__`s closest to some point in space.
+For non-point `__indexable__`s the shortest distance is calculated.
 
  std::vector<__value__> returned_values;
  __point__ pt(...);
- index::query(rt, index::nearest(pt, k), std::back_inserter(returned_values));
-
-Use of `operator |`
-
- __point__ pt(...);
- BOOST_FOREACH(__value__ & v, rt | index::adaptors::queried(index::nearest(pt, k)))
-   ; // do something with v
+ rt.query(bgi::nearest(pt, k), std::back_inserter(returned_values));
 
 [h4 User-defined unary predicate]
 
@@ -178,6 +173,19 @@
  BOOST_FOREACH(Value & v, rt | index::adaptors::queried(index::nearest(pt, k) && index::covered_by(b)))
    ; // do something with v
 
+[h4 Breaking or pausing the query]
+
+By use of query iterators, the query may be paused and resumed if needed, e.g. when the query takes too long,
+or stopped at some point, e.g when all interesting values were gathered.
+
+ for ( Rtree::const_query_iterator it = tree.qbegin(bgi::nearest(pt, 10000)) ;
+       it != tree.qend() ; ++it )
+ {
+     // do something with value
+     if ( has_enough_nearest_values() )
+         break;
+ }
+
 [h4 Inserting query results into the other R-tree]
 
 There are several ways of inserting Values returned by a query to the other R-tree container.