ceph/src/boost/libs/geometry/doc/index/rtree/experimental.qbk

   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
  13 This section describes experimental features which are implemented but unavailable by default.
  14 Be aware that they may not be released in the future or functionalities may be released but
  15 behind different interface.
  16
  17 To enable them one must define `BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL` in compiler's command line or before
  18 including spatial index.
  19
  20 [heading Nearest query distance calculation]
  21
  22 It is possible to define how distance to the non-point `__value__` should be calculated. To do this one may pass
  23 a 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
  36 Path query returns `k` first `__value__`s intersecting a path defined by a `Segment` or a`Linestring`. The result of a query returning first 5
  37 values 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
  41 To perform this query one may pass a `path()` predicate taking a `Segment` or a `Linestring` and maximum number of `__value__`s which
  42 should 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
  51 Sometimes there is a need to stop querying at some desired moment because for example the decision that query should find another value
  52 is made after analysis of previously returned values. There can also be desirable to pause querying and resume it later.
  53
  54 Currently, those kind of incremental queries are implemented as input (single pass) const iterators, relatively
  55 big fat-iterators storing stack used in the tree-traversing process. Because the type of predicates passed
  56 to the query varies, the type of the iterator varies as well.
  57
  58 Therefore to use query iterators one must pass them to some function template, then types will be deduced
  59 automatically. If iterators objects must be stored one may use Boost.Typeof library to retrieve a type from
  60 an 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
  81 with 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`
  83 iterators 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 /]