Pointer Container Library

Overview

Boost.Pointer Container provides containers for holding heap-allocated objects in an exception-safe manner and with minimal overhead. The aim of the library is in particular to make OO programming easier in C++ by establishing a standard set of classes, methods and designs for dealing with OO specific problems

• Motivation

• Tutorial

• Reference

• Usage guidelines

• Examples

• Library headers

• FAQ

• Upgrading from Boost v. 1.33.*

• Acknowledgements

• References

Motivation

Whenever a programmer wants to have a container of pointers to heap-allocated objects, there is usually only one exception-safe way: to make a container of smart pointers like boost::shared_ptr This approach is suboptimal if:

1. the stored objects are not shared, but owned exclusively, or

2. the overhead implied by smart pointers is inappropriate

This library therefore provides standard-like containers that are for storing heap-allocated or cloned objects (or in case of a map, the mapped object must be a heap-allocated or cloned object). For each of the standard containers there is a pointer container equivalent that takes ownership of the objects in an exception safe manner. In this respect the library is intended to solve the so-called polymorphic class problem.

The advantages of pointer containers are:

1. Exception-safe pointer storage and manipulation.

2. Notational convenience compared to the use of containers of pointers.

3. Can be used for types that are neither Assignable nor Copy Constructible.

4. No memory-overhead as containers of smart pointers can have (see [11] and [12]).

5. Usually faster than using containers of smart pointers (see [11] and [12]).

6. The interface is slightly changed towards the domain of pointers instead of relying on the normal value-based interface. For example, it is possible for pop_back() to return the removed element.

7. Propagates constness s.t. one cannot modify the objects via a const_iterator.

8. Built-in support for deep-copy semantics via the The Clobable Concept

The disadvantages are:

1. Less flexible than containers of smart pointers like boost::shared_ptr

The user does not need this library when shared semantics are required.

Upgrading from Boost v. 1.33.*

If the user upgrades from one of these versions of Boost, then there has been one major interface change: map iterators now mimic iterators from std::map. Previously, the user may have written:

for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end();
     i != e; ++i )
{
  std::cout << "key:" << i.key();
  std::cout << "value:" << *i;
  i->foo(); // call T::foo()
}

This needs to be converted into:

for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end();
     i != e; ++i )
{
  std::cout << "key:" << i->first;
  std::cout << "value:" << *i->second;
  i->second->foo(); // call T::foo()
}

Apart from the above change, the library now also introduces

• std::auto_ptr<T> overloads:

  std::auto_ptr<T> p( new T );
  container.push_back( p );
  

• Derived-to-Base conversion in transfer():

  boost::ptr_vector<Base>  vec;
  boost::ptr_list<Derived> list;
  ...
  vec.transfer( vec.begin(), list ); // now ok
  

Also note that Boost.Assign introduces better support for pointer containers.

Acknowledgements

The following people have been very helpful:

• Bjørn D. Rasmussen for unintentionally motivating me to start this library

• Pavel Vozenilek for asking me to make the adapters

• David Abrahams for the indirect_fun design

• Pavol Droba for being review manager

• Ross Boylan for trying out a prototype for real

• Felipe Magno de Almeida for giving feedback based on using the library in production code even before the library was part of boost

• Jonathan Turkanis for supplying his move_ptr framework which is used internally

• Stefan Slapeta and Howard Hinnant for Metrowerks support

• Russell Hind for help with Borland compatibility

• Jonathan Wakely for his great help with GCC compatibility and bug fixes

• Pavel Chikulaev for comments and bug-fixes

• Andreas Hommel for fixing the nasty Metrowerks bug

References