122 lines
3.4 KiB
Plaintext
122 lines
3.4 KiB
Plaintext
[/
|
|
/ Copyright (c) 2008 Joseph Gauterin
|
|
/ Copyright (c) 2008, 2009 Niels Dekker
|
|
/ Copyright (c) 2014 Glen Fernandes
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See
|
|
/ accompanying file LICENSE_1_0.txt or copy at
|
|
/ http://www.boost.org/LICENSE_1_0.txt)
|
|
/ For more information, see http://www.boost.org
|
|
/]
|
|
|
|
[section:swap swap]
|
|
|
|
[simplesect Authors]
|
|
|
|
* Niels Dekker
|
|
* Joseph Gauterin
|
|
* Steven Watanabe
|
|
* Eric Niebler
|
|
|
|
[endsimplesect]
|
|
|
|
[section Header <boost/core/swap.hpp>]
|
|
|
|
`template<class T> void swap(T& left, T& right);`
|
|
|
|
[endsect]
|
|
|
|
[section Introduction]
|
|
|
|
The template function `boost::swap` allows the values of two
|
|
variables to be swapped, using argument dependent lookup to
|
|
select a specialized swap function if available. If no
|
|
specialized swap function is available, `std::swap` is used.
|
|
|
|
[endsect]
|
|
|
|
[section Rationale]
|
|
|
|
The generic `std::swap` function requires that the elements
|
|
to be swapped are assignable and copy constructible. It is
|
|
usually implemented using one copy construction and two
|
|
assignments - this is often both unnecessarily restrictive and
|
|
unnecessarily slow. In addition, where the generic swap
|
|
implementation provides only the basic guarantee, specialized
|
|
swap functions are often able to provide the no-throw exception
|
|
guarantee (and it is considered best practice to do so where
|
|
possible [footnote Scott Meyers, Effective C++ Third Edition,
|
|
Item 25: "Consider support for a non-throwing swap"].
|
|
|
|
The alternative to using argument dependent lookup in this
|
|
situation is to provide a template specialization of
|
|
`std::swap` for every type that requires a specialized swap.
|
|
Although this is legal C++, no Boost libraries use this method,
|
|
whereas many Boost libraries provide specialized swap functions
|
|
in their own namespaces.
|
|
|
|
`boost::swap` also supports swapping built-in arrays. Note that
|
|
`std::swap` originally did not do so, but a request to add an
|
|
overload of `std::swap` for built-in arrays has been accepted
|
|
by the C++ Standards Committee[footnote
|
|
[@http://open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#809
|
|
LWG Defect Report 809: std::swap should be overloaded for array
|
|
types]].
|
|
|
|
[endsect]
|
|
|
|
[section Exception Safety]
|
|
|
|
`boost::swap` provides the same exception guarantee as the
|
|
underlying swap function used, with one exception; for an array
|
|
of type `T[n]`, where `n > 1` and the underlying swap function
|
|
for `T` provides the strong exception guarantee, `boost::swap`
|
|
provides only the basic exception guarantee.
|
|
|
|
[endsect]
|
|
|
|
[section Requirements]
|
|
|
|
Either:
|
|
|
|
* T must be assignable
|
|
* T must be copy constructible
|
|
|
|
Or:
|
|
|
|
* A function with the signature `swap(T&,T&)` is available via
|
|
argument dependent lookup
|
|
|
|
Or:
|
|
|
|
* A template specialization of `std::swap` exists for T
|
|
|
|
Or:
|
|
|
|
* T is a built-in array of swappable elements
|
|
|
|
[endsect]
|
|
|
|
[section Portability]
|
|
|
|
Several older compilers do not support argument dependent
|
|
lookup. On these compilers `boost::swap` will call
|
|
`std::swap`, ignoring any specialized swap functions that
|
|
could be found as a result of argument dependent lookup.
|
|
|
|
[endsect]
|
|
|
|
[section Credits]
|
|
|
|
* *Niels Dekker* - for implementing and documenting support for
|
|
built-in arrays
|
|
* *Joseph Gauterin* - for the initial idea, implementation,
|
|
tests, and documentation
|
|
* *Steven Watanabe* - for the idea to make `boost::swap` less
|
|
specialized than `std::swap`, thereby allowing the function
|
|
to have the name 'swap' without introducing ambiguity
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|