geometry.index docs: created 'Experimental' section in R-tree docs, nearest() point relations moved to this section, added description of experimental query iterators.

[SVN r84172]
2025-05-09 23:24:02 +00:00 · 2013-05-06 16:24:11 +00:00 · 2013-05-06 16:24:11 +00:00 · c5b6130f30
commit c5b6130f30
parent 03da86e962
6 changed files with 108 additions and 24 deletions
--- a/doc/index/make_qbk.py
+++ b/doc/index/make_qbk.py
@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 # ===========================================================================
 #  Copyright (c) 2011-2012 Barend Gehrels, Amsterdam, the Netherlands.
+#  Copyright (c) 2011-2013 Adam Wulkiewicz, Lodz, Poland.
 # 
 #  Use, modification and distribution is subject to the Boost Software License,
 #  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@ -31,7 +32,7 @@ os.system(cmd % ("structboost_1_1geometry_1_1index_1_1indexable", "indexable"))
 os.system(cmd % ("structboost_1_1geometry_1_1index_1_1equal__to", "equal_to"))

 os.system(cmd % ("group__predicates", "predicates"))
-os.system(cmd % ("group__nearest__relations", "nearest_relations"))
+#os.system(cmd % ("group__nearest__relations", "nearest_relations"))
 os.system(cmd % ("group__adaptors", "adaptors"))
 os.system(cmd % ("group__inserters", "inserters"))

--- a/doc/index/rtree.qbk
+++ b/doc/index/rtree.qbk
@ -15,6 +15,7 @@
 [include rtree/creation.qbk]
 [include rtree/query.qbk]
 [include rtree/examples.qbk]
-[/include rtree/reference.qbk/]
+[include rtree/experimental.qbk]
+[/include rtree/reference.qbk]

 [endsect]
--- a/doc/index/rtree/experimental.qbk
+++ b/doc/index/rtree/experimental.qbk
@ -0,0 +1,96 @@
+[/============================================================================
+  Boost.Geometry Index
+
+  Copyright (c) 2011-2013 Adam Wulkiewicz.
+
+  Use, modification and distribution is subject to the Boost Software License,
+  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+  http://www.boost.org/LICENSE_1_0.txt)
+=============================================================================/]
+
+[section Experimental features]
+
+This section describes experimental features which are implemented but unavailable by default.
+Be aware that they may not be released in the future or functionalities may be released but
+behind different interface.
+
+To enable them one must define `BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL` in compiler's command line or before
+including spatial index.
+
+[heading Nearest query distance calculation]
+
+It is possible to define how distance to the non-point `__value__` should be calculated. To do this one may pass
+a relation object instead of a Point to the nearest predicate, as follows:
+
+ /* caluclate distance to the Indexables' nearest points */
+ rtree.query(index::nearest(index::to_nearest(pt), k), std::back_inserter(returned_values)); // same as default
+
+ /* caluclate distance to the Indexables' centroid */
+ rtree.query(index::nearest(index::to_centroid(pt), k), std::back_inserter(returned_values));
+
+ /* caluclate distance to the Indexables' furthest points */
+ rtree.query(index::nearest(index::to_furthest(pt), k), std::back_inserter(returned_values));
+
+[heading Incremental queries]
+
+Sometimes there is a need to brake querying at some desired point because it depends on objects already
+returned or to pause it in order to resume later. For this purpose iterators may be used.
+
+In this library incremental queries are implemented as input (single pass) const iterators, relatively
+big fat-iterators storing stack used in the tree-traversing process. Because the type of predicates passed
+to the query varies, the type of the iterator varies as well.
+
+Therefore to use query iterators one must pass them to some function template, then types will be deduced
+automatically. If iterators objects must be stored one may use Boost.Typeof library to retrieve a type from
+an expression or use C++11 `auto` or `decltype`.
+
+ /* function call */
+ std::copy(rtree.qbegin(index::intersects(box)), rtree.qend(index::intersects(box)), std::back_inserter(returned_values));
+ 
+ /* Boost.Typeof */
+ typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator;
+ const_query_iterator first = rtree.qbegin(index::nearest(pt, 5));
+ const_query_iterator last = rtree.qend(index::nearest(pt, 5));
+ // ...
+ for ( ; first != last ; ++first )
+     *first; // do domething with Value
+ 
+ /* C++11 */
+ auto first = rtree.qbegin(index::nearest(pt, 5));
+ auto last = rtree.qend(index::nearest(pt, 5));
+ // ...
+ for ( ; first != last ; ++first )
+     *first; // do domething with Value
+
+`qend()` method is overloaded to return a different, lighter type of iterator which may be compared
+with query iterator to check if the querying was finished. But since it has different type than the one returned by
+`qbegin(Pred)` it can't be used with STL-like functions like `std::copy()` which expect that `first` and `last`
+iterators have the same type.
+
+ /* function call */
+ template <typename First, typename Last, typename Out>
+ void my_copy(First first, Last last, Out out)
+ {
+     for ( ; first != last ; ++out, ++first )
+         *out = *first;
+ }
+ // ...
+ my_copy(rtree.qbegin(index::intersects(box)), rtree.qend(), std::back_inserter(returned_values));
+ 
+ /* Boost.Typeof */
+ typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator;
+ typedef BOOST_TYPEOF(rtree.qend()) end_iterator;
+ const_query_iterator first = rtree.qbegin(index::nearest(pt, 5));
+ end_iterator last = rtree.qend();
+ // ...
+ for ( ; first != last ; ++first )
+     *first; // do domething with Value
+ 
+ /* C++11 */
+ auto first = rtree.qbegin(index::nearest(pt, 5));
+ auto last = rtree.qend();
+ // ...
+ for ( ; first != last ; ++first )
+     *first; // do domething with Value
+
+[endsect] [/ Experimental features /]
--- a/doc/index/rtree/query.qbk
+++ b/doc/index/rtree/query.qbk
@ -1,7 +1,7 @@
 [/============================================================================
  Boost.Geometry Index

-  Copyright (c) 2011-2012 Adam Wulkiewicz.
+  Copyright (c) 2011-2013 Adam Wulkiewicz.

  Use, modification and distribution is subject to the Boost Software License,
  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@ -87,7 +87,7 @@ The example of knn query is presented below. 5 `__value__`s nearest to some poin

 [$img/index/rtree/knn.png]

-[section k nearest neighbours]
+[heading 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
@ -113,22 +113,6 @@ Use of `operator |`

 [endsect]

-[section Distance calculation]
-
-It is possible to define how distance to the non-point `__value__` should be calculated. To do this one may pass
-a relation object generated as follows:
-
- /* caluclate distance to the Indexables' nearest points */
- tree::query(index::nearest(index::to_nearest(pt), k), std::back_inserter(returned_values)); // default
- /* caluclate distance to the Indexables' centroid */
- tree::query(index::nearest(index::to_centroid(pt), k), std::back_inserter(returned_values));
- /* caluclate distance to the Indexables' furthest points */
- tree::query(index::nearest(index::to_furthest(pt), k), std::back_inserter(returned_values));
-
-[endsect]
-
-[endsect]
-
 [section User-defined unary predicate]

 The user may pass a `UnaryPredicate` - function, function object or lambda expression taking const reference to Value and returning bool.
--- a/doc/quickref.xml
+++ b/doc/quickref.xml
@ -8,6 +8,7 @@
  Copyright (c) 2009-2011 Mateusz Loskot, London, UK.
  Copyright (c) 2009-2011 Barend Gehrels, Amsterdam, the Netherlands.
  Copyright (c) 2009-2011 Bruno Lalande, Paris, France.
+  Copyright (c) 2013 Adam Wulkiewicz, Lodz, Poland.

  Use, modification and distribution is subject to the Boost Software License,
  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@ -733,17 +734,17 @@
 	 <member><link linkend="geometry.reference.spatial_indexes.group__predicates.overlaps_geometry_const___">overlaps(Geometry const &amp;)</link></member>
 	 <member><link linkend="geometry.reference.spatial_indexes.group__predicates.within_geometry_const___">within(Geometry const &amp;)</link></member>
 	 <member><link linkend="geometry.reference.spatial_indexes.group__predicates.satisfies_unarypredicate_const___">satisfies(UnaryPredicate const &amp;)</link></member>
-	 <member><link linkend="geometry.reference.spatial_indexes.group__predicates.nearest_pointorrelation_const____unsigned_">nearest(PointOrRelation const &amp;, unsigned)</link></member>
+	 <member><link linkend="geometry.reference.spatial_indexes.group__predicates.nearest_point_const____unsigned_">nearest(Point const &amp;, unsigned)</link></member>
    </simplelist>
   </entry>
-   <entry valign="top">
+   <!--entry valign="top">
    <bridgehead renderas="sect3">Nearest relations (boost::geometry::index::)</bridgehead>
    <simplelist type="vert" columns="1">
     <member><link linkend="geometry.reference.spatial_indexes.group__nearest__relations.to_nearest_t_const___">to_nearest(T const &amp;)</link></member>
 	 <member><link linkend="geometry.reference.spatial_indexes.group__nearest__relations.to_centroid_t_const___">to_centroid(T const &amp;)</link></member>
 	 <member><link linkend="geometry.reference.spatial_indexes.group__nearest__relations.to_furthest_t_const___">to_furthest(T const &amp;) </link></member>
    </simplelist>
-   </entry>
+   </entry-->
  </row>
 </tbody>
 </tgroup>
--- a/doc/reference.qbk
+++ b/doc/reference.qbk
@ -4,6 +4,7 @@
  Copyright (c) 2009-2012 Barend Gehrels, Amsterdam, the Netherlands.
  Copyright (c) 2009-2012 Mateusz Loskot, London, UK.
  Copyright (c) 2009-2012 Bruno Lalande, Paris, France.
+  Copyright (c) 2013 Adam Wulkiewicz, Lodz, Poland.

  Use, modification and distribution is subject to the Boost Software License,
  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@ -264,7 +265,7 @@
 [include index/generated/adaptors.qbk]

 [include index/generated/predicates.qbk]
-[include index/generated/nearest_relations.qbk]
+[/include index/generated/nearest_relations.qbk]

 [endsect]