The Clonable concept

Refinement of

• Heap Allocable
• Heap Deallocable

The Clonable concept is introduced to formalize the requirements for copying heap-allocated objects. A type T might be Clonable even though it is not Assignable or Copy Constructible. Notice that many operations on the containers do not even require the stored type to be Clonable.

Notation

Valid expressions

namespace boost
{
    template< class T >
    inline T* new_clone( const T& t )
    {
        return new T( t );
    }

    template< class T >
    void delete_clone( const T* t )
    {
        checked_delete( t );
    }
}

The Clone Allocator concept

The Clone Allocator concept is introduced to formalize the way pointer containers control memory of the stored objects (and not the pointers to the stored objects). The clone allocator allows users to apply custom allocators/deallocators for the cloned objects.

More information can be found below:

namespace boost
{        
    struct heap_clone_allocator
    {
        template< class U >
        static U* allocate_clone( const U& r )
        {
            return new_clone( r );
        }

        template< class U >
        static void deallocate_clone( const U* r )
        {
            delete_clone( r );
        }
    };
}

namespace boost
{
    struct view_clone_allocator
    {
        template< class U >
        static U* allocate_clone( const U& r )
        {
            return const_cast<U*>(&r);
        }

        template< class U >
        static void deallocate_clone( const U* )
        {
            // empty
        }
    };
}

Class hierarchy

The library consists of the following types of classes:

1. Pointer container adapters

2. Pointer containers

The pointer container adapters are used when you want to make a pointer container starting from your own "normal" container. For example, you might have a map class that extends std::map in some way; the adapter class then allows you to use your map class as a basis for a new pointer container.

The library provides an adapter for each type of standard container highlighted as links below:

• reversible_ptr_container
  • ptr_sequence_adapter
    • ptr_vector
    • ptr_list
    • ptr_deque
    • ptr_array
  • associative_ptr_container
    • ptr_set_adapter
    • ptr_multiset_adapter
    • ptr_map_adapter
    • ptr_multi_map_adapter
      • ptr_set
      • ptr_multi_set
      • ptr_map
      • ptr_multimap

The pointer containers of this library are all built using the adapters. There is a pointer container for each type of "normal" standard container highlighted as links below.

• reversible_ptr_container
  • ptr_sequence_adapter
    • ptr_vector
    • ptr_list
    • ptr_deque
    • ptr_array
  • associative_ptr_container
    • ptr_set_adapter
    • ptr_multiset_adapter
    • ptr_map_adapter
    • ptr_multi_map_adapter
      • ptr_set
      • ptr_multi_set
      • ptr_map
      • ptr_multimap

Serialization

As of version 1.34.0 of Boost, the library supports serialization via Boost.Serialization.

Of course, for serialization to work it is required that the stored type itself is serializable. For maps, both the key type and the mapped type must be serializable.

When dealing with serialization (and serialization of polymophic objects in particular), pay special attention to these parts of Boost.Serialization:

1. Output/saving requires a const-reference:

   //
   // serialization helper: we can't save a non-const object
   // 
   template< class T >
   inline T const& as_const( T const& r )
   {
       return r;
   }
   ...
   Container cont;
   
   std::ofstream ofs("filename");
   boost::archive::text_oarchive oa(ofs);
   oa << as_const(cont);
   

   See Compile time trap when saving a non-const value for details.

2. Derived classes need to call base_object() function:

   struct Derived : Base
   {
       template< class Archive >
       void serialize( Archive& ar, const unsigned int version )
       {
           ar & boost::serialization::base_object<Base>( *this );
           ...
       }   
   };
   

   For details, see Derived Classes.

3. You need to use BOOST_CLASS_EXPORT to register the derived classes in your class hierarchy:

   BOOST_CLASS_EXPORT( Derived )
   

   See Export Key and Object Tracking for details.

Remember these three issues and it might save you some trouble.

Class nullable

The purpose of the class is simply to tell the containers that null values should be allowed. Its definition is trivial:

namespace boost
{
    template< class T >
    struct nullable
    {
        typedef T type;
    };  
}

Please notice that nullable has no effect on the containers interface (except for is_null() functions). For example, it does not make sense to do

boost::ptr_vector< boost::nullable<T> > vec;
vec.push_back( 0 );                      // ok
vec.push_back( new boost::nullable<T> ); // no no!
boost::nullable<T>& ref = vec[0];        // also no no!

Exception classes

There are three exceptions that are thrown by this library. The exception hierarchy looks as follows:

namespace boost
{
    class bad_ptr_container_operation : public std::exception
    {
    public:
        bad_ptr_container_operation( const char* what );
    };
    
    class bad_index : public bad_ptr_container_operation
    {
    public:
        bad_index( const char* what );
    };

    class bad_pointer : public bad_ptr_container_operation
    {
    public:
        bad_pointer();
        bad_pointer( const char* what );
    };
}

Disabling the use of exceptions

As of version 1.34.0 of Boost, the library allows you to disable exceptions completely. This means the library is more fit for domains where exceptions are not used. Furthermore, it also speeds up a operations a little. Instead of throwing an exception, the library simply calls BOOST_ASSERT.

To disable exceptions, simply define this macro before including any header:

#define BOOST_PTR_CONTAINER_NO_EXCEPTIONS 1
#include <boost/ptr_container/ptr_vector.hpp>

It is, however, recommended that you define the macro on the command-line, so you are absolutely certain that all headers are compiled the same way. Otherwise you might end up breaking the One Definition Rule.

If BOOST_NO_EXCEPTIONS is defined, then BOOST_PTR_CONTAINER_NO_EXCEPTIONS is also defined.

Navigate:

• home