SysTutorials

Linux Manual Pages › Section 3

stdswap(3)

std::swap - std::swap

Synopsis

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

(none) (until C++11) noexcept specification: noexcept( std::is_nothrow_move_constructible<T>::value && (since C++11) std::is_nothrow_move_assignable<T>::value )

noexcept specification: noexcept(noexcept(swap(*a, *b))) (until C++17) The lookup for the identifier swap in the exception specification finds this function template in addition to anything found by the 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 std is not the associated namespace for the program-defined type). (until C++20)

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                                     (function template) (C++11)

std::swap(std::tuple) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::shared_ptr) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::weak_ptr) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::unique_ptr) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::function) specializes the std::swap algorithm                                     (function template) (C++11)                                     specializes the std::swap algorithm std::swap(std::basic_string) (function template)

std::swap(std::array) specializes the std::swap algorithm                                     (function template) (C++11)                                     specializes the std::swap algorithm std::swap(std::deque) (function template)

std::swap(std::forward_list) specializes the std::swap algorithm                                     (function template) (C++11)                                     specializes the std::swap algorithm std::swap(std::list) (function template)                                     specializes the std::swap algorithm std::swap(std::vector) (function template)                                     specializes the std::swap algorithm std::swap(std::map) (function template)                                     specializes the std::swap algorithm std::swap(std::multimap) (function template)                                     specializes the std::swap algorithm std::swap(std::set) (function template)                                     specializes the std::swap algorithm std::swap(std::multiset) (function template)

std::swap(std::unordered_map) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::unordered_multimap) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::unordered_set) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::unordered_multiset) specializes the std::swap algorithm                                     (function template) (C++11)                                     specializes the std::swap algorithm std::swap(std::queue) (function template)                                     specializes the std::swap algorithm std::swap(std::priority_queue) (function template)                                     specializes the std::swap algorithm std::swap(std::stack) (function template)

std::swap(std::valarray) specializes the std::swap() algorithm                                     (function template) (C++11)

std::swap(std::basic_stringbuf) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_istringstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_ostringstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_stringstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_filebuf) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_ifstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_ofstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_fstream) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::basic_syncbuf) specializes the std::swap algorithm                                     (function template) (C++20)

std::swap(std::basic_regex) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::match_results) specializes the std::swap() algorithm                                     (function template) (C++11)

std::swap(std::thread) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::unique_lock) specialization of std::swap for unique_lock                                     (function template) (C++11)

std::swap(std::promise) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::packaged_task) specializes the std::swap algorithm                                     (function template) (C++11)

std::swap(std::optional) specializes the std::swap algorithm                                     (function) (C++17)

std::swap(std::any) specializes the std::swap algorithm                                     (function) (C++17)

std::swap(std::variant) specializes the std::swap algorithm                                     (function) (C++17)                                     swaps two paths swap(std::filesystem::path) (function)

Example

// Run this code

#include <algorithm>
#include <iostream>
int main()
{
int a = 5, b = 3;
// before
std::cout << a << ’ ’ << b << ‘\n’;
std::swap(a, b);
// after
std::cout << a << ’ ’ << b << ‘\n’;
}

Output:

  5 3   3 5

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 noexcept due to name lookup problems made to work

See also

            swaps the elements pointed to by two iterators iter_swap (function template)             swaps two ranges of elements swap_ranges (function template) exchange replaces the argument with a new value and returns its previous value             (function template) (C++14)