get updates into right branch

TylerMSFT · TylerMSFT · commit 025116bf3fd8 · 2022-11-02T17:27:33.000-07:00
diff --git a/docs/standard-library/range-adaptors.md b/docs/standard-library/range-adaptors.md
@@ -5,9 +5,9 @@ ms.date: 11/2/2022
 f1_keywords: ["ranges/std::all", "ranges/std::all_t", "ranges/std::common", "ranges/std::counted", "ranges/std::drop", "ranges/std::drop_while", "ranges/std::elements", "ranges/std::filter", "ranges/std::iota", "ranges/std::join", "ranges/std::keys", "ranges/std::lazy_split", "ranges/std::reverse", "ranges/std::split", "ranges/std::subrange", "ranges/std::take", "ranges/std::take_while", "ranges/std::transform"]
 helpviewer_keywords: ["std::ranges [C++], all", "std::ranges [C++], all_t", "std::ranges [C++], common", "std::ranges [C++], counted", "std::ranges [C++], drop", "std::ranges [C++], drop_while", "std::ranges [C++], elements", "std::ranges [C++], filter", "std::ranges [C++], iota", "std::ranges [C++], join", "std::ranges [C++], keys", "std::ranges [C++], lazy_split", "std::ranges [C++], reverse", "std::ranges [C++], split", "std::ranges [C++], subrange", "std::ranges [C++], take", "std::ranges [C++], take_while", "std::ranges [C++], transform"]
 ---
-# Range adaptors
+# `ranges` adaptors
 
-Range adaptors create a *view* (one of the [view classes](view-classes.md) in the `std::views` namespace) from a range. We recommend that you use an adaptor in `std::ranges::views` instead of creating the view types directly. The adaptors are the intended way to access views. They're easier to use, and in some cases more efficient, than creating instances of the view types directly.
+Range adaptors create a *view* (one of the [View classes](view-classes.md) in the `std::views` namespace) from a range. We recommend that you use an adaptor in `std::ranges::views` instead of creating the view types directly. The adaptors are the intended way to access views. They're easier to use, and in some cases more efficient, than creating instances of the view types directly.
 
 A view is a lightweight object that refers to elements from a range. A view can:
 
@@ -1503,4 +1503,5 @@ int main()
 ## See also
 
 [`<ranges>`](ranges.md)\
+[`<ranges>` concepts](range-concepts.md)\
 [View classes](view-classes.md)
diff --git a/docs/standard-library/range-concepts.md b/docs/standard-library/range-concepts.md
@@ -2,10 +2,10 @@
 description: "Learn more about range concepts and range iterator concepts."
 title: "Concepts for ranges and range iterators"
 ms.date: 11/02/2022
-f1_keywords: ["ranges/std::ranges::range"]
-helpviewer_keywords: ["std::ranges [C++], range"]
+f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_range", "ranges/std::ranges::borrowed_range", "ranges/std::ranges::common_range", "ranges/std::ranges::contiguous_range", "ranges/std::ranges::forward_range", "ranges/std::ranges::input_range", "ranges/std::ranges::output_range", "ranges/std::ranges::random_access_range", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_range", "ranges/std::ranges::view", "ranges/std::ranges::viewable_range"]
+helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_range", "std::ranges [C++], ranges::borrowed_range", "std::ranges [C++], ranges::common_range", "std::ranges [C++], ranges::contiguous_range", "std::ranges [C++], ranges::forward_range", "std::ranges [C++], ranges::input_range", "std::ranges [C++], ranges::output_range", "std::ranges [C++], ranges::random_access_range", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_range", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_range"]
 ---
-# Concepts for `<ranges>`
+# `<ranges>` concepts
 
 Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiations, convey template argument requirements in a readable form, and provide more succinct template related compiler errors.
 
@@ -15,7 +15,7 @@ Consider the following example, which defines a concept to prevent instantiating
 // requires /std:c++20 or later
 #include <iostream>
 
-// Definition of the concept "dividable" that requires 
+// Definition of dividable concept that requires 
 // that arguments a & b of type T support division
 template <typename T>
 concept dividable = requires (T a, T b)
@@ -48,21 +48,38 @@ int main()
 }
 ```
 
+Using Visual Studio 2022, version 17.4p4, the errors generated for the preceding example are:
+
+```output
+example.cpp
+example.cpp(31): error C7602: 'DivideEmUp': the associated constraints are not satisfied
+example.cpp(18): note: see declaration of 'DivideEmUp'
+example.cpp(16): note: the concept 'dividable<char*>' evaluated to false
+example.cpp(9): note: the expression is invalid
+example.cpp(31): error C2641: cannot deduce template arguments for 'DivideEmUp'
+example.cpp(31): error C2783: 'DivideEmUp<T> DivideEmUp(void)': could not deduce template argument for 'T'
+example.cpp(18): note: see declaration of 'DivideEmUp'
+example.cpp(31): error C2780: 'DivideEmUp<T> DivideEmUp(DivideEmUp<T>)': expects 1 arguments - 0 provided
+example.cpp(18): note: see declaration of 'DivideEmUp'
+```
+
+If you specify the compiler switch `/diagnostics:caret`, then the errors generated notably includes concept `dividable<char*>` evaluated to false and even points directly to the expression requirement `(a / b)` that failed.
+
 The following concepts are defined in `std::ranges` and are declared in the `<ranges>` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on.
 
-| **Range concept ** | **Description** |
+| Range concept | Description |
 |--|--|
-| [`range`](#range)<sup>C++20</sup> | A type that can be iterated. |
+| [`range`](#range)<sup>C++20</sup> | A type that provides an iterator and a sentinel. |
 | [`bidirectional_range`](#bidirectional_range)<sup>C++20</sup> | Supports reading and writing forwards and backwards. |
 | [`borrowed_range`](#borrowed_range)<sup>C++20</sup> | The lifetime of the type's iterators aren't tied to the object's lifetime. |
-| [`common_range`](#common_range)<sup>C++20</sup> | The type of the iterator and the sentinel are the same. |
-| [`contiguous_range`](#contiguous_range)<sup>C++20</sup> | The elements are sequential in memory and can be accessed by index. |
-| [`forward_range`](#forward_range)<sup>C++20</sup> | Supports reading multiple times. |
-| [`input_range`](#input_range)<sup>C++20</sup> | Supports reading. |
+| [`common_range`](#common_range)<sup>C++20</sup> | The type of the iterator and the type of the sentinel are the same. |
+| [`contiguous_range`](#contiguous_range)<sup>C++20</sup> | The elements are sequential in memory and can be accessed by using pointer arithmetic. |
+| [`forward_range`](#forward_range)<sup>C++20</sup> | Supports reading (and possibly writing) a range multiple times. |
+| [`input_range`](#input_range)<sup>C++20</sup> | Supports reading at least once. |
 | [`output_range`](#output_range)<sup>C++20</sup> | Supports writing. |
 | [`random_access_range`](#random_access_range)<sup>C++20</sup> | Supports reading and writing by index. |
-| [`simple_view`](#simple_view)<sup>C++20</sup> | Not an official concept defined as part of the standard library, but used as a 'helper' concept on some interfaces. |
-| [`sized_range`](#sized_range)<sup>C++20</sup> | Provides the number of elements efficiently. |
+| [`Simple_View`](#simple_view)<sup>C++20</sup> | Not an official concept defined as part of the standard library, but used as a helper concept on some interfaces. |
+| [`sized_range`](#sized_range)<sup>C++20</sup> | Provides the number of elements in a range efficiently. |
 | [`view`](#view)<sup>C++20</sup> | Has efficient (constant time) move construction, assignment, and destruction. |
 | [`viewable_range`](#viewable_range)<sup>C++20</sup> | A type that either is a view or can be converted to one. |
 
@@ -89,7 +106,7 @@ Some examples of a `bidirectional_range` are `std::set`, `std::vector`, and `std
 
 ## `borrowed_range`
 
-A type models `borrowed_range` if the validity of iterators you get from the object can outlive the lifetime of the object.
+A type models `borrowed_range` if the validity of iterators you get from the object can outlive the lifetime of the object. That is, the iterators for a range can be used even when the range no longer exists.
 
 ```cpp
 template<class T>
@@ -105,7 +122,7 @@ The type to test to see if it's a `borrowed_range`.
 
 ## `common_range`
 
-The type of the iterator for a `common_range` is the same type as the sentinel type. That is, the types returned from `begin()` and `end()` are the same.
+The type of the iterator for a `common_range` is the same as the type of the sentinel. That is, `begin()` and `end()` return the same type.
 
 ```cpp
 template<class T>
@@ -120,13 +137,13 @@ The type to test to see if it's a `common_range`.
 
 ### Remarks
 
-Providing the same iterator type from `std::ranges::begin()` and `std::ranges::end()` is important for algorithms that calculate the distance between two iterators and for algorithms that accept ranges denoted by iterator pairs.
+Getting the type from `std::ranges::begin()` and `std::ranges::end()` is important for algorithms that calculate the distance between two iterators, and for algorithms that accept ranges denoted by iterator pairs.
 
 The standard containers (for example, `vector`) meet the requirements of `common_range`.
 
 ## `contiguous_range`
 
-The elements of a `contiguous_range` are laid out sequentially in memory and can be accessed using pointer arithmetic. An array is a `contiguous_range`, for example.
+The elements of a `contiguous_range` are stored sequentially in memory and can be accessed using pointer arithmetic. For example, an array is a `contiguous_range`.
 
 ```cpp
 template<class T>
@@ -146,7 +163,7 @@ A `contiguous_range` can be accessed by pointer arithmetic because the elements
 
 Some examples of a `contiguous_range` are `std::array`, `std::vector`, and `std::string`.
 
-### Example `contiguous_range`
+### Example: `contiguous_range`
 
 The following example shows using pointer arithmetic to access a `contiguous_range`:
 
@@ -160,7 +177,7 @@ int main()
 {
     // Show that vector is a contiguous_range
     std::vector<int> v = {0,1,2,3,4,5};
-    std::cout << std::boolalpha << std::ranges::contiguous_range<decltype(v)> << '\n'; // outputs "true"
+    std::cout << std::boolalpha << std::ranges::contiguous_range<decltype(v)> << '\n'; // outputs true
 
     // Show that pointer arithmetic can be used to access the elements of a contiguous_range
     auto ptr = v.data();
@@ -176,7 +193,7 @@ true
 
 ## `forward_range`
 
-A `forward_range` supports reading and possibly writing a `range` multiple times.
+A `forward_range` supports reading (and possibly writing) a `range` multiple times.
 
 ```cpp
 template<class T>
@@ -210,7 +227,7 @@ The type to test to see if it's an `input_range`.
 
 When a type meets the requirements of `input_range`:
 
-- The `ranges::begin()` function returns an `input_iterator`. Calling `begin()` more than once for an `input_range` has undefined behavior.
+- The `ranges::begin()` function returns an `input_iterator`. Calling `begin()` more than once on an `input_range` results in undefined behavior.
 - You can dereference an `input_iterator` repeatedly, which yields the same value each time. An `input_range` isn't multi-pass. Incrementing an iterator invalidates any copies.
 - It can be used with `ranges::for_each`.
 - It *at least* has an `input_iterator`. It may have a more capable iterator type.
@@ -253,16 +270,16 @@ The type to test to see if it's a `sized_range`.
 
 ### Remarks
 
-A `random_access_range` provides the most flexible iterator. It provides the capabilities of an `input_range`, `output_range`, `forward_range`, and `bidirectional_range`. A `random_access_range` is also sortable.
+A `random_access_range` is the most flexible iterator. It has the capabilities of an `input_range`, `output_range`, `forward_range`, and `bidirectional_range`. A `random_access_range` is also sortable.
 
 Some examples of a `random_access_range` are `std::vector`, `std::array`, and `std::deque`.
 
 ## `range`
 
-Defines the requirements a type must meet to be a `range`. A `range` provides an iterator and a sentinel for iterating over its elements.
+Defines the requirements a type must meet to be a `range`. A `range` provides an iterator and a sentinel, so that you can iterate over its elements.
 
 ```cpp
-template<class R>
+template<class T>
 concept range = requires(T& rg)
 {
   ranges::begin(rg);
@@ -280,7 +297,7 @@ The type to test to see if it's a `range`.
 The requirements of a `range` are:
 - It can be iterated using `std::ranges::begin()` and `std::ranges::end()`
 - `ranges::begin()` and `ranges::end()` run in amortized constant time and don't modify the `range`. Amortized constant time doesn't mean O(1), but that the average cost over a series of calls, even in the worst case, is O(n) rather than O(n^2) or worse.
-- \[`ranges::begin()`, `ranges::end()`) denotes a valid range.
+- `[ranges::begin(), ranges::end())` denotes a valid range.
 
 ## `Simple_View`
 
@@ -301,7 +318,10 @@ The type to test to see if it's a `Simple_View`.
 
 ### Remarks
 
-A `view V` is a [`Simple_View`](#simple_view) if `V` is a `view`, `const V` is a `range`, and both `v` and `const V` have the same iterator and sentinel types.
+A view `V` is a [`Simple_View`](#simple_view) if all of the following are true:
+- `V` is a view
+- `const V` is a range
+- Both `v` and `const V` have the same iterator and sentinel types.
 
 ## `sized_range`
 
@@ -327,7 +347,7 @@ The requirements of a `sized_range` are that calling `ranges::size` on it:
 
 Some examples of a `sized_range` are `std::list` and `std::vector`.
 
-### Example `sized_range`
+### Example: `sized_range`
 
 The following example shows that a `vector` of `int` is a `sized_range`:
 
@@ -345,9 +365,9 @@ int main()
 
 ## `view`
 
-A `view` has constant time move construction, assignment, and destruction operations regardless of the number of elements it has. Views don't need to be copy constructible or copy assignable, but if they are those operations must also be constant time.
+A `view` has constant time move construction, assignment, and destruction operations--regardless of the number of elements it has. Views don't need to be copy constructible or copy assignable, but if they are, those operations must also run in constant time.
 
-Because of this performance in constant time, views can be efficiently composed. For example, given a vector of `int` called `input`, a lambda that determines if a number is divisible by three, and a lambda that squares a number, the statement `auto x = input | std::views::filter(divisible_by_three) | std::views::transform(square);` efficiently produces a view that contains the squares of the numbers in input that are divisible by three. Connecting views together with `|` is referred to as composing the views. If a type satisfies the `view` concept, then it meets the requirements of being efficiently composable.
+Because of the constant time requirement, you can efficiently compose views. For example, given a vector of `int` called `input`, a function that determines if a number is divisible by three, and a function that squares a number, the statement `auto x = input | std::views::filter(divisible_by_three) | std::views::transform(square);` efficiently produces a view that contains the squares of the numbers in input that are divisible by three. Connecting views together with `|` is referred to as composing the views. If a type satisfies the [`view`](range-concepts.md#view) concept, then it can be composed efficiently.
 
 ```cpp
 template<class T>
@@ -357,22 +377,26 @@ concept view = ranges::range<T> && std::movable<T> && ranges::enable_view<T>;
 ### Parameters
 
 *`T`*\
-The type to test to see if it's a composable `view`.
+The type to test to see if it's a view.
 
 ### Remarks
 
-The essential requirement that makes a `view` composable is that it's cheap to move/copy. This is because the `view` is moved/copied when it's composed with another `view`. It must be a movable `range`.
+The essential requirement that makes a view composable is that it's cheap to move/copy. This is because the view is moved/copied when it's composed with another view. It must be a movable `range`.
+
+`ranges::enable_view<T>` is a trait used to claim conformance to the semantic requirements of the `view` concept. A type can opt-in by:
+- publicly and unambiguously deriving from a specialization of `ranges::view_interface`
+- publicly and unambiguously deriving from the empty class `ranges::view_base`, or
+- specializing `ranges::enable_view<T>` to `true`
+
+Option 1 is generally preferred because `view_interface` also provides default implementation that save some boilerplate code you have to write.
 
-`ranges::enable_view<T>` is a trait used to claim conformance to the semantic requirements of the `view` concept. A type can "opt-in" by:
-1. publicly and unambiguously deriving from a specialization of `ranges::view_interface`
-2. publicly and unambiguously deriving from the empty class `ranges::view_base`, or
-3. specializing `ranges::enable_view<T>` to `true`
+Failing that, option 2 is a little simpler than option 3.
 
-Option 1 is generally preferred because `view_interface` also provides default implementations that save some boilerplate code you have to write. Failing that, option 2 is a little simpler than option 3. The advantage of option 3 is that it's possible without changing the definition of the type.
+The advantage of option 3 is that it's possible without changing the definition of the type.
 
 ## `viewable_range`
 
-A `viewable_range` is a type that either is a `view` or that can be converted to one.
+A `viewable_range` is a type that either is a view or can be converted to one.
 
 ```cpp
 template<class T>
@@ -383,14 +407,14 @@ template<class T>
 ### Parameters
 
 *`T`*\
-The type to test to see if it either is a `view` or can be converted to one.
+The type to test to see if it either is a view or can be converted to one.
 
 ### Remarks
 
-Use `std::ranges::views::all()` to convert a `range` to a `view`.
+Use `std::ranges::views::all()` to convert a range to a view.
 
 ## See also
 
 [`<ranges>`](ranges.md)\
-[Range adaptors](range-adaptors.md)\
+[`<ranges> adaptors](range-adaptors.md)\
 [View classes](view-classes.md)
diff --git a/docs/standard-library/ranges.md b/docs/standard-library/ranges.md
@@ -16,7 +16,7 @@ With ranges, you can call `std::ranges::sort(myVector);`, which is treated as if
 
 But perhaps the most important benefit of ranges is that you can compose STL algorithms that operate on ranges in a style that's reminiscent of functional programming.
 
-## An example of ranges
+## A ranges example
 
 Before ranges, if you wanted to transform the elements of a collection that met a certain criterion, you needed to introduce an intermediate step to hold the results between operations. For example, if you wanted to build a vector of squares from the elements in another vector that are divisible by three, you could write something like:
 
@@ -95,7 +95,7 @@ For more information about creating views, see [Range adaptors](range-adaptors.m
 
 Some range algorithms take a range argument. An example is `std::ranges::sort(myVector);`.
 
-The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace. The difference is that they have concept-enforced constraints, and they accept either range arguments or more iterator-sentinel argument pairs. They can work directly on a container and can be easily chained together.
+The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace. The difference is that they have [concept-enforced constraints](range-concepts.md), and they accept either range arguments or more iterator-sentinel argument pairs. They can work directly on a container and can be easily chained together.
 
 ## `<ranges>` functions
 
@@ -133,6 +133,7 @@ The range concepts mirror the hierarchy of iterator categories. The following ta
 
 ## See also
 
-[Range functions](range-functions.md)\
-[Range adaptors](range-adaptors.md)\
+[`<ranges>` functions](range-functions.md)\
+[`<ranges>` adaptors](range-adaptors.md)\
+[`<ranges>` concepts](range-concepts.md)\
 [Header files reference](../standard-library/cpp-standard-library-header-files.md)
diff --git a/docs/standard-library/toc.yml b/docs/standard-library/toc.yml
