NAME

std::swap - std::swap

Synopsis

Defined in header <algorithm> (until C++11)
Defined in header <utility> (since C++11)
Defined in header <string_view> (since C++17)
template< class T > (until C++11)
void swap( T& a, T& b );
template< class T > (since C++11)
void swap( T& a, T& b ) noexcept(/* (until C++20)
see below */);
template< class T >
constexpr void swap( T& a, T& b ) (1) (since C++20)
noexcept(/* see below */);
template< class T2, std::size_t N > (since C++11)
void swap( T2 (&a)[N], T2 (&b)[N]) (until C++20)
noexcept(/* see below */); (2)
template< class T2, std::size_t N >
constexpr void swap( T2 (&a)[N], T2 (since C++20)
(&b)[N]) noexcept(/* see below */);

Exchanges the given values.

1) Swaps the values a and b.
This overload does not participate in overload resolution unless
std::is_move_constructible_v<T> && std::is_move_assignable_v<T> is true.
(since C++17)
2) Swaps the arrays a and b. In effect calls std::swap_ranges(a, a+N, b).
This overload does not participate in overload resolution unless
std::is_swappable_v<T2> is true.
(since C++17)

Parameters

a, b - the values to be swapped

Type requirements

-
T must meet the requirements of MoveAssignable and MoveConstructible.
-
T2 must meet the requirements of Swappable.

Return value

(none)

Exceptions

1)

(none) (until C++11)
noexcept specification:
noexcept(

std::is_nothrow_move_constructible<T>::value && (since C++11)
std::is_nothrow_move_assignable<T>::value

)

2)

noexcept specification:
noexcept(noexcept(swap(*a, *b)))
The lookup for the identifier swap in the exception specification (since C++11)
finds this function template in addition to anything found by the (until C++17)
usual lookup rules, making the exception specification equivalent to
C++17 std::is_nothrow_swappable.
noexcept specification: (since C++17)
noexcept(std::is_nothrow_swappable_v<T2>)

Complexity

1) Constant
2) Linear in N

Specializations

std::swap may be specialized in namespace std for program-defined
types, but such specializations are not found by ADL (the namespace (until C++20)
std is not the associated namespace for the program-defined type).

The expected way to make a program-defined type swappable is to provide a non-member
function swap in the same namespace as the type: see Swappable for details.

The following overloads are already provided by the standard library:

std::swap(std::pair) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::tuple) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::shared_ptr) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::weak_ptr) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::unique_ptr) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::function) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_string) specializes the std::swap algorithm
(function template)
std::swap(std::array) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::deque) specializes the std::swap algorithm
(function template)
std::swap(std::forward_list) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::list) specializes the std::swap algorithm
(function template)
std::swap(std::vector) specializes the std::swap algorithm
(function template)
std::swap(std::map) specializes the std::swap algorithm
(function template)
std::swap(std::multimap) specializes the std::swap algorithm
(function template)
std::swap(std::set) specializes the std::swap algorithm
(function template)
std::swap(std::multiset) specializes the std::swap algorithm
(function template)
std::swap(std::unordered_map) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::unordered_multimap) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::unordered_set) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::unordered_multiset) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::queue) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::priority_queue) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::stack) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::valarray) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_stringbuf) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_istringstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_ostringstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_stringstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_filebuf) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_ifstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_ofstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_fstream) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::basic_syncbuf) specializes the std::swap algorithm
(C++20) (function template)
std::swap(std::basic_spanbuf) specializes the std::swap algorithm
(C++23) (function template)
std::swap(std::basic_ispanstream) specializes the std::swap algorithm
(C++23) (function template)
std::swap(std::basic_ospanstream) specializes the std::swap algorithm
(C++23) (function template)
std::swap(std::basic_spanstream) specializes the std::swap algorithm
(C++23) (function template)
std::swap(std::basic_regex) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::match_results) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::thread) specializes the std::swap algorithm
(C++11) (function)
std::swap(std::unique_lock) specialization of std::swap for unique_lock
(C++11) (function template)
std::swap(std::promise) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::packaged_task) specializes the std::swap algorithm
(C++11) (function template)
std::swap(std::optional) specializes the std::swap algorithm
(C++17) (function template)
std::swap(std::any) specializes the std::swap algorithm
(C++17) (function)
std::swap(std::variant) specializes the std::swap algorithm
(C++17) (function template)
swap(std::filesystem::path) swaps two paths
(C++17) (function)

Example

// Run this code

#include <algorithm>
#include <iostream>

namespace Ns {
class A {
int id{};

friend void swap(A& lhs, A& rhs) {
std::cout << "swap(" << lhs << ", " << rhs << ")\n";
std::swap(lhs.id, rhs.id);
}

friend std::ostream& operator<< (std::ostream& os, A const& a) {
return os << "A::id=" << a.id;
}

public:
A(int i) : id{i} { }
A(A const&) = delete;
A& operator = (A const&) = delete;
};
}

int main()
{
int a = 5, b = 3;
std::cout << a << ' ' << b << '\n';
std::swap(a,b);
std::cout << a << ' ' << b << '\n';

Ns::A p{6}, q{9};
std::cout << p << ' ' << q << '\n';
// std::swap(p, q); // error, type requirements are not satisfied
swap(p, q); // OK, ADL finds the appropriate friend `swap`
std::cout << p << ' ' << q << '\n';
}

Output:

5 3
3 5
A::id=6 A::id=9
swap(A::id=6, A::id=9)
A::id=9 A::id=6

Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 2554 C++11 swapping multi-dimensional arrays can never be made to work
noexcept due to name lookup problems