123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121 |
- [/
- / 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]
|