reference.rst

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

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_sequence_adapter.html>`_

    - ``ptr_vector``
    - ``ptr_list``
    - ``ptr_deque``
    - ``ptr_array`` 
    
  - ``associative_ptr_container``
 
    - `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_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_vector.html>`_
    - `ptr_list <ptr_list.html>`_ 
    - `ptr_deque <ptr_deque.html>`_
    - `ptr_array <ptr_array.html>`_
    
  - ``associative_ptr_container`` 
  
    - ``ptr_set_adapter``
    - ``ptr_multiset_adapter``
    - ``ptr_map_adapter``
    - ``ptr_multi_map_adapter`` 

      - `ptr_set <ptr_set.html>`_
      - `ptr_multi_set <ptr_multiset.html>`_ 
      - `ptr_map <ptr_map.html>`_
      - `ptr_multimap <ptr_multimap.html>`_

Serialization
+++++++++++++

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

.. __: ../../serialization/index.html

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.
   
.. __: ../../serialization/doc/rationale.html#trap

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`_.
   
.. _`Derived Classes`: ../../serialization/doc/tutorial.html#derivedclasses
            
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.
   
.. __: ../../serialization/doc/traits.html#export 
.. _`Object Tracking`: ../../serialization/doc/special.html
        
Remember these three issues and it might save you some trouble.

..
        Map iterator operations
        +++++++++++++++++++++++
        
        The map iterators are a bit different compared to the normal ones.  The 
        reason is that it is a bit clumsy to access the key and the mapped object 
        through i->first and i->second, and one tends to forget what is what. 
        Moreover, and more importantly, we also want to hide the pointer as much as possibble.
        The new style can be illustrated with a small example:: 
        
            typedef ptr_map<string,int> map_t;
            map_t  m;
            m[ "foo" ] = 4; // insert pair
            m[ "bar" ] = 5; // ditto
            ...
            for( map_t::iterator i = m.begin(); i != m.end(); ++i )
            {
                     *i += 42; // add 42 to each value
                     cout << "value=" << *i << ", key=" << i.key() << "n";
            } 
            
        So the difference from the normal map iterator is that 
        
        - ``operator*()`` returns a reference to the mapped object (normally it returns a reference to a ``std::pair``, and
        - that the key can be accessed through the ``key()`` function. 

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`__.

.. __: ../../utility/assert.html

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.

.. raw:: html 

        <hr>

**Navigate:**

- `home <ptr_container.html>`_

.. raw:: html 

        <hr>

:Copyright:     Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).

__ http://www.boost.org/LICENSE_1_0.txt