view and action examples; workaround for gcc-7/8 ICE, fixes ericniebl…

…er#1105 (ericniebler#1274)

view and action examples; workaround for gcc-7/8 ICE, fixes ericniebler#1105

doc/examples.md

@@ -37,11 +37,23 @@ Examples
 
 \section example-views Examples: Views
 
-TBD
+\subsection example-filter-transform Filter and transform
+
+\snippet filter_transform.cpp filter_transform
+
+\subsection example-accumulate-ints Generate ints and accumulate
+
+\snippet accumulate_ints.cpp accumulate_ints
+
+\subsection example-comprehension-conversion Convert a range comprehension to a vector
+
+\snippet comprehension_conversion.cpp comprehension_conversion
 
 \section example-actions Examples: Actions
 
-TBD
+\subsection example-sort-unique Remove non-unique elements from a container
+
+\snippet sort_unique.cpp sort_unique
 
 \section example-gestalt Examples: Putting it all together
 

doc/index.md

@@ -100,7 +100,7 @@ with
     ranges::sort( v );
 ~~~~~~~
 
-Range-v3 contains a full implementation of all the standard algorithms with
+Range-v3 contains full implementations of all the standard algorithms with
 range-based overloads for convenience.
 
 **Composability**
@@ -172,7 +172,7 @@ examples that use views:
 Filter a container using a predicate and transform it.
 
 ~~~~~~~{.cpp}
-    std::vector<int> vi{1,2,3,4,5,6,7,8,9,10};
+    std::vector<int> const vi{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
     using namespace ranges;
     auto rng = vi | views::remove_if([](int i){return i % 2 == 1;})
                   | views::transform([](int i){return std::to_string(i);});
@@ -194,25 +194,33 @@ vector with it:
 
 ~~~~~~~{.cpp}
     using namespace ranges;
-    std::vector<int> vi =
-        views::for_each(views::ints(1,10), [](int i){
-            return yield_from(views::repeat_n(i,i));
-        });
+    auto vi =
+        views::for_each(views::ints(1, 10), [](int i) {
+            return yield_from(views::repeat_n(i, i));
+        })
+      | to<std::vector>();
     // vi == {1,2,2,3,3,3,4,4,4,4,5,5,5,5,5,...}
 ~~~~~~~
 
 ### View const-ness
 
-Logically, a view is like a pair of iterators. In order to work, and work fast,
-many views need to cache some data. In order to keep iterators small, this
-cached data is usually stored in the view itself, and iterators hold only
-pointers to their view. Because of the cache, many views lack a
-`const`-qualified `begin()`/`end()`. When `const` versions of `begin()`/`end()`
-are provided, they are truly `const`; that is, thread-safe.
+Logically, a view is a factory for iterators, but in practice a view is often
+implemented as a state machine, with the state stored within the view object
+itself (to keep iterators small) and mutated as the view is iterated. Because
+the view contains mutable state, many views lack a `const`-qualified
+`begin()`/`end()`. When `const` versions of `begin()`/`end()` are provided, they
+are truly `const`; that is, thread-safe.
+
+Since views present the same interface as containers, the temptation is to think
+they behave like containers with regard to `const`-ness. This is not the case.
+Their behavior with regards to `const`-ness is similar to iterators and
+pointers.
 
 The `const`-ness of a view is not related to the `const`-ness of the underlying
-data. Non-`const` view may return `const` iterators. This is analogous to
-pointers; an `int* const` is a `const` pointer to a mutable `int`.
+data. A non-`const` view may refer to elements that are themselves `const`, and
+_vice versa_. This is analogous to pointers; an `int* const` is a `const`
+pointer to a mutable `int`, and a `int const*` is a non-`const` pointer to a
+`const` `int`.
 
 Use non-`const` views whenever possible. If you need thread-safety, work with
 view copies in threads; don't share.

example/BUCK

@@ -101,3 +101,55 @@ cxx_binary(
     '-std=c++14',
   ],
 )
+
+cxx_binary(
+  name = 'filter_transform',
+  srcs = [
+    'filter_transform.cpp',
+  ],
+  deps = [
+    '//:range-v3',
+  ],
+  compiler_flags = [
+    '-std=c++14',
+  ],
+)
+
+cxx_binary(
+  name = 'accumulate_ints',
+  srcs = [
+    'accumulate_ints.cpp',
+  ],
+  deps = [
+    '//:range-v3',
+  ],
+  compiler_flags = [
+    '-std=c++14',
+  ],
+)
+
+cxx_binary(
+  name = 'comprehension_conversion',
+  srcs = [
+    'comprehension_conversion.cpp',
+  ],
+  deps = [
+    '//:range-v3',
+  ],
+  compiler_flags = [
+    '-std=c++14',
+  ],
+)
+
+cxx_binary(
+  name = 'sort_unique',
+  srcs = [
+    'sort_unique.cpp',
+  ],
+  deps = [
+    '//:range-v3',
+  ],
+  compiler_flags = [
+    '-std=c++14',
+  ],
+)

example/CMakeLists.txt

@@ -14,6 +14,10 @@ rv3_add_test(example.for_each_sequence for_each_sequence for_each_sequence.cpp)
 rv3_add_test(example.for_each_assoc for_each_assoc for_each_assoc.cpp)
 rv3_add_test(example.is_sorted is_sorted is_sorted.cpp)
 rv3_add_test(example.find find find.cpp)
+rv3_add_test(example.filter_transform filter_transform filter_transform.cpp)
+rv3_add_test(example.accumulate_ints accumulate_ints accumulate_ints.cpp)
+rv3_add_test(example.comprehension_conversion comprehension_conversion comprehension_conversion.cpp)
+rv3_add_test(example.sort_unique sort_unique sort_unique.cpp)
 
 # Guarded with a variable because the calendar example causes gcc to puke.
 if(RANGES_BUILD_CALENDAR_EXAMPLE)

example/accumulate_ints.cpp

@@ -0,0 +1,37 @@
+// Range v3 library
+//
+//  Copyright Eric Niebler 2019
+//
+//  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)
+//
+// Project home: https://github.com/ericniebler/range-v3
+//
+
+///[accumulate_ints]
+// Sums the first ten squares and prints them, using views::ints to generate
+// and infinite range of integers, views::transform to square them, views::take
+// to drop all but the first 10, and accumulate to sum them.
+
+#include <iostream>
+#include <vector>
+
+#include <range/v3/numeric/accumulate.hpp>
+#include <range/v3/view/iota.hpp>
+#include <range/v3/view/take.hpp>
+#include <range/v3/view/transform.hpp>
+using std::cout;
+
+int main()
+{
+    using namespace ranges;
+    int sum = accumulate(views::ints(1, unreachable) | views::transform([](int i) {
+                             return i * i;
+                         }) | views::take(10),
+                         0);
+    // prints: 385
+    cout << sum << '\n';
+}
+///[accumulate_ints]

example/comprehension_conversion.cpp

@@ -0,0 +1,35 @@
+// Range v3 library
+//
+//  Copyright Eric Niebler 2019
+//
+//  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)
+//
+// Project home: https://github.com/ericniebler/range-v3
+//
+
+///[comprehension_conversion]
+// Use a range comprehension (views::for_each) to construct a custom range, and
+// then convert it to a std::vector.
+
+#include <iostream>
+#include <vector>
+
+#include <range/v3/range/conversion.hpp>
+#include <range/v3/view/for_each.hpp>
+#include <range/v3/view/iota.hpp>
+#include <range/v3/view/repeat_n.hpp>
+using std::cout;
+
+int main()
+{
+    using namespace ranges;
+    auto vi = views::for_each(views::ints(1, 6),
+                              [](int i) { return yield_from(views::repeat_n(i, i)); }) |
+              to<std::vector>();
+    // prints: [1,2,2,3,3,3,4,4,4,4,5,5,5,5,5]
+    cout << views::all(vi) << '\n';
+}
+///[comprehension_conversion]

example/count.cpp

@@ -1,4 +1,3 @@
-
 // Range v3 library
 //
 //  Copyright Jeff Garland 2017

example/filter_transform.cpp

@@ -0,0 +1,34 @@
+// Range v3 library
+//
+//  Copyright Eric Niebler 2019
+//
+//  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)
+//
+// Project home: https://github.com/ericniebler/range-v3
+//
+
+///[filter_transform]
+// This example demonstrates filtering and transforming a range on the
+// fly with view adaptors.
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+#include <range/v3/view/filter.hpp>
+#include <range/v3/view/transform.hpp>
+using std::cout;
+
+int main()
+{
+    std::vector<int> const vi{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+    using namespace ranges;
+    auto rng = vi | views::filter([](int i) { return i % 2 == 0; }) |
+               views::transform([](int i) { return std::to_string(i); });
+    // prints: [2,4,6,8,10]
+    cout << rng << '\n';
+}
+///[filter_transform]

example/sort_unique.cpp

@@ -0,0 +1,34 @@
+// Range v3 library
+//
+//  Copyright Eric Niebler 2019
+//
+//  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)
+//
+// Project home: https://github.com/ericniebler/range-v3
+//
+
+///[sort_unique]
+// Remove all non-unique elements from a container.
+
+#include <iostream>
+#include <vector>
+
+#include <range/v3/action/sort.hpp>
+#include <range/v3/action/unique.hpp>
+#include <range/v3/view/all.hpp>
+using std::cout;
+
+int main()
+{
+    std::vector<int> vi{9, 4, 5, 2, 9, 1, 0, 2, 6, 7, 4, 5, 6, 5, 9, 2, 7,
+                        1, 4, 5, 3, 8, 5, 0, 2, 9, 3, 7, 5, 7, 5, 5, 6, 1,
+                        4, 3, 1, 8, 4, 0, 7, 8, 8, 2, 6, 5, 3, 4, 5};
+    using namespace ranges;
+    vi |= actions::sort | actions::unique;
+    // prints: [0,1,2,3,4,5,6,7,8,9]
+    cout << views::all(vi) << '\n';
+}
+///[sort_unique]