libs/ptr_container/doc/ptr_array.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 Class ``ptr_array``
   8 -------------------
   9
  10 A ``ptr_array<T,size>`` is a pointer container that uses an underlying ``boost::array<void*,size>``
  11 to store the pointers. The class is useful when there is no requirement
  12 of dynamic expansion and when no overhead is tolerable.
  13
  14 **Hierarchy:**
  15
  16 - `reversible_ptr_container <reversible_ptr_container.html>`_
  17
  18   - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
  19
  20     - `ptr_vector <ptr_vector.html>`_
  21     - `ptr_list <ptr_list.html>`_
  22     - `ptr_deque <ptr_deque.html>`_
  23     - ``ptr_array``
  24
  25 **Navigate:**
  26
  27 - `home <ptr_container.html>`_
  28 - `reference <reference.html>`_
  29
  30
  31
  32 **Synopsis:**
  33
  34 .. parsed-literal::
  35
  36         namespace boost
  37         {
  38
  39             template
  40             <
  41                 class T,
  42                 size_t N,
  43                 CloneAllocator = heap_clone_allocator
  44             >
  45             class ptr_array : public *implementation-defined*
  46             {
  47             public: // `construct/copy/destroy`_
  48                 ptr_array();
  49                 explicit ptr_array( const ptr_array& r );
  50                 template< class U >
  51                 explicit ptr_array( const ptr_array<U,N>& r );
  52                 explicit ptr_array( std::auto_ptr<ptr_array>& r );
  53
  54                 ptr_array& operator=( const ptr_array& r );
  55                 template< class U >
  56                 ptr_array& operator=( const ptr_array<U,N>& r );
  57                 ptr_array& operator=( std::auto_ptr<this_type> r );
  58
  59             public: // `iterators`_
  60
  61             public: // `capacity`_
  62
  63             public: // `element access`_
  64                 T&        front();
  65                 const T&  front() const;
  66                 T&        back();
  67                 const T&  back() const;
  68
  69                 template< size_t idx >
  70                 T&        at();
  71                 template< size_t idx >
  72                 const T&  at() const;
  73                 T&        at( size_t );
  74                 const T&  at( size_t );
  75
  76                 T&        operator[]( size_t );
  77                 const T&  operator[]( size_t ) const;
  78
  79             public: // `modifiers`_
  80                 void  swap( ptr_array& r );
  81
  82                 template< size_t idx >
  83                 auto_type replace( T* r );
  84                 template< size_t idx, class U >
  85                 auto_type replace( std::auto_ptr<U> r );
  86                 auto_type replace( size_t idx, T* r );
  87                 template< class U >
  88                 auto_type replace( size_t idx, std::auto_ptr<U> r );
  89
  90             public: // `pointer container requirements`_
  91                 std::auto_ptr<ptr_array>  clone() const;
  92                 std::auto_ptr<ptr_array>  release();
  93                 template< size_t idx >
  94                 bool                      is_null() const;
  95                 bool                      is_null( size_t idx ) const;
  96
  97             }; //  class 'ptr_sequence_adapter'
  98
  99         } // namespace 'boost'
 100
 101 .. _iterators: reversible_ptr_container.html#iterators
 102
 103 .. _capacity: reversible_ptr_container.html#capacity
 104
 105 .. _`inherited element access`: reversible_ptr_container.html#element-access
 106
 107 Semantics
 108 ---------
 109
 110 .. _`construct/copy/destroy`:
 111
 112 Semantics: construct/copy/destroy
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 - ``ptr_array();``
 116
 117     - Effects: constructs array where each element is null
 118
 119 -   ``explicit ptr_array( const ptr_array& r );``
 120 -   ``template< class U >
 121     explicit ptr_array( const ptr_array<U,N>& r );``
 122
 123     - Effects: Constructs array by cloning ``r``
 124
 125 - ``ptr_array( std::auto_ptr<ptr_array>& r );``
 126
 127     - Effects: take ownership of the supplied pointers
 128
 129 - ``ptr_array& operator=( const ptr_array& r );``
 130
 131 - ``template< class U > ptr_array& operator=( const ptr_array<U,N>& r );``
 132
 133     - Effects: Assigns a clone of ``r``
 134
 135     - Exception safety: Strong guarantee
 136
 137 - ``ptr_array& operator=( std::auto_ptr<this_type> r );``
 138
 139    - Effects: take ownership of the supplied pointers
 140
 141    - Throws: Nothing
 142
 143 .. _`element access`:
 144
 145 Semantics: element access
 146 ^^^^^^^^^^^^^^^^^^^^^^^^^
 147
 148
 149 - ``T&       front();``
 150 - ``const T& front() const;``
 151
 152     - Requirements: ``not empty();``
 153
 154     - Effects: ``return *begin();``
 155
 156     - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
 157
 158
 159 - ``T&       back();``
 160 - ``const T& back() const;``
 161
 162     - Requirements: ``not empty();``
 163
 164     - Effects: ``return *--end();``
 165
 166     - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
 167
 168 - ``template< size_t idx > T&       at( size_type n );``
 169 - ``template< size_t idx > const T& at( size_type n ) const;``
 170
 171     - Requirements: ``idx < size()`` (compile-time enforced)
 172
 173     - Effects: Returns a reference to the ``n``'th element
 174
 175     - Throws: nothing
 176
 177 - ``T&       at( size_type n );``
 178 - ``const T& at( size_type n ) const;``
 179
 180     - Requirements: ``n < size()``
 181
 182     - Effects: Returns a reference to the ``n``'th element
 183
 184     - Throws: ``bad_index`` if ``n >=size()``
 185
 186
 187 - ``T&       operator[]( size_type n );``
 188 - ``const T& operator[]( size_type n ) const;``
 189
 190     - Requirements: ``n < size()``
 191
 192     - Effects: Returns a reference to the ``n``'th element
 193
 194     - Throws: Nothing
 195
 196
 197 .. _`modifiers`:
 198
 199 Semantics: modifiers
 200 ^^^^^^^^^^^^^^^^^^^^
 201
 202 - ``void swap( ptr_array& r );``
 203
 204     - Effects: swaps the two arrays
 205
 206     - Complexity: Linear
 207
 208     - Throws: nothing
 209
 210 - ``template< size_t idx > auto_type replace( T* r );``
 211
 212     - Requirements:
 213
 214             - ``idx < size()`` (compile-time enforced)
 215             - ``r != 0``
 216
 217     - Effects: returns the object indexed by ``idx`` and replaces it with ``r``.
 218
 219     - Throws: ``bad_pointer`` if ``x == 0``.
 220
 221     - Exception safety: Strong guarantee
 222
 223 - ``template< size_t idx, class U > auto_type replace( std::auto_ptr<U> r );``
 224
 225     - Effects: ``return replace<idx>( r.release() );``
 226
 227 - ``auto_type replace( size_t idx, T* r );``
 228
 229     - Requirements: `` x != 0 and idx < size()``
 230
 231     - Effects: returns the object indexed by ``idx`` and replaces it with ``x``.
 232
 233     - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``.
 234
 235     - Exception safety: Strong guarantee
 236
 237 - ``template< class U > auto_type replace( size_t idx, std::auto_ptr<U> r );``
 238
 239     - Effects: ``return replace( idx, r.release() );``
 240
 241 .. _`pointer container requirements`:
 242
 243 Semantics: pointer container requirements
 244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 245
 246 - ``std::auto_ptr<ptr_array>  clone() const;``
 247
 248     - Effects: Returns a deep copy of the container
 249
 250     - Throws: ``std::bad_alloc`` if there is not enough memory to make a clone of the container
 251
 252     - Complexity: Linear
 253
 254
 255 - ``std::auto_ptr<ptr_array>  release();``
 256
 257     - Effects: Releases ownership of the container. This is a useful way of returning a container from a function.
 258
 259     - Postconditions: ``empty() == true`` and all pointers are null
 260
 261     - Throws: ``std::bad_alloc`` if the return value cannot be allocated
 262
 263     - Exception safety: Strong guarantee
 264
 265
 266 - ``template< size_t idx > bool is_null() const;``
 267
 268     - Requirements: ``idx < size()`` (compile-time enforced)
 269
 270     - Effects: returns whether the pointer at index ``idx`` is null
 271
 272     - Exception safety: Nothrow guarantee
 273
 274 - ``bool is_null( size_type idx ) const;``
 275
 276     - Requirements: ``idx < size()``
 277
 278     - Effects: returns whether the pointer at index ``idx`` is null
 279
 280     - Exception safety: Nothrow guarantee
 281
 282 .. raw:: html
 283
 284         <hr>
 285
 286 :Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 287
 288 __ http://www.boost.org/LICENSE_1_0.txt
 289
 290