22 Iterators library [iterators]

22.5 Iterator adaptors [predef.iterators]

22.5.3 Move iterators and sentinels [move.iterators]

1
#
Class template move_­iterator is an iterator adaptor with the same behavior as the underlying iterator except that its indirection operator implicitly converts the value returned by the underlying iterator's indirection operator to an rvalue.
Some generic algorithms can be called with move iterators to replace copying with moving.
2
#
[ Example
: 
list<string> s;
// populate the list s
vector<string> v1(s.begin(), s.end());          // copies strings into v1
vector<string> v2(make_move_iterator(s.begin()),
                  make_move_iterator(s.end())); // moves strings into v2
— end example
 ]

22.5.3.1 Class template move_­iterator [move.iterator]

namespace std {
  template<class Iterator>
  class move_iterator {
  public:
    using iterator_type     = Iterator;
    using iterator_concept  = input_iterator_tag;
    using iterator_category = see below;
    using value_type        = iter_value_t<Iterator>;
    using difference_type   = iter_difference_t<Iterator>;
    using pointer           = Iterator;
    using reference         = iter_rvalue_reference_t<Iterator>;

    constexpr move_iterator();
    constexpr explicit move_iterator(Iterator i);
    template<class U> constexpr move_iterator(const move_iterator<U>& u);
    template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);

    constexpr iterator_type base() const;
    constexpr reference operator*() const;
    constexpr pointer operator->() const;

    constexpr move_iterator& operator++();
    constexpr auto operator++(int);
    constexpr move_iterator& operator--();
    constexpr move_iterator operator--(int);

    constexpr move_iterator operator+(difference_type n) const;
    constexpr move_iterator& operator+=(difference_type n);
    constexpr move_iterator operator-(difference_type n) const;
    constexpr move_iterator& operator-=(difference_type n);
    constexpr reference operator[](difference_type n) const;

    template<Sentinel<Iterator> S>
      friend constexpr bool
        operator==(const move_iterator& x, const move_sentinel<S>& y);
    template<Sentinel<Iterator> S>
      friend constexpr bool
        operator==(const move_sentinel<S>& x, const move_iterator& y);
    template<Sentinel<Iterator> S>
      friend constexpr bool
        operator!=(const move_iterator& x, const move_sentinel<S>& y);
    template<Sentinel<Iterator> S>
      friend constexpr bool
        operator!=(const move_sentinel<S>& x, const move_iterator& y);
    template<SizedSentinel<Iterator> S>
      friend constexpr iter_difference_t<Iterator>
        operator-(const move_sentinel<S>& x, const move_iterator& y);
    template<SizedSentinel<Iterator> S>
      friend constexpr iter_difference_t<Iterator>
        operator-(const move_iterator& x, const move_sentinel<S>& y);
    friend constexpr iter_rvalue_reference_t<Iterator>
      iter_move(const move_iterator& i)
        noexcept(noexcept(ranges::iter_move(i.current)));
    template<IndirectlySwappable<Iterator> Iterator2>
      friend constexpr void
        iter_swap(const move_iterator& x, const move_iterator<Iterator2>& y)
          noexcept(noexcept(ranges::iter_swap(x.current, y.current)));

  private:
    Iterator current;   // exposition only
  };
}
1
#
The member typedef-name iterator_­category denotes
  • (1.1)
    random_­access_­iterator_­tag if the type iterator_­traits<​Iterator>::iterator_­category models DerivedFrom<random_­access_­iterator_­tag>, and
  • (1.2)
    iterator_­traits<​Iterator>::iterator_­category otherwise.

22.5.3.2 Requirements [move.iter.requirements]

1
#
The template parameter Iterator shall either meet the Cpp17InputIterator requirements ([input.iterators]) or model InputIterator ([iterator.concept.input]).
Additionally, if any of the bidirectional traversal functions are instantiated, the template parameter shall either meet the Cpp17BidirectionalIterator requirements ([bidirectional.iterators]) or model BidirectionalIterator ([iterator.concept.bidir]).
If any of the random access traversal functions are instantiated, the template parameter shall either meet the Cpp17RandomAccessIterator requirements ([random.access.iterators]) or model RandomAccessIterator ([iterator.concept.random.access]).

22.5.3.3 Construction and assignment [move.iter.cons]

🔗
constexpr move_iterator();
1
#
Effects: Constructs a move_­iterator, value-initializing current.
Iterator operations applied to the resulting iterator have defined behavior if and only if the corresponding operations are defined on a value-initialized iterator of type Iterator.
🔗
constexpr explicit move_iterator(Iterator i);
2
#
Effects: Constructs a move_­iterator, initializing current with i.
🔗
template<class U> constexpr move_iterator(const move_iterator<U>& u);
3
#
Effects: Constructs a move_­iterator, initializing current with u.base().
4
#
Requires: U shall be convertible to Iterator.
🔗
template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
5
#
Effects: Assigns u.base() to current.
6
#
Requires: U shall be convertible to Iterator.

22.5.3.4 Conversion [move.iter.op.conv]

🔗
constexpr Iterator base() const;
1
#
Returns: current.

22.5.3.5 Element access [move.iter.elem]

🔗
constexpr reference operator*() const;
1
#
Effects: Equivalent to: return ranges::iter_­move(current);
🔗
constexpr pointer operator->() const;
2
#
Returns: current.
🔗
constexpr reference operator[](difference_type n) const;
3
#
Effects: Equivalent to: ranges::iter_­move(current + n);

22.5.3.6 Navigation [move.iter.nav]

🔗
constexpr move_iterator& operator++();
1
#
Effects: As if by ++current.
2
#
Returns: *this.
🔗
constexpr auto operator++(int);
3
#
Effects: If Iterator models ForwardIterator, equivalent to: 
move_iterator tmp = *this;
++current;
return tmp;
Otherwise, equivalent to ++current.
🔗
constexpr move_iterator& operator--();
4
#
Effects: As if by --current.
5
#
Returns: *this.
🔗
constexpr move_iterator operator--(int);
6
#
Effects: As if by: 
move_iterator tmp = *this;
--current;
return tmp;
🔗
constexpr move_iterator operator+(difference_type n) const;
7
#
Returns: move_­iterator(current + n).
🔗
constexpr move_iterator& operator+=(difference_type n);
8
#
Effects: As if by: current += n;
9
#
Returns: *this.
🔗
constexpr move_iterator operator-(difference_type n) const;
10
#
Returns: move_­iterator(current - n).
🔗
constexpr move_iterator& operator-=(difference_type n);
11
#
Effects: As if by: current -= n;
12
#
Returns: *this.

22.5.3.7 Comparisons [move.iter.op.comp]

🔗
template<class Iterator1, class Iterator2> constexpr bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<Sentinel<Iterator> S> friend constexpr bool operator==(const move_iterator& x, const move_sentinel<S>& y); template<Sentinel<Iterator> S> friend constexpr bool operator==(const move_sentinel<S>& x, const move_iterator& y);
1
#
Constraints: The expression x.base() == y.base() shall be valid and convertible to bool.
2
#
Returns: x.base() == y.base().
🔗
template<class Iterator1, class Iterator2> constexpr bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); template<Sentinel<Iterator> S> friend constexpr bool operator!=(const move_iterator& x, const move_sentinel<S>& y); template<Sentinel<Iterator> S> friend constexpr bool operator!=(const move_sentinel<S>& x, const move_iterator& y);
3
#
Constraints: The expression x.base() == y.base() shall be valid and convertible to bool.
4
#
Returns: !(x == y).
🔗
template<class Iterator1, class Iterator2> constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
5
#
Constraints: The expression x.base() < y.base() shall be valid and convertible to bool.
6
#
Returns: x.base() < y.base().
🔗
template<class Iterator1, class Iterator2> constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
7
#
Constraints: The expression y.base() < x.base() shall be valid and convertible to bool.
8
#
Returns: y < x.
🔗
template<class Iterator1, class Iterator2> constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
9
#
Constraints: The expression y.base() < x.base() shall be valid and convertible to bool.
10
#
Returns: !(y < x).
🔗
template<class Iterator1, class Iterator2> constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
11
#
Constraints: The expression x.base() < y.base() shall be valid and convertible to bool.
12
#
Returns: !(x < y).

22.5.3.8 Non-member functions [move.iter.nonmember]

🔗
template<class Iterator1, class Iterator2> constexpr auto operator-(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base()); template<SizedSentinel<Iterator> S> friend constexpr iter_difference_t<Iterator> operator-(const move_sentinel<S>& x, const move_iterator& y); template<SizedSentinel<Iterator> S> friend constexpr iter_difference_t<Iterator> operator-(const move_iterator& x, const move_sentinel<S>& y);
1
#
Returns: x.base() - y.base().
🔗
template<class Iterator> constexpr move_iterator<Iterator> operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x);
2
#
Constraints: The expression x + n shall be valid and have type Iterator.
3
#
Returns: x + n.
🔗
friend constexpr iter_rvalue_reference_t<Iterator> iter_move(const move_iterator& i) noexcept(noexcept(ranges::iter_move(i.current)));
4
#
Effects: Equivalent to: return ranges::iter_­move(i.current);
🔗
template<IndirectlySwappable<Iterator> Iterator2> friend constexpr void iter_swap(const move_iterator& x, const move_iterator<Iterator2>& y) noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
5
#
Effects: Equivalent to: ranges::iter_­swap(x.current, y.current).
🔗
template<class Iterator> constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
6
#
Returns: move_­iterator<Iterator>(i).

22.5.3.9 Class template move_­sentinel [move.sentinel]

1
#
Class template move_­sentinel is a sentinel adaptor useful for denoting ranges together with move_­iterator.
When an input iterator type I and sentinel type S model Sentinel<S, I>, move_­sentinel<S> and move_­iterator<I> model Sentinel<move_­sentinel<S>, move_­iterator<I>> as well.
2
#
[ Example
:
A move_­if algorithm is easily implemented with copy_­if using move_­iterator and move_­sentinel:
template<InputIterator I, Sentinel<I> S, WeaklyIncrementable O,
         IndirectUnaryPredicate<I> Pred>
  requires IndirectlyMovable<I, O>
void move_if(I first, S last, O out, Pred pred) {
  std::ranges::copy_if(move_iterator<I>{first}, move_sentinel<S>{last}, out, pred);
}
— end example
 ]
namespace std {
  template<Semiregular S>
  class move_sentinel {
  public:
    constexpr move_sentinel();
    constexpr explicit move_sentinel(S s);
    template<class S2>
      requires ConvertibleTo<const S2&, S>
        constexpr move_sentinel(const move_sentinel<S2>& s);
    template<class S2>
      requires Assignable<S&, const S2&>
        constexpr move_sentinel& operator=(const move_sentinel<S2>& s);

    constexpr S base() const;
  private:
    S last;     // exposition only
  };
}

22.5.3.10 Operations [move.sent.ops]

🔗
constexpr move_sentinel();
1
#
Effects: Value-initializes last.
If is_­trivially_­default_­constructible_­v<S> is true, then this constructor is a constexpr constructor.
🔗
constexpr explicit move_sentinel(S s);
2
#
Effects: Initializes last with std::move(s).
🔗
template<class S2> requires ConvertibleTo<const S2&, S> constexpr move_sentinel(const move_sentinel<S2>& s);
3
#
Effects: Initializes last with s.last.
🔗
template<class S2> requires Assignable<S&, const S2&> constexpr move_sentinel& operator=(const move_sentinel<S2>& s);
4
#
Effects: Equivalent to: last = s.last; return *this;