Przejdź do głównej zawartości

std::swap() algorithm

// (1)
template< class T >
constexpr void swap( T& a, T& b ) noexcept(/* see below */);

// (2)
template< class T2, std::size_t N >
constexpr void swap( T2 (&a)[N], T2 (&b)[N] ) noexcept(/* see below */);

Exchanges the given values.

  • (1) Swaps the values a and b.

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

    Overload Resolution
    This overload does not participate in overload resolution unless std::is_swappable_v<T2> is true. (od C++17)

Parameters

a
b

The values to be swapped.

Type requirements

T MoveConstructible, MoveAssignable  (od C++11)
CopyConstructible, CopyAssignable  (do C++11)
T2Swappable

Return value

(none)

Complexity

  • (1) - Constant.
  • (1) - Linear in N.

Exceptions

Before C++11 no exceptions were thrown.

  • (1)

    noexcept specification:

    noexcept(
    std::is_nothrow_move_constructible<T>::value &&
    std::is_nothrow_move_assignable<T>::value
    )
  • (2)

    noexcept specification:

    noexcept(std::is_nothrow_swappable_v<T2>)

The overloads with a template parameter named ExecutionPolicy report errors as follows:

  • If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies, std::terminate is called. For none other ExecutionPolicy, the behavior is implementation-defined.
  • If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Specializations

std::swap may be specialized in namespace std for program-defined types, but such specializations are not found by ADL (the namespace 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 for std::pair

std::swap(std::tuple)  (od C++11)

Specializes the std::swap algorithm for std::tuple

std::swap(std::shader_ptr)  (od C++11)

Specializes the std::swap algorithm for std::shader_ptr

std::swap(std::weak_ptr)  (od C++11)

Specializes the std::swap algorithm for std::weak_ptr

std::swap(std::unique_ptr)  (od C++11)

Specializes the std::swap algorithm for std::unique_ptr

std::swap(std::function)  (od C++11)

Specializes the std::swap algorithm for std::function

std::swap(std::basic_string)

Specializes the std::swap algorithm for std::basic_string

std::swap(std::array)  (od C++11)

Specializes the std::swap algorithm for std::array

std::swap(std::deque)  (od C++11)

Specializes the std::swap algorithm for std::deque

std::swap(std::forward_list)  (od C++11)

Specializes the std::swap algorithm for std::forward_list

std::swap(std::list)

Specializes the std::swap algorithm for std::list

std::swap(std::vector)

Specializes the std::swap algorithm for std::vector

std::swap(std::map)

Specializes the std::swap algorithm for std::map

std::swap(std::multimap)

Specializes the std::swap algorithm for std::multimap

std::swap(std::set)

Specializes the std::swap algorithm for std::set

std::swap(std::multiset)

Specializes the std::swap algorithm for std::multiset

std::swap(std::unordered_map)  (od C++11)

Specializes the std::swap algorithm for std::unordered_map

std::swap(std::unordered_multimap)  (od C++11)

Specializes the std::swap algorithm for std::unordered_multimap

std::swap(std::unordered_set)  (od C++11)

Specializes the std::swap algorithm for std::unordered_set

std::swap(std::unordered_multiset)  (od C++11)

Specializes the std::swap algorithm for std::unordered_multiset

std::swap(std::queue)  (od C++11)

Specializes the std::swap algorithm for std::queue

std::swap(std::priority_queue)  (od C++11)

Specializes the std::swap algorithm for std::priority_queue

std::swap(std::stack)  (od C++11)

Specializes the std::swap algorithm for std::stack

std::swap(std::valarray)  (od C++11)

Specializes the std::swap algorithm for std::valarray

std::swap(std::basic_stringbuf)  (od C++11)

Specializes the std::swap algorithm for std::basic_stringbuf

std::swap(std::basic_istringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_istringstream

std::swap(std::basic_ostringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ostringstream

std::swap(std::basic_stringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_stringstream

std::swap(std::basic_filebuf)  (od C++11)

Specializes the std::swap algorithm for std::basic_filebuf

std::swap(std::basic_ifstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ifstream

std::swap(std::basic_ofstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ofstream

std::swap(std::basic_fstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_fstream

std::swap(std::basic_syncbuf)  (od C++20)

Specializes the std::swap algorithm for std::basic_syncbuf

std::swap(std::basic_spanbuf)  (od C++23)

Specializes the std::swap algorithm for std::basic_spanbuf

std::swap(std::basic_ispanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_ispanstream

std::swap(std::basic_ospanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_ospanstream

std::swap(std::basic_spanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_spanstream

std::swap(std::basic_regex)  (od C++11)

Specializes the std::swap algorithm for std::basic_regex

std::swap(std::match_results)  (od C++11)

Specializes the std::swap algorithm for std::match_results

std::swap(std::thread)  (od C++11)

Specializes the std::swap algorithm for std::thread

std::swap(std::unique_lock)  (od C++11)

Specializes the std::swap algorithm for std::unique_lock

std::swap(std::shared_lock)  (od C++14)

Specializes the std::swap algorithm for std::shared_lock

std::swap(std::promise)  (od C++11)

Specializes the std::swap algorithm for std::promise

std::swap(std::packaged_task)  (od C++11)

Specializes the std::swap algorithm for std::packaged_task

std::swap(std::optional)  (od C++17)

Specializes the std::swap algorithm for std::optional

std::swap(std::any)  (od C++17)

Specializes the std::swap algorithm for std::any

std::swap(std::variant)  (od C++17)

Specializes the std::swap algorithm for std::variant

std::swap(std::basic_stacktrace)  (od C++17)

Specializes the std::swap algorithm for std::basic_stacktrace

swap(std::filesystem::path)  (od C++17)

Specializes (hidden friend) the std::swap algorithm for std::filesystem::path

swap(std::expected)  (od C++23)

Specializes (hidden friend) the std::swap algorithm for std::expected

swap(std::jthread)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::jthread

swap(std::move_only_function)  (od C++23)

Specializes (hidden friend) the std::swap algorithm for std::move_only_function

swap(std::stop_source)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::stop_source

swap(std::stop_token)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::stop_token

Examples

Main.cpp
#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
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.

std::swap() algorithm

// (1)
template< class T >
constexpr void swap( T& a, T& b ) noexcept(/* see below */);

// (2)
template< class T2, std::size_t N >
constexpr void swap( T2 (&a)[N], T2 (&b)[N] ) noexcept(/* see below */);

Exchanges the given values.

  • (1) Swaps the values a and b.

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

    Overload Resolution
    This overload does not participate in overload resolution unless std::is_swappable_v<T2> is true. (od C++17)

Parameters

a
b

The values to be swapped.

Type requirements

T MoveConstructible, MoveAssignable  (od C++11)
CopyConstructible, CopyAssignable  (do C++11)
T2Swappable

Return value

(none)

Complexity

  • (1) - Constant.
  • (1) - Linear in N.

Exceptions

Before C++11 no exceptions were thrown.

  • (1)

    noexcept specification:

    noexcept(
    std::is_nothrow_move_constructible<T>::value &&
    std::is_nothrow_move_assignable<T>::value
    )
  • (2)

    noexcept specification:

    noexcept(std::is_nothrow_swappable_v<T2>)

The overloads with a template parameter named ExecutionPolicy report errors as follows:

  • If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies, std::terminate is called. For none other ExecutionPolicy, the behavior is implementation-defined.
  • If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Specializations

std::swap may be specialized in namespace std for program-defined types, but such specializations are not found by ADL (the namespace 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 for std::pair

std::swap(std::tuple)  (od C++11)

Specializes the std::swap algorithm for std::tuple

std::swap(std::shader_ptr)  (od C++11)

Specializes the std::swap algorithm for std::shader_ptr

std::swap(std::weak_ptr)  (od C++11)

Specializes the std::swap algorithm for std::weak_ptr

std::swap(std::unique_ptr)  (od C++11)

Specializes the std::swap algorithm for std::unique_ptr

std::swap(std::function)  (od C++11)

Specializes the std::swap algorithm for std::function

std::swap(std::basic_string)

Specializes the std::swap algorithm for std::basic_string

std::swap(std::array)  (od C++11)

Specializes the std::swap algorithm for std::array

std::swap(std::deque)  (od C++11)

Specializes the std::swap algorithm for std::deque

std::swap(std::forward_list)  (od C++11)

Specializes the std::swap algorithm for std::forward_list

std::swap(std::list)

Specializes the std::swap algorithm for std::list

std::swap(std::vector)

Specializes the std::swap algorithm for std::vector

std::swap(std::map)

Specializes the std::swap algorithm for std::map

std::swap(std::multimap)

Specializes the std::swap algorithm for std::multimap

std::swap(std::set)

Specializes the std::swap algorithm for std::set

std::swap(std::multiset)

Specializes the std::swap algorithm for std::multiset

std::swap(std::unordered_map)  (od C++11)

Specializes the std::swap algorithm for std::unordered_map

std::swap(std::unordered_multimap)  (od C++11)

Specializes the std::swap algorithm for std::unordered_multimap

std::swap(std::unordered_set)  (od C++11)

Specializes the std::swap algorithm for std::unordered_set

std::swap(std::unordered_multiset)  (od C++11)

Specializes the std::swap algorithm for std::unordered_multiset

std::swap(std::queue)  (od C++11)

Specializes the std::swap algorithm for std::queue

std::swap(std::priority_queue)  (od C++11)

Specializes the std::swap algorithm for std::priority_queue

std::swap(std::stack)  (od C++11)

Specializes the std::swap algorithm for std::stack

std::swap(std::valarray)  (od C++11)

Specializes the std::swap algorithm for std::valarray

std::swap(std::basic_stringbuf)  (od C++11)

Specializes the std::swap algorithm for std::basic_stringbuf

std::swap(std::basic_istringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_istringstream

std::swap(std::basic_ostringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ostringstream

std::swap(std::basic_stringstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_stringstream

std::swap(std::basic_filebuf)  (od C++11)

Specializes the std::swap algorithm for std::basic_filebuf

std::swap(std::basic_ifstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ifstream

std::swap(std::basic_ofstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_ofstream

std::swap(std::basic_fstream)  (od C++11)

Specializes the std::swap algorithm for std::basic_fstream

std::swap(std::basic_syncbuf)  (od C++20)

Specializes the std::swap algorithm for std::basic_syncbuf

std::swap(std::basic_spanbuf)  (od C++23)

Specializes the std::swap algorithm for std::basic_spanbuf

std::swap(std::basic_ispanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_ispanstream

std::swap(std::basic_ospanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_ospanstream

std::swap(std::basic_spanstream)  (od C++23)

Specializes the std::swap algorithm for std::basic_spanstream

std::swap(std::basic_regex)  (od C++11)

Specializes the std::swap algorithm for std::basic_regex

std::swap(std::match_results)  (od C++11)

Specializes the std::swap algorithm for std::match_results

std::swap(std::thread)  (od C++11)

Specializes the std::swap algorithm for std::thread

std::swap(std::unique_lock)  (od C++11)

Specializes the std::swap algorithm for std::unique_lock

std::swap(std::shared_lock)  (od C++14)

Specializes the std::swap algorithm for std::shared_lock

std::swap(std::promise)  (od C++11)

Specializes the std::swap algorithm for std::promise

std::swap(std::packaged_task)  (od C++11)

Specializes the std::swap algorithm for std::packaged_task

std::swap(std::optional)  (od C++17)

Specializes the std::swap algorithm for std::optional

std::swap(std::any)  (od C++17)

Specializes the std::swap algorithm for std::any

std::swap(std::variant)  (od C++17)

Specializes the std::swap algorithm for std::variant

std::swap(std::basic_stacktrace)  (od C++17)

Specializes the std::swap algorithm for std::basic_stacktrace

swap(std::filesystem::path)  (od C++17)

Specializes (hidden friend) the std::swap algorithm for std::filesystem::path

swap(std::expected)  (od C++23)

Specializes (hidden friend) the std::swap algorithm for std::expected

swap(std::jthread)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::jthread

swap(std::move_only_function)  (od C++23)

Specializes (hidden friend) the std::swap algorithm for std::move_only_function

swap(std::stop_source)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::stop_source

swap(std::stop_token)  (od C++20)

Specializes (hidden friend) the std::swap algorithm for std::stop_token

Examples

Main.cpp
#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
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.