2000-07-27 13:38:51 +00:00
< html >
2002-11-14 14:53:32 +00:00
< 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" >
2004-10-05 15:45:52 +00:00
< h1 > < img src = "../../boost.png" alt = "boost.png (6897 bytes)" align = "center" WIDTH = "277" HEIGHT = "86" > Header
2002-11-14 14:53:32 +00:00
< 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 = "base_from_member.html" > base-from-member
idiom< / a > < / li >
< li >
Function templates < a href = "#checked_delete" > checked_delete() and
checked_array_delete()< / a > < / li >
< li >
2003-01-09 13:03:37 +00:00
Function templates < a href = "#functions_next_prior" > next() and prior()< / a > < / li >
2002-11-14 14:53:32 +00:00
< li >
2003-01-09 13:03:37 +00:00
Class < a href = "#Class_noncopyable" > noncopyable< / a > < / li >
2002-11-14 14:53:32 +00:00
< li >
Function template < a href = "#addressof" > addressof()< / a > < / li >
2004-05-02 19:55:02 +00:00
< li > Class template < a href = "#result_of" > result_of< / a > < / li >
2002-11-14 14:53:32 +00:00
< / ul >
< h2 >
Function templates < a name = "checked_delete" > checked_delete< / a > () and
checked_array_delete()< / h2 >
< p > See < a href = "checked_delete.html" > separate documentation< / a > .< / p >
< h2 >
2003-01-09 13:03:37 +00:00
< a name = "functions_next_prior" > Function< / a > templates next() and prior()< / h2 >
2002-11-14 14:53:32 +00:00
< 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>
2000-07-27 13:38:51 +00:00
T next(T x) { return ++x; }
2003-12-23 14:59:59 +00:00
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 >
2002-11-14 14:53:32 +00:00
< / blockquote >
< p > Usage is simple:< / p >
< blockquote >
< pre > const std::list< T> ::iterator p = get_some_iterator();
2003-12-23 14:59:59 +00:00
const std::list< T> ::iterator prev = boost::prior(p);
const std::list< T> ::iterator next = boost::next(prev, 2);< / pre >
2002-11-14 14:53:32 +00:00
< / blockquote >
2003-12-23 14:59:59 +00:00
< 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 = "../../people/dave_abrahams.htm" > Dave Abrahams< / a > . Two-argument versions by Daniel Walker.< / p >
2003-01-09 13:03:37 +00:00
< h2 > < a name = "Class_noncopyable" > Class noncopyable< / a > < / h2 >
2002-11-14 14:53:32 +00:00
< p > Class < strong > noncopyable< / strong > is a base class. Derive your own class
from < strong > noncopyable< / strong > when you want to prohibit copy construction
and copy assignment.< / p >
< p > Some objects, particularly those which hold complex resources like files or
network connections, have no sensible copy semantics. Sometimes there are
possible copy semantics, but these would be of very limited usefulness and be
very difficult to implement correctly. Sometimes you're implementing a
class that doesn't need to be copied just yet and you don't want to take the
time to write the appropriate functions. Deriving from < b > noncopyable< / b >
will prevent the otherwise implicitly-generated functions (which don't have the
proper semantics) from becoming a trap for other programmers.< / p >
< p > The traditional way to deal with these is to declare a private copy constructor
and copy assignment, and then document why this is done. But deriving
from < b > noncopyable< / b > is simpler and clearer, and doesn't require additional
documentation.< / p >
< p > The program < a href = "noncopyable_test.cpp" > noncopyable_test.cpp< / a > can be used
to verify class < b > noncopyable< / b > works as expected. It has have been run
successfully under GCC 2.95, Metrowerks CodeWarrior 5.0, and Microsoft Visual
C++ 6.0 sp 3.< / p >
< p > Contributed by < a href = "../../people/dave_abrahams.htm" > Dave Abrahams< / a > .< / p >
< h3 > Example< / h3 >
< blockquote >
< pre > // inside one of your own headers ...
2000-07-27 13:38:51 +00:00
#include < boost/utility.hpp>
2001-02-14 20:35:39 +00:00
class ResourceLadenFileSystem : boost::noncopyable {
2000-07-27 13:38:51 +00:00
...< / pre >
2002-11-14 14:53:32 +00:00
< / blockquote >
< h3 > Rationale< / h3 >
< p > Class noncopyable has protected constructor and destructor members to emphasize
that it is to be used only as a base class. Dave Abrahams notes concern
about the effect on compiler optimization of adding (even trivial inline)
destructor declarations. He says " Probably this concern is misplaced,
because noncopyable will be used mostly for classes which own resources and
thus have non-trivial destruction semantics." < / p >
< h2 > < a name = "addressof" > Function template addressof()< / a > < / h2 >
< p > Function < strong > addressof()< / strong > returns the address of an object.< / p >
< blockquote >
2003-01-09 13:03:37 +00:00
< pre > template < typename T> inline T* addressof(T& v);
2002-04-10 03:31:18 +00:00
template < typename T> inline const T* addressof(const T& v);
template < typename T> inline volatile T* addressof(volatile T& v);
template < typename T> inline const volatile T* addressof(const volatile T& v);
< / pre >
2002-11-14 14:53:32 +00:00
< / blockquote >
< p > C++ allows programmers to replace the unary < strong > operator& ()< / strong > class
member used to get the address of an object. Getting the real address of an
object requires ugly casting tricks to avoid invoking the overloaded < strong > operator& ()< / strong > .
Function < strong > addressof()< / strong > provides a wrapper around the necessary
code to make it easy to get an object's real address.
< / p >
< p > The program < a href = "addressof_test.cpp" > addressof_test.cpp< / a > can be used to
verify that < b > addressof()< / b > works as expected.< / p >
< p > Contributed by Brad King based on ideas from discussion with Doug Gregor.< / p >
< h3 > Example< / h3 >
< blockquote >
< pre > #include < boost/utility.hpp>
2002-04-10 03:31:18 +00:00
struct useless_type {};
class nonaddressable {
useless_type operator& () const;
};
void f() {
nonaddressable x;
nonaddressable* xp = boost::addressof(x);
// nonaddressable* xpe = & x; /* error */
}< / pre >
2002-11-14 14:53:32 +00:00
< / blockquote >
2004-05-02 19:55:02 +00:00
< 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. 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 > . The implementation permits
the type < code > F< / code > to be a function pointer,
function reference, member function pointer, or class
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 > )> < / code > is
< code > F::result_type< / code > . Otherwise,
< code > result_of< F(T1, T2, ...,
T< em > N< / em > )> < / 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 > . For additional
information about < code > result_of< / code > , see the
current draft of the C++ Library TR, < a
href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2004/n1647.pdf">N1647< / a > ,
or the < code > result_of< / code > < a
href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1454.html">proposal< / a > .< / p >
< p > 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 > . By
default, < em > N< / em > may be any value between 0 and
10. To change the upper limit, define the macro
< code > BOOST_RESULT_OF_NUM_ARGS< / code > to the maximum
value for < em > N< / em > .< / p >
< p > This implementation of < code > result_of< / code > requires class template partial specialization, the ability to parse function types properly, and support for SFINAE. Contributed by Doug Gregor.< / p >
2002-11-14 14:53:32 +00:00
< h2 > Class templates for the Base-from-Member Idiom< / h2 >
< p > See < a href = "base_from_member.html" > separate documentation< / a > .< / p >
< hr >
< p > Revised <!-- webbot bot="Timestamp" S - Type="EDITED" S - Format="%d %B, %Y" startspan
2004-05-02 19:55:02 +00:00
-->02 May, 2004<!-- webbot bot="Timestamp" endspan i - checksum="38582"
2000-07-27 13:38:51 +00:00
-->
2002-11-14 14:53:32 +00:00
< / p >
2003-09-01 21:04:26 +00:00
< p > © Copyright boost.org 1999-2003. Permission to copy, use, modify, sell and distribute
2002-11-14 14:53:32 +00:00
this document is granted provided this copyright notice appears in all copies.
This document is provided " as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.< / p >
< / body >
2003-09-01 21:04:26 +00:00
< / html >
