Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r68869 - in trunk/libs/geometry/doc: . doxy ref/algorithms reference src/docutils/tools/doxygen_xml2qbk src/examples/algorithms
From: barend.gehrels_at_[hidden]
Date: 2011-02-14 13:39:43


Author: barendgehrels
Date: 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
New Revision: 68869
URL: http://svn.boost.org/trac/boost/changeset/68869

Log:
Documentaton and samples for for_each
Fix - added default value in free functions
Added:
   trunk/libs/geometry/doc/src/examples/algorithms/for_each_point.cpp (contents, props changed)
   trunk/libs/geometry/doc/src/examples/algorithms/for_each_point_const.cpp (contents, props changed)
Text files modified:
   trunk/libs/geometry/doc/doxy/Doxyfile | 4 +++
   trunk/libs/geometry/doc/geometry.qbk | 2 +
   trunk/libs/geometry/doc/quickref.xml | 4 +++
   trunk/libs/geometry/doc/ref/algorithms/num_points.qbk | 2
   trunk/libs/geometry/doc/reference.qbk | 6 ++--
   trunk/libs/geometry/doc/reference/append.qbk | 2
   trunk/libs/geometry/doc/reference/buffer.qbk | 4 +-
   trunk/libs/geometry/doc/reference/distance_haversine.qbk | 2
   trunk/libs/geometry/doc/reference/for_each.qbk | 46 +++++++++++++++++++++++++++------------
   trunk/libs/geometry/doc/reference/num_points.qbk | 2
   trunk/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp | 1
   trunk/libs/geometry/doc/src/examples/algorithms/Jamfile.v2 | 3 ++
   12 files changed, 55 insertions(+), 23 deletions(-)

Modified: trunk/libs/geometry/doc/doxy/Doxyfile
==============================================================================
--- trunk/libs/geometry/doc/doxy/Doxyfile (original)
+++ trunk/libs/geometry/doc/doxy/Doxyfile 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -57,6 +57,7 @@
                         tparam_container="container type, for example std::vector, std::deque" \
                         tparam_dimension_required="Dimension, this template parameter is required. Should contain \[0 .. n-1\] for an n-dimensional geometry" \
                         tparam_first_point="first point type" \
+ tparam_functor="Function or class with operator()" \
                         tparam_geometry="Any type fulfilling a Geometry Concept" \
                         tparam_geometry{1}="A type fulfilling a \1 Concept" \
                         tparam_index_required="Index, this template parameter is required. For a Box: either min_corner or max_corner. For a Segment: either 0 or 1 for first or last point." \
@@ -97,8 +98,11 @@
                         return_check{1}="Returns true if the geometry \1" \
                         return_check2{1}="Returns true if two geometries \1" \
                         return_out="The output iterator" \
+ brf_for_each{1}="Applies function [*f] to each \1" \
                         det_envelope="envelope (also known as axis aligned bounding box, aabb, or minimum bounding rectangle, mbr)" \
                         det_buffer="buffer (a polygon being the spatial point set collection within a specified maximum distance from a geometry)" \
+ det_for_each{1}="Applies a function [*f] (functor, having operator() defined) to each \1 making up the geometry" \
+ par_for_each_f{1}="Unary function, taking a \1 as argument" \
                         macro_x="first (usually x)" \
                         macro_y="second (usually y)" \
                         macro_z="third (usually z)" \

Modified: trunk/libs/geometry/doc/geometry.qbk
==============================================================================
--- trunk/libs/geometry/doc/geometry.qbk (original)
+++ trunk/libs/geometry/doc/geometry.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -71,6 +71,8 @@
 [import src/examples/quick_start.cpp]
 [import src/examples/algorithms/area.cpp]
 [import src/examples/algorithms/area_with_strategy.cpp]
+[import src/examples/algorithms/for_each_point.cpp]
+[import src/examples/algorithms/for_each_point_const.cpp]
 [import src/examples/algorithms/length.cpp]
 [import src/examples/algorithms/length_with_strategy.cpp]
 [import src/examples/algorithms/intersection_ls_ls_point.cpp]

Modified: trunk/libs/geometry/doc/quickref.xml
==============================================================================
--- trunk/libs/geometry/doc/quickref.xml (original)
+++ trunk/libs/geometry/doc/quickref.xml 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -352,6 +352,10 @@
     <simplelist type="vert" columns="1">
      <member><link linkend="geometry.reference.algorithms.envelope">envelope</link></member>
     </simplelist>
+ <bridgehead renderas="sect3">For Each</bridgehead>
+ <simplelist type="vert" columns="1">
+ <member><link linkend="geometry.reference.algorithms.for_each">for each (point, segment)</link></member>
+ </simplelist>
     <bridgehead renderas="sect3">Intersection</bridgehead>
     <simplelist type="vert" columns="1">
      <member><link linkend="geometry.reference.algorithms.intersection">intersection</link></member>

Modified: trunk/libs/geometry/doc/ref/algorithms/num_points.qbk
==============================================================================
--- trunk/libs/geometry/doc/ref/algorithms/num_points.qbk (original)
+++ trunk/libs/geometry/doc/ref/algorithms/num_points.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -18,7 +18,7 @@
 [[__box__][[qbk_ret 4]]]
 [[__range__][[qbk_ret boost::size(geometry)]]]
 [[__other__][[qbk_ret the sum of the number of points of its elements]]]
-[[Open geometries][[qbk_ret the sum of the number of points of its elements, it adds one for open if specified]]]
+[[Open geometries][[qbk_ret the sum of the number of points of its elements, it adds one for open (per ring) if specified]]]
 [[Closed geometries][[qbk_ret the sum of the number of points of its elements]]]
 ]
 

Modified: trunk/libs/geometry/doc/reference.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference.qbk (original)
+++ trunk/libs/geometry/doc/reference.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -109,9 +109,9 @@
 [include reference/equals.qbk]
 [endsect]
 
-[/section:for_each for_each]
-[/include reference/for_each.qbk]
-[/endsect]
+[section:for_each for_each]
+[include reference/for_each.qbk]
+[endsect]
 
 [section:intersection intersection]
 [include reference/intersection.qbk]

Modified: trunk/libs/geometry/doc/reference/append.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference/append.qbk (original)
+++ trunk/libs/geometry/doc/reference/append.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -19,7 +19,7 @@
 
 [heading Synopsis]
 ``template<typename Geometry, typename RoP>
-void append(Geometry & geometry, RoP const & range_or_point, int ring_index, int multi_index)``
+void append(Geometry & geometry, RoP const & range_or_point, int ring_index = -1, int multi_index = 0)``
 
 [heading Parameters]
 

Modified: trunk/libs/geometry/doc/reference/buffer.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference/buffer.qbk (original)
+++ trunk/libs/geometry/doc/reference/buffer.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -22,7 +22,7 @@
 
 [heading Synopsis]
 ``template<typename Input, typename Output, typename Distance>
-void buffer(Input const & geometry_in, Output & geometry_out, Distance const & distance, Distance const & chord_length)``
+void buffer(Input const & geometry_in, Output & geometry_out, Distance const & distance, Distance const & chord_length = -1)``
 
 [heading Parameters]
 
@@ -58,7 +58,7 @@
 
 [heading Synopsis]
 ``template<typename Output, typename Input, typename T, >
-Output make_buffer(Input const & geometry, T const & distance, T const & chord_length)``
+Output make_buffer(Input const & geometry, T const & distance, T const & chord_length = -1)``
 
 [heading Parameters]
 

Modified: trunk/libs/geometry/doc/reference/distance_haversine.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference/distance_haversine.qbk (original)
+++ trunk/libs/geometry/doc/reference/distance_haversine.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -36,7 +36,7 @@
 [heading Constructor(s)]
 [table
 [[Function] [Description] [Parameters] ]
-[[``haversine( const & radius)``
+[[``haversine( const & radius = 1.0)``
 
 ] [Constructor. ] [[* const &]: ['radius]: radius of the sphere, defaults to 1.0 for the unit sphere
 

Modified: trunk/libs/geometry/doc/reference/for_each.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference/for_each.qbk (original)
+++ trunk/libs/geometry/doc/reference/for_each.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -15,7 +15,10 @@
 [/ Generated from doxy/doxygen_output/xml/group__for__each.xml]
 [section:for_each_point_2 for_each_point]
 
-Calls functor for geometry.
+Applies function [*f] to each point.
+
+[heading Description]
+Applies a function [*f] (functor, having operator() defined) to each point making up the geometry
 
 [heading Synopsis]
 ``template<typename Geometry, typename Functor>
@@ -25,8 +28,8 @@
 
 [table
 [[Type] [Concept] [Name] [Description] ]
-[[Geometry &] [] [geometry] [geometry to loop through ]]
-[[Functor] [] [f] [functor to use]]
+[[Geometry &] [Any type fulfilling a Geometry Concept ] [geometry] [A model of the specified concept ]]
+[[Functor] [Function or class with operator()] [f] [Unary function, taking a point as argument ]]
 ]
 
 
@@ -39,12 +42,18 @@
 
 `#include <boost/geometry/algorithms/for_each.hpp>`
 
+[heading Examples]
+[for_each_point] [for_each_point_output]
+
 
 [endsect]
 
-[section:for_each_point_2 for_each_point]
+[section:for_each_point_2_const_version for_each_point (const version)]
+
+Applies function [*f] to each point.
 
-Calls functor for geometry.
+[heading Description]
+Applies a function [*f] (functor, having operator() defined) to each point making up the geometry
 
 [heading Synopsis]
 ``template<typename Geometry, typename Functor>
@@ -54,8 +63,8 @@
 
 [table
 [[Type] [Concept] [Name] [Description] ]
-[[Geometry const &] [] [geometry] [geometry to loop through ]]
-[[Functor] [] [f] [functor to use]]
+[[Geometry const &] [Any type fulfilling a Geometry Concept ] [geometry] [A model of the specified concept ]]
+[[Functor] [Function or class with operator()] [f] [Unary function, taking a const point as argument ]]
 ]
 
 
@@ -68,12 +77,18 @@
 
 `#include <boost/geometry/algorithms/for_each.hpp>`
 
+[heading Examples]
+[for_each_point_const] [for_each_point_const_output]
+
 
 [endsect]
 
 [section:for_each_segment_2 for_each_segment]
 
-Calls functor for segments on linestrings, rings, polygons, ...
+Applies function [*f] to each segment.
+
+[heading Description]
+Applies a function [*f] (functor, having operator() defined) to each segment making up the geometry
 
 [heading Synopsis]
 ``template<typename Geometry, typename Functor>
@@ -83,8 +98,8 @@
 
 [table
 [[Type] [Concept] [Name] [Description] ]
-[[Geometry &] [] [geometry] [geometry to loop through ]]
-[[Functor] [] [f] [functor to use]]
+[[Geometry &] [Any type fulfilling a Geometry Concept ] [geometry] [A model of the specified concept ]]
+[[Functor] [Function or class with operator() ] [f] [Unary function, taking a segment as argument ]]
 ]
 
 
@@ -100,9 +115,12 @@
 
 [endsect]
 
-[section:for_each_segment_2 for_each_segment]
+[section:for_each_segment_2_const_version for_each_segment (const version)]
+
+Applies function [*f] to each segment.
 
-Calls functor for segments on linestrings, rings, polygons, ...
+[heading Description]
+Applies a function [*f] (functor, having operator() defined) to each segment making up the geometry
 
 [heading Synopsis]
 ``template<typename Geometry, typename Functor>
@@ -112,8 +130,8 @@
 
 [table
 [[Type] [Concept] [Name] [Description] ]
-[[Geometry const &] [] [geometry] [geometry to loop through ]]
-[[Functor] [] [f] [functor to use]]
+[[Geometry const &] [Any type fulfilling a Geometry Concept ] [geometry] [A model of the specified concept ]]
+[[Functor] [Function or class with operator()] [f] [Unary function, taking a const segment as argument ]]
 ]
 
 

Modified: trunk/libs/geometry/doc/reference/num_points.qbk
==============================================================================
--- trunk/libs/geometry/doc/reference/num_points.qbk (original)
+++ trunk/libs/geometry/doc/reference/num_points.qbk 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -22,7 +22,7 @@
 
 [heading Synopsis]
 ``template<typename Geometry>
-std::size_t num_points(Geometry const & geometry, bool add_for_open)``
+std::size_t num_points(Geometry const & geometry, bool add_for_open = false)``
 
 [heading Parameters]
 

Modified: trunk/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp
==============================================================================
--- trunk/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp (original)
+++ trunk/libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk/doxygen_xml_parser.hpp 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -41,6 +41,7 @@
         if (it->brief_description.empty()) it->brief_description = p.brief_description;
         if (it->type.empty()) it->type = p.type;
         if (it->fulltype.empty()) it->fulltype = p.fulltype;
+ if (it->default_value.empty()) it->default_value = p.default_value;
     }
     else
     {

Modified: trunk/libs/geometry/doc/src/examples/algorithms/Jamfile.v2
==============================================================================
--- trunk/libs/geometry/doc/src/examples/algorithms/Jamfile.v2 (original)
+++ trunk/libs/geometry/doc/src/examples/algorithms/Jamfile.v2 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -14,6 +14,9 @@
 exe area : area.cpp ;
 exe area_with_strategy : area_with_strategy.cpp ;
 
+exe for_each_point : for_each_point.cpp ;
+exe for_each_point_const : for_each_point_const.cpp ;
+
 exe intersection_ls_ls_point : intersection_ls_ls_point.cpp ;
 exe intersection_segment : intersection_segment.cpp ;
 

Added: trunk/libs/geometry/doc/src/examples/algorithms/for_each_point.cpp
==============================================================================
--- (empty file)
+++ trunk/libs/geometry/doc/src/examples/algorithms/for_each_point.cpp 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -0,0 +1,68 @@
+// Boost.Geometry (aka GGL, Generic Geometry Library)
+//
+// Copyright Barend Gehrels 2011, Geodan, Amsterdam, the Netherlands
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// Quickbook Example
+
+//[for_each_point
+//` Convenient usage of for_each_point, rounding all points of a geometry
+
+#include <iostream>
+
+#include <boost/geometry/geometry.hpp>
+#include <boost/geometry/geometries/geometries.hpp>
+#include <boost/geometry/extensions/gis/io/wkt/wkt.hpp>
+
+
+
+template <typename Point>
+class round_coordinates
+{
+private :
+ typedef typename boost::geometry::coordinate_type<Point>::type coordinate_type;
+ coordinate_type factor;
+
+ inline coordinate_type round(coordinate_type value)
+ {
+ return floor(0.5 + (value / factor)) * factor;
+ }
+
+public :
+ round_coordinates(coordinate_type f)
+ : factor(f)
+ {}
+
+ inline void operator()(Point& p)
+ {
+ using boost::geometry::get;
+ using boost::geometry::set;
+ set<0>(p, round(get<0>(p)));
+ set<1>(p, round(get<1>(p)));
+ }
+};
+
+
+int main()
+{
+ typedef boost::geometry::model::d2::point_xy<double> point;
+ boost::geometry::model::polygon<point> poly;
+ boost::geometry::read_wkt("POLYGON((0 0,1.123 9.987,8.876 2.234,0 0),(3.345 4.456,7.654 8.765,9.123 5.432,3.345 4.456))", poly);
+ boost::geometry::for_each_point(poly, round_coordinates<point>(0.1));
+ std::cout << "Rounded: " << boost::geometry::wkt(poly) << std::endl;
+ return 0;
+}
+
+//]
+
+
+//[for_each_point_output
+/*`
+Output:
+[pre
+ Rounded: POLYGON((0 0,1.1 10,8.9 2.2,0 0),(3.3 4.5,7.7 8.8,9.1 5.4,3.3 4.5))
+]
+*/
+//]

Added: trunk/libs/geometry/doc/src/examples/algorithms/for_each_point_const.cpp
==============================================================================
--- (empty file)
+++ trunk/libs/geometry/doc/src/examples/algorithms/for_each_point_const.cpp 2011-02-14 13:39:39 EST (Mon, 14 Feb 2011)
@@ -0,0 +1,49 @@
+// Boost.Geometry (aka GGL, Generic Geometry Library)
+//
+// Copyright Barend Gehrels 2011, Geodan, Amsterdam, the Netherlands
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// Quickbook Example
+
+//[for_each_point_const
+//` Sample using for_each_point, using a function to list coordinates
+
+#include <iostream>
+
+#include <boost/geometry/geometry.hpp>
+#include <boost/geometry/geometries/geometries.hpp>
+#include <boost/geometry/extensions/gis/io/wkt/wkt.hpp>
+
+
+template <typename Point>
+void list_coordinates(Point const& p)
+{
+ using boost::geometry::get;
+ std::cout << "x = " << get<0>(p) << " y = " << get<1>(p) << std::endl;
+}
+
+int main()
+{
+ typedef boost::geometry::model::d2::point_xy<double> point;
+ boost::geometry::model::polygon<point> poly;
+ boost::geometry::read_wkt("POLYGON((0 0,0 4,4 0,0 0))", poly);
+ boost::geometry::for_each_point(poly, list_coordinates<point>);
+ return 0;
+}
+
+//]
+
+
+//[for_each_point_const_output
+/*`
+Output:
+[pre
+x = 0 y = 0
+x = 0 y = 4
+x = 4 y = 0
+x = 0 y = 0
+]
+*/
+//]


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk