ceph/src/boost/libs/ptr_container/doc/ptr_vector.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``ptr_vector``
   8 --------------------
   9
  10 A ``ptr_vector<T>`` is a pointer container that uses an underlying ``std::vector<void*>``
  11 to store the pointers.
  12
  13 **Hierarchy:**
  14
  15 - `reversible_ptr_container <reversible_ptr_container.html>`_
  16
  17   - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
  18
  19     - ``ptr_vector``
  20     - `ptr_list <ptr_list.html>`_
  21     - `ptr_deque <ptr_deque.html>`_
  22     - `ptr_array <ptr_array.html>`_
  23
  24 **Navigate:**
  25
  26 - `home <ptr_container.html>`_
  27 - `reference <reference.html>`_
  28
  29 **Synopsis:**
  30
  31 .. parsed-literal::
  32
  33         namespace boost
  34         {
  35
  36             template
  37             <
  38                 class T,
  39                 class CloneAllocator = heap_clone_allocator,
  40                 class Allocator      = std::allocator<void*>
  41             >
  42             class ptr_vector : public ptr_sequence_adapter
  43                                       <
  44                                           T,
  45                                           std::vector<void*,Allocator>,
  46                                           CloneAllocator
  47                                       >
  48             {
  49             public: // `construction`_
  50                 explicit ptr_vector( size_type to_reserve );
  51
  52             public: // capacity_
  53                 size_type  capacity() const;
  54                 void       reserve( size_type n );
  55
  56             public: // `element access`_
  57                 T&        operator[]( size_type n );
  58                 const T&  operator[]( size_type n ) const;
  59                 T&        at( size_type n );
  60                 const T&  at( size_type n ) const;
  61
  62             public: // `pointer container requirements`_
  63                auto_type replace( size_type idx, T* x );
  64                template< class U >
  65                auto_type replace( size_type idx, std::auto_ptr<U> x );
  66                bool      is_null( size_type idx ) const;
  67
  68             public: // `C-array support`_
  69                void transfer( iterator before, T** from, size_type size, bool delete_from = true );
  70                T**  c_array();
  71
  72             };
  73
  74         } // namespace 'boost'
  75
  76
  77 Semantics
  78 ---------
  79
  80 .. _`construction`:
  81
  82 Semantics: construction
  83 ^^^^^^^^^^^^^^^^^^^^^^^
  84
  85 - ``explicit ptr_vector( size_type to_reserve );``
  86
  87     - constructs an empty vector with a buffer
  88       of size least ``to_reserve``
  89
  90 .. _`capacity`:
  91
  92 Semantics: capacity
  93 ^^^^^^^^^^^^^^^^^^^
  94
  95 - ``size_type capacity() const;``
  96
  97     - Effects: Returns the size of the allocated buffer
  98
  99     - Throws: Nothing
 100
 101 - ``void reserve( size_type n );``
 102
 103     - Requirements: ``n <= max_size()``
 104
 105     - Effects: Expands the allocated buffer
 106
 107     - Postcondition: ``capacity() >= n``
 108
 109     - Throws: ``std::length_error()`` if ``n > max_size()``
 110
 111
 112 .. _`element access`:
 113
 114 Semantics: element access
 115 ^^^^^^^^^^^^^^^^^^^^^^^^^
 116
 117 - ``T& operator[]( size_type n );``
 118 - ``const T& operator[]( size_type n ) const;``
 119
 120     - Requirements: ``n < size()``
 121
 122     - Effects: Returns a reference to the ``n``'th element
 123
 124     - Throws: Nothing
 125
 126 - ``T& at( size_type n );``
 127 - ``const T& at( size_type n ) const;``
 128
 129     - Requirements: ``n < size()``
 130
 131     - Effects: Returns a reference to the ``n``'th element
 132
 133     - Throws: ``bad_index`` if ``n >= size()``
 134
 135
 136 .. _`pointer container requirements`:
 137
 138 Semantics: pointer container requirements
 139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 140
 141 - ``auto_type replace( size_type idx, T* x );``
 142
 143     - Requirements: `` x != 0 and idx < size()``
 144
 145     - Effects: returns the object indexed by ``idx`` and replaces it with ``x``.
 146
 147     - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``.
 148
 149     - Exception safety: Strong guarantee
 150
 151 - ``template< class U > auto_type replace( size_type idx, std::auto_ptr<U> x );``
 152
 153     - Effects: ``return replace( idx, x.release() );``
 154
 155 - ``bool is_null( size_type idx ) const;``
 156
 157     - Requirements: ``idx < size()``
 158
 159     - Effects: returns whether the pointer at index ``idx`` is null
 160
 161     - Exception safety: Nothrow guarantee
 162
 163
 164 .. _`C-array support`:
 165
 166 Semantics: C-array support
 167 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 168
 169 - ``void transfer( iterator before, T** from, size_type size, bool delete_from = true );``
 170
 171     - Requirements:  ``from != 0``
 172
 173     - Effects: Takes ownership of the dynamic array ``from``
 174
 175     - Exception safety: Strong guarantee if ``delete_from == true``; if ``delete_from == false``,
 176       and an exception is thrown, the container fails to take ownership.
 177
 178     - Remarks: Eventually calls ``delete[] from`` if ``delete_from == true``.
 179
 180 - ``T** c_array();``
 181
 182     - Returns: ``0`` if the container is empty; otherwise a pointer to the first element of the stored array
 183
 184     - Throws: Nothing
 185
 186 .. raw:: html
 187
 188         <hr>
 189
 190 :Copyright:     Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 191
 192 __ http://www.boost.org/LICENSE_1_0.txt
 193
 194