[Boost-commit] svn:boost r80149 - sandbox-branches/geometry/index/boost/geometry/extensions/index

Subject: [Boost-commit] svn:boost r80149 - sandbox-branches/geometry/index/boost/geometry/extensions/index
From: adam.wulkiewicz_at_[hidden]
Date: 2012-08-22 19:32:02

Author: awulkiew
Date: 2012-08-22 19:32:01 EDT (Wed, 22 Aug 2012)
New Revision: 80149
URL: http://svn.boost.org/trac/boost/changeset/80149

Log:
Description of predicates and distance_predicates added.
Text files modified: 
   sandbox-branches/geometry/index/boost/geometry/extensions/index/distance_predicates.hpp |    98 ++++++++++++++++++++++++++++++++        
   sandbox-branches/geometry/index/boost/geometry/extensions/index/predicates.hpp          |   119 ++++++++++++++++++++++++++++++++++++++++
   2 files changed, 217 insertions(+), 0 deletions(-)

Modified: sandbox-branches/geometry/index/boost/geometry/extensions/index/distance_predicates.hpp
==============================================================================
--- sandbox-branches/geometry/index/boost/geometry/extensions/index/distance_predicates.hpp	(original)
+++ sandbox-branches/geometry/index/boost/geometry/extensions/index/distance_predicates.hpp	2012-08-22 19:32:01 EDT (Wed, 22 Aug 2012)
@@ -100,18 +100,56 @@
 
 // relations generators
 
+/*!
+Generate a nearest query Point and Value's Indexable relationship while calculating
+distances. This function may be used to define that knn query should calculate distances
+as smallest as possible between query Point and Indexable's points. In other words it
+should be the distance to the nearest Indexable's point. This function may be also used
+to define distances bounds which indicates that Indexable's nearest point should be
+closer or further than value v. This is default relation.
+
+\tparam T   Type of wrapped object. This may be a Point for PointRelation or some Value for
+            MinRelation or MaxRelation
+
+\param v    Point or bound value.
+*/
 template <typename T>
 detail::near<T> near(T const& v)
 {
     return detail::near<T>(v);
 }
 
+/*!
+Generate a nearest query Point and Value's Indexable relationship while calculating
+distances. This function may be used to define that knn query should calculate distances
+between query Point and Indexable's centroid. This function may be also used
+to define distances bounds which indicates that Indexable's centroid should be
+closer or further than value v.
+
+\tparam T   Type of wrapped object. This may be a Point for PointRelation or some Value for
+            MinRelation or MaxRelation
+
+\param v    Point or bound value.
+*/
 template <typename T>
 detail::centroid<T> centroid(T const& v)
 {
     return detail::centroid<T>(v);
 }
 
+/*!
+Generate a nearest query Point and Value's Indexable relationship while calculating
+distances. This function may be used to define that knn query should calculate distances
+as biggest as possible between query Point and Indexable's points. In other words it
+should be the distance to the furthest Indexable's point. This function may be also used
+to define distances bounds which indicates that Indexable's furthest point should be
+closer or further than value v.
+
+\tparam T   Type of wrapped object. This may be a Point for PointRelation or some Value for
+            MinRelation or MaxRelation
+
+\param v    Point or bound value.
+*/
 template <typename T>
 detail::far<T> far(T const& v)
 {
@@ -197,6 +235,17 @@
 
 // distance predicates generators
 
+/*!
+Generate a distance predicate. This defines distances bounds which are used by knn query.
+This function indicates that there is no distance bounds and Values should be returned
+if distances between Point and Indexable are the smallest. Distance calculation is defined
+by PointRelation. This is default nearest predicate.
+
+\tparam PointRelation   PointRelation type.
+
+\param pr               The point relation. This may be generated by bgi::near(Point),
+                        bgi::centroid(Point) or bgi::far(Point).
+*/
 template <typename PointRelation>
 inline detail::unbounded<PointRelation>
 unbounded(PointRelation const& pr)
@@ -204,6 +253,21 @@
     return detail::unbounded<PointRelation>(pr);
 }
 
+/*!
+Generate a distance predicate. This defines distances bounds which are used by knn query.
+This function indicates that Values should be returned only if distances between Point and
+Indexable are greater or equal to some min_distance passed in MinRelation. Check for closest Value is
+defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
+Point but only if nearest points are further than some distance.
+
+\tparam PointRelation   PointRelation type.
+\tparam MinRelation     MinRelation type.
+
+\param pr               The point relation. This may be generated by bgi::near(Point),
+                        bgi::centroid(Point) or bgi::far(Point).
+\param minr             The minimum bound relation. This may be generated by bgi::near(min_distance),
+                        bgi::centroid(min_distance) or bgi::far(min_distance).
+*/
 template <typename PointRelation, typename MinRelation>
 inline detail::min_bounded<PointRelation, MinRelation>
 min_bounded(PointRelation const& pr, MinRelation const& minr)
@@ -211,6 +275,21 @@
     return detail::min_bounded<PointRelation, MinRelation>(pr, minr);
 }
 
+/*!
+Generate a distance predicate. This defines distances bounds which are used by knn query.
+This function indicates that Values should be returned only if distances between Point and
+Indexable are lesser or equal to some max_distance passed in MaxRelation. Check for closest Value is
+defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
+Point but only if nearest points are closer than some distance.
+
+\tparam PointRelation   PointRelation type.
+\tparam MaxRelation     MaxRelation type.
+
+\param pr               The point relation. This may be generated by bgi::near(Point),
+                        bgi::centroid(Point) or bgi::far(Point).
+\param maxr             The maximum bound relation. This may be generated by bgi::near(max_distance),
+                        bgi::centroid(max_distance) or bgi::far(max_distance).
+*/
 template <typename PointRelation, typename MaxRelation>
 inline detail::max_bounded<PointRelation, MaxRelation>
 max_bounded(PointRelation const& pr, MaxRelation const& maxr)
@@ -218,6 +297,25 @@
     return detail::max_bounded<PointRelation, MaxRelation>(pr, maxr);
 }
 
+/*!
+Generate a distance predicate. This defines distances bounds which are used by knn query.
+This function indicates that Values should be returned only if distances between Point and
+Indexable are greater or equal to some min_distance passed in MinRelation and lesser or equal to
+some max_distance passed in MaxRelation. Check for closest Value is defined by PointRelation.
+So it is possible e.g. to return Values with centroids closest to some Point but only if nearest
+points are further than some distance and closer than some other distance.
+
+\tparam PointRelation   PointRelation type.
+\tparam MinRelation     MinRelation type.
+\tparam MaxRelation     MaxRelation type.
+
+\param pr               The point relation. This may be generated by bgi::near(Point),
+                        bgi::centroid(Point) or bgi::far(Point).
+\param minr             The minimum bound relation. This may be generated by bgi::near(min_distance),
+                        bgi::centroid(min_distance) or bgi::far(min_distance).
+\param maxr             The maximum bound relation. This may be generated by bgi::near(max_distance),
+                        bgi::centroid(max_distance) or bgi::far(max_distance).
+*/
 template <typename PointRelation, typename MinRelation, typename MaxRelation>
 inline detail::bounded<PointRelation, MinRelation, MaxRelation>
 bounded(PointRelation const& pr, MinRelation const& minr, MaxRelation const& maxr)

Modified: sandbox-branches/geometry/index/boost/geometry/extensions/index/predicates.hpp
==============================================================================
--- sandbox-branches/geometry/index/boost/geometry/extensions/index/predicates.hpp	(original)
+++ sandbox-branches/geometry/index/boost/geometry/extensions/index/predicates.hpp	2012-08-22 19:32:01 EDT (Wed, 22 Aug 2012)
@@ -120,83 +120,202 @@
 
 // generators
 
+/*!
+Generate empty predicate.
+*/
 inline detail::empty empty()
 {
     return detail::empty();
 }
 
+/*!
+Generate value predicate. A wrapper around user-defined functor
+describing if Value should be returned by spatial query.
+
+\tparam ValuePredicate  Functor type.
+
+\param vpred            The functor.
+*/
 template <typename ValuePredicate>
 inline detail::value<ValuePredicate> value(ValuePredicate const& vpred)
 {
     return detail::value<ValuePredicate>(vpred);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::covered_by(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::covered_by<Geometry> covered_by(Geometry const& g)
 {
     return detail::covered_by<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::disjoint(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::disjoint<Geometry> disjoint(Geometry const& g)
 {
     return detail::disjoint<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::intersects(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::intersects<Geometry> intersects(Geometry const& g)
 {
     return detail::intersects<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::overlaps(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::overlaps<Geometry> overlaps(Geometry const& g)
 {
     return detail::overlaps<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::touches(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 //template <typename Geometry>
 //inline detail::touches<Geometry> touches(Geometry const& g)
 //{
 //    return detail::touches<Geometry>(g);
 //}
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::within(Indexable, Geometry)
+returns true.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::within<Geometry> within(Geometry const& g)
 {
     return detail::within<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::covered_by(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::not_covered_by<Geometry> not_covered_by(Geometry const& g)
 {
     return detail::not_covered_by<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::disjoint(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::not_disjoint<Geometry> not_disjoint(Geometry const& g)
 {
     return detail::not_disjoint<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::intersects(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::not_intersects<Geometry> not_intersects(Geometry const& g)
 {
     return detail::not_intersects<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::overlaps(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::not_overlaps<Geometry> not_overlaps(Geometry const& g)
 {
     return detail::not_overlaps<Geometry>(g);
 }
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::touches(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 //template <typename Geometry>
 //inline detail::not_touches<Geometry> not_touches(Geometry const& g)
 //{
 //    return detail::not_touches<Geometry>(g);
 //}
 
+/*!
+Generate a predicate defining Value and Geometry relationship.
+Value will be returned by the query if bg::within(Indexable, Geometry)
+returns false.
+
+\tparam Geometry    The Geometry type.
+
+\param g            The Geometry object.
+*/
 template <typename Geometry>
 inline detail::not_within<Geometry> not_within(Geometry const& g)
 {