22 Iterators library [iterators]

22.5 Iterator adaptors [predef.iterators]

22.5.3 Move iterators [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_category = typename iterator_traits<Iterator>::iterator_category;
    using value_type        = typename iterator_traits<Iterator>::value_type;
    using difference_type   = typename iterator_traits<Iterator>::difference_type;
    using pointer           = Iterator;
    using reference         = see below;

    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 move_iterator 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 unspecified operator[](difference_type n) const;

  private:
    Iterator current;   // exposition only
  };

  template<class Iterator1, class Iterator2>
    constexpr bool operator==(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
  template<class Iterator1, class Iterator2>
    constexpr bool operator!=(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
  template<class Iterator1, class Iterator2>
    constexpr bool operator<(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
  template<class Iterator1, class Iterator2>
    constexpr bool operator>(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
  template<class Iterator1, class Iterator2>
    constexpr bool operator<=(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
  template<class Iterator1, class Iterator2>
    constexpr bool operator>=(
      const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);

  template<class Iterator1, class Iterator2>
    constexpr auto operator-(
      const move_iterator<Iterator1>& x,
      const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
  template<class Iterator>
    constexpr move_iterator<Iterator> operator+(
      typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
  template<class Iterator>
    constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
}
1
#
Let R denote iterator_­traits<Iterator>​::​reference.
If is_­reference_­v<R> is true, the template specialization move_­iterator<Iterator> shall define the nested type named reference as a synonym for remove_­reference_­t<R>&&, otherwise as a synonym for R.

22.5.3.2 move_­iterator requirements [move.iter.requirements]

1
#
The template parameter Iterator shall satisfy the Cpp17InputIterator requirements ([input.iterators]).
Additionally, if any of the bidirectional or random access traversal functions are instantiated, the template parameter shall satisfy the Cpp17BidirectionalIterator requirements ([bidirectional.iterators]) or Cpp17RandomAccessIterator requirements ([random.access.iterators]), respectively.

22.5.3.3 move_­iterator 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 move_­iterator conversion [move.iter.op.conv]

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

22.5.3.5 move_­iterator element access [move.iter.elem]

🔗
constexpr reference operator*() const;
1
#
Returns: static_­cast<reference>(*current).
🔗
constexpr pointer operator->() const;
2
#
Returns: current.
🔗
constexpr unspecified operator[](difference_type n) const;
3
#
Returns: std​::​move(current[n]).

22.5.3.6 move_­iterator navigation [move.iter.nav]

🔗
constexpr move_iterator& operator++();
1
#
Effects: As if by ++current.
2
#
Returns: *this.
🔗
constexpr move_iterator operator++(int);
3
#
Effects: As if by: 
move_iterator tmp = *this;
++current;
return tmp;
🔗
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 move_­iterator comparisons [move.iter.op.comp]

🔗
template<class Iterator1, class Iterator2> constexpr bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
1
#
Returns: x.base() == y.base().
🔗
template<class Iterator1, class Iterator2> constexpr bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
2
#
Returns: !(x == y).
🔗
template<class Iterator1, class Iterator2> constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
3
#
Returns: x.base() < y.base().
🔗
template<class Iterator1, class Iterator2> constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
4
#
Returns: y < x.
🔗
template<class Iterator1, class Iterator2> constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
5
#
Returns: !(y < x).
🔗
template<class Iterator1, class Iterator2> constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
6
#
Returns: !(x < y).

22.5.3.8 move_­iterator 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());
1
#
Returns: x.base() - y.base().
🔗
template<class Iterator> constexpr move_iterator<Iterator> operator+( typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
2
#
Returns: x + n.
🔗
template<class Iterator> constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
3
#
Returns: move_­iterator<Iterator>(i).