24 Iterators library [iterators]

24.5 Iterator adaptors [predef.iterators]

24.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 ]

24.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.

24.5.3.2 move_iterator requirements [move.iter.requirements]

1

The template parameter Iterator shall meet the requirements for an Input Iterator ([input.iterators]). Additionally, if any of the bidirectional or random access traversal functions are instantiated, the template parameter shall meet the requirements for a Bidirectional Iterator ([bidirectional.iterators]) or a Random Access Iterator ([random.access.iterators]), respectively.

24.5.3.3 move_iterator operations [move.iter.ops]

24.5.3.3.1 move_iterator constructors [move.iter.op.const]

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.

24.5.3.3.2 move_iterator::operator= [move.iter.op=]

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

1

Effects: Assigns u.base() to current.

2

Requires: U shall be convertible to Iterator.

24.5.3.3.3 move_iterator conversion [move.iter.op.conv]

constexpr Iterator base() const;

1

Returns: current.

24.5.3.3.4 move_iterator::operator* [move.iter.op.star]

constexpr reference operator*() const;

1

Returns: static_cast<reference>(*current).

24.5.3.3.5 move_iterator::operator-> [move.iter.op.ref]

constexpr pointer operator->() const;

1

Returns: current.

24.5.3.3.6 move_iterator::operator++ [move.iter.op.incr]

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;

24.5.3.3.7 move_iterator::operator-- [move.iter.op.decr]

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;

24.5.3.3.8 move_iterator::operator+ [move.iter.op.+]

constexpr move_iterator operator+(difference_type n) const;

1

Returns: move_iterator(current + n).

24.5.3.3.9 move_iterator::operator+= [move.iter.op.+=]

constexpr move_iterator& operator+=(difference_type n);

1

Effects: As if by: current += n;

2

Returns: *this.

24.5.3.3.10 move_iterator::operator- [move.iter.op.-]

constexpr move_iterator operator-(difference_type n) const;

1

Returns: move_iterator(current - n).

24.5.3.3.11 move_iterator::operator-= [move.iter.op.-=]

constexpr move_iterator& operator-=(difference_type n);

1

Effects: As if by: current -= n;

2

Returns: *this.

24.5.3.3.12 move_iterator::operator[] [move.iter.op.index]

constexpr unspecified operator[](difference_type n) const;

1

Returns: std::move(current[n]).

24.5.3.3.13 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).

24.5.3.3.14 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).