[ceph.git] / ceph / src / boost / libs / utility / utility.htm

<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">&lt;boost/utility.hpp&gt;</a></code>
			are in <code>namespace boost</code>.</p>
		<h2>Contents</h2>
		<ul>
			<li>
				Class templates supporting the <a href="doc/html/base_from_member.html">
					base-from-member idiom</a></li>
			<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="../iterator/doc/html/iterator/algorithms/next_prior.html">next() and prior()</a> (moved to the Boost.Iterator library)</li>
			<li>
				Class <a href="../core/doc/html/core/noncopyable.html">noncopyable</a> (moved to the Boost.Core library)</li>
			<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>

                <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. 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>, ...,
                <code>T<em>N</em></code>, respectively, the type
                <code>result_of&lt;F(T1, T2, ...,
                T<em>N</em>)&gt;::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
                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>&lt;<a
                href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>&gt;</code>.</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&lt;F(T1, T2, ...,
                T<em>N</em>)&gt;::type</code> names the type
                <code>decltype(boost::declval&lt;F&gt;()(boost::declval&lt;T1&gt;(),
                boost::declval&lt;T2&gt;(), ...,
                boost::declval&lt;T<em>N</em>&gt;()))</code>, as in the
                following example.</p>

                <blockquote>
                <pre>struct functor {
    template&lt;class T&gt;
    T operator()(T x)
    {
        return x;
    }
};

typedef boost::result_of&lt;
    functor(int)
&gt;::type type; // type is int</pre>
                </blockquote>

                <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&lt;F(T1, T2, ...,
                T<em>N</em>)&gt;::type</code> is
                <code>F::result_type</code>. When <code>F</code> does
                not contain <code>result_type</code>,
                <code>result_of&lt;F(T1, T2, ...,
                T<em>N</em>)&gt;::type</code> is <code>F::result&lt;F(T1,
                T2, ..., T<em>N</em>)&gt;::type</code> when
                <code><em>N</em> &gt; 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&lt;class&gt; struct result;

    template&lt;class F, class T&gt;
    struct result&lt;F(T)&gt; {
        typedef T type;
    };

    template&lt;class T&gt;
    T operator()(T x)
    {
        return x;
    }
};

typedef boost::result_of&lt;
    functor(int)
&gt;::type type; // type is int</pre>
                </blockquote>

                <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>, there are two options:
                You can use <code>boost::tr1_result_of</code>, which is also
                defined in <code>&lt;<a href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>&gt;</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&lt;&gt;</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&lt;&gt;</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>
                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://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&lt;
    functor(int)
&gt;::type type1; // type1 is int &

typedef boost::result_of&lt;
    const functor(int)
&gt;::type type2; // type2 is int const &

typedef boost::result_of&lt;
    functor(float&)
&gt;::type type3; // type3 is float &

typedef boost::result_of&lt;
    functor(float const&)
&gt;::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&lt;class&gt; struct result;

    template&lt;class F&gt;
    struct result&lt;F(int)&gt; {
        typedef int& type;
    };
    result&lt;functor(int)&gt;::type operator()(int);

    template&lt;class F&gt;
    struct result&lt;const F(int)&gt; {
        typedef int const& type;
    };
    result&lt;const functor(int)&gt;::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&lt;class&gt; struct result;

    template&lt;class F, class T&gt;
    struct result&lt;F(T)&gt; 
        : boost::remove_cv&lt;
              typename boost::remove_reference&lt;T&gt;::type
          &gt;
    {};

    template&lt;class T&gt;
    T operator()(T const&amp; 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&lt;boost::result_of&lt;functor(short)&gt;::type, int&gt;::value
)); 

#else

BOOST_STATIC_ASSERT((
   boost::is_same&lt;boost::result_of&lt;functor(short)&gt;::type, short&gt;::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&lt;class&gt; struct result {
       typedef int type;
   };
   int operator()();
};

#ifdef BOOST_RESULT_OF_USE_DECLTYPE

BOOST_STATIC_ASSERT((
   boost::is_same&lt;boost::result_of&lt;functor()&gt;::type, int&gt;::value
));

#else

BOOST_STATIC_ASSERT((
   boost::is_same&lt;boost::result_of&lt;functor()&gt;::type, void&gt;::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&lt;class&gt; struct result;
   template&lt;class F, class T&gt; struct result&lt;F(const T)&gt; {
       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&lt;
       boost::result_of&lt;functor(int const &)&gt;::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&lt;
       boost::result_of&lt;functor(const short)&gt;::type,
       short
::value
));

#else

BOOST_STATIC_ASSERT((
   boost::is_same&lt;
       boost::result_of&lt;functor(const short)&gt;::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><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">&lt;boost/utility/binary.hpp&gt;</a>
                which is automatically included by
                <a
                href="../../boost/utility.hpp">&lt;boost/utility.hpp&gt;</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&nbsp; <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan
-->04 September, 2008<!--webbot bot="Timestamp" endspan i-checksum="39369"
-->
		</p>
		<p>&copy; 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>
Commit	Line	Data
7c673cae FG	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"><boost/utility.hpp></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="doc/html/base_from_member.html">
	15	base-from-member idiom</a></li>
	16	<li>
	17	Function templates <a href="../core/doc/html/core/checked_delete.html">checked_delete() and
	18	checked_array_delete()</a> (moved to the Boost.Core library)</li>
	19	<li>
b32b8144	20	Function templates <a href="../iterator/doc/html/iterator/algorithms/next_prior.html">next() and prior()</a> (moved to the Boost.Iterator library)</li>
7c673cae FG	21	<li>
	22	Class <a href="../core/doc/html/core/noncopyable.html">noncopyable</a> (moved to the Boost.Core library)</li>
	23	<li>
	24	Function template <a href="../core/doc/html/core/addressof.html">addressof()</a> (moved to the Boost.Core library)</li>
	25	<li>Class template <a href="#result_of">result_of</a></li>
	26	<li>
	27	Macro <a href="#BOOST_BINARY">BOOST_BINARY</a></li>
	28	<li><a href="index.html">Other utilities not part of <code>utility.hpp</code></a></li>
	29	</ul>
	30	<h2>
7c673cae FG	31
	32	<h2><a name="result_of">Class template
	33	result_of</a></h2> <p>The class template
	34	<code>result_of</code> helps determine the type of a
	35	call expression. For example, given an lvalue <code>f</code> of
	36	type <code>F</code> and lvalues <code>t1</code>,
	37	<code>t2</code>, ..., <code>t<em>N</em></code> of
	38	types <code>T1</code>, <code>T2</code>, ...,
	39	<code>T<em>N</em></code>, respectively, the type
	40	<code>result_of<F(T1, T2, ...,
	41	T<em>N</em>)>::type</code> defines the result type
	42	of the expression <code>f(t1, t2,
	43	...,t<em>N</em>)</code>. This implementation permits
	44	the type <code>F</code> to be a function pointer,
	45	function reference, member function pointer, or class
	46	type. By default, <em>N</em> may be any value between 0 and
	47	16. To change the upper limit, define the macro
	48	<code>BOOST_RESULT_OF_NUM_ARGS</code> to the maximum
	49	value for <em>N</em>. Class template <code>result_of</code>
	50	resides in the header <code><<a
	51	href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>></code>.</p>
	52
	53	<p>If your compiler's support for <code>decltype</code> is
	54	adequate, <code>result_of</code> automatically uses it to
	55	deduce the type of the call expression, in which case
	56	<code>result_of<F(T1, T2, ...,
	57	T<em>N</em>)>::type</code> names the type
	58	<code>decltype(boost::declval<F>()(boost::declval<T1>(),
	59	boost::declval<T2>(), ...,
	60	boost::declval<T<em>N</em>>()))</code>, as in the
	61	following example.</p>
	62
	63	<blockquote>
	64	<pre>struct functor {
	65	template<class T>
	66	T operator()(T x)
	67	{
	68	return x;
	69	}
	70	};
	71
	72	typedef boost::result_of<
	73	functor(int)
	74	>::type type; // type is int</pre>
	75	</blockquote>
	76
	77	<p>You can test whether <code>result_of</code> is using
	78	<code>decltype</code> by checking if the macro
	79	<code>BOOST_RESULT_OF_USE_DECLTYPE</code> is defined after
	80	including <code>result_of.hpp</code>. You can also force
	81	<code>result_of</code> to use <code>decltype</code> by
	82	defining <code>BOOST_RESULT_OF_USE_DECLTYPE</code> prior
	83	to including <code>result_of.hpp</code>.</p>
	84
	85	<p>If <code>decltype</code> is not used,
	86	then automatic result type deduction of function
	87	objects is not possible. Instead, <code>result_of</code>
	88	uses the following protocol to allow the programmer to
	89	specify a type. When <code>F</code> is a class type with a
	90	member type <code>result_type</code>,
	91	<code>result_of<F(T1, T2, ...,
	92	T<em>N</em>)>::type</code> is
	93	<code>F::result_type</code>. When <code>F</code> does
	94	not contain <code>result_type</code>,
95	<code>result_of<F(T1, T2, ...,
96	T<em>N</em>)>::type</code> is <code>F::result<F(T1,
97	T2, ..., T<em>N</em>)>::type</code> when
98	<code><em>N</em> > 0</code> or <code>void</code>
99	when <code><em>N</em> = 0</code>. Note that it is the
100	responsibility of the programmer to ensure that
101	function objects accurately advertise their result
102	type via this protocol, as in the following
103	example.</p>
104
105	<blockquote>
106	<pre>struct functor {
107	template<class> struct result;
108
109	template<class F, class T>
110	struct result<F(T)> {
111	typedef T type;
112	};
113
114	template<class T>
115	T operator()(T x)
116	{
117	return x;
118	}
119	};
120
121	typedef boost::result_of<
122	functor(int)
123	>::type type; // type is int</pre>
124	</blockquote>
125
126	<p>Since <code>decltype</code> is a new language
127	feature recently standardized in C++11,
128	if you are writing a function object
129	to be used with <code>result_of</code>, for
130	maximum portability, you might consider following
131	the above protocol even if your compiler has
132	proper <code>decltype</code> support. If you wish to continue to
133	use the protocol on compilers that
134	support <code>decltype</code>, there are two options:
135	You can use <code>boost::tr1_result_of</code>, which is also
136	defined in <code><<a href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>></code>.
137	Alternatively, you can define the macro
138	<code>BOOST_RESULT_OF_USE_TR1</code>, which causes
139	<code>result_of</code> to use the protocol described
140	above instead of <code>decltype</code>. If you choose to
141	follow the protocol, take care to ensure that the
142	<code>result_type</code> and
143	<code>result<></code> members accurately
144	represent the return type of
145	<code>operator()</code> given a call expression.</p>
146
147	<p>Additionally, <code>boost::result_of</code>
148	provides a third mode of operation, which some users
149	may find convenient. When
150	<code>BOOST_RESULT_OF_USE_TR1_WITH_DECLTYPE_FALLBACK</code>
151	is defined, <code>boost::result_of</code> behaves as
152	follows. If the function object has a member
153	type <code>result_type</code> or member
154	template <code>result<></code>, then
155	<code>boost::result_of</code> will use the TR1
156	protocol. Otherwise,
157	<code>boost::result_of</code> will
158	use <code>decltype</code>. Using TR1 with
159	a <code>declytpe</code> fallback may workaround
160	certain problems at the cost of portability. For
161	example:
162	<ul>
163	<li>Deficient compiler: If your code
164	requires <code>boost::result_of</code> to work
165	with incomplete return types but your
166	compiler's <code>decltype</code> implementation
167	does not support incomplete return types, then you
168	can use the TR1 protocol as a workaround. Support
169	for incomplete return types was added late in the
170	C++11 standardization process
171	(see <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf">N3276</a>)
172	and is not implemented by some compilers.</li>
173
174	<li>Deficient legacy code: If your existing TR1
175	function object advertises a different type than
176	the actual result type deduced
177	by <code>decltype</code>, then using TR1 with a
178	<code>decltype</code> fallback will allow you to
179	work with both your existing TR1 function objects
180	and new C++11 function object. This situation
181	could occur if your legacy function objects
182	misused the TR1 protocol. See the documentation on
183	known <a href="#result_of_tr1_diff">differences</a>
184	between <code>boost::result_of</code> and TR1.</li>
185	</ul>
186
187	<a name="BOOST_NO_RESULT_OF"></a>
188	<p>This implementation of <code>result_of</code>
189	requires class template partial specialization, the
190	ability to parse function types properly, and support
191	for SFINAE. If <code>result_of</code> is not supported
192	by your compiler, including the header
193	<code>boost/utility/result_of.hpp</code> will
194	define the macro <code>BOOST_NO_RESULT_OF</code>.</p>
195
196	<p>For additional information
197	about <code>result_of</code>, see the C++ Library
198	Technical Report,
199	<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">N1836</a>,
200	or, for motivation and design rationale,
201	the <code>result_of</code> <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1454.html">proposal</a>.</p>
202
203	<a name="result_of_guidelines">
204	<h3>Usage guidelines for boost::result_of</h3>
205	</a>
206
207	<p>The following are general suggestions about when
208	and how to use <code>boost::result_of</code>.</p>
209
210	<ol>
211	<li> If you are targeting C++11 and are not concerned
212	about portability to non-compliant compilers or
213	previous versions of the standard, then use
214	<code>std::result_of</code>. If <code>std::result_of</code>
215	meets your needs, then there's no reason to stop using
216	it.</li>
217
218	<li> If you are targeting C++11 but may port your code
219	to legacy compilers at some time in the future, then
220	use <code>boost::result_of</code> with
221	<code>decltype</code>. When <code>decltype</code> is
222	used <code>boost::result_of</code>
223	and <code>std::result_of</code> are usually
224	interchangeable. See the documentation on
225	known <a href="#result_of_cxx11_diff">differences</a>
226	between boost::result_of and C++11 result_of.</li>
227
228	<li> If compiler portability is required,
229	use <code>boost::result_of</code> with the TR1 protocol.</li>
230	</ol>
231
232	<p>Regardless of how you
233	configure <code>boost::result_of</code>, it is
234	important to bear in mind that the return type of a
235	function may change depending on its arguments, and
236	additionally, the return type of a member function may
237	change depending on the cv-qualification of the
238	object. <code>boost::result_of</code> must be passed
239	the appropriately cv-qualified types in order to
240	deduce the corresponding return type. For example:
241
242	<blockquote>
243	<pre>struct functor {
244	int& operator()(int);
245	int const& operator()(int) const;
246
247	float& operator()(float&);
248	float const& operator()(float const&);
249	};
250
251	typedef boost::result_of<
252	functor(int)
253	>::type type1; // type1 is int &
254
255	typedef boost::result_of<
256	const functor(int)
257	>::type type2; // type2 is int const &
258
259	typedef boost::result_of<
260	functor(float&)
261	>::type type3; // type3 is float &
262
263	typedef boost::result_of<
264	functor(float const&)
265	>::type type4; // type4 is float const &</pre>
266	</blockquote>
267
268	<a name="result_of_tr1_protocol_guidelines">
269	<h3>Usage guidelines for the TR1 result_of protocol</h3>
270	</a>
271
272	<p>On compliant C++11
273	compilers, <code>boost::result_of</code> can
274	use <code>decltype</code> to deduce the type of any
275	call expression, including calls to function
276	objects. However, on pre-C++11 compilers or on
277	compilers without adequate decltype support,
278	additional scaffolding is needed from function
279	objects as described above. The following are
280	suggestions about how to use the TR1 protocol.</p>
281
282	<ul>
283	<li>When the return type does not depend on the
284	argument types or the cv-qualification of the
285	function object, simply
286	define <code>result_type</code>. There is no need
287	to use the <code>result</code> template unless the
288	return type varies.</li>
289
290	<li>Use the protocol specified type when defining
291	function prototypes. This can help ensure the
292	actual return type does not get out of sync with
293	the protocol specification. For example:
294
295	<blockquote>
296	<pre>struct functor {
297	typedef int result_type;
298	result_type operator()(int);
299	};</pre>
300	</blockquote> </li>
301
302	<li>Always specify the <code>result</code>
303	specialization near the corresponding
304	<code>operator()</code> overload. This can make it
305	easier to keep the specializations in sync with the
306	overloads. For example:
307
308	<blockquote>
309	<pre>struct functor {
310	template<class> struct result;
311
312	template<class F>
313	struct result<F(int)> {
314	typedef int& type;
315	};
316	result<functor(int)>::type operator()(int);
317
318	template<class F>
319	struct result<const F(int)> {
320	typedef int const& type;
321	};
322	result<const functor(int)>::type operator()(int) const;
323	};</pre>
324	</blockquote> </li>
325
326	<li>Use type transformations to simplify
327	the <code>result</code> template specialization. For
328	example, the following uses
329	<a href="../type_traits/doc/html/index.html">Boost.TypeTraits</a>
330	to specialize the <code>result</code> template for
331	a single <code>operator()</code> that can be called on
332	both a const and non-const function object with
333	either an lvalue or rvalue argument.
334
335	<blockquote>
336	<pre>struct functor {
337	template<class> struct result;
338
339	template<class F, class T>
340	struct result<F(T)>
341	: boost::remove_cv<
342	typename boost::remove_reference<T>::type
343	>
344	{};
345
346	template<class T>
347	T operator()(T const& x) const;
348	};</pre>
349	</blockquote></li>
350	</ul>
351
352	<a name="result_of_tr1_diff">
353	<h3>Known differences between boost::result_of and TR1 result_of</h3>
354	</a>
355
356	When using <code>decltype</code>, <code>boost::result_of</code>
357	ignores the TR1 protocol and instead deduces the
358	return type of function objects directly
359	via <code>decltype</code>. In most situations, users
360	will not notice a difference, so long as they use the
361	protocol correctly. The following are situations in
362	which the type deduced
363	by <code>boost::result_of</code> is known to differ depending on
364	whether <code>decltype</code> or the TR1 protocol is
365	used.
366
367	<ul>
368	<li> TR1 protocol misusage
369
370	<p>When using the TR1
371	protocol, <code>boost::result_of</code> cannot
372	detect whether the actual type of a call to a
373	function object is the same as the type specified
374	by the protocol, which allows for the possibility
375	of inadvertent mismatches between the specified
376	type and the actual type. When
377	using <code>decltype</code>, these subtle bugs
378	may result in compilation errors. For example:</p>
379
380	<blockquote>
381	<pre>struct functor {
382	typedef short result_type;
383	int operator()(short);
384	};
385
386	#ifdef BOOST_RESULT_OF_USE_DECLTYPE
387
388	BOOST_STATIC_ASSERT((
389	boost::is_same<boost::result_of<functor(short)>::type, int>::value
390	));
391
392	#else
393
394	BOOST_STATIC_ASSERT((
395	boost::is_same<boost::result_of<functor(short)>::type, short>::value
396	));
397
398	#endif</pre>
399	</blockquote>
400
401	<p>Note that the user can
402	force <code>boost::result_of</code> to use the TR1
403	protocol even on platforms that
404	support <code>decltype</code> by
405	defining <code>BOOST_RESULT_OF_USE_TR1</code>.</p></li>
406
407	<li> Nullary function objects
408
409	<p>When using the TR1 protocol, <code>boost::result_of</code>
410	cannot always deduce the type of calls to
411	nullary function objects, in which case the
412	type defaults to void. When using <code>decltype</code>,
413	<code>boost::result_of</code> always gives the actual type of the
414	call expression. For example:</p>
415
416	<blockquote>
417	<pre>struct functor {
418	template<class> struct result {
419	typedef int type;
420	};
421	int operator()();
422	};
423
424	#ifdef BOOST_RESULT_OF_USE_DECLTYPE
425
426	BOOST_STATIC_ASSERT((
427	boost::is_same<boost::result_of<functor()>::type, int>::value
428	));
429
430	#else
431
432	BOOST_STATIC_ASSERT((
433	boost::is_same<boost::result_of<functor()>::type, void>::value
434	));
435
436	#endif</pre>
437	</blockquote>
438
439	<p>Note that there are some workarounds for the
440	nullary function problem. So long as the return
441	type does not vary,
442	<code>result_type</code> can always be used to
443	specify the return type regardless of arity. If the
444	return type does vary, then the user can
445	specialize <code>boost::result_of</code> itself for
446	nullary calls.</p></li>
447
448	<li> Non-class prvalues and cv-qualification
449
450	<p>When using the TR1
451	protocol, <code>boost::result_of</code> will
452	report the cv-qualified type specified
453	by <code>result_type</code> or
454	the <code>result</code> template regardless of
455	the actual cv-qualification of the call
456	expression. When using
457	<code>decltype</code>, <code>boost::result_of</code>
458	will report the actual type of the call expression,
459	which is not cv-qualified when the expression is a
460	non-class prvalue. For example:</p>
461
462	<blockquote>
463	<pre>struct functor {
464	template<class> struct result;
465	template<class F, class T> struct result<F(const T)> {
466	typedef const T type;
467	};
468
469	const short operator()(const short);
470	int const & operator()(int const &);
471	};
472
473	// Non-prvalue call expressions work the same with or without decltype.
474
475	BOOST_STATIC_ASSERT((
476	boost::is_same<
477	boost::result_of<functor(int const &)>::type,
478	int const &
479	::value
480	));
481
482	// Non-class prvalue call expressions are not actually cv-qualified,
483	// but only the decltype-based result_of reports this accurately.
484
485	#ifdef BOOST_RESULT_OF_USE_DECLTYPE
486
487	BOOST_STATIC_ASSERT((
488	boost::is_same<
489	boost::result_of<functor(const short)>::type,
490	short
491	::value
492	));
493
494	#else
495
496	BOOST_STATIC_ASSERT((
497	boost::is_same<
498	boost::result_of<functor(const short)>::type,
499	const short
500	::value
501	));
502
503	#endif</pre>
504	</blockquote></li>
505	</ul>
506
507	<a name="result_of_cxx11_diff">
508	<h3>Known differences between boost::result_of and C++11 result_of</h3>
509	</a>
510
511	<p>When using <code>decltype</code>, <code>boost::result_of</code>
512	implements most of the C++11 result_of
513	specification. One known exception is that
514	<code>boost::result_of</code> does not implement the
515	requirements regarding pointers to member data.</p>
516
517	<p>Created by Doug Gregor. Contributions from Daniel Walker, Eric Niebler, Michel Morin and others</p>
518
519	<h2><a name="BOOST_BINARY">Macro BOOST_BINARY</a></h2>
520
521	<p>The macro <code>BOOST_BINARY</code> is used for the
522	representation of binary literals. It takes as an argument
523	a binary number arranged as an arbitrary amount of 1s and 0s in
524	groupings of length 1 to 8, with groups separated
525	by spaces. The type of the literal yielded is determined by
526	the same rules as those of hex and octal
527	literals (<i>2.13.1p1</i>). By implementation, this macro
528	expands directly to an octal literal during preprocessing, so
529	there is no overhead at runtime and the result is useable in
530	any place that an octal literal would be.</p>
531
532	<p>In order to directly support binary literals with suffixes,
533	additional macros of the form BOOST_BINARY_XXX are also
534	provided, where XXX is a standard integer suffix in all capital
535	letters. In addition, LL and ULL suffixes may be used for representing
536	long long and unsigned long long types in compilers which provide
537	them as an extension.</p>
538
539
540	<p>The BOOST_BINARY family of macros resides in the header
541	<a
542	href="../../boost/utility/binary.hpp"><boost/utility/binary.hpp></a>
543	which is automatically included by
544	<a
545	href="../../boost/utility.hpp"><boost/utility.hpp></a>.
546
547	<p>Contributed by Matt Calabrese.</p><p>
548	</p><h3>Example</h3>
549	<blockquote>
550	<pre>
551	void foo( int );
552
553	void foo( unsigned long );
554
555	void bar()
556	{
557	int value1 = BOOST_BINARY( 100 111000 01 1 110 );
558
559	unsigned long value2 = BOOST_BINARY_UL( 100 001 ); // unsigned long
560
561	long long value3 = BOOST_BINARY_LL( 11 000 ); // long long if supported
562
563	assert( BOOST_BINARY( 10010 )
564	& BOOST_BINARY( 11000 )
565	== BOOST_BINARY( 10000 )
566	);
567
568	foo( BOOST_BINARY( 1010 ) ); // calls the first foo
569
570	foo( BOOST_BINARY_LU( 1010 ) ); // calls the second foo
571	}
572	</pre></blockquote>
573	<hr>
574	<p>Revised  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan
575	-->04 September, 2008<!--webbot bot="Timestamp" endspan i-checksum="39369"
576	-->
577	</p>
578	<p>© Copyright Beman Dawes 1999-2003.</p>
579	<p>Distributed under the Boost Software License, Version 1.0. See
580	<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
581
582	</body>
583	</html>