1++++++++++++++++++++++++++++++++++
2 |Boost| Pointer Container Library
3++++++++++++++++++++++++++++++++++
4
5.. |Boost| image:: boost.png
6
7Class ``ptr_sequence_adapter``
8------------------------------
9
10This section describes all the common operations for all the pointer
11sequences:
12
13- `ptr_vector <ptr_vector.html>`_
14- `ptr_list <ptr_list.html>`_
15- `ptr_deque <ptr_deque.html>`_
16
17
18The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer
19containers from.
20
21**Hierarchy:**
22
23- `reversible_ptr_container <reversible_ptr_container.html>`_
24
25  - ``ptr_sequence_adapter``
26
27    - `ptr_vector <ptr_vector.html>`_
28    - `ptr_list <ptr_list.html>`_
29    - `ptr_deque <ptr_deque.html>`_
30    - `ptr_array <ptr_array.html>`_
31
32**Navigate:**
33
34- `home <ptr_container.html>`_
35- `reference <reference.html>`_
36
37
38**Synopsis:**
39
40.. parsed-literal::
41
42        namespace boost
43        {
44
45            template
46            <
47                class T,
48                class VoidPtrSeq,
49                class CloneAllocator = heap_clone_allocator
50            >
51            class ptr_sequence_adapter
52            {
53            public: // `construct/copy/destroy`_
54                template< class InputIterator >
55                assign( InputIterator first, InputIterator last );
56                template< class InputRange >
57                assign( const InputRange& e );
58
59            public: // `element access`_
60                T&        front();
61                const T&  front() const;
62                T&        back();
63                const T&  back() const;
64
65            public: // `modifiers`_
66                void      push_back( T* x );
67                template< class U >
68                void      push_back( std::auto_ptr<U> x );
69                auto_type pop_back();
70                iterator  insert( iterator position, T* x );
71                template< class U >
72                iterator  insert( iterator position, std::auto_ptr<U> x );
73                template< class InputIterator >
74                void      insert( iterator position, InputIterator first, InputIterator last );
75                template< class InputRange >
76                void      insert( iterator position, const InputRange& r );
77                iterator  erase( iterator position );
78                iterator  erase( iterator first, iterator last );
79                template< class Range >
80                iterator  erase( const Range& r );
81                void      resize( size_type size );
82                void      resize( size_type size, T* to_clone );
83
84            public: // `pointer container requirements`_
85                template< class PtrSequence >
86                void transfer( iterator before, typename PtrSequence::iterator object,
87                               PtrSequence& from );
88                template< class PtrSequence >
89                void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last,
90                               PtrSequence& from );
91                void template< class PtrSequence, class Range >
92                void transfer( iterator before, const Range& r, PtrSequence& from );
93                template< class PtrSequence >
94                void transfer( iterator before, PtrSequence& from );
95
96            public: // `algorithms`_
97
98                void sort();
99                void sort( iterator first, iterator last );
100                template< class Compare >
101                void sort( Compare comp );
102                template< class Compare >
103                void sort( iterator begin, iterator end, Compare comp );
104
105                void unique();
106                void unique( iterator first, iterator last );
107                template< class Compare >
108                void unique( Compare comp );
109                template< class Compare >
110                void unique( iterator begin, iterator end, Compare comp );
111
112                template< class Pred >
113                void erase_if( Pred pred );
114                template< class Pred >
115                void erase_if( iterator begin, iterator end, Pred pred );
116
117                void merge( ptr_sequence_adapter& r );
118                template< class Compare >
119                void merge( ptr_sequence_adapter& r, Compare comp );
120                void merge( iterator first, iterator last, ptr_sequence_adapter& from );
121                template< class Compare >
122                void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );
123
124            public: // `ptr_list interface`_
125
126            public: // `ptr_vector interface`_
127
128            public: // `ptr_deque interface`_
129
130            }; //  class 'ptr_sequence_adapter'
131
132        } // namespace 'boost'
133
134.. _`ptr_list interface`: ptr_list.html
135.. _`ptr_vector interface`: ptr_vector.html
136.. _`ptr_deque interface`: ptr_deque.html
137
138Semantics
139---------
140
141.. _`construct/copy/destroy`:
142
143Semantics: construct/copy/destroy
144^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
145
146- ``template< class InputIterator >
147  void assign( InputIterator first, InputIterator last );``
148
149    - Requirements: ``(first,last]`` is a valid range
150
151    - Effects: ``clear(); insert( first, last );``
152
153    - Postconditions: ``size() == std::distance( first, last );``
154
155    - Exception safety: strong guarantee
156
157- ``template< class InputRange >
158  void assign( const InputRange& r );``
159
160    - Effects: ``assign( boost::begin(r), boost::end(r) );``
161
162
163..
164        - ``assign( size_type n, const T& u )``
165
166        - Effects: ``clear(); insert( begin(), n, u );``
167
168        - Postconditions: ``size() == n``
169
170        - Exception safety: Strong guarantee
171
172
173..
174        void resize( size_type sz, const T& x );
175        Effects:
176
177        if ( sz > size() )
178            insert( end(), sz-size(), x );
179            else if ( sz < size() )
180            erase( begin()+sz, end() );
181            else
182            ; //do nothing
183
184        Postconditions: size() == sz
185
186        Exception safety: Strong guarantee
187
188
189.. _`element access`:
190
191Semantics: element access
192^^^^^^^^^^^^^^^^^^^^^^^^^
193
194- ``T& front();``
195
196    - Requirements: ``not empty();``
197
198    - Effects: ``return *begin();``
199
200
201- ``const T& front() const;``
202
203    - Requirements: ``not empty();``
204
205    - Effects: ``return *begin();``
206
207
208- ``T& back();``
209
210    - Requirements: ``not empty();``
211
212    - Effects: ``return *--end();``
213
214
215- ``const T& back() const;``
216
217    - Requirements: ``not empty();``
218
219    - Effects: ``return *--end();``
220
221
222.. _`modifiers`:
223
224Semantics: modifiers
225^^^^^^^^^^^^^^^^^^^^
226
227- ``void push_back( T* x );``
228
229    - Requirements: ``x != 0``
230
231    - Effects: Inserts the pointer into container and takes ownership of it
232
233    - Throws: ``bad_pointer`` if ``x == 0``
234
235    - Exception safety: Strong guarantee
236
237- ``template< class U > void push_back( std::auto_ptr<U> x );``
238
239    - Effects: ``push_back( x.release() );``
240
241..
242        - ``void push_back( const T& x );``
243
244        - Effects: ``push_back( CloneAllocator::clone( x ) );``
245
246        - Exception safety: Strong guarantee
247
248- ``auto_type pop_back();``
249
250    - Requirements:``not empty()``
251
252    - Effects: Removes the last element in the container
253
254    - Postconditions: ``size()`` is one less
255
256    - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
257
258    - Exception safety: Strong guarantee
259
260
261- ``iterator insert( iterator position, T* x );``
262
263    - Requirements: ``position`` is a valid iterator from the container and
264      ``x != 0``
265
266    - Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it
267
268    - Throws: ``bad_pointer`` if ``x == 0``
269
270    - Exception safety: Strong guarantee
271
272- ``template< class U > iterator insert( iterator position, std::auto_ptr<U> x );``
273
274    - Effects: ``return insert( position, x.release() );``
275
276..
277        - ``iterator insert( iterator position, const T& x );``
278
279        - Requirements: ``position`` is a valid iterator from the container
280
281        - Effects: ``return insert( position, CloneAllocator::clone( x ) );``
282
283        - Exception safety: Strong guarantee
284
285        - ``void insert( iterator position, size_type n, const T& x );``
286
287        - Requirements: ``position`` is a valid iterator from the container
288
289        - Effects: Inserts ``n`` clones of ``x`` before position into the container
290
291        - Exception safety: Strong guarantee
292
293- ``template< class InputIterator >
294  void insert( iterator position, InputIterator first, InputIterator last );``
295
296    - Requirements: ``position`` is a valid iterator from the container
297
298    - Effects: Inserts a cloned range before ``position``
299
300    - Exception safety: Strong guarantee
301
302- ``template< class InputRange >
303  void insert( iterator position, const InputRange& r );``
304
305    - Effects: ``insert( position, boost::begin(r), boost::end(r) );``
306
307- ``iterator erase( iterator position );``
308
309    - Requirements: ``position`` is a valid iterator from the container
310
311    - Effects: Removes the element defined by ``position`` and returns an iterator to the following element
312
313    - Throws: Nothing
314
315- ``iterator erase( iterator first, iterator last );``
316
317    - Requirements: ``[first,last)`` is a valid range
318
319    - Effects: Removes the range of element defined by ``[first,last)`` and returns an iterator to the following element
320
321    - Throws: Nothing
322
323- ``template< class Range >
324  void erase( const Range& r );``
325
326    - Effects: ``erase( boost::begin(r), boost::end(r) );``
327
328- ``void resize( size_type size );``
329
330    - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, it happens at the back.
331
332    - Requirements: ``T`` is default constructible
333
334    - Postcondition: ``size() == size;``
335
336    - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
337
338- ``void resize( size_type size, T* to_clone );``
339
340    - Effects: Resizes the container. If elements are erased, it happens from the back. If elements are inserted, clones of ``*to_clone`` are inserted at the back.
341
342    - Postcondition: ``size() == size;``
343
344    - Exception safety: Basic guarantee under expansion; nothrow guarantee otherwise
345
346    - Remarks: ``to_clone == 0`` is valid if the container supports nulls. The container does not take ownership of ``to_clone``.
347
348.. _`pointer container requirements`:
349
350Semantics: pointer container requirements
351^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352
353You can use ``transfer()`` to move elements between two containers of the same type. Furthermore,
354you can also move elements from a container of type ``T`` to a container of type ``U`` as long as
355``T::value_type`` is convertible to ``U::value_type``. An example would be transferring from ``boost::ptr_vector<Derived>``
356to ``boost::ptr_deque<Base>``.
357
358(**Remark:** *When moving elements between two different containers, it is your responsibility to make sure the allocators are compatible.*
359*The special latitude of being able to transfer between two different containers is only available for Sequences and not for Associative Containers.*)
360
361..
362
363- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator object, PtrSequence& from );``
364
365    - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
366      Insertion takes place before ``before``.
367
368    - Postconditions: If ``from.empty()``, nothing happens. Otherwise
369      ``size()`` is one more, ``from.size()`` is one less.
370
371    - Exception safety: Strong guarantee
372
373
374- ``template< class PtrSequence > void transfer( iterator before, typename PtrSequence::iterator first, typename PtrSequence::iterator last, PtrSequence& from );``
375
376    - Requirements: ``from.size() >= std::distance(first,last)``
377
378    - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
379      Insertion takes place before ``before``.
380
381    - Postconditions: If ``from.empty()``, nothing happens. Otherwise,
382      let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.
383
384    - Exception safety: Strong guarantee
385
386    - Complexity: Linear or better
387
388- ``void template< class PtrSequence, class Range > void transfer( iterator before, const Range& r, PtrSequence& from );``
389
390    - Effects: ``transfer(before, boost::begin(r), boost::end(r), from);``
391
392- ``template< class PtrSequence> void transfer( iterator before, PtrSequence& from );``
393
394    - Effects: ``transfer(before, from, from);``
395
396.. _`algorithms`:
397
398Semantics: algorithms
399^^^^^^^^^^^^^^^^^^^^^
400
401The general requirement for these algorithms is that the container *does not
402contain any nulls*.
403
404- ``void sort();``
405- ``void sort( iterator first, iterator last );``
406- ``template< class Compare > void sort( Compare comp );``
407- ``template< class Compare > void sort( iterator begin, iterator end, Compare comp );``
408
409    - Requirements: (versions without ``Compare``) ``bool operator<( const T&, const T& )`` is defined
410    - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
411    - Effects: sorts the entire container or the specified range
412    - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
413    - Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list``
414
415- ``void unique();``
416- ``void unique( iterator first, iterator last );``
417- ``template< class Compare > void unique( Compare comp );``
418- ``template< class Compare > void unique( iterator begin, iterator end, Compare comp );``
419
420    - Requirements: (versions without ``Compare``) ``bool operator==( const T&, const T& )`` is defined
421    - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
422    - Effects: removes adjacent and equal objects from the entire container or the specified range
423    - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
424
425- ``template< class Pred > void erase_if( Pred pred );``
426- ``template< class Pred > void erase_if( iterator begin, iterator end, Pred pred );``
427
428    - Requirements: ``Pred`` must take an ``const T&`` argument
429    - Effects: removes all elements ``t`` for which ``pred(t)`` returns ``true`` from the entire container or the specified range
430    - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
431
432- ``void merge( ptr_sequence_adapter& r );``
433- ``template< class Compare > void merge( ptr_sequence_adapter& r, Compare comp );``
434- ``void merge( iterator first, iterator last, ptr_sequence_adapter& from );``
435- ``template< class Compare > void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );``
436
437    - Requirements: (``Compare`` versions) ``Compare`` must take ``const T&`` arguments
438    - Requirements: both sequences are sorted wrt. the same predicate
439    - Effects: transfers the entire container or the specified sequence to the container while
440      ensuring the new sequence is also sorted
441    - Postconditions: (Container versions) ``r.empty()``
442    - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
443
444.. raw:: html
445
446        <hr>
447
448:Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
449
450__ http://www.boost.org/LICENSE_1_0.txt
451
452
453