boost_1_45_0/libs/ptr_container/doc/ptr_vector.rst

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

Class ``ptr_vector``
--------------------

A ``ptr_vector<T>`` is a pointer container that uses an underlying ``std::vector<void*>``
to store the pointers. 

**Hierarchy:**

- `reversible_ptr_container <reversible_ptr_container.html>`_

  - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_

    - ``ptr_vector``
    - `ptr_list <ptr_list.html>`_
    - `ptr_deque <ptr_deque.html>`_
    - `ptr_array <ptr_array.html>`_

**Navigate:**

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

**Synopsis:**

.. parsed-literal::  
           
        namespace boost
        {      
        
            template
            < 
                class T, 
                class CloneAllocator = heap_clone_allocator,
                class Allocator      = std::allocator<void*>
            >
            class ptr_vector : public ptr_sequence_adapter
                                      <
                                          T,
                                          std::vector<void*,Allocator>,
                                          CloneAllocator
                                      >
            {
            public: // `construction`_
                explicit ptr_vector( size_type to_reserve );
            
            public: // capacity_
                size_type  capacity() const;
                void       reserve( size_type n );
            
            public: // `element access`_
                T&        operator[]( size_type n );
                const T&  operator[]( size_type n ) const;
                T&        at( size_type n );
                const T&  at( size_type n ) const;

            public: // `pointer container requirements`_
               auto_type replace( size_type idx, T* x );  
               template< class U >
               auto_type replace( size_type idx, std::auto_ptr<U> x );  
               bool      is_null( size_type idx ) const;
               
            public: // `C-array support`_
               void transfer( iterator before, T** from, size_type size, bool delete_from = true );
               T**  c_array();

            };
           
        } // namespace 'boost'  


Semantics
---------

.. _`construction`:

Semantics: construction
^^^^^^^^^^^^^^^^^^^^^^^

- ``explicit ptr_vector( size_type to_reserve );``

    - constructs an empty vector with a buffer
      of size least ``to_reserve``

.. _`capacity`:

Semantics: capacity
^^^^^^^^^^^^^^^^^^^

- ``size_type capacity() const;``

    - Effects: Returns the size of the allocated buffer

    - Throws: Nothing

- ``void reserve( size_type n );``

    - Requirements: ``n <= max_size()``
                 
    - Effects: Expands the allocated buffer

    - Postcondition: ``capacity() >= n``

    - Throws: ``std::length_error()`` if ``n > max_size()``


.. _`element access`:

Semantics: element access
^^^^^^^^^^^^^^^^^^^^^^^^^

- ``T& operator[]( size_type n );``
- ``const T& operator[]( size_type n ) const;``

    - Requirements: ``n < size()``

    - Effects: Returns a reference to the ``n``'th element

    - Throws: Nothing

- ``T& at( size_type n );``
- ``const T& at( size_type n ) const;``

    - Requirements: ``n < size()``

    - Effects: Returns a reference to the ``n``'th element

    - Throws: ``bad_index`` if ``n >= size()``


.. _`pointer container requirements`:

Semantics: pointer container requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``auto_type replace( size_type idx, T* x );``    

    - Requirements: `` x != 0 and idx < size()``

    - Effects: returns the object indexed by ``idx`` and replaces it with ``x``.

    - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``.

    - Exception safety: Strong guarantee

- ``template< class U > auto_type replace( size_type idx, std::auto_ptr<U> x );``

    - Effects: ``return replace( idx, x.release() );``  

- ``bool is_null( size_type idx ) const;``

    - Requirements: ``idx < size()``

    - Effects: returns whether the pointer at index ``idx`` is null

    - Exception safety: Nothrow guarantee


.. _`C-array support`:

Semantics: C-array support
^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``void transfer( iterator before, T** from, size_type size, bool delete_from = true );``

    - Requirements:  ``from != 0``
    
    - Effects: Takes ownership of the dynamic array ``from``
    
    - Exception safety: Strong guarantee if ``delete_from == true``; if ``delete_from == false``,
      and an exception is thrown, the container fails to take ownership.                  
    
    - Remarks: Eventually calls ``delete[] from`` if ``delete_from == true``.   
         
- ``T** c_array();``

    - Returns: ``0`` if the container is empty; otherwise a pointer to the first element of the stored array

    - Throws: Nothing
    
.. raw:: html 

        <hr>

:Copyright:     Thorsten Ottosen 2004-2007. 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