1. Null pointers cannot be stored in the containers

my_container.push_back( 0 );            // throws bad_ptr 
my_container.replace( an_iterator, 0 ); // throws bad_ptr
my_container.insert( an_iterator, 0 );  // throws bad_ptr       
std::auto_ptr<T> p( 0 );
my_container.push_back( p );            // throws bad_ptr                                                          

2. Iterators and other operations return indirected values

ptr_vector<X> pvec; 
std::vector<X*> vec;
*vec.begin()  = new X;   // fine, memory leak
*pvec.begin() = new X;   // compile time error
( *vec.begin() )->foo(); // call X::foo(), a bit clumsy
pvec.begin()->foo();     // no indirection needed
*vec.front()  = X();     // overwrite first element
pvec.front()  = X();     // no indirection needed

3. Copy-semantics of pointer containers

ptr_vector<T> vec1; 
...
ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive
vec2 = vec1.release();              // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap
vec2.release();                     // give up ownership; the objects will be deallocated if not assigned to another container
vec1 = vec2;                        // compile time error: 'operator=()' not defined 
ptr_vector<T> vec3( vec1 );         // compile time error: copy-constructor not defined 

4. Making a non-copyable type Clonable

 // a class that has no normal copy semantics
class X : boost::noncopyable { public: X* clone() const; ... };
                                                                   
// this will be found by the library by argument dependent lookup (ADL)                                                                  
X* new_clone( const X& x ) 
{ return x.clone(); }
                                                                   
// we can now use the interface that requires clonability
ptr_vector<X> vec1, vec2;
...
vec2 = vec1.clone();                                 // 'clone()' requires cloning <g> 
vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones 

5. Objects are cloned before insertion, inserted pointers are owned by the container

class X { ... };                     // assume 'X' is Clonable 
X x;                                 // and 'X' can be stack-allocated 
ptr_list<X> list; 
list.push_back( new_clone( x ) );    // insert a clone
list.push_back( new X );             // always give the pointer directly to the container to avoid leaks
list.push_back( &x );                // don't do this!!! 
std::auto_ptr<X> p( new X );
list.push_back( p );                 // give up ownership
BOOST_ASSERT( p.get() == 0 );

6. Transferring ownership of a single element

ptr_deque<T>                    deq; 
typedef ptr_deque<T>::auto_type auto_type;

// ... fill the container somehow

auto_type ptr  = deq.release_back();             // remove back element from container and give up ownership
auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release
ptr            = deq.release_front();            // supported for 'ptr_list' and 'ptr_deque'
                                
deq.push_back( ptr.release() );                  // give ownership back to the container

7. Transferring ownership of pointers between different pointer containers

ptr_list<X> list; ptr_vector<X> vec;
...
//
// note: no cloning happens in these examples                                
//
list.transfer( list.begin(), vec.begin(), vec );           // make the first element of 'vec' the first element of 'list'
vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector                                 

We can also transfer objects from ptr_container<Derived> to ptr_container<Base without any problems.

8. Selected test files

9. A large example

This examples shows many of the most common features at work. The example provide lots of comments.