reference.rst

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

++++++++++++++++++++++++++++++++++
 |Boost| Pointer Container Library
++++++++++++++++++++++++++++++++++
 
.. |Boost| image:: boost.png

=========
Reference
=========

The documentation is divided into an explanation for 
each container. When containers have the same interface, that common interface is explained only once,
but links are always provided to more relevant information.
Please make sure you understand 
the `Clonable <reference.html#the-Clonable-concept>`_ concept and 
the `Clone Allocator <reference.html#the-clone-allocator-concept>`_ concept. 

- `Conventions <conventions.html>`_
- `The Clonable concept`_
- `The Clone Allocator concept`_

- `Class hierarchy`_:

  - `reversible_ptr_container <reversible_ptr_container.html>`_

    - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_

      - `ptr_vector <ptr_vector.html>`_
      - `ptr_list <ptr_list.html>`_ 
      - `ptr_deque <ptr_deque.html>`_
      - `ptr_array <ptr_array.html>`_
    
    - `associative_ptr_container <associative_ptr_container.html>`_ 
  
      - `ptr_set_adapter <ptr_set_adapter.html>`_
      - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
      - `ptr_map_adapter <ptr_map_adapter.html>`_
      - `ptr_multi_map_adapter <ptr_multimap_adapter.html>`_

        - `ptr_set <ptr_set.html>`_
        - `ptr_multi_set <ptr_multiset.html>`_ 
        - `ptr_map <ptr_map.html>`_
        - `ptr_multimap <ptr_multimap.html>`_
      
- `Serialization`_  
- `Indirected functions <indirect_fun.html>`_  
- `Insert iterators <ptr_inserter.html>`_
- `Class nullable`_     
- `Exception classes`_   
- `Disabling the use of exceptions`_      


..
        - Class `reversible_ptr_container <reversible_ptr_container.html>`_
        - Class `associative_ptr_container <associative_ptr_container.html>`_
        - `Pointer container adapters`_
        
          - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
          - `ptr_set_adapter <ptr_set_adapter.html>`_
          - `ptr_multiset_adapter <ptr_multiset_adapter.html>`_
          - `ptr_map_adapter <ptr_map_adapter.html>`_
          - `ptr_multimap_adapter <ptr_multimap_adapter.html>`_    
        - `Sequence containers`_
        
          - `ptr_vector <ptr_vector.html>`_
          - `ptr_deque <ptr_deque.html>`_
          - `ptr_list <ptr_list.html>`_
          - `ptr_array <ptr_array.html>`_
        - `Associative containers`_
        
          - `ptr_set <ptr_set.html>`_
          - `ptr_multiset <ptr_multiset.html>`_
          - `ptr_map <ptr_map.html>`_
          - `ptr_multimap <ptr_multimap.html>`_



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**

======================= ============================================  =================== =====================
   **Type**                **Object** (``const`` or non-``const``)        **Pointer**        **Describes**
   ``T``                  ``a``                                           ``ptr``            A Clonable type
======================= ============================================  =================== =====================       
       
**Valid expressions**

===================================== =========================== ======================================================================================== ===================================
     **Expression**                          **Type**                  **Semantics**                                                                        **Postcondition**
   ``new_clone(a);``                         ``T*``                  Allocate a new object that can be considered equivalent to the ``a`` object            ``typeid(*new_clone(a)) == typeid(a)``
   ``delete_clone(ptr);``                    ``void``                Deallocate an object previously allocated with ``allocate_clone()``. Must not throw 
===================================== =========================== ======================================================================================== ===================================


Default implementation
----------------------

In the ``<boost/ptr_container/clone_allocator.hpp>`` header a default implementation
of the two functions is given:

.. parsed-literal::

    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 );
        }
    }


Notice that this implementation  makes normal Copy Constructible classes automatically 
Clonable unless ``operator new()`` or ``operator delete()`` are hidden. 

The two functions represent a layer of indirection which is necessary to support 
classes that are not Copy Constructible by default.  Notice that the implementation 
relies on argument-dependent lookup (ADL) to find the right version of 
``new_clone()`` and ``delete_clone()``. This means that one does not need to overload or specialize 
the function in the boost namespace, but it can be placed together with 
the rest of the interface of the class.  If you are implementing a class 
inline in headers, remember to forward declare the functions.
 
**Warning: We are considering the removal of default implementation above. Therefore always make sure that you overload the functions for your types and do not rely on the defaults in any way.**  

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:

..  contents:: :depth: 1 
               :local: 


Clone Allocator requirements
----------------------------

**Notation**

===================== ============================================= ==================================================
   **Type**               **Object** (``const`` or non-``const``)                 **Describes**
       ``T``                 ``a``                                   A type
       ``T*``                ``ptr``                                 A pointer to ``T`` 
===================== ============================================= ==================================================

**Valid expressions**

============================================== ============= ============================================================================= =============================================================
     **Expression**                              **Type**                              **Semantics**                                                                  **Postcondition**
  ``CloneAllocator::allocate_clone(a);``          ``T*``             Allocate a new object that can be considered equivalent to the 
                                                                     ``a`` object                                                          ``typeid(*CloneAllocator::allocate_clone(a)) == typeid(a)``
  ``CloneAllocator::deallocate_clone(ptr);``     ``void``            Deallocate an object previously allocated with 
                                                                     ``CloneAllocator::allocate_clone()`` or a compatible allocator. 
                                                                     Must not throw.
============================================== ============= ============================================================================= =============================================================



The library comes with two predefined clone allocators.

Class ``heap_clone_allocator``
------------------------------

This is the default clone allocator used by all pointer containers. For most
purposes you will never have to change this default. 

**Definition**

.. parsed-literal::

    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 );
            }
        };
    }

Notice that the above definition allows you to support custom allocation
schemes by relying on ``new_clone()`` and ``delete_clone()``.
   
Class ``view_clone_allocator``
------------------------------

This class provides a way to remove ownership properties of the
pointer containers. As its name implies, this means that you can
instead use the pointer containers as a view into an existing
container.

**Definition**
 
.. parsed-literal::

    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
            }
        };
    }

.. **See also**

  - `Changing the clone allocator <examples.html#changing-the-clone-allocator>`_

Class hierarchy
+++++++++++++++