]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |