|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r49763 - in branches/release/libs: . utility
From: joseph.gauterin_at_[hidden]
Date: 2008-11-14 20:15:54
Author: joseph.gauterin
Date: 2008-11-14 20:15:54 EST (Fri, 14 Nov 2008)
New Revision: 49763
URL: http://svn.boost.org/trac/boost/changeset/49763
Log:
Merged utility/swap documentation to release branch.
Added:
branches/release/libs/utility/swap.html (contents, props changed)
Text files modified:
branches/release/libs/libraries.htm | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
Modified: branches/release/libs/libraries.htm
==============================================================================
--- branches/release/libs/libraries.htm (original)
+++ branches/release/libs/libraries.htm 2008-11-14 20:15:54 EST (Fri, 14 Nov 2008)
@@ -253,6 +253,8 @@
Guzman, Hartmut Kaiser, Dan Nuffer and team.</li>
<li>string_algo -
String algorithms library, from Pavol Droba.</li>
+ <li>swap -
+ Enhanced generic swap function, from Joseph Gauterin.</li>
<li>system - Operating system support,
including the diagnostics support that will be part of the C++0x standard
library, from Beman Dawes.</li>
Added: branches/release/libs/utility/swap.html
==============================================================================
--- (empty file)
+++ branches/release/libs/utility/swap.html 2008-11-14 20:15:54 EST (Fri, 14 Nov 2008)
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Boost: Swap Documentation</title>
+ </head>
+ <body>
+ <!-- Page header -->
+ <img src="../../boost.png" alt="C++ Boost" align="middle" width="277" height="86"/>
+ <h1>Swap</h1>
+
+ <p>
+ <tt>template<class T> void swap(T& <em>left</em>, T& <em>right</em>);</tt>
+ </p>
+
+ <!-- Intoduction -->
+ <p>
+ The template function <tt>boost::swap</tt> 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, <tt>std::swap</tt> is used.
+ </p>
+
+ <!-- Rationale -->
+ <h2>Rationale</h2>
+ <p>
+ The generic <tt>std::swap</tt> 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<sup>1</sup>).</p>
+ <p>
+ 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.
+ </p>
+ <p>
+ <tt>boost::swap</tt> also supports swapping built-in arrays. Note that <tt>std::swap</tt> doesn't yet do so, but a request to add an overload of <tt>std::swap</tt> for built-in arrays has been well-received by the Library Working Group of the C++ Standards Committee<sup>2</sup>.
+ </p>
+
+ <!-- Exception Safety -->
+ <h2>Exception Safety</h2>
+ <p>
+ <tt>boost::swap</tt> provides the same exception guarantee as the underlying swap function used, with one exception; for an array of type <tt>T[n]</tt>, where <tt>n > 1</tt> and the underlying swap function for <tt>T</tt> provides the strong exception guarantee, <tt>boost::swap</tt> provides only the basic exception guarantee.
+ </p>
+
+ <!-- Requirements -->
+ <h2>Requirements</h2>
+ <p>Either:</p>
+ <ul>
+ <li>T must be assignable</li>
+ <li>T must be copy constructible</li>
+ </ul>
+ <p>Or:</p>
+ <ul>
+ <li>A function with the signature <tt>swap(T&,T&)</tt> is available via argument dependent lookup</li>
+ </ul>
+ <p>Or:</p>
+ <ul>
+ <li>A template specialization of std::swap exists for T</li>
+ </ul>
+ <p>Or:</p>
+ <ul>
+ <li>T is a built-in array of swappable elements</li>
+ </ul>
+
+
+ <!-- Portability -->
+ <h2>Portability</h2>
+ <p>
+ Several older compilers do not support argument dependent lookup ‒ on these compilers <tt>boost::swap</tt> will call <tt>std::swap</tt>, ignoring any specialized swap functions that could be found as a result of argument dependent lookup.
+ </p>
+
+ <!-- Credits -->
+ <h2>Credits</h2>
+ <ul>
+ <li>
+ <em>Niels Dekker</em> - for implementing and documenting support for built-in arrays
+ </li>
+ <li>
+ <em><a href="mailto:Joseph.Gauterin_at_[hidden]">Joseph Gauterin</a></em> - for the initial idea, implementation, tests, and documentation
+ </li>
+ <li>
+ <em>Steven Watanabe</em> - for the idea to make boost::swap less specialized than std::swap, thereby allowing the function to have the name 'swap' without introducing ambiguity
+ </li>
+ </ul>
+
+ <!-- References -->
+ <hr/>
+ <p><sup><a id="ref1"/>[1]</sup>Scott Meyers, Effective C++ Third Edition, Item 25: "Consider support for a non-throwing swap"</p>
+ <p><sup><a id="ref2"/>[2]</sup>LWG issue 809 (std::swap should be overloaded for array types)</p>
+
+ <!-- Copyright info -->
+ <hr/>
+ <p>Revised: 21 October 2008</p>
+ <p>
+ Copyright 2007, 2008 Joseph Gauterin. Use, modification, and distribution are subject to the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)
+ </p>
+
+ </body>
+</html>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk