boost_1_45_0/libs/ptr_container/doc/associative_ptr_container.rst

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

Class ``associative_ptr_container``
-------------------------------------

This section describes all the common operations for all associative
pointer containers (in addition to ``reversible_ptr_container``).

**Hierarchy:**

- `reversible_ptr_container <reversible_ptr_container.html>`_

  - ``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_set.html>`_
      - `ptr_multi_set <ptr_multiset.html>`_ 
      - `ptr_map <ptr_map.html>`_
      - `ptr_multimap <ptr_multimap.html>`_

**See also:**

- `iterator_range <http://www.boost.org/libs/range/doc/utility_class.html#iter_range>`_

**Navigate:**

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

**Synopsis:**

.. parsed-literal::

        namespace boost
        {
            template
            < 
                class Key, 
                class CloneAllocator = heap_clone_allocator 
            >
            class associative_ptr_container 
            {
            public: // typedefs_
                typedef ...   key_type;
                typedef ...   key_compare;
                typedef ...   value_compare;
        
            public: // `observers`_
                key_compare    key_comp() const;
                value_compare  value_comp() const;
        
            public: // `modifiers`_         
                template< typename InputIterator >
                void       insert( InputIterator first, InputIterator last );     
                template< class InputRange >
                void       insert( const InputRange& r );
                void       erase( iterator position ); 
                size_type  erase( const key_type& x );
                template< class Range >
                void       erase( const Range& r );
                void       erase( iterator first, iterator last );

            public: // `algorithms`_
                iterator                        find( const key_type& x );
                const_iterator                  find( const key_type& x ) const;
                size_type                       count( const key_type& x ) const;              
                iterator                        lower_bound( const key_type& x );                     
                const_iterator                  lower_bound( const key_type& x ) const;
                iterator                        upper_bound( const key_type& x );                           
                const_iterator                  upper_bound( const key_type& x ) const;
                iterator_range<iterator>        equal_range( const key_type& x );                 
                iterator_range<const_iterator>  equal_range( const key_type& x ) const;
             
            }; //  class 'associative_ptr_container'
            
        } // namespace 'boost'  

    
Semantics
---------

.. _typedefs:

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

- ``typedef ... key_type;``

    - if we are dealing with a map, then simply the key type
    - if we are dealing with a set, then the *indirected* key type, that is, 
      given ``ptr_set<T>``, ``key_type*`` will be ``T*``.

- ``typedef ... key_compare;``

    -  comparison object type that determines the order of elements in the container

- ``typedef ... value_compare;``

    - comparison object type that determines the order of elements in the container
    - if we are dealing with a map, then this comparison simply forwards to the ``key_compare`` comparison operation

.. _`observers`:

Semantics: observers
^^^^^^^^^^^^^^^^^^^^

- ``key_compare key_comp() const;``
- ``value_compare value_comp() const;``

    - returns copies of objects used to determine the order of elements

.. _`modifiers`:

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

- ``template< typename InputIterator >
  void insert( InputIterator first, InputIterator last );``

    - Requirements: ``[first,last)`` is a valid range

    - Effects: Inserts a cloned range 

    - Exception safety: Basic guarantee

- ``template< class InputRange >
  void insert( const InputRange& r );``

    - Effects: ``insert( boost::begin(r), boost::end(r) );``

- ``void erase( iterator position );``

    - Requirements: ``position`` is a valid iterator from the container

    - Effects: Removes the element defined by ``position``.

    - Throws: Nothing

- ``size_type erase( const key_type& x );``

    - Effects: Removes all the elements in the container with a key equivalent to ``x`` and returns the number of erased elements.

    - Throws: Nothing

- ``void erase( iterator first, iterator last );``

    - Requirements: ``[first,last)`` is a valid range

    - Effects: Removes the range of elements defined by ``[first,last)``.

    - Throws: Nothing

- ``template< class Range > void erase( const Range& r );``

    - Effects: ``erase( boost::begin(r), boost::end(r) );``

.. _`algorithms`:

Semantics: algorithms
^^^^^^^^^^^^^^^^^^^^^

- ``iterator       find( const Key& x );``
- ``const_iterator find( const Key& x ) const;``

    - Effects: Searches for the key and returns ``end()`` on failure.

    - Complexity: Logarithmic

- ``size_type count( const Key& x ) const;``

    - Effects: Counts the elements with a key equivalent to ``x``

    - Complexity: Logarithmic

- ``iterator       lower_bound( const Key& x );``
- ``const_iterator lower_bound( const Key& x ) const;``

    - Effects: Returns an iterator pointing to the first element with a key not less than ``x``

    - Complexity: Logarithmic

- ``iterator       upper_bound( const Key& x );``
- ``const_iterator upper_bound( const Key& x ) const;``

    - Effects: Returns an iterator pointing to the first element with a key greater than ``x``

    - Complexity: Logarithmic

- ``iterator_range<iterator>       equal_range( const Key& x );`` 
- ``iterator_range<const_iterator> equal_range( const Key& x ) const;`` 

    - Effects: ``return boost::make_iterator_range( lower_bound( x ), upper_bound( x ) );``

    - Complexity: Logarithmic

..
        - ``reference       at( const key_type& key );``
        - ``const_reference at( const key_type& key ) const;`` 
    
        - Requirements: the key exists
    
        - Effects: returns the object with key ``key``
    
        - Throws: ``bad_ptr_container_operation`` if the key does not exist                                 
    

.. _`pointer container requirements`:

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