ceph/src/boost/libs/core/doc/swap.qbk

   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
  31 The template function `boost::swap` allows the values of two
  32 variables to be swapped, using argument dependent lookup to
  33 select a specialized swap function if available. If no
  34 specialized swap function is available, `std::swap` is used.
  35
  36 [endsect]
  37
  38 [section Rationale]
  39
  40 The generic `std::swap` function requires that the elements
  41 to be swapped are assignable and copy constructible. It is
  42 usually implemented using one copy construction and two
  43 assignments - this is often both unnecessarily restrictive and
  44 unnecessarily slow. In addition, where the generic swap
  45 implementation provides only the basic guarantee, specialized
  46 swap functions are often able to provide the no-throw exception
  47 guarantee (and it is considered best practice to do so where
  48 possible [footnote Scott Meyers, Effective C++ Third Edition,
  49 Item 25: "Consider support for a non-throwing swap"].
  50
  51 The alternative to using argument dependent lookup in this
  52 situation is to provide a template specialization of
  53 `std::swap` for every type that requires a specialized swap.
  54 Although this is legal C++, no Boost libraries use this method,
  55 whereas many Boost libraries provide specialized swap functions
  56 in 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
  60 overload of `std::swap` for built-in arrays has been accepted
  61 by 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
  71 underlying swap function used, with one exception; for an array
  72 of type `T[n]`, where `n > 1` and the underlying swap function
  73 for `T` provides the strong exception guarantee, `boost::swap`
  74 provides only the basic exception guarantee.
  75
  76 [endsect]
  77
  78 [section Requirements]
  79
  80 Either:
  81
  82 * T must be assignable
  83 * T must be copy constructible
  84
  85 Or:
  86
  87 * A function with the signature `swap(T&,T&)` is available via
  88   argument dependent lookup
  89
  90 Or:
  91
  92 * A template specialization of `std::swap` exists for T
  93
  94 Or:
  95
  96 * T is a built-in array of swappable elements
  97
  98 [endsect]
  99
 100 [section Portability]
 101
 102 Several older compilers do not support argument dependent
 103 lookup. On these compilers `boost::swap` will call
 104 `std::swap`, ignoring any specialized swap functions that
 105 could 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]