3 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1">
4 <title>Header boost/utility.hpp Documentation
</title>
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>
14 Class templates supporting the
<a href=
"doc/html/base_from_member.html">
15 base-from-member idiom
</a></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>
20 Function templates
<a href=
"../iterator/doc/html/iterator/algorithms/next_prior.html">next() and prior()
</a> (moved to the Boost.Iterator library)
</li>
22 Class
<a href=
"../core/doc/html/core/noncopyable.html">noncopyable
</a> (moved to the Boost.Core library)
</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>
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>
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>
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>
65 template
<class T
>
72 typedef boost::result_of
<
74 >::type type; // type is int
</pre>
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>
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
106 <pre>struct functor {
107 template
<class
> struct result;
109 template
<class F, class T
>
110 struct result
<F(T)
> {
114 template
<class T
>
121 typedef boost::result_of
<
123 >::type type; // type is int
</pre>
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>
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
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
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>
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>
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>
196 <p>For additional information
197 about
<code>result_of
</code>, see the C++ Library
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>
203 <a name=
"result_of_guidelines">
204 <h3>Usage guidelines for boost::result_of
</h3>
207 <p>The following are general suggestions about when
208 and how to use
<code>boost::result_of
</code>.
</p>
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
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>
228 <li> If compiler portability is required,
229 use
<code>boost::result_of
</code> with the TR1 protocol.
</li>
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:
243 <pre>struct functor {
244 int& operator()(int);
245 int const& operator()(int) const;
247 float& operator()(float&);
248 float const& operator()(float const&);
251 typedef boost::result_of
<
253 >::type type1; // type1 is int &
255 typedef boost::result_of
<
257 >::type type2; // type2 is int const &
259 typedef boost::result_of
<
261 >::type type3; // type3 is float &
263 typedef boost::result_of
<
264 functor(float const&)
265 >::type type4; // type4 is float const &
</pre>
268 <a name=
"result_of_tr1_protocol_guidelines">
269 <h3>Usage guidelines for the TR1 result_of protocol
</h3>
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>
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>
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:
296 <pre>struct functor {
297 typedef int result_type;
298 result_type operator()(int);
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:
309 <pre>struct functor {
310 template
<class
> struct result;
312 template
<class F
>
313 struct result
<F(int)
> {
316 result
<functor(int)
>::type operator()(int);
318 template
<class F
>
319 struct result
<const F(int)
> {
320 typedef int const& type;
322 result
<const functor(int)
>::type operator()(int) const;
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.
336 <pre>struct functor {
337 template
<class
> struct result;
339 template
<class F, class T
>
340 struct result
<F(T)
>
341 : boost::remove_cv
<
342 typename boost::remove_reference
<T
>::type
346 template
<class T
>
347 T operator()(T const
& x) const;
352 <a name=
"result_of_tr1_diff">
353 <h3>Known differences between boost::result_of and TR1 result_of
</h3>
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
368 <li> TR1 protocol misusage
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>
381 <pre>struct functor {
382 typedef short result_type;
383 int operator()(short);
386 #ifdef BOOST_RESULT_OF_USE_DECLTYPE
388 BOOST_STATIC_ASSERT((
389 boost::is_same
<boost::result_of
<functor(short)
>::type, int
>::value
394 BOOST_STATIC_ASSERT((
395 boost::is_same
<boost::result_of
<functor(short)
>::type, short
>::value
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>
407 <li> Nullary function objects
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>
417 <pre>struct functor {
418 template
<class
> struct result {
424 #ifdef BOOST_RESULT_OF_USE_DECLTYPE
426 BOOST_STATIC_ASSERT((
427 boost::is_same
<boost::result_of
<functor()
>::type, int
>::value
432 BOOST_STATIC_ASSERT((
433 boost::is_same
<boost::result_of
<functor()
>::type, void
>::value
439 <p>Note that there are some workarounds for the
440 nullary function problem. So long as the return
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>
448 <li> Non-class prvalues and cv-qualification
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>
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;
469 const short operator()(const short);
470 int const & operator()(int const &);
473 // Non-prvalue call expressions work the same with or without decltype.
475 BOOST_STATIC_ASSERT((
477 boost::result_of
<functor(int const &)
>::type,
482 // Non-class prvalue call expressions are not actually cv-qualified,
483 // but only the decltype-based result_of reports this accurately.
485 #ifdef BOOST_RESULT_OF_USE_DECLTYPE
487 BOOST_STATIC_ASSERT((
489 boost::result_of
<functor(const short)
>::type,
496 BOOST_STATIC_ASSERT((
498 boost::result_of
<functor(const short)
>::type,
507 <a name=
"result_of_cxx11_diff">
508 <h3>Known differences between boost::result_of and C++
11 result_of
</h3>
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>
517 <p>Created by Doug Gregor. Contributions from Daniel Walker, Eric Niebler, Michel Morin and others
</p>
519 <h2><a name=
"BOOST_BINARY">Macro BOOST_BINARY
</a></h2>
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>
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>
540 <p>The BOOST_BINARY family of macros resides in the header
542 href=
"../../boost/utility/binary.hpp"><boost/utility/binary.hpp
></a>
543 which is automatically included by
545 href=
"../../boost/utility.hpp"><boost/utility.hpp
></a>.
547 <p>Contributed by Matt Calabrese.
</p><p>
553 void foo( unsigned long );
557 int value1 = BOOST_BINARY(
100 111000 01 1 110 );
559 unsigned long value2 = BOOST_BINARY_UL(
100 001 ); // unsigned long
561 long long value3 = BOOST_BINARY_LL(
11 000 ); // long long if supported
563 assert( BOOST_BINARY(
10010 )
564 & BOOST_BINARY(
11000 )
565 == BOOST_BINARY(
10000 )
568 foo( BOOST_BINARY(
1010 ) ); // calls the first foo
570 foo( BOOST_BINARY_LU(
1010 ) ); // calls the second foo
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"
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>