boost/libs/ptr_container/doc/ptr_map_adapter.rst

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

Class ``ptr_map_adapter``
-------------------------

This class is used to build custom pointer containers with
an underlying map-like container. The interface of the class is an extension
of the interface from ``associative_ptr_container``.

**Hierarchy:**

- `reversible_ptr_container <reversible_ptr_container.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_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>`_
      
**Navigate:**

- `home <ptr_container.html>`_
- `reference <reference.html>`_

**Synopsis:**

.. parsed-literal::

                     
        namespace boost
        {
            template
            < 
                class T,
                class VoidPtrMap, 
                class CloneAllocator = heap_clone_allocator 
            >
            class ptr_map_adapter 
            {
	    public: // `typedefs`_
		typedef VoidPtrMap::key_type key_type;
		typedef T*                   mapped_type;
		typedef T&                   mapped_reference;
		typedef const T&             const_mapped_reference;
		typedef ...                  value_type;
		typedef ...                  reference;
		typedef ...                  const_reference;
		typedef ...                  pointer;
		typedef ...                  const_pointer;  
                
            public: // `modifiers`_         
                std::pair<iterator,bool>  insert( key_type& k, T* x );                         
		template< class U >
		std::pair<iterator,bool>  insert( const key_type& k, compatible-smart-ptr<U> x );                         

            public; // `lookup`_
                T&       operator[]( const key_type& key );
                T&       at( const key_type& key );
                const T& at( const key_type& key ) const;
                
            public: // `pointer container requirements`_
                bool      transfer( iterator object, ptr_map_adapter& from );
                size_type transfer( iterator first, iterator last, ptr_map_adapter& from );
                template< class Range >
                size_type transfer( const Range& r, ptr_map_adapter& from );
                size_type transfer( ptr_map_adapter& from );
                    
            }; //  class 'ptr_map_adapter'
        
        } // namespace 'boost'  

            
Semantics
---------

.. _`typedefs`:

Semantics: typedefs
^^^^^^^^^^^^^^^^^^^

The following types are implementation defined::

	typedef ... value_type;
	typedef ... reference;
	typedef ... const_reference;
	typedef ... pointer;
	typedef ... const_pointer;  
        
However, the structure of the type mimics ``std::pair`` s.t. one
can use ``first`` and ``second`` members. The reference-types
are not real references and the pointer-types are not real pointers.
However, one may still write ::

    map_type::value_type       a_value      = *m.begin();
    a_value.second->foo();
    map_type::reference        a_reference  = *m.begin();
    a_reference.second->foo();
    map_type::const_reference  a_creference = *const_begin(m);
    map_type::pointer          a_pointer    = &*m.begin();
    a_pointer->second->foo();
    map_type::const_pointer    a_cpointer   = &*const_begin(m);

The difference compared to ``std::map<Key,T*>`` is that constness
is propagated to the pointer (that is, to ``second``) in ``const_itertor``. 	

.. _`modifiers`:

Semantics: modifiers
^^^^^^^^^^^^^^^^^^^^

- ``std::pair<iterator,bool> insert( key_type& k, value_type x );``

    - Requirements: ``x != 0``

    - Effects: Takes ownership of ``x`` and insert it iff there is no equivalent of it already. The bool part of the return value indicates insertion and the iterator points to the element with key ``x``.

    - Throws: bad_pointer if ``x == 0``

    - Exception safety: Strong guarantee


- ``template< class U > std::pair<iterator,bool> insert( const key_type& k, compatible-smart-ptr<U> x );``                         

   - Equivalent to (but without the ``const_cast``): ``return insert( const_cast<key_type&>(k), x.release() );``

..
        - ``std::pair<iterator,bool> insert( key_type& k, const_reference x );``
    
        - Effects: ``return insert( allocate_clone( x ) );``
    
        - Exception safety: Strong guarantee


.. _`lookup`: 

Semantics: lookup
^^^^^^^^^^^^^^^^^

- ``T& operator[]( const key_type& key );``

    - Effects: returns the object with key ``key`` if it exists; otherwise a new object is allocated and inserted and its reference returned.
    - Exception-safety: Strong guarantee           

- ``T&       at( const key_type& key );``
- ``const T& at( const key_type& jey ) const;``

    - Requirement: the key exists
    - Throws: ``bad_ptr_container_operation`` if the key does not exist                                 

.. _`pointer container requirements`:

Semantics: pointer container requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``bool transfer( iterator object, ptr_map_adapter& from );``

   - Requirements: ``not from.empty()``

   - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from`` 
     iff no equivalent object exists.

   - Returns: whether the object was transfered
   
   - Exception safety: Strong guarantee

- ``size_type transfer( iterator first, iterator last, ptr__set_adapter& from );``

   - Requirements: ``not from.empty()``

   - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
     An object is only transferred if no equivalent object exists. 

   - Returns: the number of transfered objects
              
   - Exception safety: Basic guarantee

- ``template< class Range > void transfer( const Range& r, ptr_map_adapter& from );``

    - Effects: ``return transfer( boost::begin(r), boost::end(r), from );``
                   
- ``size_type transfer( ptr_set_adapter& from );``

   - Effects: ``return transfer( from.begin(), from.end(), from );``.

.. raw:: html 

        <hr>
 
:Copyright:     Thorsten Ottosen 2004-2006. 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