| <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="../../boost.png" alt="boost.png (6897 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_prior">next() and prior()</a></li> |
| <li> |
| Class <a href="#Class_noncopyable">noncopyable</a></li> |
| <li> |
| Function template <a href="#addressof">addressof()</a></li> |
| <li>Class template <a href="#result_of">result_of</a></li> |
| <li> |
| Macro <a href="#BOOST_BINARY">BOOST_BINARY</a></li> |
| <li><a href="index.html">Other utilities not part of <code>utility.hpp</code></a></li> |
| </ul> |
| <h2> |
| Function templates <a name="checked_delete">checked_delete</a>() and |
| checked_array_delete()</h2> |
| <p>See <a href="checked_delete.html">separate documentation</a>.</p> |
| <h2> |
| <a name="functions_next_prior">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 T, class Distance> |
| T next(T x, Distance n) |
| { |
| std::advance(x, n); |
| return x; |
| } |
| |
| template <class T> |
| T prior(T x) { return --x; } |
| |
| template <class T, class Distance> |
| T prior(T x, Distance n) |
| { |
| std::advance(x, -n); |
| 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); |
| const std::list<T>::iterator next = boost::next(prev, 2);</pre> |
| </blockquote> |
| <p>The distance from the given iterator should be supplied as an absolute value. For |
| example, the iterator four iterators prior to the given iterator <code>p</code> |
| may be obtained by <code>prior(p, 4)</code>.</p> |
| <p>Contributed by <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a>. Two-argument versions by Daniel Walker.</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="http://www.boost.org/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><a name="result_of">Class template |
| result_of</a></h2> <p>The class template |
| <code>result_of</code> helps determine the type of a |
| call expression. Given an lvalue <code>f</code> of |
| type <code>F</code> and lvalues <code>t1</code>, |
| <code>t2</code>, ..., <code>t<em>N</em></code> of |
| types <code>T1</code>, <code>T2</code>, ..., |
| <code>T<em>N</em></code>, respectively, the type |
| <code>result_of<F(T1, T2, ..., |
| T<em>N</em>)>::type</code> defines the result type |
| of the expression <code>f(t1, t2, |
| ...,t<em>N</em>)</code>. This implementation permits |
| the type <code>F</code> to be a function pointer, |
| function reference, member function pointer, or class |
| type. By default, <em>N</em> may be any value between 0 and |
| 10. To change the upper limit, define the macro |
| <code>BOOST_RESULT_OF_NUM_ARGS</code> to the maximum |
| value for <em>N</em>. Class template <code>result_of</code> |
| resides in the header <code><<a |
| href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>></code>.</p> |
| |
| <p>If your compiler supports <code>decltype</code>, |
| then you can enable automatic result type deduction by |
| defining the macro <code>BOOST_RESULT_OF_USE_DECLTYPE</code>, |
| as in the following example.</p> |
| |
| <blockquote> |
| <pre>#define BOOST_RESULT_OF_USE_DECLTYPE |
| #include <boost/utility/result_of.hpp> |
| |
| struct functor { |
| template<class T> |
| T operator()(T x) |
| { |
| return x; |
| } |
| }; |
| |
| typedef boost::result_of< |
| functor(int) |
| >::type type;</pre> |
| </blockquote> |
| |
| <p>If <code>decltype</code> is not enabled, |
| then automatic result type deduction of function |
| objects is not possible. Instead, <code>result_of</code> |
| uses the following protocol to allow the programmer to |
| specify a type. When <code>F</code> is a class type with a |
| member type <code>result_type</code>, |
| <code>result_of<F(T1, T2, ..., |
| T<em>N</em>)></code> is |
| <code>F::result_type</code>. When <code>F</code> does |
| not contain <code>result_type</code>, |
| <code>result_of<F(T1, T2, ..., |
| T<em>N</em>)></code> is <code>F::result<F(T1, |
| T2, ..., T<em>N</em>)>::type</code> when |
| <code><em>N</em> > 0</code> or <code>void</code> |
| when <code><em>N</em> = 0</code>. Note that it is the |
| responsibility of the programmer to ensure that |
| function objects accurately advertise their result |
| type via this protocol, as in the following |
| example.</p> |
| |
| <blockquote> |
| <pre>struct functor { |
| template<class> struct result; |
| |
| template<class F, class T> |
| struct result<F(T)> { |
| typedef T type; |
| }; |
| |
| template<class T> |
| T operator()(T x) |
| { |
| return x; |
| } |
| }; |
| |
| typedef boost::result_of< |
| functor(int) |
| >::type type;</pre> |
| </blockquote> |
| |
| <a name="BOOST_NO_RESULT_OF"></a> |
| <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>.</p> |
| |
| <p>For additional information |
| about <code>result_of</code>, see the C++ Library |
| Technical Report, |
| <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">N1836</a>, |
| or, for motivation and design rationale, |
| the <code>result_of</code> <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1454.html">proposal</a>.</p> |
| Contributed by Doug Gregor.</p> |
| |
| <h2>Class templates for the Base-from-Member Idiom</h2> |
| <p>See <a href="base_from_member.html">separate documentation</a>.</p> |
| <h2><a name="BOOST_BINARY">Macro BOOST_BINARY</a></h2> |
| |
| <p>The macro <code>BOOST_BINARY</code> is used for the |
| representation of binary literals. It takes as an argument |
| a binary number arranged as an arbitrary amount of 1s and 0s in |
| groupings of length 1 to 8, with groups separated |
| by spaces. The type of the literal yielded is determined by |
| the same rules as those of hex and octal |
| literals (<i>2.13.1p1</i>). By implementation, this macro |
| expands directly to an octal literal during preprocessing, so |
| there is no overhead at runtime and the result is useable in |
| any place that an octal literal would be.</p> |
| |
| <p>In order to directly support binary literals with suffixes, |
| additional macros of the form BOOST_BINARY_XXX are also |
| provided, where XXX is a standard integer suffix in all capital |
| letters. In addition, LL and ULL suffixes may be used for representing |
| long long and unsigned long long types in compilers which provide |
| them as an extension.</p> |
| |
| |
| <p>The BOOST_BINARY family of macros resides in the header |
| <a |
| href="../../boost/utility/binary.hpp"><boost/utility/binary.hpp></a> |
| which is automatically included by |
| <a |
| href="../../boost/utility.hpp"><boost/utility.hpp></a>. |
| |
| <p>Contributed by Matt Calabrese.</p><p> |
| </p><h3>Example</h3> |
| <blockquote> |
| <pre> |
| void foo( int ); |
| |
| void foo( unsigned long ); |
| |
| void bar() |
| { |
| int value1 = BOOST_BINARY( 100 111000 01 1 110 ); |
| |
| unsigned long value2 = BOOST_BINARY_UL( 100 001 ); // unsigned long |
| |
| long long value3 = BOOST_BINARY_LL( 11 000 ); // long long if supported |
| |
| assert( BOOST_BINARY( 10010 ) |
| & BOOST_BINARY( 11000 ) |
| == BOOST_BINARY( 10000 ) |
| ); |
| |
| foo( BOOST_BINARY( 1010 ) ); // calls the first foo |
| |
| foo( BOOST_BINARY_LU( 1010 ) ); // calls the second foo |
| } |
| </pre></blockquote> |
| <hr> |
| <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan |
| -->04 September, 2008<!--webbot bot="Timestamp" endspan i-checksum="39369" |
| --> |
| </p> |
| <p>© Copyright Beman Dawes 1999-2003.</p> |
| <p>Distributed under the Boost Software License, Version 1.0. See |
| <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p> |
| |
| </body> |
| </html> |
