[iterator.primitives] (original) (raw)

24 Iterators library [iterators]

24.4.1 General [iterator.primitives.general]

24.4.2 Standard iterator tags [std.iterator.tags]

24.4.3 Iterator operations [iterator.operations]

24.4.4 Range iterator operations [range.iter.ops]

24.4.4.1 General [range.iter.ops.general]

24.4.4.2 ranges​::​advance [range.iter.op.advance]

24.4.4.3 ranges​::​distance [range.iter.op.distance]

24.4.4.4 ranges​::​next [range.iter.op.next]

24.4.4.5 ranges​::​prev [range.iter.op.prev]

24.4.1 General [iterator.primitives.general]

To simplify the use of iterators, the library provides several classes and functions.

24.4.2 Standard iterator tags [std.iterator.tags]

24.4.3 Iterator operations [iterator.operations]

Since only random access iterators provide+and-operators, the library provides two function templatesadvanceanddistance.

These function templates use+and-for random access iterators (and are, therefore, constant time for them); for input, forward and bidirectional iterators they use++to provide linear time implementations.

template<class InputIterator, class Distance> constexpr void advance(InputIterator& i, Distance n);

Preconditions: nis negative only for bidirectional iterators.

Effects: Increments i by n if n is non-negative, and decrements i by -n otherwise.

template<class InputIterator> constexpr typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);

Preconditions: last is reachable from first, orInputIterator meets the Cpp17RandomAccessIterator requirements andfirst is reachable from last.

Effects: If InputIterator meets the Cpp17RandomAccessIterator requirements, returns (last - first); otherwise, incrementsfirst until last is reached and returns the number of increments.

template<class InputIterator> constexpr InputIterator next(InputIterator x,typename iterator_traits<InputIterator>::difference_type n = 1);

Effects: Equivalent to: advance(x, n); return x;

template<class BidirectionalIterator> constexpr BidirectionalIterator prev(BidirectionalIterator x,typename iterator_traits<BidirectionalIterator>::difference_type n = 1);

Effects: Equivalent to: advance(x, -n); return x;

24.4.4 Range iterator operations [range.iter.ops]

24.4.4.1 General [range.iter.ops.general]

The library includes the function templatesranges​::​advance, ranges​::​distance,ranges​::​next, and ranges​::​prevto 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 arandom_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_]

24.4.4.2 ranges​::​advance [range.iter.op.advance]

Effects:

• Otherwise, if n is non-negative, incrementsi by n.
• Otherwise, decrements i by -n.

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.

Preconditions: If n > 0, [i, bound) denotes a range.

If n == 0, [i, bound) or [bound, i) denotes a range.

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.

24.4.4.3 ranges​::​distance [range.iter.op.distance]

Preconditions: [first, last) denotes a range.

Effects: Increments first until last is reached and returns the number of increments.

template<class I, [sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized%5Fsentinel%5Ffor "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<decay_t<I>> S> constexpr iter_difference_t<decay_t<I>> ranges::distance(I&& first, S last);

Effects: Equivalent to:if constexpr (!is_array_v<remove_reference_t<I>>) return last - first;else return last - static_cast<decay_t<I>>(first);

template<[range](range.range#concept:range "25.4.2 Ranges [range.range]") R> constexpr range_difference_t<R> ranges::distance(R&& r);

Effects: If R models sized_range, equivalent to:return static_cast<range_difference_t<R>>(ranges::size(r));

Otherwise, equivalent to:return ranges::distance(ranges::begin(r), ranges::end(r));

24.4.4.4 ranges​::​next [range.iter.op.next]

Effects: Equivalent to: ++x; return x;

Effects: Equivalent to: ranges​::​advance(x, n); return x;

Effects: Equivalent to: ranges​::​advance(x, bound); return x;

Effects: Equivalent to: ranges​::​advance(x, n, bound); return x;

24.4.4.5 ranges​::​prev [range.iter.op.prev]

Effects: Equivalent to: --x; return x;

Effects: Equivalent to: ranges​::​advance(x, -n); return x;

Effects: Equivalent to: ranges​::​advance(x, -n, bound); return x;