incorp some review

TylerMSFT · TylerMSFT · commit a429f2360412 · 2021-04-10T14:41:54.000-07:00
diff --git a/docs/standard-library/ranges.md b/docs/standard-library/ranges.md
@@ -1,24 +1,22 @@
 ---
 title: "<ranges>"
-description: "API reference for the Standard Template Library (STL) ranges namespace, which provides ... JTW"
+description: "Overview of the Standard Template Library (STL) ranges library"
 ms.date: "04/13/2021"
 f1_keywords: ["<ranges>"]
 helpviewer_keywords: ["ranges header"]
 ---
 
 # `<ranges>`
 
-## Overview
-
 At a high level, a range is something you can iterate over. A range is a rich abstraction over iterators that simplifies and amplifies your ability to use the Standard Template Library (STL).
 
-STL algorithms usually take iterators that point to the collection they operate on. But generally speaking, you want to operate on the entire collection. Consider how you sort a `vector` today. To call `std::sort()`, you pass two iterators marking the beginning and end of the `vector`. That's flexible, but is noisy since much of the time you'd just like to sort the entire `vector`, but you still have to pass the beginning and end of what to sort.
+STL algorithms usually take iterators that point to the collection they operate on. But generally speaking, you want to operate on the entire collection. Consider how you sort a `vector` today. To call `std::sort()`, you pass two iterators marking the beginning and end of the `vector`. That's flexible, but is noisy since much of the time you just want to sort the entire `vector`, but you still have to pass the beginning and end of what to sort.
 
-With ranges, you can call `std::ranges::sort(myVector);`. It is treated as if you had called `std::sort(myVector.begin(), myVector.end());` In range libraries, STL algorithms take ranges as parameters, instead of iterators. Examples of range algorithms available in `<algorithm>` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, and `none_of`, `find`, `find_if`, and `find_if_not`, `count` and `count_if`, `for_each` and `for_each_n`, `equal` and `mismatch`.
+With ranges, you can call `std::ranges::sort(myVector);`. It is treated as if you had called `std::sort(myVector.begin(), myVector.end());` In range libraries, in addition to taking iterators, STL algorithms can take ranges as parameters. Examples of range algorithms available in `<algorithm>` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, and `none_of`, `find`, `find_if`, and `find_if_not`, `count` and `count_if`, `for_each` and `for_each_n`, `equal` and `mismatch`.
 
 Simplified code that is more readable is great, but the benefits of ranges extend further to making it much easier to filter and transform collections of data, and to compose STL algorithms more easily.
 
-Unlike an iterator, ranges are copyable and assignable. Because they don't own the elements like a container does, they are lightweight.
+Because ranges don't own elements like a container does, they are lightweight.
 
 ## An example
 
@@ -32,21 +30,15 @@ std::transform(intermediate.begin(), intermediate.end(), std::back_inserter(outp
 With ranges, you can instead write this as:
 
 ```cpp
+// requires /std:c++latest
 std::vector<int> input = { 1, 2, 3, 5, 8, 13, 21, 34, 45, 79 };
-vector<int> output;
 auto output = input | std::views::filter([](const int n) {return n % 3 == 0; }) | std::views::transform([](const int n) {return n * n; });
 ```  
+> [!NOTE] The ranges examples need to be compiled with the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option.
 
-*** Note: I'd like to write something like this but it doesn't work:
-```cpp
-std::ranges::copy( input, std::views::filter([](const int n) {return n % 3 == 0; })
-		| std::views::filter([](const int n) {return n * n; }),
-		std::back_inserter(output));
-```
-
-In the code above, the input is first filtered to just the entries that are divisible by three. The result is combined with a transformation that squares those elements (the ones divisible by three).
+In addition to being a little easier to read, it avoid the memory allocation required for `intermediate` in the non-ranges example.
 
-The '`|`' symbol chains the range view operations together, and is read left to right.
+In the code above, the input is first filtered to just the entries that are divisible by three. The result is combined with a transformation that squares those elements (the ones divisible by three). The '`|`' symbol chains the range view operations together, and is read left to right.
 
 The result, `output`, is itself a type of range called a view, which is discussed next.
 
@@ -58,24 +50,27 @@ A view is lightweight. Like a range, a view doesn't own the elements it provides
 
 Views are composable. In the example above, the view of vector elements that are divisible by three is then combined with the view that squares those elements.
 
-The elements of a view are evaluated lazily. That is, the transformation you apply to yield elements in a view is not evaluated until you ask for an element. For example, if you run the following code in a debugger, and put a breakpoint on the line `auto x = ...`, you'll hit that breakpoint each iteration through the range `for` loop. That's because it isn't until the element is accessed that the operation that define the view are evaluated for that element.
+The elements of a view are evaluated lazily. That is, the transformation you apply to yield elements in a view is not evaluated until you ask for an element. For example, if you run the following code in a debugger, and put a breakpoint on the lines `auto divisible_by_three = ...` and `auto square =  ...`, you'll see that you hit the first breakpoint as every element is tested for divisibility by three, and then the second breakpoint as the ones that are divisible by three are squared.
 
 ```cpp
-#include <iostream>
+// requires /std:c++latest
 #include <ranges>
 #include <vector>
+#include <iostream>
 
 int main()
 {
-	std::vector<int> input = { 1, 2, 3, 5, 8, 13, 21, 34, 45, 79 };
+    std::vector<int> input = { 1, 2, 3, 5, 8, 13, 21, 34, 45, 79 };
+    auto divisible_by_three = [](const int n) {return n % 3 == 0; };
+    auto square = [](const int n) {return n * n; };
 
-    auto x = input | std::views::filter([](const int n) {return n % 3 == 0; })
-                            | std::views::transform([](const int n) {return n * n; });
+    auto x = input | std::views::filter(divisible_by_three)
+                   | std::views::transform(square);
 
     for (int i : x)
-	{
-		std::cout << i << '\n';
-	}
+    {
+        std::cout << i << '\n';
+    }
     return 0;
 }
 ```
@@ -84,7 +79,7 @@ int main()
 
 A view adaptor provides a view over a range. The range being viewed remains unchanged. The produced view doesn't own any elements. Instead, a view allows you to iterate over the underlying range, but using customized behavior that you specify.
 
-In the example above, the first view acts like an iterator that only provides the elements of `input` that are divisible by three. The other range acts like an iterator that takes the elements divisible by three, and provides their square.
+In the example above, the first view acts like an iterator that only provides the elements of `input` that are divisible by three. The other view acts like an iterator that takes the elements divisible by three, and provides their square.
 
 The `<ranges>` library provides many kinds of view adaptors. In addition to the filter and transform views above, there are views that take or skip the first N elements of another view, reverse the order of a view, join views, skip elements of another view until a condition is met, transform the elements of another view, among others.
 
@@ -111,12 +106,12 @@ Range-based algorithms are basically iterator-based algorithms where instead of
 What you can do with a range depends on the underlying iterator type. Range concepts are named to reflect the traversal category its iterators support.
 
 There are different kinds, or refinements, of ranges, that are codified as concepts. This table lists them, along with the type of container they can be applied to:
-
+j
 | Range refinement | Description | Supported containers |
 |--|--|--|
-| `std::ranges::input_range` | Can iterate from beginning to end at least once | `std::forward_list`<br>`std::unordered_map`<br>`std::unordered_multimap`<br>`std::unordered_set`<br>`std::unordered_multiset` | 
+| `std::ranges::input_range` | Can iterate from beginning to end at least once | `std::forward_list`<br>`std::unordered_map`<br>`std::unordered_multimap`<br>`std::unordered_set`<br>`std::unordered_multiset`<br>`basic_istream_view` | 
 | `std::ranges::output_range ` | A range whose iterator type satisfies output_iterator | ? |
-| `std::ranges::forward_range` | Can iterate from beginning to end more than once) | ? |
+| `std::ranges::forward_range` | Can iterate from beginning to end more than once) | `std::forward_list`<br>`std::unordered_map`<br>`std::unordered_multimap`<br>`std::unordered_set`<br>`std::unordered_multiset` |
 | `std::ranges::bidirectional_range` | Can iterate forward and backward more than once | `std::list`<br>`std::map`<br>`std::multimap`<br>`std::multiset`<br>`std::set`|
 | `std::ranges::random_access_range` | Can access an arbitrary element (in constant time) using the `[]` operator) | `std::deque` |
 | `std::ranges::contiguous_range` | The elements are stored in memory consecutively | `std::array`<br>`std::string`<br>`std::vector` |
