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*>
{