std::move

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Utilities library

Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Library feature-test macros
Date and time
Function objects
initializer_list (C++11)
bitset
hash (C++11)
integer_sequence (C++14)
Relational operators (deprecated)
rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=
Comparisons (C++20)
strong_order weak_order partial_order strong_equal weak_equal	strong_ordering weak_ordering partial_ordering strong_equality weak_equality	is_eqis_neqis_ltis_lteqis_gtis_gteq
common_comparison_category
Common vocabulary types
pair tuple (C++11) apply (C++17) make_from_tuple (C++17)	optional (C++17) any (C++17) variant (C++17)
Swap, forward and move
swap
exchange (C++14)
forward (C++11)
move (C++11)
move_if_noexcept (C++11)
Elementary string conversions
to_chars (C++17)
from_chars (C++17)
chars_format (C++17)
Type operations
declval (C++11)
as_const (C++17)

Defined in header <utility>
template< class T > typename std::remove_reference<T>::type&& move( T&& t ) noexcept;		(since C++11) (until C++14)
template< class T > constexpr typename std::remove_reference<T>::type&& move( T&& t ) noexcept;		(since C++14)

std::move is used to indicate that an object t may be "moved from", i.e. allowing the efficient transfer of resources from t to another object.

In particular, std::move produces an xvalue expression that identifies its argument t. It is exactly equivalent to a static_cast to an rvalue reference type.

Parameters

t

-

the object to be moved

Return value

static_cast<typename std::remove_reference<T>::type&&>(t)

Notes

The functions that accept rvalue reference parameters (including move constructors, move assignment operators, and regular member functions such as std::vector::push_back) are selected, by overload resolution, when called with rvalue arguments (either prvalues such as a temporary objects or xvalues such as the one produced by std::move). If the argument identifies a resource-owning object, these overloads have the option, but aren't required, to move any resources held by the argument. For example, a move constructor of a linked list might copy the pointer to the head of the list and store nullptr in the argument instead of allocating and copying individual nodes.

Names of rvalue reference variables are lvalues and have to be converted to xvalues to be bound to the function overloads that accept rvalue reference parameters, which is why move constructors and move assignment operators typically use std::move:

// Simple move constructor
A(A&& arg) : member(std::move(arg.member)) // the expression "arg.member" is lvalue
{} 
// Simple move assignment operator
A& operator=(A&& other) {
     member = std::move(other.member);
     return *this;
}

One exception is when the type of the function parameter is rvalue reference to type template parameter ("forwarding reference" or "universal reference"), in which case std::forward is used instead.

Unless otherwise specified, all standard library objects that have been moved from are placed in a valid but unspecified state. That is, only the functions without preconditions, such as the assignment operator, can be safely used on the object after it was moved from:

std::vector<std::string> v;
std::string str = "example";
v.push_back(std::move(str)); // str is now valid but unspecified
str.back(); // undefined behavior if size() == 0: back() has a precondition!empty()
str.clear(); // OK, clear() has no preconditions

Also, the standard library functions called with xvalue arguments may assume the argument is the only reference to the object; if it was constructed from an lvalue with std::move, no aliasing checks are made. In particular, this means that standard library move assignment operators do not have to perform self-assignment checks:

std::vector<int> v = {2, 3, 3};
v = std::move(v); // the value of v is unspecified

Example

Run this code

#include <iostream>
#include <utility>
#include <vector>
#include <string>

int main()
{
    std::string str = "Hello";
    std::vector<std::string> v;

    // uses the push_back(const T&) overload, which means 
    // we'll incur the cost of copying str
    v.push_back(str);
    std::cout << "After copy, str is \"" << str << "\"\n";

    // uses the rvalue reference push_back(T&&) overload, 
    // which means no strings will be copied; instead, the contents
    // of str will be moved into the vector.  This is less
    // expensive, but also means str might now be empty.
    v.push_back(std::move(str));
    std::cout << "After move, str is \"" << str << "\"\n";

    std::cout << "The contents of the vector are \"" << v[0]
                                         << "\", \"" << v[1] << "\"\n";
}

Possible output:

After copy, str is "Hello"
After move, str is ""
The contents of the vector are "Hello", "Hello"

See also

forward (C++11)	forwards a function argument (function template)
move_if_noexcept (C++11)	obtains an rvalue reference if the move constructor does not throw (function template)
move (C++11)	moves a range of elements to a new location (function template)