1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``ptr_vector``
8--------------------
9
10A ``ptr_vector<T>`` is a pointer container that uses an underlying ``std::vector<void*>``
11to 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, compatible-smart-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
77Semantics
78---------
79
80.. _`construction`:
81
82Semantics: 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
92Semantics: 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
114Semantics: 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
138Semantics: 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, compatible-smart-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
166Semantics: 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
195