[Boost-commit] svn:boost r80150 - in sandbox-branches/geometry/index/boost/geometry/extensions/index: rtree translator

Subject: [Boost-commit] svn:boost r80150 - in sandbox-branches/geometry/index/boost/geometry/extensions/index: rtree translator
From: adam.wulkiewicz_at_[hidden]
Date: 2012-08-22 20:51:24

Author: awulkiew
Date: 2012-08-22 20:51:24 EDT (Wed, 22 Aug 2012)
New Revision: 80150
URL: http://svn.boost.org/trac/boost/changeset/80150

Log:
r-tree methods description expanded, default translator description added
Text files modified: 
   sandbox-branches/geometry/index/boost/geometry/extensions/index/rtree/rtree.hpp    |    86 ++++++++++++++++++++++++++++++++++----- 
   sandbox-branches/geometry/index/boost/geometry/extensions/index/translator/def.hpp |    13 ++++++                                  
   2 files changed, 88 insertions(+), 11 deletions(-)

Modified: sandbox-branches/geometry/index/boost/geometry/extensions/index/rtree/rtree.hpp
==============================================================================
--- sandbox-branches/geometry/index/boost/geometry/extensions/index/rtree/rtree.hpp	(original)
+++ sandbox-branches/geometry/index/boost/geometry/extensions/index/rtree/rtree.hpp	2012-08-22 20:51:24 EDT (Wed, 22 Aug 2012)
@@ -47,11 +47,22 @@
 namespace boost { namespace geometry { namespace index {
 
 /*!
-The R-tree spatial index.
+The R-tree spatial index. This is self-balancing spatial index capable to store various types
+of Values and balancing algorithms.
 
 \tparam Value       The type of objects stored in the container.
-\tparam Parameters  Compile-time parameters.
-\tparam Translator  The type of the translator.
+\tparam Parameters  Compile-time parameters. The user must pass a type defining the Parameters which will
+                    be used in rtree creation process. This type is used e.g. to specify balancing algorithm
+                    with compile-time parameters like min and max number of elements in node.
+                    Predefined Algorithms/Parameters are:
+                    bgi::linear<MinElements, MaxElements>,
+                    bgi::quadratic<MinElements, MaxElements>,
+                    bgi::rstar<MinElements, MaxElements, OverlapCostThreshold = 0, ReinsertedElements = MaxElements * 0.3>.
+\tparam Translator  The type of the translator which translates from Value to Indexable. This translation is done each time
+                    the r-tree wants to know Value's Indexable. Default translator can translate all types adapted to Point
+                    or Box concepts (which are Indexables). It also handles std::pair<Indexable, T>, pointers, smart pointers,
+                    and iterators. E.g. If std::pair<Box, int> is stored, the default translator translates from
+                    std::pair<Box, int> const& to Box const&.
 \tparam Allocator   The allocator.
 */
 template <
@@ -339,8 +350,16 @@
     /*!
     Find values meeting spatial predicates, e.g. intersecting some box.
 
-    \param pred     The spatial predicates.
-    \param out_it   The output iterator of the result range. E.g. a back_insert_iterator.
+    \param pred     The spatial predicates. May be a Geometry (in this case default
+                    predicate - intersects is used) or generated by bgi::covered_by(geometry),
+                    bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry),
+                    bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry),
+                    !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry)
+                    or bgi::value(func). Those predicates may be passed together in std::pair
+                    or boost::tuple.
+                    
+    \param out_it   The output iterator of the result range. E.g. an iterator generated by
+                    std::back_inserter(container)
 
     \return         The number of values found.
     */
@@ -358,7 +377,16 @@
     /*!
     Find one value meeting distances predicates, e.g. nearest to some point.
 
-    \param dpred    The distances predicates.
+    \param dpred    The distances predicates. May be a Point. This is default case where Value which
+                    nearest point is closest to Point is returned. May be a PointRelation which define
+                    how distance to Value is calculated. This may be generated by bgi::near(Point),
+                    bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances
+                    bounds. E.g. that some distance must be between min_distance and max_distance. This may
+                    be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation),
+                    bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation).
+                    MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound),
+                    bgi::centroid(dist_bound) or bgi::far(dist_bound).
+
     \param v        The reference to the object which will contain the result.
 
     \return         The number of values found.
@@ -373,8 +401,22 @@
     Find one value meeting distances predicates and spatial predicates,
     e.g. nearest to some point and intersecting some box.
 
-    \param dpred    The distances predicates.
-    \param pred     The spatial predicates.
+    \param dpred    The distances predicates. May be a Point. This is default case where Value which
+                    nearest point is closest to Point is returned. May be a PointRelation which define
+                    how distance to Value is calculated. This may be generated by bgi::near(Point),
+                    bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances
+                    bounds. E.g. that some distance must be between min_distance and max_distance. This may
+                    be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation),
+                    bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation).
+                    MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound),
+                    bgi::centroid(dist_bound) or bgi::far(dist_bound).
+    \param pred     The spatial predicates. May be a Geometry (in this case default
+                    predicate - intersects is used) or generated by bgi::covered_by(geometry),
+                    bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry),
+                    bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry),
+                    !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry)
+                    or bgi::value(func). Those predicates may be passed together in std::pair
+                    or boost::tuple.
     \param v        The reference to the object which will contain the result.
 
     \return         The number of values found.
@@ -388,7 +430,15 @@
     /*!
     Find k values meeting distances predicates, e.g. k nearest values to some point.
 
-    \param dpred    The distance predicate.
+    \param dpred    The distances predicates. May be a Point. This is default case where Value which
+                    nearest point is closest to Point is returned. May be a PointRelation which define
+                    how distance to Value is calculated. This may be generated by bgi::near(Point),
+                    bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances
+                    bounds. E.g. that some distance must be between min_distance and max_distance. This may
+                    be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation),
+                    bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation).
+                    MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound),
+                    bgi::centroid(dist_bound) or bgi::far(dist_bound).
     \param k        The max number of values.
     \param out_it   The output iterator of the result range. E.g. a back_insert_iterator.
 
@@ -404,9 +454,23 @@
     Find k values meeting distances predicates and spatial predicates,
     e.g. k nearest values to some point and intersecting some box.
 
-    \param dpred    The distances predicates.
+    \param dpred    The distances predicates. May be a Point. This is default case where Value which
+                    nearest point is closest to Point is returned. May be a PointRelation which define
+                    how distance to Value is calculated. This may be generated by bgi::near(Point),
+                    bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances
+                    bounds. E.g. that some distance must be between min_distance and max_distance. This may
+                    be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation),
+                    bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation).
+                    MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound),
+                    bgi::centroid(dist_bound) or bgi::far(dist_bound).
     \param k        The max number of values.
-    \param pred     The spatial predicates.
+    \param pred     The spatial predicates. May be a Geometry (in this case default
+                    predicate - intersects is used) or generated by bgi::covered_by(geometry),
+                    bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry),
+                    bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry),
+                    !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry)
+                    or bgi::value(func). Those predicates may be passed together in std::pair
+                    or boost::tuple.
     \param out_it   The output iterator of the result range. E.g. a back_insert_iterator.
 
     \return         The number of values found.

Modified: sandbox-branches/geometry/index/boost/geometry/extensions/index/translator/def.hpp
==============================================================================
--- sandbox-branches/geometry/index/boost/geometry/extensions/index/translator/def.hpp	(original)
+++ sandbox-branches/geometry/index/boost/geometry/extensions/index/translator/def.hpp	2012-08-22 20:51:24 EDT (Wed, 22 Aug 2012)
@@ -71,6 +71,12 @@
 
 } // namespace dispatch
 
+/*!
+The default translator. It translates Value object to Indexable object. This is done in
+operator() which takes const reference to Value and returns const reference to Indexable.
+
+\tparam Value       The Value type which the translator translates to Indexable.
+*/
 template <typename Value>
 struct def
     : public dispatch::def
@@ -82,6 +88,13 @@
 {
 };
 
+/*!
+The default translator. It translates Value object to Indexable object. Since this is
+a specialization for pointers to Values operator() takes const ptr to Value and returns
+const reference to Indexable.
+
+\tparam Value       The Value type which the translator translates to Indexable.
+*/
 template <typename Value>
 struct def<Value*>
 {