1 ++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3 ++++++++++++++++++++++++++++++++++
5 .. |Boost| image:: boost.png
10 A ``ptr_vector<T>`` is a pointer container that uses an underlying ``std::vector<void*>``
11 to store the pointers.
15 - `reversible_ptr_container <reversible_ptr_container.html>`_
17 - `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
20 - `ptr_list <ptr_list.html>`_
21 - `ptr_deque <ptr_deque.html>`_
22 - `ptr_array <ptr_array.html>`_
26 - `home <ptr_container.html>`_
27 - `reference <reference.html>`_
39 class CloneAllocator = heap_clone_allocator,
40 class Allocator = std::allocator<void*>
42 class ptr_vector : public ptr_sequence_adapter
45 std::vector<void*,Allocator>,
49 public: // `construction`_
50 explicit ptr_vector( size_type to_reserve );
53 size_type capacity() const;
54 void reserve( size_type n );
56 public: // `element access`_
57 T& operator[]( size_type n );
58 const T& operator[]( size_type n ) const;
60 const T& at( size_type n ) const;
62 public: // `pointer container requirements`_
63 auto_type replace( size_type idx, T* x );
65 auto_type replace( size_type idx, std::auto_ptr<U> x );
66 bool is_null( size_type idx ) const;
68 public: // `C-array support`_
69 void transfer( iterator before, T** from, size_type size, bool delete_from = true );
74 } // namespace 'boost'
82 Semantics: construction
83 ^^^^^^^^^^^^^^^^^^^^^^^
85 - ``explicit ptr_vector( size_type to_reserve );``
87 - constructs an empty vector with a buffer
88 of size least ``to_reserve``
95 - ``size_type capacity() const;``
97 - Effects: Returns the size of the allocated buffer
101 - ``void reserve( size_type n );``
103 - Requirements: ``n <= max_size()``
105 - Effects: Expands the allocated buffer
107 - Postcondition: ``capacity() >= n``
109 - Throws: ``std::length_error()`` if ``n > max_size()``
112 .. _`element access`:
114 Semantics: element access
115 ^^^^^^^^^^^^^^^^^^^^^^^^^
117 - ``T& operator[]( size_type n );``
118 - ``const T& operator[]( size_type n ) const;``
120 - Requirements: ``n < size()``
122 - Effects: Returns a reference to the ``n``'th element
126 - ``T& at( size_type n );``
127 - ``const T& at( size_type n ) const;``
129 - Requirements: ``n < size()``
131 - Effects: Returns a reference to the ``n``'th element
133 - Throws: ``bad_index`` if ``n >= size()``
136 .. _`pointer container requirements`:
138 Semantics: pointer container requirements
139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
141 - ``auto_type replace( size_type idx, T* x );``
143 - Requirements: `` x != 0 and idx < size()``
145 - Effects: returns the object indexed by ``idx`` and replaces it with ``x``.
147 - Throws: ``bad_index`` if ``idx >= size()`` and ``bad_pointer`` if ``x == 0``.
149 - Exception safety: Strong guarantee
151 - ``template< class U > auto_type replace( size_type idx, std::auto_ptr<U> x );``
153 - Effects: ``return replace( idx, x.release() );``
155 - ``bool is_null( size_type idx ) const;``
157 - Requirements: ``idx < size()``
159 - Effects: returns whether the pointer at index ``idx`` is null
161 - Exception safety: Nothrow guarantee
164 .. _`C-array support`:
166 Semantics: C-array support
167 ^^^^^^^^^^^^^^^^^^^^^^^^^^
169 - ``void transfer( iterator before, T** from, size_type size, bool delete_from = true );``
171 - Requirements: ``from != 0``
173 - Effects: Takes ownership of the dynamic array ``from``
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.
178 - Remarks: Eventually calls ``delete[] from`` if ``delete_from == true``.
182 - Returns: ``0`` if the container is empty; otherwise a pointer to the first element of the stored array
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__).
192 __ http://www.boost.org/LICENSE_1_0.txt