boost-react-native-bundle

<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="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="#functions_next_prior">next() and prior()</a></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> <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="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<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 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'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>struct functor { template<class T> T operator()(T x) { return x; } }; typedef boost::result_of< functor(int) >::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<F(T1, T2, ..., 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>)>::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 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; // 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><<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> 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< 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><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  04 September, 2008 </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>