Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/utility/utility.htm @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 9.9 KB
Line 
1<html>
2        <head>
3                <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
4                <title>Header boost/utility.hpp Documentation</title>
5        </head>
6        <body bgcolor="#FFFFFF" text="#000000">
7                <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="center" WIDTH="277" HEIGHT="86">Header
8                        <a href="../../boost/utility.hpp">boost/utility.hpp</a></h1>
9                <p>The entire contents of the header <code><a href="../../boost/utility.hpp">&lt;boost/utility.hpp&gt;</a></code>
10                        are in <code>namespace boost</code>.</p>
11                <h2>Contents</h2>
12                <ul>
13                        <li>
14                                Class templates supporting the <a href="base_from_member.html">base-from-member
15                                        idiom</a></li>
16                        <li>
17                                Function templates <a href="#checked_delete">checked_delete() and
18                                        checked_array_delete()</a></li>
19                        <li>
20                                Function templates <a href="#functions_next_prior">next() and prior()</a></li>
21                        <li>
22                                Class <a href="#Class_noncopyable">noncopyable</a></li>
23                        <li>
24                                Function template <a href="#addressof">addressof()</a></li>
25                        <li>Class template <a href="#result_of">result_of</a></li>
26                        <li><a href="index.html">Other utilities not part of <code>utility.hpp</code></a></li>
27                </ul>
28                <h2>
29                        Function templates <a name="checked_delete">checked_delete</a>() and
30                        checked_array_delete()</h2>
31                <p>See <a href="checked_delete.html">separate documentation</a>.</p>
32                <h2>
33                        <a name="functions_next_prior">Function</a> templates next() and prior()</h2>
34                <p>Certain data types, such as the C++ Standard Library's forward and bidirectional
35                        iterators, do not provide addition and subtraction via operator+() or
36                        operator-().&nbsp; This means that non-modifying computation of the next or
37                        prior value requires a temporary, even though operator++() or operator--() is
38                        provided.&nbsp; It also means that writing code like <code>itr+1</code> inside
39                        a template restricts the iterator category to random access iterators.</p>
40                <p>The next() and prior() functions provide a simple way around these problems:</p>
41                <blockquote>
42                        <pre>template &lt;class T&gt;
43T next(T x) { return ++x; }
44
45template &lt;class T, class Distance&gt;
46T next(T x, Distance n)
47{
48    std::advance(x, n);
49    return x;
50}
51
52template &lt;class T&gt;
53T prior(T x) { return --x; }
54
55template &lt;class T, class Distance&gt;
56T prior(T x, Distance n)
57{
58    std::advance(x, -n);
59    return x;
60}</pre>
61                </blockquote>
62                <p>Usage is simple:</p>
63                <blockquote>
64                        <pre>const std::list&lt;T&gt;::iterator p = get_some_iterator();
65const std::list&lt;T&gt;::iterator prev = boost::prior(p);
66const std::list&lt;T&gt;::iterator next = boost::next(prev, 2);</pre>
67                </blockquote>
68                <p>The distance from the given iterator should be supplied as an absolute value. For
69                        example, the iterator four iterators prior to the given iterator <code>p</code>
70                        may be obtained by <code>prior(p, 4)</code>.</p>
71                <p>Contributed by <a href="../../people/dave_abrahams.htm">Dave Abrahams</a>.  Two-argument versions by Daniel Walker.</p>
72                <h2><a name="Class_noncopyable">Class noncopyable</a></h2>
73                <p>Class <strong>noncopyable</strong> is a base class.&nbsp; Derive your own class
74                        from <strong>noncopyable</strong> when you want to prohibit copy construction
75                        and copy assignment.</p>
76                <p>Some objects, particularly those which hold complex resources like files or
77                        network connections, have no sensible copy semantics.&nbsp; Sometimes there are
78                        possible copy semantics, but these would be of very limited usefulness and be
79                        very difficult to implement correctly.&nbsp; Sometimes you're implementing a
80                        class that doesn't need to be copied just yet and you don't want to take the
81                        time to write the appropriate functions.&nbsp; Deriving from <b>noncopyable</b> 
82                        will prevent the otherwise implicitly-generated functions (which don't have the
83                        proper semantics) from becoming a trap for other programmers.</p>
84                <p>The traditional way to deal with these is to declare a private copy constructor
85                        and copy assignment, and then document why this is done.&nbsp; But deriving
86                        from <b>noncopyable</b> is simpler and clearer, and doesn't require additional
87                        documentation.</p>
88                <p>The program <a href="noncopyable_test.cpp">noncopyable_test.cpp</a> can be used
89                        to verify class <b>noncopyable</b> works as expected. It has have been run
90                        successfully under GCC 2.95, Metrowerks CodeWarrior 5.0, and Microsoft Visual
91                        C++ 6.0 sp 3.</p>
92                <p>Contributed by <a href="../../people/dave_abrahams.htm">Dave Abrahams</a>.</p>
93                <h3>Example</h3>
94                <blockquote>
95                        <pre>// inside one of your own headers ...
96#include &lt;boost/utility.hpp&gt;
97
98class ResourceLadenFileSystem : boost::noncopyable {
99...</pre>
100                </blockquote>
101                <h3>Rationale</h3>
102                <p>Class noncopyable has protected constructor and destructor members to emphasize
103                        that it is to be used only as a base class.&nbsp; Dave Abrahams notes concern
104                        about the effect on compiler optimization of adding (even trivial inline)
105                        destructor declarations. He says &quot;Probably this concern is misplaced,
106                        because noncopyable will be used mostly for classes which own resources and
107                        thus have non-trivial destruction semantics.&quot;</p>
108                <h2><a name="addressof">Function template addressof()</a></h2>
109                <p>Function <strong>addressof()</strong> returns the address of an object.</p>
110                <blockquote>
111                        <pre>template &lt;typename T&gt; inline T*                addressof(T& v);
112template &lt;typename T&gt; inline const T*          addressof(const T& v);
113template &lt;typename T&gt; inline volatile T*       addressof(volatile T& v);
114template &lt;typename T&gt; inline const volatile T* addressof(const volatile T& v);
115</pre>
116                </blockquote>
117                <p>C++ allows programmers to replace the unary <strong>operator&()</strong> class
118                        member used to get the address of an object. Getting the real address of an
119                        object requires ugly casting tricks to avoid invoking the overloaded <strong>operator&()</strong>.
120                        Function <strong>addressof()</strong> provides a wrapper around the necessary
121                        code to make it easy to get an object's real address.
122                </p>
123                <p>The program <a href="addressof_test.cpp">addressof_test.cpp</a> can be used to
124                        verify that <b>addressof()</b> works as expected.</p>
125                <p>Contributed by Brad King based on ideas from discussion with Doug Gregor.</p>
126                <h3>Example</h3>
127                <blockquote>
128                        <pre>#include &lt;boost/utility.hpp&gt;
129
130struct useless_type {};
131class nonaddressable {
132  useless_type operator&() const;
133};
134
135void f() {
136  nonaddressable x;
137  nonaddressable* xp = boost::addressof(x);
138  // nonaddressable* xpe = &amp;x; /* error */
139}</pre>
140                </blockquote>
141                <h2><a name="result_of">Class template
142                result_of</a></h2> <p>The class template
143                <code>result_of</code> helps determine the type of a
144                call expression. Given an lvalue <code>f</code> of
145                type <code>F</code> and lvalues <code>t1</code>,
146                <code>t2</code>, ..., <code>t<em>N</em></code> of
147                types <code>T1</code>, <code>T2</code>, ...,
148                <code>T<em>N</em></code>, respectively, the type
149                <code>result_of&lt;F(T1, T2, ...,
150                T<em>N</em>)&gt;::type</code> defines the result type
151                of the expression <code>f(t1, t2,
152                ...,t<em>N</em>)</code>. The implementation permits
153                the type <code>F</code> to be a function pointer,
154                function reference, member function pointer, or class
155                type. When <code>F</code> is a class type with a
156                member type <code>result_type</code>,
157                <code>result_of&lt;F(T1, T2, ...,
158                T<em>N</em>)&gt;</code> is
159                <code>F::result_type</code>. Otherwise,
160                <code>result_of&lt;F(T1, T2, ...,
161                T<em>N</em>)&gt;</code> is <code>F::result&lt;F(T1,
162                T2, ..., T<em>N</em>)&gt;::type</code> when
163                <code><em>N</em> &gt; 0</code> or <code>void</code>
164                when <code><em>N</em> = 0</code>. For additional
165                information about <code>result_of</code>, see the
166                current draft of the C++ Library TR, <a
167                href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2004/n1647.pdf">N1647</a>,
168                or the <code>result_of</code> <a
169                href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1454.html">proposal</a>.</p>
170
171                <p>Class template <code>result_of</code> resides in
172                the header <code>&lt;<a
173                href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>&gt;</code>. By
174                default, <em>N</em> may be any value between 0 and
175                10. To change the upper limit, define the macro
176                <code>BOOST_RESULT_OF_NUM_ARGS</code> to the maximum
177                value for <em>N</em>.</p>
178
179                <a name="BOOST_NO_RESULT_OF"></a>
180                <p>This implementation of <code>result_of</code> requires class template partial specialization, the ability to parse function types properly, and support for SFINAE. If <code>result_of</code> is not supported by your compiler, including the header <code>boost/utility/result_of.hpp</code> will define the macro <code>BOOST_NO_RESULT_OF</code>. Contributed by Doug Gregor.</p>
181
182                <h2>Class templates for the Base-from-Member Idiom</h2>
183                <p>See <a href="base_from_member.html">separate documentation</a>.</p>
184                <hr>
185                <p>Revised&nbsp; <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan
186-->02 May, 2004<!--webbot bot="Timestamp" endspan i-checksum="38582"
187-->
188                </p>
189                <p>&copy; Copyright boost.org 1999-2003. Permission to copy, use, modify, sell and distribute
190                        this document is granted provided this copyright notice appears in all copies.
191                        This document is provided &quot;as is&quot; without express or implied
192                        warranty, and with no claim as to its suitability for any purpose.</p>
193        </body>
194</html>
Note: See TracBrowser for help on using the repository browser.