std::exchange

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros(C++20) Program utilities Variadic functions initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine support(C++20) Contract support(C++26) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Function objects Bit manipulation(C++20) bitset hash (C++11) Relational operators(deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

Defined in header <utility>
template<class T, class U = T > T exchange( T& obj, U&& new_value );		(since C++14) (constexpr since C++20) (conditionally noexcept since C++23)

Replaces the value of obj with new_value and returns the old value of obj.

Parameters

obj	-	object whose value to replace
new_value	-	the value to assign to obj
Type requirements
- T must meet the requirements of MoveConstructible. Also, it must be possible to move-assign objects of type U to objects of type T.

Return value

The old value of obj.

Exceptions

(none)	(until C++23)
noexcept specification:   noexcept(     std::is_nothrow_move_constructible_v<T>&&     std::is_nothrow_assignable_v<T&, U> )	(since C++23)

Possible implementation

template<class T, class U = T>constexpr// Since C++20 T exchange(T& obj, U&& new_value)noexcept(// Since C++23std::is_nothrow_move_constructible<T>::value&&std::is_nothrow_assignable<T&, U>::value){ T old_value = std::move(obj); obj =std::forward<U>(new_value);return old_value;}

Notes

std::exchange can be used when implementing move constructors and, for the members that don't require special cleanup, move assignment operators:

struct S {int n;   S(S&& other)noexcept: n{std::exchange(other.n, 0)}{}   S& operator=(S&& other)noexcept{ n = std::exchange(other.n, 0);// Move n, while leaving zero in other.n// Note: in case of self-move-assignment, n is unchanged// Also note: if n is an opaque resource handle that requires// special cleanup, the resource is leaked.return*this;}};

Feature-test macro	Value	Std	Feature
__cpp_lib_exchange_function	201304L	(C++14)	std::exchange

Example

Run this code

#include <iostream>#include <iterator>#include <utility>#include <vector>   class stream {public:using flags_type =int;   public: flags_type flags()const{return flags_;}   // Replaces flags_ by newf, and returns the old value. flags_type flags(flags_type newf){return std::exchange(flags_, newf);}   private: flags_type flags_ =0;};   void f(){std::cout<<"f()";}   int main(){ stream s;   std::cout<< s.flags()<<'\n';std::cout<< s.flags(12)<<'\n';std::cout<< s.flags()<<"\n\n";   std::vector<int> v;   // Since the second template parameter has a default value, it is possible// to use a braced-init-list as second argument. The expression below// is equivalent to std::exchange(v, std::vector<int>{1, 2, 3, 4});   std::exchange(v, {1, 2, 3, 4});   std::copy(begin(v), end(v), std::ostream_iterator<int>(std::cout, ", "));   std::cout<<"\n\n";   void(*fun)();   // The default value of template parameter also makes possible to use a// normal function as second argument. The expression below is equivalent to// std::exchange(fun, static_cast<void(*)()>(f)) std::exchange(fun, f); fun();   std::cout<<"\n\nFibonacci sequence: ";for(int a{0}, b{1}; a <100; a = std::exchange(b, a + b))std::cout<< a <<", ";std::cout<<"...\n";}

Output:

0 0 12   1, 2, 3, 4,   f()   Fibonacci sequence: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, ...

See also

swap	swaps the values of two objects (function template)
atomic_exchangeatomic_exchange_explicit (C++11)(C++11)	atomically replaces the value of the atomic object with non-atomic argument and returns the old value of the atomic (function template)