mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 10:24:00 +00:00
6e26a5bbe7
- Include boost/utility/addressof.hpp boost/utility/addressof.hpp: - addressof() implementation libs/utility/utility.htm: - Document addressof libs/utility/addressof_test.cpp: - Test addressof() [SVN r13414]
194 lines
7.8 KiB
HTML
194 lines
7.8 KiB
HTML
<html>
|
||
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<title>Header boost/utility.hpp Documentation</title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF" text="#000000">
|
||
|
||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" WIDTH="277" HEIGHT="86">Header
|
||
<a href="../../boost/utility.hpp">boost/utility.hpp</a></h1>
|
||
|
||
<p>The entire contents of the header <code><a href="../../boost/utility.hpp"><boost/utility.hpp></a></code>
|
||
are in <code>namespace boost</code>.</p>
|
||
|
||
<h2>Contents</h2>
|
||
|
||
<ul>
|
||
<li>Class templates supporting the <a href="base_from_member.html">base-from-member
|
||
idiom</a></li>
|
||
<li>Function templates <a href="#checked_delete">checked_delete() and
|
||
checked_array_delete()</a></li>
|
||
<li>Function templates <a href="#functions next">next() and prior()</a></li>
|
||
<li>Class <a href="#Class noncopyable">noncopyable</a></li>
|
||
<li>Function template <a href="#addressof">addressof()</a></li>
|
||
<li>Function template <a href="tie.html">tie()</a> and supporting class tied.</li>
|
||
</ul>
|
||
<h2> Function templates <a name="checked_delete">checked_delete</a>() and
|
||
checked_array_delete()</h2>
|
||
|
||
<p>Deletion of a pointer to an incomplete type is an unsafe programming practice
|
||
because there is no way for the compiler to verify that the destructor is indeed
|
||
trivial. The checked_delete() and checked_array_delete() function
|
||
templates simply <b>delete</b> or <b>delete[]</b> their argument, but also
|
||
require that their argument be a complete type. They issue an appropriate
|
||
compiler error diagnostic if that requirement is not met. A typical
|
||
implementation is shown; other implementations may vary:</p>
|
||
|
||
<pre> template< typename T >
|
||
inline void checked_delete(T const volatile * x)
|
||
{
|
||
BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
|
||
// of instantiation
|
||
delete x;
|
||
}
|
||
|
||
template< typename T >
|
||
inline void checked_array_delete(T const volatile * x)
|
||
{
|
||
BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
|
||
// of instantiation
|
||
delete [] x;
|
||
}</pre>
|
||
|
||
<p>Contributed by Beman Dawes, based on a suggestion from Dave Abrahams,
|
||
generalizing an idea from Vladimir Prus, with comments from Rainer Deyke, John
|
||
Maddock, and others.</p>
|
||
|
||
<h3>Background</h3>
|
||
|
||
<p>The C++ Standard specifies that delete on a pointer to an incomplete types is
|
||
undefined behavior if the type has a non-trivial destructor in [expr.delete]
|
||
5.3.5 paragraph. No diagnostic is required. Some but not all
|
||
compilers issue warnings if the type is incomplete at point of deletion.</p>
|
||
|
||
<h2> <a name="functions next">Function</a> templates next() and prior()</h2>
|
||
|
||
<p>Certain data types, such as the C++ Standard Library's forward and
|
||
bidirectional iterators, do not provide addition and subtraction via operator+()
|
||
or operator-(). This means that non-modifying computation of the next or
|
||
prior value requires a temporary, even though operator++() or operator--() is
|
||
provided. It also means that writing code like <code>itr+1</code> inside a
|
||
template restricts the iterator category to random access iterators.</p>
|
||
|
||
<p>The next() and prior() functions provide a simple way around these problems:</p>
|
||
|
||
<blockquote>
|
||
|
||
<pre>template <class T>
|
||
T next(T x) { return ++x; }
|
||
|
||
template <class X>
|
||
T prior(T x) { return --x; }</pre>
|
||
|
||
</blockquote>
|
||
|
||
<p>Usage is simple:</p>
|
||
|
||
<blockquote>
|
||
|
||
<pre>const std::list<T>::iterator p = get_some_iterator();
|
||
const std::list<T>::iterator prev = boost::prior(p);</pre>
|
||
|
||
</blockquote>
|
||
|
||
<p>Contributed by <a href="../../people/dave_abrahams.htm">Dave Abrahams</a>.</p>
|
||
|
||
<h2><a name="Class noncopyable">Class noncopyable</a></h2>
|
||
|
||
<p>Class <strong>noncopyable</strong> is a base class. Derive your own class from <strong>noncopyable</strong>
|
||
when you want to prohibit copy construction and copy assignment.</p>
|
||
|
||
<p>Some objects, particularly those which hold complex resources like files or
|
||
network connections, have no sensible copy semantics. Sometimes there are
|
||
possible copy semantics, but these would be of very limited usefulness and be
|
||
very difficult to implement correctly. Sometimes you're implementing a class that doesn't need to be copied
|
||
just yet and you don't want to take the time to write the appropriate functions.
|
||
Deriving from <b> noncopyable</b> will prevent the otherwise implicitly-generated
|
||
functions (which don't have the proper semantics) from becoming a trap for other programmers.</p>
|
||
|
||
<p>The traditional way to deal with these is to declare a private copy constructor and copy assignment, and then
|
||
document why this is done. But deriving from <b>noncopyable</b> is simpler
|
||
and clearer, and doesn't require additional documentation.</p>
|
||
|
||
<p>The program <a href="noncopyable_test.cpp">noncopyable_test.cpp</a> can be
|
||
used to verify class <b>noncopyable</b> works as expected. It has have been run successfully under
|
||
GCC 2.95, Metrowerks
|
||
CodeWarrior 5.0, and Microsoft Visual C++ 6.0 sp 3.</p>
|
||
|
||
<p>Contributed by <a href="../../people/dave_abrahams.htm">Dave Abrahams</a>.</p>
|
||
|
||
<h3>Example</h3>
|
||
<blockquote>
|
||
<pre>// inside one of your own headers ...
|
||
#include <boost/utility.hpp>
|
||
|
||
class ResourceLadenFileSystem : boost::noncopyable {
|
||
...</pre>
|
||
</blockquote>
|
||
|
||
<h3>Rationale</h3>
|
||
<p>Class noncopyable has protected constructor and destructor members to
|
||
emphasize that it is to be used only as a base class. Dave Abrahams notes
|
||
concern about the effect on compiler optimization of adding (even trivial inline)
|
||
destructor declarations. He says "Probably this concern is misplaced, because
|
||
noncopyable will be used mostly for classes which own resources and thus have non-trivial destruction semantics."</p>
|
||
<h2><a name="addressof">Function template addressof()</a></h2>
|
||
<p>Function <strong>addressof()</strong> returns the address of an object.</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
template <typename T> inline T* addressof(T& v);
|
||
template <typename T> inline const T* addressof(const T& v);
|
||
template <typename T> inline volatile T* addressof(volatile T& v);
|
||
template <typename T> inline const volatile T* addressof(const volatile T& v);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
|
||
<p>C++ allows programmers to replace the unary
|
||
<strong>operator&()</strong> class member used to get the address of
|
||
an object. Getting the real address of an object requires ugly
|
||
casting tricks to avoid invoking the overloaded
|
||
<strong>operator&()</strong>. Function <strong>addressof()</strong>
|
||
provides a wrapper around the necessary code to make it easy to get an
|
||
object's real address.
|
||
</p>
|
||
|
||
<p>The program <a href="addressof_test.cpp">addressof_test.cpp</a> can be
|
||
used to verify that <b>addressof()</b> works as expected.</p>
|
||
|
||
<p>Contributed by Brad King based on ideas from discussion with Doug Gregor.</p>
|
||
<h3>Example</h3>
|
||
<blockquote>
|
||
<pre>#include <boost/utility.hpp>
|
||
|
||
struct useless_type {};
|
||
class nonaddressable {
|
||
useless_type operator&() const;
|
||
};
|
||
|
||
void f() {
|
||
nonaddressable x;
|
||
nonaddressable* xp = boost::addressof(x);
|
||
// nonaddressable* xpe = &x; /* error */
|
||
}</pre>
|
||
</blockquote>
|
||
|
||
<h2>Class templates for the Base-from-Member Idiom</h2>
|
||
<p>See <a href="base_from_member.html">separate documentation</a>.</p>
|
||
<h2>Function template tie()</h2>
|
||
<p>See <a href="tie.html">separate documentation</a>.</p>
|
||
<hr>
|
||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan
|
||
-->10 September, 2001<!--webbot bot="Timestamp" endspan i-checksum="39328"
|
||
-->
|
||
</p>
|
||
<p><EFBFBD> Copyright boost.org 1999. Permission to copy, use, modify, sell and
|
||
distribute this document is granted provided this copyright notice appears in
|
||
all copies. This document is provided "as is" without express or
|
||
implied warranty, and with no claim as to its suitability for any purpose.</p>
|
||
</body>
|
||
</html>
|