<h2>Contents</h2>
<ul>
<li>
- Class templates supporting the <a href="base_from_member.html">base-from-member
- idiom</a></li>
+ Class templates supporting the <a href="doc/html/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>
+ Function templates <a href="../core/doc/html/core/checked_delete.html">checked_delete() and
+ checked_array_delete()</a> (moved to the Boost.Core library)</li>
<li>
Function templates <a href="#functions_next_prior">next() and prior()</a></li>
<li>
- Class <a href="#Class_noncopyable">noncopyable</a></li>
+ Class <a href="../core/doc/html/core/noncopyable.html">noncopyable</a> (moved to the Boost.Core library)</li>
<li>
- Function template <a href="#addressof">addressof()</a></li>
+ Function template <a href="../core/doc/html/core/addressof.html">addressof()</a> (moved to the Boost.Core library)</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
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
+ call expression. For example, 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>, ...,
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
+ 16. 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>
+ <p>If your compiler's support for <code>decltype</code> is
+ adequate, <code>result_of</code> automatically uses it to
+ deduce the type of the call expression, in which case
+ <code>result_of<F(T1, T2, ...,
+ T<em>N</em>)>::type</code> names the type
+ <code>decltype(boost::declval<F>()(boost::declval<T1>(),
+ boost::declval<T2>(), ...,
+ boost::declval<T<em>N</em>>()))</code>, as in the
+ following example.</p>
<blockquote>
- <pre>#define BOOST_RESULT_OF_USE_DECLTYPE
-#include <boost/utility/result_of.hpp>
-
-struct functor {
+ <pre>struct functor {
template<class T>
T operator()(T x)
{
typedef boost::result_of<
functor(int)
->::type type;</pre>
+>::type type; // type is int</pre>
</blockquote>
- <p>If <code>decltype</code> is not enabled,
+ <p>You can test whether <code>result_of</code> is using
+ <code>decltype</code> by checking if the macro
+ <code>BOOST_RESULT_OF_USE_DECLTYPE</code> is defined after
+ including <code>result_of.hpp</code>. You can also force
+ <code>result_of</code> to use <code>decltype</code> by
+ defining <code>BOOST_RESULT_OF_USE_DECLTYPE</code> prior
+ to including <code>result_of.hpp</code>.</p>
+
+ <p>If <code>decltype</code> is not used,
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
+ T<em>N</em>)>::type</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,
+ T<em>N</em>)>::type</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
typedef boost::result_of<
functor(int)
->::type type;</pre>
+>::type type; // type is int</pre>
</blockquote>
- <p>In a future
- release, <code>BOOST_RESULT_OF_USE_DECLTYPE</code>
- may be enabled by default on compilers that
- support <code>decltype</code>, so if you use the above
- protocol please take care to ensure that
- the <code>result_type</code>
- and <code>result<></code> members accurately
- represent the result type. If you wish to continue to
+ <p>Since <code>decltype</code> is a new language
+ feature recently standardized in C++11,
+ if you are writing a function object
+ to be used with <code>result_of</code>, for
+ maximum portability, you might consider following
+ the above protocol even if your compiler has
+ proper <code>decltype</code> support. If you wish to continue to
use the protocol on compilers that
- support <code>decltype</code>,
- use <code>boost::tr1_result_of</code>, which is also
- defined
- in <code><<a href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>></code>.</p>
+ support <code>decltype</code>, there are two options:
+ You can use <code>boost::tr1_result_of</code>, which is also
+ defined in <code><<a href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>></code>.
+ Alternatively, you can define the macro
+ <code>BOOST_RESULT_OF_USE_TR1</code>, which causes
+ <code>result_of</code> to use the protocol described
+ above instead of <code>decltype</code>. If you choose to
+ follow the protocol, take care to ensure that the
+ <code>result_type</code> and
+ <code>result<></code> members accurately
+ represent the return type of
+ <code>operator()</code> given a call expression.</p>
+
+ <p>Additionally, <code>boost::result_of</code>
+ provides a third mode of operation, which some users
+ may find convenient. When
+ <code>BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK</code>
+ is defined, <code>boost::result_of</code> behaves as
+ follows. If the function object has a member
+ type <code>result_type</code> or member
+ template <code>result<></code>, then
+ <code>boost::result_of</code> will use the TR1
+ protocol. Otherwise,
+ <code>boost::result_of</code> will
+ use <code>decltype</code>. Using TR1 with
+ a <code>declytpe</code> fallback may workaround
+ certain problems at the cost of portability. For
+ example:
+ <ul>
+ <li>Deficient compiler: If your code
+ requires <code>boost::result_of</code> to work
+ with incomplete return types but your
+ compiler's <code>decltype</code> implementation
+ does not support incomplete return types, then you
+ can use the TR1 protocol as a workaround. Support
+ for incomplete return types was added late in the
+ C++11 standardization process
+ (see <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf">N3276</a>)
+ and is not implemented by some compilers.</li>
+
+ <li>Deficient legacy code: If your existing TR1
+ function object advertises a different type than
+ the actual result type deduced
+ by <code>decltype</code>, then using TR1 with a
+ <code>decltype</code> fallback will allow you to
+ work with both your existing TR1 function objects
+ and new C++11 function object. This situation
+ could occur if your legacy function objects
+ misused the TR1 protocol. See the documentation on
+ known <a href="#result_of_tr1_diff">differences</a>
+ between <code>boost::result_of</code> and TR1.</li>
+ </ul>
<a name="BOOST_NO_RESULT_OF"></a>
<p>This implementation of <code>result_of</code>
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>
+ the <code>result_of</code> <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1454.html">proposal</a>.</p>
+
+ <a name="result_of_guidelines">
+ <h3>Usage guidelines for boost::result_of</h3>
+ </a>
+
+ <p>The following are general suggestions about when
+ and how to use <code>boost::result_of</code>.</p>
+
+ <ol>
+ <li> If you are targeting C++11 and are not concerned
+ about portability to non-compliant compilers or
+ previous versions of the standard, then use
+ <code>std::result_of</code>. If <code>std::result_of</code>
+ meets your needs, then there's no reason to stop using
+ it.</li>
+
+ <li> If you are targeting C++11 but may port your code
+ to legacy compilers at some time in the future, then
+ use <code>boost::result_of</code> with
+ <code>decltype</code>. When <code>decltype</code> is
+ used <code>boost::result_of</code>
+ and <code>std::result_of</code> are usually
+ interchangeable. See the documentation on
+ known <a href="#result_of_cxx11_diff">differences</a>
+ between boost::result_of and C++11 result_of.</li>
+
+ <li> If compiler portability is required,
+ use <code>boost::result_of</code> with the TR1 protocol.</li>
+ </ol>
+
+ <p>Regardless of how you
+ configure <code>boost::result_of</code>, it is
+ important to bear in mind that the return type of a
+ function may change depending on its arguments, and
+ additionally, the return type of a member function may
+ change depending on the cv-qualification of the
+ object. <code>boost::result_of</code> must be passed
+ the appropriately cv-qualified types in order to
+ deduce the corresponding return type. For example:
+
+ <blockquote>
+ <pre>struct functor {
+ int& operator()(int);
+ int const& operator()(int) const;
+
+ float& operator()(float&);
+ float const& operator()(float const&);
+};
+
+typedef boost::result_of<
+ functor(int)
+>::type type1; // type1 is int &
+
+typedef boost::result_of<
+ const functor(int)
+>::type type2; // type2 is int const &
+
+typedef boost::result_of<
+ functor(float&)
+>::type type3; // type3 is float &
+
+typedef boost::result_of<
+ functor(float const&)
+>::type type4; // type4 is float const &</pre>
+ </blockquote>
+
+ <a name="result_of_tr1_protocol_guidelines">
+ <h3>Usage guidelines for the TR1 result_of protocol</h3>
+ </a>
+
+ <p>On compliant C++11
+ compilers, <code>boost::result_of</code> can
+ use <code>decltype</code> to deduce the type of any
+ call expression, including calls to function
+ objects. However, on pre-C++11 compilers or on
+ compilers without adequate decltype support,
+ additional scaffolding is needed from function
+ objects as described above. The following are
+ suggestions about how to use the TR1 protocol.</p>
+
+ <ul>
+ <li>When the return type does not depend on the
+ argument types or the cv-qualification of the
+ function object, simply
+ define <code>result_type</code>. There is no need
+ to use the <code>result</code> template unless the
+ return type varies.</li>
+
+ <li>Use the protocol specified type when defining
+ function prototypes. This can help ensure the
+ actual return type does not get out of sync with
+ the protocol specification. For example:
+
+ <blockquote>
+ <pre>struct functor {
+ typedef int result_type;
+ result_type operator()(int);
+};</pre>
+ </blockquote> </li>
+
+ <li>Always specify the <code>result</code>
+ specialization near the corresponding
+ <code>operator()</code> overload. This can make it
+ easier to keep the specializations in sync with the
+ overloads. For example:
+
+ <blockquote>
+ <pre>struct functor {
+ template<class> struct result;
+
+ template<class F>
+ struct result<F(int)> {
+ typedef int& type;
+ };
+ result<functor(int)>::type operator()(int);
+
+ template<class F>
+ struct result<const F(int)> {
+ typedef int const& type;
+ };
+ result<const functor(int)>::type operator()(int) const;
+};</pre>
+ </blockquote> </li>
+
+ <li>Use type transformations to simplify
+ the <code>result</code> template specialization. For
+ example, the following uses
+ <a href="../type_traits/doc/html/index.html">Boost.TypeTraits</a>
+ to specialize the <code>result</code> template for
+ a single <code>operator()</code> that can be called on
+ both a const and non-const function object with
+ either an lvalue or rvalue argument.
+
+ <blockquote>
+ <pre>struct functor {
+ template<class> struct result;
+
+ template<class F, class T>
+ struct result<F(T)>
+ : boost::remove_cv<
+ typename boost::remove_reference<T>::type
+ >
+ {};
+
+ template<class T>
+ T operator()(T const& x) const;
+};</pre>
+ </blockquote></li>
+ </ul>
+
+ <a name="result_of_tr1_diff">
+ <h3>Known differences between boost::result_of and TR1 result_of</h3>
+ </a>
+
+ When using <code>decltype</code>, <code>boost::result_of</code>
+ ignores the TR1 protocol and instead deduces the
+ return type of function objects directly
+ via <code>decltype</code>. In most situations, users
+ will not notice a difference, so long as they use the
+ protocol correctly. The following are situations in
+ which the type deduced
+ by <code>boost::result_of</code> is known to differ depending on
+ whether <code>decltype</code> or the TR1 protocol is
+ used.
+
+ <ul>
+ <li> TR1 protocol misusage
+
+ <p>When using the TR1
+ protocol, <code>boost::result_of</code> cannot
+ detect whether the actual type of a call to a
+ function object is the same as the type specified
+ by the protocol, which allows for the possibility
+ of inadvertent mismatches between the specified
+ type and the actual type. When
+ using <code>decltype</code>, these subtle bugs
+ may result in compilation errors. For example:</p>
+
+ <blockquote>
+ <pre>struct functor {
+ typedef short result_type;
+ int operator()(short);
+};
+
+#ifdef BOOST_RESULT_OF_USE_DECLTYPE
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<boost::result_of<functor(short)>::type, int>::value
+));
+
+#else
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<boost::result_of<functor(short)>::type, short>::value
+));
+
+#endif</pre>
+ </blockquote>
+
+ <p>Note that the user can
+ force <code>boost::result_of</code> to use the TR1
+ protocol even on platforms that
+ support <code>decltype</code> by
+ defining <code>BOOST_RESULT_OF_USE_TR1</code>.</p></li>
+
+ <li> Nullary function objects
+
+ <p>When using the TR1 protocol, <code>boost::result_of</code>
+ cannot always deduce the type of calls to
+ nullary function objects, in which case the
+ type defaults to void. When using <code>decltype</code>,
+ <code>boost::result_of</code> always gives the actual type of the
+ call expression. For example:</p>
+
+ <blockquote>
+ <pre>struct functor {
+ template<class> struct result {
+ typedef int type;
+ };
+ int operator()();
+};
+
+#ifdef BOOST_RESULT_OF_USE_DECLTYPE
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<boost::result_of<functor()>::type, int>::value
+));
+
+#else
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<boost::result_of<functor()>::type, void>::value
+));
+
+#endif</pre>
+ </blockquote>
+
+ <p>Note that there are some workarounds for the
+ nullary function problem. So long as the return
+ type does not vary,
+ <code>result_type</code> can always be used to
+ specify the return type regardless of arity. If the
+ return type does vary, then the user can
+ specialize <code>boost::result_of</code> itself for
+ nullary calls.</p></li>
+
+ <li> Non-class prvalues and cv-qualification
+
+ <p>When using the TR1
+ protocol, <code>boost::result_of</code> will
+ report the cv-qualified type specified
+ by <code>result_type</code> or
+ the <code>result</code> template regardless of
+ the actual cv-qualification of the call
+ expression. When using
+ <code>decltype</code>, <code>boost::result_of</code>
+ will report the actual type of the call expression,
+ which is not cv-qualified when the expression is a
+ non-class prvalue. For example:</p>
+
+ <blockquote>
+ <pre>struct functor {
+ template<class> struct result;
+ template<class F, class T> struct result<F(const T)> {
+ typedef const T type;
+ };
+
+ const short operator()(const short);
+ int const & operator()(int const &);
+};
+
+// Non-prvalue call expressions work the same with or without decltype.
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<
+ boost::result_of<functor(int const &)>::type,
+ int const &
+::value
+));
+
+// Non-class prvalue call expressions are not actually cv-qualified,
+// but only the decltype-based result_of reports this accurately.
+
+#ifdef BOOST_RESULT_OF_USE_DECLTYPE
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<
+ boost::result_of<functor(const short)>::type,
+ short
+::value
+));
+
+#else
+
+BOOST_STATIC_ASSERT((
+ boost::is_same<
+ boost::result_of<functor(const short)>::type,
+ const short
+::value
+));
+
+#endif</pre>
+ </blockquote></li>
+ </ul>
+
+ <a name="result_of_cxx11_diff">
+ <h3>Known differences between boost::result_of and C++11 result_of</h3>
+ </a>
+
+ <p>When using <code>decltype</code>, <code>boost::result_of</code>
+ implements most of the C++11 result_of
+ specification. One known exception is that
+ <code>boost::result_of</code> does not implement the
+ requirements regarding pointers to member data.</p>
+
+ <p>Created by Doug Gregor. Contributions from Daniel Walker, Eric Niebler, Michel Morin and others</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
projects / platform / upstream / boost.git / blobdiff