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

Subject: [Boost-commit] svn:boost r84172 - in trunk/libs/geometry/doc: . index index/rtree
From: adam.wulkiewicz_at_[hidden]
Date: 2013-05-06 12:24:12

Author: awulkiew
Date: 2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
New Revision: 84172
URL: http://svn.boost.org/trac/boost/changeset/84172

Log:
geometry.index docs: created 'Experimental' section in R-tree docs, nearest() point relations moved to this section, added description of experimental query iterators.
Added:
   trunk/libs/geometry/doc/index/rtree/experimental.qbk   (contents, props changed)
Text files modified: 
   trunk/libs/geometry/doc/index/make_qbk.py     |     3 ++-                                     
   trunk/libs/geometry/doc/index/rtree.qbk       |     3 ++-                                     
   trunk/libs/geometry/doc/index/rtree/query.qbk |    20 ++------------------                    
   trunk/libs/geometry/doc/quickref.xml          |     7 ++++---                                 
   trunk/libs/geometry/doc/reference.qbk         |     3 ++-                                     
   5 files changed, 12 insertions(+), 24 deletions(-)

Modified: trunk/libs/geometry/doc/index/make_qbk.py
==============================================================================
--- trunk/libs/geometry/doc/index/make_qbk.py	(original)
+++ trunk/libs/geometry/doc/index/make_qbk.py	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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_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"))
 

Modified: trunk/libs/geometry/doc/index/rtree.qbk
==============================================================================
--- trunk/libs/geometry/doc/index/rtree.qbk	(original)
+++ trunk/libs/geometry/doc/index/rtree.qbk	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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]

Added: trunk/libs/geometry/doc/index/rtree/experimental.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/geometry/doc/index/rtree/experimental.qbk	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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 /]

Modified: trunk/libs/geometry/doc/index/rtree/query.qbk
==============================================================================
--- trunk/libs/geometry/doc/index/rtree/query.qbk	(original)
+++ trunk/libs/geometry/doc/index/rtree/query.qbk	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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 @@
 
 [$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 @@
 
 [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.

Modified: trunk/libs/geometry/doc/quickref.xml
==============================================================================
--- trunk/libs/geometry/doc/quickref.xml	(original)
+++ trunk/libs/geometry/doc/quickref.xml	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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>

Modified: trunk/libs/geometry/doc/reference.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference.qbk	(original)
+++ trunk/libs/geometry/doc/reference.qbk	2013-05-06 12:24:11 EDT (Mon, 06 May 2013)
@@ -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]