123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203 |
- ++++++++++++++++++++++++++++++++++
- |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
|