1[/============================================================================ 2 Boost.Geometry Index 3 4 Copyright (c) 2011-2013 Adam Wulkiewicz. 5 6 Use, modification and distribution is subject to the Boost Software License, 7 Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 8 http://www.boost.org/LICENSE_1_0.txt) 9=============================================================================/] 10 11[section Experimental Features] 12 13This section describes experimental features which are implemented but unavailable by default. 14Be aware that they may not be released in the future or functionalities may be released but 15behind different interface. 16 17To enable them one must define `BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL` in compiler's command line or before 18including spatial index. 19 20[heading Nearest query distance calculation] 21 22It is possible to define how distance to the non-point `__value__` should be calculated. To do this one may pass 23a relation object instead of a Point to the nearest predicate, as follows: 24 25 /* calculate distance to the Indexables' nearest points */ 26 rtree.query(index::nearest(index::to_nearest(pt), k), std::back_inserter(returned_values)); // same as default 27 28 /* calculate distance to the Indexables' centroid */ 29 rtree.query(index::nearest(index::to_centroid(pt), k), std::back_inserter(returned_values)); 30 31 /* calculate distance to the Indexables' furthest points */ 32 rtree.query(index::nearest(index::to_furthest(pt), k), std::back_inserter(returned_values)); 33 34[heading Path query] 35 36Path query returns `k` first `__value__`s intersecting a path defined by a `Segment` or a`Linestring`. The result of a query returning first 5 37values intersecting a path is presented below. Path's flow is denoted by blue arrows, returned values are orange. 38 39[$img/index/rtree/path.png] 40 41To perform this query one may pass a `path()` predicate taking a `Segment` or a `Linestring` and maximum number of `__value__`s which 42should be returned: 43 44 rtree.query(index::path(segment, k), std::back_inserter(returned_values)); 45 rtree.query(index::path(linestring, k), std::back_inserter(returned_values)); 46 47[warning Only one distance predicate may be used in a query. This means that there can be only one `nearest()` or `path()` predicate passed. Passing more of them will result in compile-time error.] 48 49[heading Incremental queries] 50 51Sometimes there is a need to stop querying at some desired moment because for example the decision that query should find another value 52is made after analysis of previously returned values. There can also be desirable to pause querying and resume it later. 53 54Currently, those kind of incremental queries are implemented as input (single pass) const iterators, relatively 55big fat-iterators storing stack used in the tree-traversing process. Because the type of predicates passed 56to the query varies, the type of the iterator varies as well. 57 58Therefore to use query iterators one must pass them to some function template, then types will be deduced 59automatically. If iterators objects must be stored one may use Boost.Typeof library to retrieve a type from 60an expression or use C++11 `auto` or `decltype`. 61 62 /* function call */ 63 std::copy(rtree.qbegin(index::intersects(box)), rtree.qend(index::intersects(box)), std::back_inserter(returned_values)); 64 65 /* Boost.Typeof */ 66 typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator; 67 const_query_iterator first = rtree.qbegin(index::nearest(pt, 5)); 68 const_query_iterator last = rtree.qend(index::nearest(pt, 5)); 69 // ... 70 for ( ; first != last ; ++first ) 71 *first; // do something with Value 72 73 /* C++11 */ 74 auto first = rtree.qbegin(index::nearest(pt, 5)); 75 auto last = rtree.qend(index::nearest(pt, 5)); 76 // ... 77 for ( ; first != last ; ++first ) 78 *first; // do something with Value 79 80`qend()` method is overloaded to return a different, lighter type of iterator which may be compared 81with query iterator to check if the querying was finished. But since it has different type than the one returned by 82`qbegin(Pred)` it can't be used with STL-like functions like `std::copy()` which expect that `first` and `last` 83iterators have the same type. 84 85 /* function call */ 86 template <typename First, typename Last, typename Out> 87 void my_copy(First first, Last last, Out out) 88 { 89 for ( ; first != last ; ++out, ++first ) 90 *out = *first; 91 } 92 // ... 93 my_copy(rtree.qbegin(index::intersects(box)), rtree.qend(), std::back_inserter(returned_values)); 94 95 /* Boost.Typeof */ 96 typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator; 97 typedef BOOST_TYPEOF(rtree.qend()) end_iterator; 98 const_query_iterator first = rtree.qbegin(index::nearest(pt, 5)); 99 end_iterator last = rtree.qend(); 100 // ... 101 for ( ; first != last ; ++first ) 102 *first; // do something with Value 103 104 /* C++11 */ 105 auto first = rtree.qbegin(index::nearest(pt, 5)); 106 auto last = rtree.qend(); 107 // ... 108 for ( ; first != last ; ++first ) 109 *first; // do something with Value 110 111[endsect] [/ Experimental features /] 112
