• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``ptr_array``
8-------------------
9
10A ``ptr_array<T,size>`` is a pointer container that uses an underlying ``boost::array<void*,size>``
11to store the pointers. The class is useful when there is no requirement
12of 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( compatible-smart-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=( compatible-smart-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( compatible-smart-ptr<U> r );
86                auto_type replace( size_t idx, T* r );
87                template< class U >
88                auto_type replace( size_t idx, compatible-smart-ptr<U> r );
89
90            public: // `pointer container requirements`_
91                compatible-smart-ptr<ptr_array>  clone() const;
92                compatible-smart-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
107Semantics
108---------
109
110.. _`construct/copy/destroy`:
111
112Semantics: 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( compatible-smart-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=( compatible-smart-ptr<this_type> r );``
138
139   - Effects: take ownership of the supplied pointers
140
141   - Throws: Nothing
142
143.. _`element access`:
144
145Semantics: 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
199Semantics: 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( compatible-smart-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, compatible-smart-ptr<U> r );``
238
239    - Effects: ``return replace( idx, r.release() );``
240
241.. _`pointer container requirements`:
242
243Semantics: pointer container requirements
244^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245
246- ``compatible-smart-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- ``compatible-smart-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
291