[iterator.primitives] - C++20 → C++23

Files changed (1) hide show

tmp/tmpb485e88s/{from.md → to.md} +29 -17

tmp/tmpb485e88s/{from.md → to.md} RENAMED Viewed

@@ -1,7 +1,9 @@
 ## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
 To simplify the use of iterators, the library provides several classes
 and functions.
 ### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
@@ -29,13 +31,13 @@ namespace std {
 }
 ```
 [*Example 1*:
-For a program-defined iterator `BinaryTreeIterator`, it could be
-included into the bidirectional iterator category by specializing the
-`iterator_traits` template:
 ``` cpp
 template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
   using iterator_category = bidirectional_iterator_tag;
   using difference_type   = ptrdiff_t;
@@ -103,12 +105,12 @@ template<class InputIterator>
 *Preconditions:* `last` is reachable from `first`, or `InputIterator`
 meets the *Cpp17RandomAccessIterator* requirements and `first` is
 reachable from `last`.
 *Effects:* If `InputIterator` meets the *Cpp17RandomAccessIterator*
-requirements, returns `(last - first)`; otherwise, returns the number of
-increments needed to get from `first` to `last`.
 ``` cpp
 template<class InputIterator>
   constexpr InputIterator next(InputIterator x,
     typename iterator_traits<InputIterator>::difference_type n = 1);
@@ -124,10 +126,12 @@ template<class BidirectionalIterator>
 *Effects:* Equivalent to: `advance(x, -n); return x;`
 ### Range iterator operations <a id="range.iter.ops">[[range.iter.ops]]</a>
 The library includes the function templates `ranges::advance`,
 `ranges::distance`, `ranges::next`, and `ranges::prev` to manipulate
 iterators. These operations adapt to the set of operators provided by
 each iterator category to provide the most efficient implementation
 possible for a concrete iterator type.
@@ -136,11 +140,11 @@ possible for a concrete iterator type.
 `random_access_iterator` forward `n` steps in constant time. For an
 iterator type that does not model `random_access_iterator`,
 `ranges::advance` instead performs `n` individual increments with the
 `++` operator. — *end example*]
-The function templates defined in this subclause are not found by
 argument-dependent name lookup [[basic.lookup.argdep]]. When found by
 unqualified [[basic.lookup.unqual]] name lookup for the
 *postfix-expression* in a function call [[expr.call]], they inhibit
 argument-dependent name lookup.
@@ -155,18 +159,18 @@ void foo() {
 ```
 The function call expression at `#1` invokes `std::ranges::distance`,
 not `std::distance`, despite that (a) the iterator type returned from
 `begin(vec)` and `end(vec)` may be associated with namespace `std` and
-(b) `std::distance` is more specialized ([[temp.func.order]]) than
 `std::ranges::distance` since the former requires its first two
 parameters to have the same type.
 — *end example*]
 The number and order of deducible template parameters for the function
-templates defined in this subclause is unspecified, except where
 explicitly stated otherwise.
 #### `ranges::advance` <a id="range.iter.op.advance">[[range.iter.op.advance]]</a>
 ``` cpp
@@ -186,11 +190,13 @@ not negative.
 ``` cpp
 template<input_or_output_iterator I, sentinel_for<I> S>
   constexpr void ranges::advance(I& i, S bound);
 ```
-*Preconditions:* \[`i`, `bound`) denotes a range.
 *Effects:*
 - If `I` and `S` model `assignable_from<I&, S>`, equivalent to
   `i = std::move(bound)`.
@@ -223,21 +229,27 @@ template<input_or_output_iterator I, sentinel_for<I> S>
 starting positions of `i`.
 #### `ranges::distance` <a id="range.iter.op.distance">[[range.iter.op.distance]]</a>
 ``` cpp
-template<input_or_output_iterator I, sentinel_for<I> S>
   constexpr iter_difference_t<I> ranges::distance(I first, S last);
 ```
-*Preconditions:* \[`first`, `last`) denotes a range, or \[`last`,
-`first`) denotes a range and `S` and `I` model
-`same_as<S, I> && sized_sentinel_for<S, I>`.
-*Effects:* If `S` and `I` model `sized_sentinel_for<S, I>`, returns
-`(last - first)`; otherwise, returns the number of increments needed to
-get from `first` to `last`.
 ``` cpp
 template<range R>
   constexpr range_difference_t<R> ranges::distance(R&& r);
 ```
@@ -289,11 +301,11 @@ template<input_or_output_iterator I, sentinel_for<I> S>
 ``` cpp
 template<bidirectional_iterator I>
   constexpr I ranges::prev(I x);
 ```
-*Effects:* Equivalent to: `-``-``x; return x;`
 ``` cpp
 template<bidirectional_iterator I>
   constexpr I ranges::prev(I x, iter_difference_t<I> n);
 ```

 ## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
+### General <a id="iterator.primitives.general">[[iterator.primitives.general]]</a>
 To simplify the use of iterators, the library provides several classes
 and functions.
 ### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
 }
 ```
 [*Example 1*:
+A program-defined iterator `BinaryTreeIterator` can be included into the
+bidirectional iterator category by specializing the `iterator_traits`
+template:
 ``` cpp
 template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
   using iterator_category = bidirectional_iterator_tag;
   using difference_type   = ptrdiff_t;
 *Preconditions:* `last` is reachable from `first`, or `InputIterator`
 meets the *Cpp17RandomAccessIterator* requirements and `first` is
 reachable from `last`.
 *Effects:* If `InputIterator` meets the *Cpp17RandomAccessIterator*
+requirements, returns `(last - first)`; otherwise, increments `first`
+until `last` is reached and returns the number of increments.
 ``` cpp
 template<class InputIterator>
   constexpr InputIterator next(InputIterator x,
     typename iterator_traits<InputIterator>::difference_type n = 1);
 *Effects:* Equivalent to: `advance(x, -n); return x;`
 ### Range iterator operations <a id="range.iter.ops">[[range.iter.ops]]</a>
+#### General <a id="range.iter.ops.general">[[range.iter.ops.general]]</a>
 The library includes the function templates `ranges::advance`,
 `ranges::distance`, `ranges::next`, and `ranges::prev` to manipulate
 iterators. These operations adapt to the set of operators provided by
 each iterator category to provide the most efficient implementation
 possible for a concrete iterator type.
 `random_access_iterator` forward `n` steps in constant time. For an
 iterator type that does not model `random_access_iterator`,
 `ranges::advance` instead performs `n` individual increments with the
 `++` operator. — *end example*]
+The function templates defined in [[range.iter.ops]] are not found by
 argument-dependent name lookup [[basic.lookup.argdep]]. When found by
 unqualified [[basic.lookup.unqual]] name lookup for the
 *postfix-expression* in a function call [[expr.call]], they inhibit
 argument-dependent name lookup.
 ```
 The function call expression at `#1` invokes `std::ranges::distance`,
 not `std::distance`, despite that (a) the iterator type returned from
 `begin(vec)` and `end(vec)` may be associated with namespace `std` and
+(b) `std::distance` is more specialized [[temp.func.order]] than
 `std::ranges::distance` since the former requires its first two
 parameters to have the same type.
 — *end example*]
 The number and order of deducible template parameters for the function
+templates defined in [[range.iter.ops]] is unspecified, except where
 explicitly stated otherwise.
 #### `ranges::advance` <a id="range.iter.op.advance">[[range.iter.op.advance]]</a>
 ``` cpp
 ``` cpp
 template<input_or_output_iterator I, sentinel_for<I> S>
   constexpr void ranges::advance(I& i, S bound);
 ```
+*Preconditions:* Either
+`assignable_from<I&, S> || sized_sentinel_for<S, I>` is modeled, or
+\[`i`, `bound`) denotes a range.
 *Effects:*
 - If `I` and `S` model `assignable_from<I&, S>`, equivalent to
   `i = std::move(bound)`.
 starting positions of `i`.
 #### `ranges::distance` <a id="range.iter.op.distance">[[range.iter.op.distance]]</a>
 ``` cpp
+template<class I, sentinel_for<I> S>
+  requires (!sized_sentinel_for<S, I>)
   constexpr iter_difference_t<I> ranges::distance(I first, S last);
 ```
+*Preconditions:* \[`first`, `last`) denotes a range.
+*Effects:* Increments `first` until `last` is reached and returns the
+number of increments.
+``` cpp
+template<class I, sized_sentinel_for<decay_t<I>> S>
+  constexpr iter_difference_t<decay_t<I>> ranges::distance(I&& first, S last);
+```
+*Effects:* Equivalent to:
+`return last - static_cast<const decay_t<I>&>(first);`
 ``` cpp
 template<range R>
   constexpr range_difference_t<R> ranges::distance(R&& r);
 ```
 ``` cpp
 template<bidirectional_iterator I>
   constexpr I ranges::prev(I x);
 ```
+*Effects:* Equivalent to: `–x; return x;`
 ``` cpp
 template<bidirectional_iterator I>
   constexpr I ranges::prev(I x, iter_difference_t<I> n);
 ```

Diff to HTML by rtfpessoa