Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Boost 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:

Navigate:

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

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, compatible-smart-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).