std::swap - cppreference.com (original) (raw)
| Defined in header | (until C++11) | |
|---|---|---|
| Defined in header | (since C++11) | |
| Defined in header <string_view> | ||
| template< class T > void swap( T& a, T& b ); | (1) | (conditionally noexcept since C++11)(constexpr since C++20) |
| template< class T2, std::size_t N > void swap( T2 (&a)[N], T2 (&b)[N] ); | (2) | (conditionally noexcept since C++11)(constexpr since C++20) |
Exchanges the given values.
Swaps the values a and b.
Swaps the arrays a and b. Equivalent to std::swap_ranges(a, a + N, b).
| This overload participates in overload resolution only if std::is_swappable_v<T2> is true. | (since C++17) |
|---|
Contents
- 1 Parameters
- 2 Return value
- 3 Exceptions
- 4 Complexity
- 5 Specializations
- 6 Example
- 7 Defect reports
- 8 See also
[edit] 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. |
[edit] Return value
(none)
[edit] Exceptions
| noexcept specification: noexcept(noexcept(swap(*a, *b))) 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. | (since C++11)(until C++17) |
|---|---|
| (since C++17) |
[edit] Complexity
Constant.
Linear in N.
[edit] 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)(C++11) | specializes the std::swap algorithm (function template) [edit] |
|---|---|
| std::swap(std::tuple)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::shared_ptr)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::weak_ptr)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::unique_ptr)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::function)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_string) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::array)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::deque) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::forward_list)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::list) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::vector) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::map) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::multimap) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::set) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::multiset) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::unordered_map)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::unordered_multimap)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::unordered_set)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::unordered_multiset)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::queue)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::priority_queue)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::stack)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::valarray)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_stringbuf)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_istringstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_ostringstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_stringstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_filebuf)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_ifstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_ofstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_fstream)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_syncbuf)(C++20) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_spanbuf)(C++23) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_ispanstream)(C++23) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_ospanstream)(C++23) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_spanstream)(C++23) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_regex)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::match_results)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::thread)(C++11) | specializes the std::swap algorithm (function) [edit] |
| std::swap(std::unique_lock)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::shared_lock)(C++14) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::promise)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::packaged_task)(C++11) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::optional)(C++17) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::any)(C++17) | specializes the std::swap algorithm (function) [edit] |
| std::swap(std::variant)(C++17) | specializes the std::swap algorithm (function template) [edit] |
| std::swap(std::basic_stacktrace)(C++23) | specializes the std::swap algorithm (function template) [edit] |
| swap(std::filesystem::path)(C++17) | specializes the std::swap algorithm (function) [edit] |
| swap(std::expected)(C++23) | specializes the std::swap algorithm (function) [edit] |
| swap(std::jthread)(C++20) | specializes the std::swap algorithm (function) [edit] |
| swap(std::move_only_function)(C++23) | specializes the std::swap algorithm (function) [edit] |
| swap(std::stop_source)(C++20) | specializes the std::swap algorithm (function) [edit] |
| swap(std::stop_token)(C++20) | specializes the std::swap algorithm (function) [edit] |
[edit] Example
#include
#include
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
[edit] 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 227 | C++98 | T was not required to be CopyConstructible or DefaultConstructible(a temporary object of type T might not be able to be constructed) | T is also required tobe CopyConstructible |
| LWG 809 | C++98 | arrays could not be swapped | added overload (2) |
| LWG 2554 | C++11 | swapping multi-dimensional arrays can neverbe noexcept due to name lookup problems | made to work |
[edit] See also
| | swaps the values of two objects(customization point object)[edit] | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | swaps the elements pointed to by two iterators (function template) [edit] | | | swaps two ranges of elements (function template) [edit] | | | replaces the argument with a new value and returns its previous value (function template) [edit] |