for_each_segment doc update (doc folder)

[SVN r68931]

doc/geometry.qbk

@@ -73,6 +73,7 @@ Simplify algorithm [link geometry.reference.algorithms.simplify.simplify_3 here]
 [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/for_each_segment_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]

doc/reference/for_each.qbk

@@ -42,7 +42,7 @@ Or
 
 `#include <boost/geometry/algorithms/for_each.hpp>`
 
-[heading Examples]
+[heading Example]
 [for_each_point] [for_each_point_output]
 
 
@@ -77,7 +77,7 @@ Or
 
 `#include <boost/geometry/algorithms/for_each.hpp>`
 
-[heading Examples]
+[heading Example]
 [for_each_point_const] [for_each_point_const_output]
 
 
@@ -144,6 +144,9 @@ Or
 
 `#include <boost/geometry/algorithms/for_each.hpp>`
 
+[heading Example]
+[for_each_segment_const] [for_each_segment_const_output]
+
 
 [endsect]
 

doc/src/examples/algorithms/Jamfile.v2

@@ -16,6 +16,7 @@ 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 for_each_segment_const : for_each_segment_const.cpp ;
 
 exe intersection_ls_ls_point : intersection_ls_ls_point.cpp ;
 exe intersection_segment : intersection_segment.cpp ;

doc/src/examples/algorithms/for_each_segment_const.cpp

@@ -0,0 +1,94 @@
+// 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_segment_const
+//` Sample using for_each_segment, using a functor to get the minimum and maximum length of a segment in a linestring
+
+#include <iostream>
+
+#include <boost/geometry/geometry.hpp>
+#include <boost/geometry/geometries/geometries.hpp>
+
+#include <boost/assign.hpp>
+
+
+template <typename Segment>
+struct gather_segment_statistics
+{
+    // Remember that if coordinates are integer, the length might be floating point
+    // So use "double" for integers. In other cases, use coordinate type
+    typedef typename boost::geometry::select_most_precise
+        <
+            typename boost::geometry::coordinate_type<Segment>::type,
+            double
+        >::type type;
+
+    type min_length, max_length;
+
+    // Initialize min and max
+    gather_segment_statistics()
+        : min_length(1e38)
+        , max_length(-1)
+    {}
+
+    // This operator is called for each segment
+    inline void operator()(Segment const& s)
+    {
+        type length = boost::geometry::length(s);
+        if (length < min_length) min_length = length;
+        if (length > max_length) max_length = length;
+    }
+};
+
+int main()
+{
+    // Bring "+=" for a vector into scope
+    using namespace boost::assign;
+
+    // Define a type
+    typedef boost::geometry::model::d2::point_xy<double> point;
+
+    // Declare a linestring
+    boost::geometry::model::linestring<point> polyline;
+
+    // Use Boost.Assign to initialize a linestring
+    polyline += point(0, 0), point(3, 3), point(5, 1), point(6, 2),
+                point(8, 0), point(4, -4), point(1, -1), point(3, 2);
+
+
+    // Declare the gathering class...
+    gather_segment_statistics
+        <
+            boost::geometry::model::referring_segment<point>
+        > functor;
+
+    // ... and use it, the essention.
+    // As also in std::for_each it is a const value, so retrieve it as a return value.
+    functor = boost::geometry::for_each_segment(polyline, functor);
+
+    // Output the results
+    std::cout
+        << "Min segment length: " << functor.min_length << std::endl
+        << "Max segment length: " << functor.max_length << std::endl;
+
+    return 0;
+}
+
+//]
+
+
+//[for_each_segment_const_output
+/*`
+Output:
+[pre
+Min segment length: 1.41421
+Max segment length: 5.65685
+]
+*/
+//]