home | help 
std::swap(3)		       C++ Standard Libary		    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)				    (un-
     til 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  de-
     tails.

	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 retroac-
     tively 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  Copy-
     Constructible
			    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 pre-
     vious value
	(C++14)      (function template)

Category:
	  * conditionally noexcept

http://cppreference.com 	   2024.06.10			    std::swap(3)
home | help