# Pointer Container Library

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

Navigate:

- home
- reference

Synopsis:

    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, std::auto_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

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

## 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, std::auto_ptr<U> x );`

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

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

## 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 );`.

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