std::swap

template <class T> void swap (T& a, T& b);

header	// moved from <algorithm> to <utility> in C++11
non-array (1)	template <class T> void swap (T& a, T& b) noexcept (is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value);
array (2)	template <class T, size_t N> void swap(T (&a)[N], T (&b)[N]) noexcept (noexcept(swap(a,b)));

header

// moved from <algorithm> to <utility> in C++11

non-array (1)

template <class T> void swap (T& a, T& b)  noexcept (is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value);

array (2)

template <class T, size_t N> void swap(T (&a)[N], T (&b)[N])  noexcept (noexcept(swap(*a,*b)));

Exchange values of two objects

Exchanges the values of a and b.

The behavior of this function template is equivalent to:

template <class T> void swap ( T& a, T& b )
{
  T c(a); a=b; b=c;
}

Notice how this function involves a copy construction and two assignment operations, which may not be the most efficient way of swapping the contents of classes that store large quantities of data, since each of these operations generally operate in linear time on their size.

Large data types can provide an overloaded version of this function optimizing its performance. Notably, all standard containers specialize it in such a way that only a few internal pointers are swapped instead of their entire contents, making them operate in constant time.

This function is no longer defined in header <algorithm>, but in <utility>.

The behavior of these function templates is equivalent to:

template <class T> void swap (T& a, T& b)
{
  T c(std::move(a)); a=std::move(b); b=std::move(c);
}
template <class T, size_t N> void swap (T (&a)[N], T (&b)[N])
{
  for (size_t i = 0; i<N; ++i) swap (a[i],b[i]);
}

Many components of the standard library (within std) call swap in an unqualified manner to allow custom overloads for non-fundamental types to be called instead of this generic version: Custom overloads of swap declared in the same namespace as the type for which they are provided get selected through argument-dependent lookup over this generic version.

Parameters

a, b: Two objects, whose contents are swapped.

Type T shall be copy-constructible and assignable.

Type T shall be move-constructible and move-assignable (or have swap defined for it, for version (2)).

Return value

none

Example

// swap algorithm example (C++98)
#include <iostream>     // std::cout
#include <algorithm>    // std::swap
#include <vector>       // std::vector

int main () {

  int x=10, y=20;                              // x:10 y:20
  std::swap(x,y);                              // x:20 y:10

  std::vector<int> foo (4,x), bar (6,y);       // foo:4x20 bar:6x10
  std::swap(foo,bar);                          // foo:6x10 bar:4x20

  std::cout << "foo contains:";
  for (std::vector<int>::iterator it=foo.begin(); it!=foo.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

foo contains: 10 10 10 10 10 10

Complexity

Non-array: Constant: Performs exactly one construction and two assignments (although notice that each of these operations works on its own complexity).
Array: Linear in N: performs a swap operation per element.

Data races

Both a and b are modified.

Exceptions

Throws if the construction or assignment of type T throws.
Never throws if T is nothrow-move-constructible and nothrow-move-assignable.
Note that if T does not fulfill the requirements specified above (in parameters), it causes undefined behavior.