[range.iter.ops] - C++17 → C++20

Files changed (1) hide show

tmp/tmp93q2ylcl/{from.md → to.md} +183 -0

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

	@@ -0,0 +1,183 @@

+### 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.
+[*Example 1*: `ranges::advance` uses the `+` operator to move a
+`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.
+[*Example 2*:
+``` cpp
+void foo() {
+    using namespace std::ranges;
+    std::vector<int> vec{1,2,3};
+    distance(begin(vec), end(vec));     // #1
+}
+```
+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
+template<input_or_output_iterator I>
+  constexpr void ranges::advance(I& i, iter_difference_t<I> n);
+```
+*Preconditions:* If `I` does not model `bidirectional_iterator`, `n` is
+not negative.
+*Effects:*
+- If `I` models `random_access_iterator`, equivalent to `i += n`.
+- Otherwise, if `n` is non-negative, increments `i` by `n`.
+- Otherwise, decrements `i` by `-n`.
+``` 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)`.
+- Otherwise, if `S` and `I` model `sized_sentinel_for<S, I>`, equivalent
+  to `ranges::advance(i, bound - i)`.
+- Otherwise, while `bool(i != bound)` is `true`, increments `i`.
+``` cpp
+template<input_or_output_iterator I, sentinel_for<I> S>
+  constexpr iter_difference_t<I> ranges::advance(I& i, iter_difference_t<I> n, S bound);
+```
+*Preconditions:* If `n > 0`, \[`i`, `bound`) denotes a range. If
+`n == 0`, \[`i`, `bound`) or \[`bound`, `i`) denotes a range. If
+`n < 0`, \[`bound`, `i`) denotes a range, `I` models
+`bidirectional_iterator`, and `I` and `S` model `same_as<I, S>`.
+*Effects:*
+- If `S` and `I` model `sized_sentinel_for<S, I>`:
+  - If |`n`| ≥ |`bound - i`|, equivalent to `ranges::advance(i, bound)`.
+  - Otherwise, equivalent to `ranges::advance(i, n)`.
+- Otherwise,
+  - if `n` is non-negative, while `bool(i != bound)` is `true`,
+    increments `i` but at most `n` times.
+  - Otherwise, while `bool(i != bound)` is `true`, decrements `i` but at
+    most `-n` times.
+*Returns:* `n - `M, where M is the difference between the ending and
+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);
+```
+*Effects:* If `R` models `sized_range`, equivalent to:
+``` cpp
+return static_cast<range_difference_t<R>>(ranges::size(r));     // [range.prim.size]
+```
+Otherwise, equivalent to:
+``` cpp
+return ranges::distance(ranges::begin(r), ranges::end(r));      // [range.access]
+```
+#### `ranges::next` <a id="range.iter.op.next">[[range.iter.op.next]]</a>
+``` cpp
+template<input_or_output_iterator I>
+  constexpr I ranges::next(I x);
+```
+*Effects:* Equivalent to: `++x; return x;`
+``` cpp
+template<input_or_output_iterator I>
+  constexpr I ranges::next(I x, iter_difference_t<I> n);
+```
+*Effects:* Equivalent to: `ranges::advance(x, n); return x;`
+``` cpp
+template<input_or_output_iterator I, sentinel_for<I> S>
+  constexpr I ranges::next(I x, S bound);
+```
+*Effects:* Equivalent to: `ranges::advance(x, bound); return x;`
+``` cpp
+template<input_or_output_iterator I, sentinel_for<I> S>
+  constexpr I ranges::next(I x, iter_difference_t<I> n, S bound);
+```
+*Effects:* Equivalent to: `ranges::advance(x, n, bound); return x;`
+#### `ranges::prev` <a id="range.iter.op.prev">[[range.iter.op.prev]]</a>
+``` 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);
+```
+*Effects:* Equivalent to: `ranges::advance(x, -n); return x;`
+``` cpp
+template<bidirectional_iterator I>
+  constexpr I ranges::prev(I x, iter_difference_t<I> n, I bound);
+```
+*Effects:* Equivalent to: `ranges::advance(x, -n, bound); return x;`

Diff to HTML by rtfpessoa