C++ named requirements: Swappable

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

C++ named requirements

Basic
DefaultConstructible CopyAssignable CopyConstructible	MoveAssignable (C++11) MoveConstructible (C++11) Destructible
Type properties
ScalarType TriviallyCopyable (C++11) StandardLayoutType (C++11)	PODType TrivialType (C++11) ImplicitLifetimeType (C++20)
Library-Wide
EqualityComparable LessThanComparable Swappable (C++11) ValueSwappable (C++11) NullablePointer (C++11) Hash (C++11)	Allocator FunctionObject Callable Predicate BinaryPredicate Compare
Container
Container SequenceContainer ContiguousContainer (C++17) ReversibleContainer	AssociativeContainer AllocatorAwareContainer UnorderedAssociativeContainer (C++11)
Container Elements
DefaultInsertable (C++11) CopyInsertable (C++11) MoveInsertable (C++11)	EmplaceConstructible (C++11) Erasable (C++11)
Iterator
LegacyIterator LegacyOutputIterator LegacyInputIterator LegacyForwardIterator	LegacyBidirectionalIterator LegacyRandomAccessIterator LegacyContiguousIterator (C++17) ConstexprIterator (C++20)
Stream I/O
FormattedInputFunction UnformattedInputFunction	FormattedOutputFunction UnformattedOutputFunction
Formatting
BasicFormatter (C++20)	Formatter (C++20)
Random Numbers
SeedSequence (C++11) RandomNumberEngine (C++11)	RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11) RandomNumberEngineAdaptor (C++11)
Concurrency
BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11) SharedLockable (C++14) SharedTimedLockable (C++14)	Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14)
Other
CharTraits RegexTraits (C++11) BitmaskType NumericType LiteralType (C++11)	UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

Any lvalue or rvalue of this type can be swapped with any lvalue or rvalue of some other type, using unqualified function call swap() in the context where both std::swap and the user-defined swap()s are visible.

Requirements

Type U is swappable with type T if, for any object u of type U and any object t of type T,

Expression	Requirements	Semantics
#include <utility> using std::swap; swap(u, t);	After the call, the value of t is the value held by u before the call, and the value of u is the value held by t before the call.	Calls the function named swap() found by overload resolution among all functions with that name that are found by argument-dependent lookup and the two std::swap templates defined in the header <utility>.
#include <utility> using std::swap; swap(t, u);	same	same

Many standard library functions (for example, many algorithms) expect their arguments to satisfy Swappable, which means that any time the standard library performs a swap, it uses the equivalent of using std::swap; swap(t, u);.

Typical implementations either

1) Define a non-member swap in the enclosing namespace, which may forward to a member swap if access to non-public data members is required

2) Define a friend function in-class (this approach hides the class-specific swap from name lookup other than ADL)

Notes

It is unspecified whether <utility> is actually included when the standard library functions perform the swap, so the user-provided swap() should not expect it to be included.

Example

Run this code

#include <iostream>
#include <vector>
 
struct IntVector {
    std::vector<int> v;
    IntVector& operator=(IntVector) = delete; // not assignable
    void swap(IntVector& other) {
        v.swap(other.v);
    }
    void operator()(auto rem, char term = ' ') {
        for(std::cout << rem << " { "; int e: v) { std::cout << e << ' '; }
        std::cout << "}" << term;
    }
};
void swap(IntVector& v1, IntVector& v2) {
    v1.swap(v2);
}
 
int main()
{
    IntVector v1{ {1,1,1,1,1} }, v2{ {2222,2222} };
    auto prn = [&]{ v1("v1"), v2("v2", '\n'); };
 
//  std::swap(v1, v2); // compiler error! std::swap requires MoveAssignable
    prn();
    std::iter_swap(&v1, &v2); // OK: library calls unqualified swap()
    prn();
    std::ranges::swap(v1, v2); // OK: library calls unqualified swap()
    prn();
}

Output:

v1 { 1 1 1 1 1 } v2 { 2222 2222 }
v1 { 2222 2222 } v2 { 1 1 1 1 1 }
v1 { 1 1 1 1 1 } v2 { 2222 2222 }

See also

is_swappable_withis_swappableis_nothrow_swappable_withis_nothrow_swappable (C++17)(C++17)(C++17)(C++17)	checks if objects of a type can be swapped with objects of same or different type (class template)
swappableswappable_with (C++20)	specifies that a type can be swapped or that two types can be swapped with each other (concept)