std::swap(3)

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>
   template< class T > (until C++11)
   void swap( T& a, T& b );
   template< class T > (since C++11)
   void swap( T& a, T& b ) (constexpr since
   noexcept(/* see below */); C++20)
   template< class T2, std::size_t
   N > (1) (until C++11)
   void swap( T2 (&a)[N], T2
   (&b)[N] );
   template< class T2, std::size_t (2)
   N > (since C++11)
   void swap( T2 (&a)[N], T2 (constexpr since
   (&b)[N] ) noexcept(/* see below C++20)
   */);
   Exchanges the given values.
   1) Swaps the values a and b.
   This overload participates in overload resolution only if
   std::is_move_constructible_v<T> && std::is_move_assignable_v<T> is (since C++17)
   true.
   2) Swaps the arrays a and b. In effect calls std::swap_ranges(a, a + N, b).
   This overload participates in overload resolution only if (since C++17)
   std::is_swappable_v<T2> is true.

Parameters
   a, b - the values to be swapped

Type requirements
   -
   T must meet the requirements of
   CopyConstructible and CopyAssignable
   (until C++11)
   MoveConstructible and MoveAssignable
   (since C++11)
   -
   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::shared_lock) specialization of std::swap for shared_lock
   (C++14) (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)
   std::swap(std::basic_stacktrace) specializes the std::swap algorithm
   (C++23) (function template)
   swap(std::filesystem::path) swaps two paths
   (C++17) (function)
   swap(std::expected) specializes the std::swap algorithm
   (C++23) (function)
   swap(std::jthread) specializes the std::swap algorithm
   (C++20) (function)
   swap(std::move_only_function) overloads the std::swap algorithm
   (C++23) (function)
   swap(std::stop_source) specializes the std::swap algorithm
   (C++20) (function)
   swap(std::stop_token) specializes the std::swap algorithm
   (C++20) (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
                       T was not required to be CopyConstructible
   LWG 227 C++98 or DefaultConstructible T is also required to
                       (a temporary object of type T might not be be CopyConstructible
                       able to be constructed)
   LWG 809 C++98 arrays could not be swapped added overload (2)
                       swapping multi-dimensional arrays can
   LWG 2554 C++11 never made to work
                       be noexcept due to name lookup problems

See also
   ranges::swap swaps the values of two objects
   (C++20) (customization point object)
   iter_swap swaps the elements pointed to by two iterators
                (function template)
   swap_ranges swaps two ranges of elements
                (function template)
   exchange replaces the argument with a new value and returns its previous value
   (C++14) (function template)

Category:
     * conditionally noexcept