Header boost/utility.hpp

The entire contents of the header <boost/utility.hpp> are in namespace boost.

Class templates supporting the base-from-member idiom
Function templates checked_delete() and checked_array_delete()
Function templates next() and prior()
Class noncopyable
Function template tie() and supporting class tied.

Function templates checked_delete() and checked_array_delete()

Deletion of a pointer to an incomplete type is an unsafe programming practice because there is no way for the compiler to verify that the destructor is indeed trivial. The checked_delete() and checked_array_delete() function templates simply delete or delete[] their argument, but also require that their argument be a complete type. They issue an appropriate compiler error diagnostic if that requirement is not met. A typical implementation is shown; other implementations may vary:

    template< typename T >
    inline void checked_delete(T const volatile * x)
    {
        BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
                                          // of instantiation
        delete x;
    }

    template< typename T >
    inline void checked_array_delete(T const volatile * x)
    {
        BOOST_STATIC_ASSERT( sizeof(T) ); // assert type complete at point
                                          // of instantiation
        delete [] x;
    }

Contributed by Beman Dawes, based on a suggestion from Dave Abrahams, generalizing an idea from Vladimir Prus, with comments from Rainer Deyke, John Maddock, and others.

Background

The C++ Standard specifies that delete on a pointer to an incomplete types is undefined behavior if the type has a non-trivial destructor in [expr.delete] 5.3.5 paragraph. No diagnostic is required. Some but not all compilers issue warnings if the type is incomplete at point of deletion.

Function templates next() and prior()

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 itr+1 inside a template restricts the iterator category to random access iterators.

The next() and prior() functions provide a simple way around these problems:

template <class T>
T next(T x) { return ++x; }

template <class X>
T prior(T x) { return --x; }

Usage is simple:

const std::list<T>::iterator p = get_some_iterator();
const std::list<T>::iterator prev = boost::prior(p);

Contributed by Dave Abrahams.

Class noncopyable

Class noncopyable is a base class. Derive your own class from noncopyable when you want to prohibit copy construction and copy assignment.

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 noncopyable will prevent the otherwise implicitly-generated functions (which don't have the proper semantics) from becoming a trap for other programmers.

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 noncopyable is simpler and clearer, and doesn't require additional documentation.

The program noncopyable_test.cpp can be used to verify class noncopyable 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.

Contributed by Dave Abrahams.

Example

// inside one of your own headers ...
#include <boost/utility.hpp>

class ResourceLadenFileSystem : boost::noncopyable {
...

Rationale

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."

Class templates for the Base-from-Member Idiom

See separate documentation.

Function template tie()