204 lines
6.5 KiB
ReStructuredText
204 lines
6.5 KiB
ReStructuredText
++++++++++++++++++++++++++++++++++
|
|
|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
|
|
|
|
|