24 KiB
[iterators.counted]
24 Iterators library [iterators]
24.5 Iterator adaptors [predef.iterators]
24.5.7 Counted iterators [iterators.counted]
24.5.7.1 Class template counted_iterator [counted.iterator]
Class template counted_iterator is an iterator adaptor with the same behavior as the underlying iterator except that it keeps track of the distance to the end of its range.
It can be used together with default_sentinel in calls to generic algorithms to operate on a range of N elements starting at a given position without needing to know the end position a priori.
[Example 1: list s;// populate the list s with at least 10 strings vector v;// copies 10 strings into v: ranges::copy(counted_iterator(s.begin(), 10), default_sentinel, back_inserter(v)); â end example]
Two values i1 and i2 of typescounted_iterator andcounted_iterator refer to elements of the same sequence if and only if there exists some integer n such thatnext(i1.base(), i1.count() + n) andnext(i2.base(), i2.count() + n) refer to the same (possibly past-the-end) element.
namespace std {template<input_or_output_iterator I>class counted_iterator {public:using iterator_type = I; using value_type = iter_value_t; // present only// if I models indirectly_readableusing difference_type = iter_difference_t; using iterator_concept = typename I::iterator_concept; // present only// if the qualified-id I::iterator_concept is valid and denotes a typeusing iterator_category = typename I::iterator_category; // present only// if the qualified-id I::iterator_category is valid and denotes a typeconstexpr counted_iterator() requires default_initializable = default; constexpr counted_iterator(I x, iter_difference_t n); templaterequires convertible_to<const I2&, I>constexpr counted_iterator(const counted_iterator& x); templaterequires assignable_from<I&, const I2&>constexpr counted_iterator& operator=(const counted_iterator& x); constexpr const I& base() const & noexcept; constexpr I base() &&; constexpr iter_difference_t count() const noexcept; constexpr decltype(auto) operator*(); constexpr decltype(auto) operator*() constrequires dereferenceable; constexpr auto operator->() const noexceptrequires contiguous_iterator; constexpr counted_iterator& operator++(); constexpr decltype(auto) operator++(int); constexpr counted_iterator operator++(int)requires forward_iterator; constexpr counted_iterator& operator--()requires bidirectional_iterator; constexpr counted_iterator operator--(int)requires bidirectional_iterator; constexpr counted_iterator operator+(iter_difference_t n) constrequires random_access_iterator; friend constexpr counted_iterator operator+( iter_difference_t n, const counted_iterator& x)requires random_access_iterator; constexpr counted_iterator& operator+=(iter_difference_t n)requires random_access_iterator; constexpr counted_iterator operator-(iter_difference_t n) constrequires random_access_iterator; template<common_with I2>friend constexpr iter_difference_t operator-(const counted_iterator& x, const counted_iterator& y); friend constexpr iter_difference_t operator-(const counted_iterator& x, default_sentinel_t) noexcept; friend constexpr iter_difference_t operator-( default_sentinel_t, const counted_iterator& y) noexcept; constexpr counted_iterator& operator-=(iter_difference_t n)requires random_access_iterator; constexpr decltype(auto) operator[](iter_difference_t n) constrequires random_access_iterator; template<common_with I2>friend constexpr bool operator==(const counted_iterator& x, const counted_iterator& y); friend constexpr bool operator==(const counted_iterator& x, default_sentinel_t) noexcept; template<common_with I2>friend constexpr strong_ordering operator<=>(const counted_iterator& x, const counted_iterator& y); friend constexpr decltype(auto) iter_move(const counted_iterator& i)noexcept(noexcept(ranges::iter_move(i.current)))requires input_iterator; template<indirectly_swappable I2>friend constexpr void iter_swap(const counted_iterator& x, const counted_iterator& y)noexcept(noexcept(ranges::iter_swap(x.current, y.current))); private: I current = I(); // exposition only iter_difference_t length = 0; // exposition only}; template<input_iterator I>requires same_as<ITER_TRAITS(I), iterator_traits> // see [iterator.concepts.general]struct iterator_traits<counted_iterator> : iterator_traits {using pointer = conditional_t<contiguous_iterator, add_pointer_t<iter_reference_t>, void>; };}
24.5.7.2 Constructors and conversions [counted.iter.const]
constexpr counted_iterator(I i, iter_difference_t<I> n);
Hardened preconditions: n >= 0 is true.
Effects: Initializes current with std::move(i) andlength with n.
template<class I2> requires [convertible_to](concept.convertible#concept:convertible_to "18.4.4 Concept convertible_to [concept.convertible]")<const I2&, I> constexpr counted_iterator(const counted_iterator<I2>& x);
Effects: Initializes current with x.current andlength with x.length.
template<class I2> requires [assignable_from](concept.assignable#concept:assignable_from "18.4.8 Concept assignable_from [concept.assignable]")<I&, const I2&> constexpr counted_iterator& operator=(const counted_iterator<I2>& x);
Effects: Assigns x.current to current andx.length to length.
Returns: *this.
24.5.7.3 Accessors [counted.iter.access]
constexpr const I& base() const & noexcept;
Effects: Equivalent to: return current;
constexpr I base() &&;
Returns: std::move(current).
constexpr iter_difference_t<I> count() const noexcept;
Effects: Equivalent to: return length;
24.5.7.4 Element access [counted.iter.elem]
constexpr decltype(auto) operator*(); constexpr decltype(auto) operator*() const requires [dereferenceable](iterator.synopsis#concept:dereferenceable "24.2 Header <iterator> synopsis [iterator.synopsis]")<const I>;
Hardened preconditions: length > 0 is true.
Effects: Equivalent to: return *current;
constexpr auto operator->() const noexcept requires [contiguous_iterator](iterator.concept.contiguous#concept:contiguous_iterator "24.3.4.14 Concept contiguous_iterator [iterator.concept.contiguous]")<I>;
Effects: Equivalent to: return to_address(current);
constexpr decltype(auto) operator[](iter_difference_t<I> n) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Hardened preconditions: n < length is true.
Effects: Equivalent to: return current[n];
24.5.7.5 Navigation [counted.iter.nav]
constexpr counted_iterator& operator++();
Hardened preconditions: length > 0 is true.
Effects: Equivalent to:++current;--length;return *this;
constexpr decltype(auto) operator++(int);
Hardened preconditions: length > 0 is true.
Effects: Equivalent to:--length;try { return current++; }catch(...) { ++length; throw; }
constexpr counted_iterator operator++(int) requires [forward_iterator](iterator.concept.forward#concept:forward_iterator "24.3.4.11 Concept forward_iterator [iterator.concept.forward]")<I>;
Effects: Equivalent to:counted_iterator tmp = *this;++*this;return tmp;
constexpr counted_iterator& operator--() requires [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]")<I>;
Effects: Equivalent to:--current;++length;return *this;
constexpr counted_iterator operator--(int) requires [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_iterator [iterator.concept.bidir]")<I>;
Effects: Equivalent to:counted_iterator tmp = *this;--*this;return tmp;
constexpr counted_iterator operator+(iter_difference_t<I> n) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Effects: Equivalent to: return counted_iterator(current + n, length - n);
friend constexpr counted_iterator operator+( iter_difference_t<I> n, const counted_iterator& x) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Effects: Equivalent to: return x + n;
constexpr counted_iterator& operator+=(iter_difference_t<I> n) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Hardened preconditions: n <= length is true.
Effects: Equivalent to:current += n; length -= n;return *this;
constexpr counted_iterator operator-(iter_difference_t<I> n) const requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Effects: Equivalent to: return counted_iterator(current - n, length + n);
template<[common_with](concept.common#concept:common_with "18.4.6 Concept common_with [concept.common]")<I> I2> friend constexpr iter_difference_t<I2> operator-( const counted_iterator& x, const counted_iterator<I2>& y);
Preconditions: x and y refer to elements of the same sequence ([counted.iterator]).
Effects: Equivalent to: return y.length - x.length;
friend constexpr iter_difference_t<I> operator-( const counted_iterator& x, default_sentinel_t) noexcept;
Effects: Equivalent to:return -x.length;
friend constexpr iter_difference_t<I> operator-( default_sentinel_t, const counted_iterator& y) noexcept;
Effects: Equivalent to: return y.length;
constexpr counted_iterator& operator-=(iter_difference_t<I> n) requires [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_access_iterator [iterator.concept.random.access]")<I>;
Hardened preconditions: -n <= length is true.
Effects: Equivalent to:current -= n; length += n;return *this;
24.5.7.6 Comparisons [counted.iter.cmp]
template<[common_with](concept.common#concept:common_with "18.4.6 Concept common_with [concept.common]")<I> I2> friend constexpr bool operator==( const counted_iterator& x, const counted_iterator<I2>& y);
Preconditions: x and y refer to elements of the same sequence ([counted.iterator]).
Effects: Equivalent to: return x.length == y.length;
friend constexpr bool operator==( const counted_iterator& x, default_sentinel_t) noexcept;
Effects: Equivalent to: return x.length == 0;
template<[common_with](concept.common#concept:common_with "18.4.6 Concept common_with [concept.common]")<I> I2> friend constexpr strong_ordering operator<=>( const counted_iterator& x, const counted_iterator<I2>& y);
Preconditions: x and y refer to elements of the same sequence ([counted.iterator]).
Effects: Equivalent to: return y.length <=> x.length;
[Note 1:
The argument order in the Effects: element is reversed because length counts down, not up.
â end note]
24.5.7.7 Customizations [counted.iter.cust]
friend constexpr decltype(auto) iter_move(const counted_iterator& i) noexcept(noexcept(ranges::iter_move(i.current))) requires [input_iterator](iterator.concept.input#concept:input_iterator "24.3.4.9 Concept input_iterator [iterator.concept.input]")<I>;
Hardened preconditions: i.length > 0 is true.
Effects: Equivalent to: return ranges::iter_move(i.current);
template<[indirectly_swappable](alg.req.ind.swap#concept:indirectly_swappable "24.3.7.4 Concept indirectly_swappable [alg.req.ind.swap]")<I> I2> friend constexpr void iter_swap(const counted_iterator& x, const counted_iterator<I2>& y) noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
Hardened preconditions: Both x.length > 0 and y.length > 0 are true.
Effects: Equivalent to ranges::iter_swap(x.current, y.current).