draft

TylerMSFT · TylerMSFT · commit d52872929485 · 2022-12-15T09:43:54.000-08:00
diff --git a/docs/standard-library/iterator-concepts.md b/docs/standard-library/iterator-concepts.md
@@ -1,11 +1,11 @@
 ---
 description: "Learn more about iterator concepts."
-title: "<iterator> concepts"
+title: "Iterator concepts"
 ms.date: 12/05/2022
 f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_iterator", "ranges/std::ranges::borrowed_iterator", "ranges/std::ranges::common_iterator", "ranges/std::ranges::contiguous_iterator", "ranges/std::ranges::forward_iterator", "ranges/std::ranges::input_iterator", "ranges/std::ranges::output_iterator", "ranges/std::ranges::random_access_iterator", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_iterator", "ranges/std::ranges::view", "ranges/std::ranges::viewable_iterator"]
 helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_iterator", "std::ranges [C++], ranges::borrowed_iterator", "std::ranges [C++], ranges::common_iterator", "std::ranges [C++], ranges::contiguous_iterator", "std::ranges [C++], ranges::forward_iterator", "std::ranges [C++], ranges::input_iterator", "std::ranges [C++], ranges::output_iterator", "std::ranges [C++], ranges::random_access_iterator", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_iterator", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_iterator"]
 ---
-# `<iterator>` concepts
+# Iterator concepts
 
 Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiation, specify template argument requirements in a readable form, and provide more succinct template related compiler errors.
 
@@ -52,17 +52,19 @@ When you pass the compiler switch `/diagnostics:caret` to Visual Studio 2022 ver
 
 Iterator concepts are defined in the `std` namespace as declared in the `<iterator>` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on.
 
-There are six categories of iterators. They are directly related to the categories of ranges listed in [`<ranges>`](ranges.md#kinds-of-ranges). In order of increasing capability, the categories are:
+There are six categories of iterators. They are directly related to the categories of ranges listed in [`<ranges>`](ranges.md#kinds-of-ranges).
 
-| Iterator concept | Description |
-|--|--|
-DONE | [`input_or_output_iterator`](#input_or_output_iterator)<sup>C++20</sup> | The basis of the iterator concept taxonomy. |
-DONE | [`output_iterator`](#output_iterator)<sup>C++20</sup> | Test for an iterator that you can write to. |
-DONE | [`input_iterator`](#input_iterator)<sup>C++20</sup> | Test for an iterator that you can read from at least once. |
-DONE | [`forward_iterator`](#forward_iterator)<sup>C++20</sup> | Test for an iterator that can read (and possibly write) multiple times. |
-DONE | [`bidirectional_iterator`](#bidirectional_iterator)<sup>C++20</sup> | Test for an iterator that can read and write both forwards and backwards. |
-DONE | [`random_access_iterator`](#random_access_iterator)<sup>C++20</sup> | Test for an iterator that can read and write by index. |
-DONE | [`contiguous_iterator`](#contiguous_iterator)<sup>C++20</sup> | Test for an iterator whose elements are sequential in memory and can be accessed using pointer arithmetic. |
+The following iterator concepts are listed in order of increasing capability. `input_or_output_iterator` is at the low end of the capability hierarchy, and `contiguous_iterator` is at the high end. Iterators higher in the hierarchy can generally be used in place of those that are lower, but not vice-versa. For example, a `random_access_iterator` iterator can be used in place of a `forward_iterator`, but not the other way around. An exception to the rule that iterators higher in the hierarchy can generally be used in place of those that are lower is `input_iterator`, which can't be used in place of `output_iterator` because it can't write.
+
+| Iterator concept | Description | Direction | Read/write | Multi-pass | Example types that use this iterator |
+|--|--|--|--|--|--|
+| [`input_or_output_iterator`](#input_or_output_iterator)<sup>C++20</sup> | The basis of the iterator concept taxonomy. | Forward | Read or write | Single-pass | `std::istream_iterator`, `std::ostream_iterator` |
+| [`output_iterator`](#output_iterator)<sup>C++20</sup> | Test for an iterator that you can write to. | Forward | Write | Single-pass | `ostream`, `inserter` |
+| [`input_iterator`](#input_iterator)<sup>C++20</sup> | Test for an iterator that you can read from at least once. | Forward | Read | Single-pass | `istream`, `istreambuf_iterator` |
+| [`forward_iterator`](#forward_iterator)<sup>C++20</sup> | Test for an iterator that can read (and possibly write) multiple times. | Forward | Read/write | Multi-pass | `vector::iterator`, `list::iterator` |
+| [`bidirectional_iterator`](#bidirectional_iterator)<sup>C++20</sup> | Test for an iterator that can read and write both forwards and backwards. | Forward/Backward | Read/write | Multi-pass | `list`, `set`, `multiset`, `map`, and `multimap`. |
+| [`random_access_iterator`](#random_access_iterator)<sup>C++20</sup> | Test for an iterator that can read and write by index. | Read/write | Multi-pass | `vector::iterator`, `array::iterator` |
+| [`contiguous_iterator`](#contiguous_iterator)<sup>C++20</sup> | Test for an iterator whose elements are sequential in memory and can be accessed using pointer arithmetic. | Read/write | Multi-pass | `array`, `vector` |
 
 An iterator that meets the requirements of a concept generally meets the requirements of the concepts in the rows that precede it in the previous table. For example, a `random_access_iterator` has the capability of a `bidirectional_iterator`, `forward_iterator`, `input_iterator`, and `output_iterator`. An exception is `input_iterator` which doesn't have the capability of an `output_iterator` because it can't be written to.
 
diff --git a/docs/standard-library/iterator.md b/docs/standard-library/iterator.md
@@ -1,6 +1,6 @@
 ---
-description: "Learn more about: <iterator>"
 title: "<iterator>"
+description: "Learn more about: <iterator>"
 ms.date: 12/14/2022
 f1_keywords: ["<iterator>"]
 helpviewer_keywords: ["iterator header"]
@@ -9,10 +9,6 @@ helpviewer_keywords: ["iterator header"]
 
 Defines predefined iterators and stream iterators, iterator primitives, and supporting templates.
 
-The predefined iterators include insert and reverse adaptors.
-
-There are three classes of insert iterator adaptors: front, back, and general. They provide insert semantics rather than overwrite semantics that the container member function iterators provide.
-
 ## Requirements
 
 **Header:** `<iterator>`
@@ -21,30 +17,9 @@ There are three classes of insert iterator adaptors: front, back, and general. T
 
 ## Remarks
 
-Iterators are a generalization of pointers that allow a C++ program to work with different data structures in a uniform way. Instead of operating on specific data types, algorithms operate on a range specified by a type of iterator. Any data structure that satisfies the requirements of the iterator can be operated upon by the algorithm. In C++20, there are 6 categories of iterators:
-
-JTW fix this table up
+Iterators are a generalization of pointers that allow a C++ program to work with different data structures in a uniform way. Instead of operating on specific data types, algorithms operate on a range of values as specified by a kind of iterator. Algorithms can operate on any data structure that satisfies the requirements of the iterator.
 
-| Kind  | Direction | Read/Write| Example types|
-|---|---|---|---|
-| `bidirectional_iterator` | Forward and backward | Read/Write | `list`, `set`, `multiset`, `map`, and `multimap`. |
-| `contiguous_iterator` | Forward and backward | Read/Write | JTW |
-| `forward_iterator` | Forward | Read/Write | `vector` |
-| `input_iterator` | Forward | Read | `istream`|
-| `output_iterator` | Forward  | Write | `ostream`, `inserter` |
-| `random_access_iterator` | Any order | Read/Write | `vector`, `deque`, `string`, and `array`. |
-
-Until In C++17, there are five types or categories of iterators:
-
-| Kind  | Direction | Read/Write| Multipass | Some example types|
-|---|---|---|---|
-| Output | Forward  | Write | No | `ostream`, `inserter` |
-| Input | Forward | Read | No | `istream`|
-| Forward | Forward | Read/Write | Yes | `vector`, `unordered_set`, `unordered_multiset`, `unordered_map`, and `unordered_multimap`. |
-| Bidirectional | Forward and backward | Read/Write | Yes | `list`, `set`, `multiset`, `map`, and `multimap`. |
-| Random access | Any order | Read/Write | Yes | `vector`, `deque`, `string`, and `array`. |
-
-Iterators are arranged in a hierarchy of capability. In the table above, output iterators are at the low end of the capability hierarchy, and random-access iterators are at the high end. Iterators higher in the hierarchy can generally be used in place of those that are lower, but not vice-versa. For example, a random-access iterator can be used in place of a forward iterator, but not the other way around.
+In C++20, there are 6 categories of iterators. Iterators are arranged in a hierarchy of capability. Their capabilities are specified by C++20 concepts. For a description of the various iterators and their capabilities, see [Iterator concepts](iterator-concepts.md)
 
 Visual Studio has added extensions to C++ Standard Library iterators to support debugging for checked and unchecked iterators. For more information, see [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md).
 
@@ -114,17 +89,19 @@ Visual Studio has added extensions to C++ Standard Library iterators to support
 
 ## Concepts
 
+The following concepts are defined in the `std` namespace. They apply to iterators, and are related to the iterator categories for ranges described in [`<ranges>` concepts](range-concepts.md).
+
 | Iterator concept | Description |
 |--|--|
-| [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator) | Specifies an iterator that can read and write both forwards and backwards. |
-| [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator) | Specifies an iterator whose elements are sequential in memory and can be accessed using pointer arithmetic. |
-| [`forward_iterator`](iterator-concepts.md#forward_iterator) | Specifies an iterator that can read (and possibly write) multiple times. |
-| [`input_iterator`](iterator-concepts.md#input_iterator) | Specifies an iterator that you can read from at least once. |
-| [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator) | The basis of the iterator concept taxonomy. |
+| [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator)<sup>C++20</sup> | Specifies an iterator that can read and write both forwards and backwards. |
+| [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator)<sup>C++20</sup> | Specifies an iterator whose elements are sequential in memory and can be accessed using pointer arithmetic. |
+| [`forward_iterator`](iterator-concepts.md#forward_iterator)<sup>C++20</sup> | Specifies an iterator that can read (and possibly write) multiple times. |
+| [`input_iterator`](iterator-concepts.md#input_iterator)<sup>C++20</sup> | Specifies an iterator that you can read from at least once. |
+| [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator)<sup>C++20</sup> | The basis of the iterator concept taxonomy. |
 | [`output_iterator`](iterator-concepts.md#output_iterator) | Specifies an iterator that you can write to. |
-| [`random_access_iterator`](iterator-concepts.md#random_access_iterator) | Specifies an iterator that can read and write by index. |
-| [`sentinel_for`](iterator-concepts.md#sentinel_for)<sup>C++20</sup> | JTW |
-| [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for)<sup>C++20</sup> | JTW |
+| [`random_access_iterator`](iterator-concepts.md#random_access_iterator)<sup>C++20</sup> | Specifies an iterator that can read and write by index. |
+| [`sentinel_for`](iterator-concepts.md#sentinel_for)<sup>C++20</sup> | Test that a type is a sentinel for an iterator type. |
+| [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for)<sup>C++20</sup> | Specifies that an iterator and its sentinel can be subtracted (using `-`) to find their difference in constant time. |
 
 ## See also
 
diff --git a/docs/standard-library/ranges.md b/docs/standard-library/ranges.md
@@ -116,7 +116,7 @@ The range algorithms are almost identical to the corresponding iterator-pair alg
 
 ### Kinds of ranges
 
-How you can iterate over the elements of a range depends on its underlying iterator type. The iterator type a range requires is specified as a C++20 concept.
+How you can iterate over the elements of a range depends on its underlying iterator type. Ranges use C++ concepts to specify the iterator they support.
 
 In C++20, to say that concept *X* refines concept *Y* means that everything that satisfies concept *Y* also satisfies concept *X*. For example: *car*, *bus*, and *truck* all refine *vehicle*.
 
diff --git a/docs/standard-library/view-classes.md b/docs/standard-library/view-classes.md
@@ -146,7 +146,7 @@ Each view class topic has a **Characteristics** section after the syntax section
 
 ### Ranges iterator hierarchy
 
-In the **Characteristics** section of each view class topic, the iterator category in **Underlying range** and **View iterator category** refers to the kind of iterators that ranges and views support. Ranges iterators are categorized into six levels of capability, which are identified by C++20 concepts. That hierarchy, in increasing order of capability, is:
+In the **Characteristics** section of each view class topic, the iterator category in **Underlying range** and **View iterator category** refers to the kind of iterator that the range/view supports. Ranges iterators are categorized into six levels of capability, which are identified by C++20 concepts. That hierarchy, in increasing order of capability, is:
 
 | Range iterator concept | Description |
 |--|--|
