Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / a57b70145cb0a950c1c3a9a4fddf0438c60126f2 / . / third_party / boostorg / utility / utility.htm
blob: 711b58c2601f05de4c78612e012eeb8200b8fb5f [file] [log] [blame]
Brian Silverman60e3e2a2018-08-04 23:57:12 -0700[diff] [blame]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">&lt;boost/utility.hpp&gt;</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&lt;F(T1, T2, ...,
41 T<em>N</em>)&gt;::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>&lt;<a
51 href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>&gt;</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&lt;F(T1, T2, ...,
57 T<em>N</em>)&gt;::type</code> names the type
58 <code>decltype(boost::declval&lt;F&gt;()(boost::declval&lt;T1&gt;(),
59 boost::declval&lt;T2&gt;(), ...,
60 boost::declval&lt;T<em>N</em>&gt;()))</code>, as in the
61 following example.</p>
62
63 <blockquote>
64 <pre>struct functor {
65 template&lt;class T&gt;
66 T operator()(T x)
67 {
68 return x;
69 }
70};
71
72typedef boost::result_of&lt;
73 functor(int)
74&gt;::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&lt;F(T1, T2, ...,
92 T<em>N</em>)&gt;::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&lt;F(T1, T2, ...,
96 T<em>N</em>)&gt;::type</code> is <code>F::result&lt;F(T1,
97 T2, ..., T<em>N</em>)&gt;::type</code> when
98 <code><em>N</em> &gt; 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&lt;class&gt; struct result;
108
109 template&lt;class F, class T&gt;
110 struct result&lt;F(T)&gt; {
111 typedef T type;
112 };
113
114 template&lt;class T&gt;
115 T operator()(T x)
116 {
117 return x;
118 }
119};
120
121typedef boost::result_of&lt;
122 functor(int)
123&gt;::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>&lt;<a href="../../boost/utility/result_of.hpp">boost/utility/result_of.hpp</a>&gt;</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&lt;&gt;</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&lt;&gt;</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&lt;
252 functor(int)
253&gt;::type type1; // type1 is int &
254
255typedef boost::result_of&lt;
256 const functor(int)
257&gt;::type type2; // type2 is int const &
258
259typedef boost::result_of&lt;
260 functor(float&)
261&gt;::type type3; // type3 is float &
262
263typedef boost::result_of&lt;
264 functor(float const&)
265&gt;::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&lt;class&gt; struct result;
311
312 template&lt;class F&gt;
313 struct result&lt;F(int)&gt; {
314 typedef int& type;
315 };
316 result&lt;functor(int)&gt;::type operator()(int);
317
318 template&lt;class F&gt;
319 struct result&lt;const F(int)&gt; {
320 typedef int const& type;
321 };
322 result&lt;const functor(int)&gt;::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&lt;class&gt; struct result;
338
339 template&lt;class F, class T&gt;
340 struct result&lt;F(T)&gt;
341 : boost::remove_cv&lt;
342 typename boost::remove_reference&lt;T&gt;::type
343 &gt;
344 {};
345
346 template&lt;class T&gt;
347 T operator()(T const&amp; 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&lt;boost::result_of&lt;functor(short)&gt;::type, int&gt;::value
390));
391
392#else
393
394BOOST_STATIC_ASSERT((
395 boost::is_same&lt;boost::result_of&lt;functor(short)&gt;::type, short&gt;::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&lt;class&gt; 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&lt;boost::result_of&lt;functor()&gt;::type, int&gt;::value
428));
429
430#else
431
432BOOST_STATIC_ASSERT((
433 boost::is_same&lt;boost::result_of&lt;functor()&gt;::type, void&gt;::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&lt;class&gt; struct result;
465 template&lt;class F, class T&gt; struct result&lt;F(const T)&gt; {
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&lt;
477 boost::result_of&lt;functor(int const &)&gt;::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&lt;
489 boost::result_of&lt;functor(const short)&gt;::type,
490 short
491::value
492));
493
494#else
495
496BOOST_STATIC_ASSERT((
497 boost::is_same&lt;
498 boost::result_of&lt;functor(const short)&gt;::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">&lt;boost/utility/binary.hpp&gt;</a>
543 which is automatically included by
544 <a
545 href="../../boost/utility.hpp">&lt;boost/utility.hpp&gt;</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&nbsp; <!--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>&copy; 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>