function template

std::move

template <class InputIterator, class OutputIterator>  OutputIterator move (InputIterator first, InputIterator last, OutputIterator result);

Move range of elements

Moves the elements in the range [first,last) into the range beginning at result.

The value of the elements in the [first,last) is transferred to the elements pointed by result. After the call, the elements in the range [first,last) are left in an unspecified but valid state.

The ranges shall not overlap in such a way that result points to an element in the range [first,last). For such cases, see move_backward.

The behavior of this function template is equivalent to:

template<class InputIterator, class OutputIterator>
  OutputIterator move (InputIterator first, InputIterator last, OutputIterator result)
{
  while (first!=last) {
    *result = std::move(*first);
    ++result; ++first;
  }
  return result;
}

Parameters

first, last: Input iterators to the initial and final positions in a sequence to be moved. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
result: Output iterator to the initial position in the destination sequence.
This shall not point to any element in the range [first,last).

Return value

An iterator to the end of the destination range where elements have been moved.

Example

// move algorithm example
#include <iostream>     // std::cout
#include <algorithm>    // std::move (ranges)
#include <utility>      // std::move (objects)
#include <vector>       // std::vector
#include <string>       // std::string

int main () {
  std::vector<std::string> foo = {"air","water","fire","earth"};
  std::vector<std::string> bar (4);

  // moving ranges:
  std::cout << "Moving ranges...\n";
  std::move ( foo.begin(), foo.begin()+4, bar.begin() );

  std::cout << "foo contains " << foo.size() << " elements:";
  std::cout << " (each in an unspecified but valid state)";
  std::cout << '\n';

  std::cout << "bar contains " << bar.size() << " elements:";
  for (std::string& x: bar) std::cout << " [" << x << "]";
  std::cout << '\n';

  // moving container:
  std::cout << "Moving container...\n";
  foo = std::move (bar);

  std::cout << "foo contains " << foo.size() << " elements:";
  for (std::string& x: foo) std::cout << " [" << x << "]";
  std::cout << '\n';

  std::cout << "bar is in an unspecified but valid state";
  std::cout << '\n';

  return 0;
}

Possible output:

Moving ranges...
foo contains 4 elements: (each in an unspecified but valid state)
bar contains 4 elements: [air] [water] [fire] [earth]
Moving container...
foo contains 4 elements: [air] [water] [fire] [earth]
bar is in an unspecified but valid state

Complexity

Linear in the distance between first and last: Performs a move-assignment for each element in the range.

Data races

The objects in both ranges are modified.

Exceptions

Throws if either an element move-assignment or an operation on iterators throws.
Note that invalid arguments cause undefined behavior.