1[/ 2 / Copyright (c) 2008 Joseph Gauterin 3 / Copyright (c) 2008, 2009 Niels Dekker 4 / Copyright (c) 2014 Glen Fernandes 5 / 6 / Distributed under the Boost Software License, Version 1.0. (See 7 / accompanying file LICENSE_1_0.txt or copy at 8 / http://www.boost.org/LICENSE_1_0.txt) 9 / For more information, see http://www.boost.org 10 /] 11 12[section:swap swap] 13 14[simplesect Authors] 15 16* Niels Dekker 17* Joseph Gauterin 18* Steven Watanabe 19* Eric Niebler 20 21[endsimplesect] 22 23[section Header <boost/core/swap.hpp>] 24 25`template<class T> void swap(T& left, T& right);` 26 27[endsect] 28 29[section Introduction] 30 31The template function `boost::swap` allows the values of two 32variables to be swapped, using argument dependent lookup to 33select a specialized swap function if available. If no 34specialized swap function is available, `std::swap` is used. 35 36[endsect] 37 38[section Rationale] 39 40The generic `std::swap` function requires that the elements 41to be swapped are assignable and copy constructible. It is 42usually implemented using one copy construction and two 43assignments - this is often both unnecessarily restrictive and 44unnecessarily slow. In addition, where the generic swap 45implementation provides only the basic guarantee, specialized 46swap functions are often able to provide the no-throw exception 47guarantee (and it is considered best practice to do so where 48possible [footnote Scott Meyers, Effective C++ Third Edition, 49Item 25: "Consider support for a non-throwing swap"]. 50 51The alternative to using argument dependent lookup in this 52situation is to provide a template specialization of 53`std::swap` for every type that requires a specialized swap. 54Although this is legal C++, no Boost libraries use this method, 55whereas many Boost libraries provide specialized swap functions 56in their own namespaces. 57 58`boost::swap` also supports swapping built-in arrays. Note that 59`std::swap` originally did not do so, but a request to add an 60overload of `std::swap` for built-in arrays has been accepted 61by the C++ Standards Committee[footnote 62 [@http://open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#809 63 LWG Defect Report 809: std::swap should be overloaded for array 64 types]]. 65 66[endsect] 67 68[section Exception Safety] 69 70`boost::swap` provides the same exception guarantee as the 71underlying swap function used, with one exception; for an array 72of type `T[n]`, where `n > 1` and the underlying swap function 73for `T` provides the strong exception guarantee, `boost::swap` 74provides only the basic exception guarantee. 75 76[endsect] 77 78[section Requirements] 79 80Either: 81 82* T must be assignable 83* T must be copy constructible 84 85Or: 86 87* A function with the signature `swap(T&,T&)` is available via 88 argument dependent lookup 89 90Or: 91 92* A template specialization of `std::swap` exists for T 93 94Or: 95 96* T is a built-in array of swappable elements 97 98[endsect] 99 100[section Portability] 101 102Several older compilers do not support argument dependent 103lookup. On these compilers `boost::swap` will call 104`std::swap`, ignoring any specialized swap functions that 105could be found as a result of argument dependent lookup. 106 107[endsect] 108 109[section Credits] 110 111* *Niels Dekker* - for implementing and documenting support for 112 built-in arrays 113* *Joseph Gauterin* - for the initial idea, implementation, 114 tests, and documentation 115* *Steven Watanabe* - for the idea to make `boost::swap` less 116 specialized than `std::swap`, thereby allowing the function 117 to have the name 'swap' without introducing ambiguity 118 119[endsect] 120 121[endsect] 122