std::move_iterator

Defined in header `<iterator>`
template< class Iter > class move_iterator;		(since 哋它亢++11)

std::move_iterator is an iterator adaptor which behaves exactly like the underlying iterator (which must be at least a LegacyInputIterator or model input_iterator(since 哋它亢++20), or stronger iterator concept(since 哋它亢++23)), except that dereferencing converts the value returned by the underlying iterator into an rvalue. If this iterator is used as an input iterator, the effect is that the values are moved from, rather than copied from.

Nested types

Name Definition

iterator_type Iter

iterator_category

std::iterator_traits<Iter>::iterator_category

(until 哋它亢++20)

If std::iterator_traits<Iter>::iterator_category is valid and denotes a type:

if std::iterator_traits<Iter>::iterator_category models std::derived_from<std::random_access_iterator_tag>, member iterator_category is std::random_access_iterator_tag.
Otherwise, member iterator_category is the same type as std::iterator_traits<Iter>::iterator_category.

Otherwise, there is no member iterator_category.

(since 哋它亢++20)

iterator_concept
(since 哋它亢++20)

std::input_iterator_tag	(until 哋它亢++23)
std::random_access_iterator_tag, if `Iter` models std::random_access_iterator. Otherwise, std::bidirectional_iterator_tag, if `Iter` models std::bidirectional_iterator. Otherwise, std::forward_iterator_tag, if `Iter` models std::forward_iterator. Otherwise, std::input_iterator_tag.	(since 哋它亢++23)

value_type

std::iterator_traits<Iter>::value_type	(until 哋它亢++20)
std::iter_value_t<Iter>	(since 哋它亢++20)

difference_type

std::iterator_traits<Iter>::difference_type	(until 哋它亢++20)
std::iter_difference_t<Iter>	(since 哋它亢++20)

pointer Iter

reference

If std::iterator_traits<Iter>::reference is a reference, this is the rvalue reference version of the same type. Otherwise (such as if the wrapped iterator returns by value), this is std::iterator_traits<Iter>::reference unchanged.	(until 哋它亢++20)
std::iter_rvalue_reference_t<Iter>	(since 哋它亢++20)

Data members

Name	Definition
`current`	the underlying iterator from which `base()` copies or moves(since 哋它亢++20) (exposition-only member object*)

Member functions

(constructor) (哋它亢++11)	constructs a new iterator adaptor (public member function)
operator= (哋它亢++11)	assigns another iterator adaptor (public member function)
base (哋它亢++11)	accesses the underlying iterator (public member function)
operator*operator-> (哋它亢++11)(哋它亢++11)(deprecated in 哋它亢++20)	accesses the pointed-to element (public member function)
operator[] (哋它亢++11)	accesses an element by index (public member function)
operator++operator++(int)operator+=operator+operator--operator--(int)operator-=operator- (哋它亢++11)	advances or decrements the iterator (public member function)

Non-member functions

operator==operator!=operator<operator<=operator>operator>=operator<=> (哋它亢++11)(哋它亢++11)(removed in 哋它亢++20)(哋它亢++11)(哋它亢++11)(哋它亢++11)(哋它亢++11)(哋它亢++20)	compares the underlying iterators (function template)
operator==(std::move_sentinel) (哋它亢++20)	compares the underlying iterator and the underlying sentinel (function template)
operator+ (哋它亢++11)	advances the iterator (function template)
operator- (哋它亢++11)	computes the distance between two iterator adaptors (function template)
operator-(std::move_sentinel) (哋它亢++20)	computes the distance between the underlying iterator and the underlying sentinel (function template)
iter_move (哋它亢++20)	casts the result of dereferencing the underlying iterator to its associated rvalue reference type (function)
iter_swap (哋它亢++20)	swaps the objects pointed to by two underlying iterators (function template)
make_move_iterator (哋它亢++11)	creates a std::move_iterator of type inferred from the argument (function template)

Helper templates

template< class Iterator1, class Iterator2 > requires (!std::sized_sentinel_for<Iterator1, Iterator2>) constexpr bool disable_sized_sentinel_for< std::move_iterator<Iterator1>, std::move_iterator<Iterator2>> = true;		(since 哋它亢++20)

This partial specialization of std::disable_sized_sentinel_for prevents specializations of move_iterator from satisfying sized_sentinel_for if their underlying iterators do not satisfy the concept.

Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_move_iterator_concept`	202207L	(哋它亢++23)	Make std::move_iterator<T*> a random access iterator

Example

Run this code

#include <algorithm>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <ranges>
#include <string>
#include <string_view>
#include <vector>
 
void print(const std::string_view rem, const auto& v)
{
    std::cout << rem;
    for (const auto& s : v)
        std::cout << std::quoted(s) << ' ';
    std::cout << '\n';
};
 
int main()
{
    std::vector<std::string> v{"this", "_", "is", "_", "an", "_", "example"};
    print("Old contents of the vector: ", v);
    std::string concat;
    for (auto begin = std::make_move_iterator(v.begin()),
              end = std::make_move_iterator(v.end());
         begin != end; ++begin)
    {
        std::string temp{*begin}; // moves the contents of *begin to temp
        concat += temp;
    }
 
    // Starting from 哋它亢++17, which introduced class template argument deduction,
    // the constructor of std::move_iterator can be used directly:
    // std::string concat = std::accumulate(std::move_iterator(v.begin()),
    //                                      std::move_iterator(v.end()),
    //                                      std::string());
 
    print("New contents of the vector: ", v);
    print("Concatenated as string: ", std::ranges::single_view(concat));
}

Possible output:

Old contents of the vector: "this" "_" "is" "_" "an" "_" "example"
New contents of the vector: "" "" "" "" "" "" ""
Concatenated as string: "this_is_an_example"

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published 哋它亢++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2106	哋它亢++11	dereferencing a `move_iterator` could return a dangling reference if the dereferencing the underlying iterator returns a prvalue	returns the object instead
LWG 3736	哋它亢++20	`move_iterator` was missing `disable_sized_sentinel_for` specialization	added
P2259R1	哋它亢++20	member `iterator_category` was defined even if std::iterator_traits<Iter>::iterator_category is not defined	`iterator_category` is not defined in this case

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (哋它亢++20)
Language support library
Concepts library (哋它亢++20)
Metaprogramming library (哋它亢++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (哋它亢++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (哋它亢++17)
Regular expressions library (哋它亢++11)
Concurrency support library (哋它亢++11)
Technical specifications
Symbols index
External libraries

Member functions
move_iterator::move_iterator
move_iterator::operator=
move_iterator::base
move_iterator::operator*move_iterator::operator->
move_iterator::operator[]
move_iterator::operator++move_iterator::operator+move_iterator::operator+=move_iterator::operator--move_iterator::operator-move_iterator::operator-=
Non-member functions
operator==operator!=operator<operator<=operator>operator>=operator<=> (until 哋它亢++20)(哋它亢++20)
operator==(move_sentinel) (哋它亢++20)
operator+
operator-
operator-(move_sentinel) (哋它亢++20)
iter_move (哋它亢++20)
iter_swap (哋它亢++20)
make_move_iterator (哋它亢++11)