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> 20 Function templates <a href="../iterator/doc/html/iterator/algorithms/next_prior.html">next() and prior()</a> (moved to the Boost.Iterator library)</li> 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> 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 72typedef 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 121typedef 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 251typedef boost::result_of< 252 functor(int) 253>::type type1; // type1 is int & 254 255typedef boost::result_of< 256 const functor(int) 257>::type type2; // type2 is int const & 258 259typedef boost::result_of< 260 functor(float&) 261>::type type3; // type3 is float & 262 263typedef 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 388BOOST_STATIC_ASSERT(( 389 boost::is_same<boost::result_of<functor(short)>::type, int>::value 390)); 391 392#else 393 394BOOST_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 426BOOST_STATIC_ASSERT(( 427 boost::is_same<boost::result_of<functor()>::type, int>::value 428)); 429 430#else 431 432BOOST_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 475BOOST_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 487BOOST_STATIC_ASSERT(( 488 boost::is_same< 489 boost::result_of<functor(const short)>::type, 490 short 491::value 492)); 493 494#else 495 496BOOST_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> 551void foo( int ); 552 553void foo( unsigned long ); 554 555void 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> 584
