1QPtrVector(3qt)                                                QPtrVector(3qt)
2
3
4

NAME

6       QPtrVector - Template collection class that provides a vector (array)
7

SYNOPSIS

9       #include <qptrvector.h>
10
11       Inherits QPtrCollection.
12
13   Public Members
14       QPtrVector ()
15       QPtrVector ( uint size )
16       QPtrVector ( const QPtrVector<type> & v )
17       ~QPtrVector ()
18       QPtrVector<type> & operator= ( const QPtrVector<type> & v )
19       bool operator== ( const QPtrVector<type> & v ) const
20       type ** data () const
21       uint size () const
22       virtual uint count () const
23       bool isEmpty () const
24       bool isNull () const
25       bool resize ( uint size )
26       bool insert ( uint i, const type * d )
27       bool remove ( uint i )
28       type * take ( uint i )
29       virtual void clear ()
30       bool fill ( const type * d, int size = -1 )
31       void sort ()
32       int bsearch ( const type * d ) const
33       int findRef ( const type * d, uint i = 0 ) const
34       int find ( const type * d, uint i = 0 ) const
35       uint containsRef ( const type * d ) const
36       uint contains ( const type * d ) const
37       type * operator[] ( int i ) const
38       type * at ( uint i ) const
39
40   Important Inherited Members
41       bool autoDelete () const
42       void setAutoDelete ( bool enable )
43
44   Protected Members
45       virtual int compareItems ( QPtrCollection::Item d1,
46           QPtrCollection::Item d2 )
47       virtual QDataStream & read ( QDataStream & s, QPtrCollection::Item &
48           item )
49       virtual QDataStream & write ( QDataStream & s, QPtrCollection::Item
50           item ) const
51

DESCRIPTION

53       The QPtrVector class is a template collection class that provides a
54       vector (array).
55
56       QValueVector is an STL-compatible alternative to this class.
57
58       QPtrVector is implemented as a template class. Defines a template
59       instance QPtrVector<X> to create a vector that contains pointers to X
60       (X*).
61
62       A vector is the same as an array. The main difference between
63       QPtrVector and QMemArray is that QPtrVector stores pointers to the
64       elements, whereas QMemArray stores the elements themselves (i.e.
65       QMemArray is value-based and QPtrVector is pointer-based).
66
67       Items are added to the vector using insert() or fill(). Items are
68       removed with remove(). You can get a pointer to an item at a particular
69       index position using at().
70
71       Unless otherwise stated, all functions that remove items from the
72       vector will also delete the element pointed to if auto-deletion is
73       enabled. By default, auto-deletion is disabled; see setAutoDelete().
74       This behaviour can be changed in a subclass by reimplementing the
75       virtual function deleteItem().
76
77       Functions that compare items (find() and sort() for example) will do so
78       using the virtual function compareItems(). The default implementation
79       of this function only compares the pointer values. Reimplement
80       compareItems() in a subclass to get searching and sorting based on the
81       item contents. You can perform a linear search for a pointer in the
82       vector using findRef(), or a binary search (of a sorted vector) using
83       bsearch(). You can count the number of times an item appears in the
84       vector with contains() or containsRef().
85
86       See also QMemArray and Non-GUI Classes.
87

MEMBER FUNCTION DOCUMENTATION

QPtrVector::QPtrVector ()

90       Constructs a null vector.
91
92       See also isNull().
93

QPtrVector::QPtrVector ( uint size )

95       Constructs an vector with room for size items. Makes a null vector if
96       size == 0.
97
98       All size positions in the vector are initialized to 0.
99
100       See also size(), resize(), and isNull().
101

QPtrVector::QPtrVector ( const QPtrVector<type> & v )

103       Constructs a copy of v. Only the pointers are copied (i.e. shallow
104       copy).
105

QPtrVector::~QPtrVector ()

107       Removes all items from the vector, and destroys the vector itself.
108
109       See also clear().
110

type * QPtrVector::at ( uint i ) const

112       Returns the item at position i, or 0 if there is no item at that
113       position. i must be less than size().
114

bool QPtrCollection::autoDelete () const

116       Returns the setting of the auto-delete option. The default is FALSE.
117
118       See also setAutoDelete().
119

int QPtrVector::bsearch ( const type * d ) const

121       In a sorted array, finds the first occurrence of d using a binary
122       search. For a sorted array, this is generally much faster than find(),
123       which performs a linear search.
124
125       Returns the position of d, or -1 if d could not be found. d must not be
126       0.
127
128       Compares items using the virtual function compareItems().
129
130       See also sort() and find().
131

void QPtrVector::clear () [virtual]

133       Removes all items from the vector, and destroys the vector itself.
134
135       The vector becomes a null vector.
136
137       See also isNull().
138
139       Reimplemented from QPtrCollection.
140

int QPtrVector::compareItems ( QPtrCollection::Item d1, QPtrCollection::Item

142       d2 ) [virtual protected]
143       This virtual function compares two list items.
144
145       Returns:
146
147       zero if d1 == d2
148
149       nonzero if d1 != d2
150
151       This function returns int rather than bool so that reimplementations
152       can return one of three values and use it to sort by:
153
154       0 if d1 == d2
155
156       > 0 (positive integer) if d1 > d2
157
158       < 0 (negative integer) if d1 < d2
159
160       The sort() and bsearch() functions require compareItems() to be
161       implemented as described here.
162
163       This function should not modify the vector because some const functions
164       call compareItems().
165

uint QPtrVector::contains ( const type * d ) const

167       Returns the number of occurrences of item d in the vector.
168
169       Compares items using the virtual function compareItems().
170
171       See also containsRef().
172

uint QPtrVector::containsRef ( const type * d ) const

174       Returns the number of occurrences of the item pointer d in the vector.
175
176       This function does not use compareItems() to compare items.
177
178       See also findRef().
179

uint QPtrVector::count () const [virtual]

181       Returns the number of items in the vector. The vector is empty if
182       count() == 0.
183
184       See also isEmpty(), size(), and isNull().
185
186       Reimplemented from QPtrCollection.
187

type ** QPtrVector::data () const

189       Returns a pointer to the actual vector data, which is an array of
190       type*.
191
192       The vector is a null vector if data() == 0 (null pointer).
193
194       See also isNull().
195

bool QPtrVector::fill ( const type * d, int size = -1 )

197       Inserts item d in all positions in the vector. Any existing items are
198       removed. If d is 0, the vector becomes empty.
199
200       If size >= 0, the vector is first resized to size. By default, size is
201       -1.
202
203       Returns TRUE if successful, i.e. size is the same as the current size,
204       or size is larger and the memory has successfully been allocated;
205       otherwise returns FALSE.
206
207       See also resize(), insert(), and isEmpty().
208

int QPtrVector::find ( const type * d, uint i = 0 ) const

210       Finds the first occurrence of item d in the vector using a linear
211       search. The search starts at position i, which must be less than
212       size(). i is by default 0; i.e. the search starts at the start of the
213       vector.
214
215       Returns the position of d, or -1 if d could not be found.
216
217       Compares items using the virtual function compareItems().
218
219       Use the much faster bsearch() to search a sorted vector.
220
221       See also findRef() and bsearch().
222

int QPtrVector::findRef ( const type * d, uint i = 0 ) const

224       Finds the first occurrence of the item pointer d in the vector using a
225       linear search. The search starts at position i, which must be less than
226       size(). i is by default 0; i.e. the search starts at the start of the
227       vector.
228
229       Returns the position of d, or -1 if d could not be found.
230
231       This function does not use compareItems() to compare items.
232
233       Use the much faster bsearch() to search a sorted vector.
234
235       See also find() and bsearch().
236

bool QPtrVector::insert ( uint i, const type * d )

238       Sets position i in the vector to contain the item d. i must be less
239       than size(). Any previous element in position i is removed.
240
241       See also at().
242

bool QPtrVector::isEmpty () const

244       Returns TRUE if the vector is empty; otherwise returns FALSE.
245
246       See also count().
247

bool QPtrVector::isNull () const

249       Returns TRUE if the vector is null; otherwise returns FALSE.
250
251       A null vector has size() == 0 and data() == 0.
252
253       See also size().
254

QPtrVector<type> & QPtrVector::operator= ( const QPtrVector<type> & v )

256       Assigns v to this vector and returns a reference to this vector.
257
258       This vector is first cleared and then all the items from v are copied
259       into the vector. Only the pointers are copied (i.e. shallow copy).
260
261       See also clear().
262

bool QPtrVector::operator== ( const QPtrVector<type> & v ) const

264       Returns TRUE if this vector and v are equal; otherwise returns FALSE.
265

type * QPtrVector::operator[] ( int i ) const

267       Returns the item at position i, or 0 if there is no item at that
268       position. i must be less than size().
269
270       Equivalent to at( i ).
271
272       See also at().
273

QDataStream & QPtrVector::read ( QDataStream & s, QPtrCollection::Item & item

275       ) [virtual protected]
276       Reads a vector item, item, from the stream s and returns a reference to
277       the stream.
278
279       The default implementation sets item to 0.
280
281       See also write().
282

bool QPtrVector::remove ( uint i )

284       Removes the item at position i in the vector, if there is one. i must
285       be less than size().
286
287       Returns TRUE if i is within range; otherwise returns FALSE.
288
289       See also take() and at().
290

bool QPtrVector::resize ( uint size )

292       Resizes (expands or shrinks) the vector to size elements. The vector
293       becomes a null vector if size == 0.
294
295       Any items at position size or beyond in the vector are removed. New
296       positions are initialized to 0.
297
298       Returns TRUE if successful, i.e. if the memory was successfully
299       allocated; otherwise returns FALSE.
300
301       See also size() and isNull().
302

void QPtrCollection::setAutoDelete ( bool enable )

304       Sets the collection to auto-delete its contents if enable is TRUE and
305       to never delete them if enable is FALSE.
306
307       If auto-deleting is turned on, all the items in a collection are
308       deleted when the collection itself is deleted. This is convenient if
309       the collection has the only pointer to the items.
310
311       The default setting is FALSE, for safety. If you turn it on, be careful
312       about copying the collection - you might find yourself with two
313       collections deleting the same items.
314
315       Note that the auto-delete setting may also affect other functions in
316       subclasses. For example, a subclass that has a remove() function will
317       remove the item from its data structure, and if auto-delete is enabled,
318       will also delete the item.
319
320       See also autoDelete().
321
322       Examples:
323

uint QPtrVector::size () const

325       Returns the size of the vector, i.e. the number of vector positions.
326       This is also the maximum number of items the vector can hold.
327
328       The vector is a null vector if size() == 0.
329
330       See also isNull(), resize(), and count().
331

void QPtrVector::sort ()

333       Sorts the items in ascending order. Any empty positions will be put
334       last.
335
336       Compares items using the virtual function compareItems().
337
338       See also bsearch().
339

type * QPtrVector::take ( uint i )

341       Returns the item at position i in the vector, and removes that item
342       from the vector. i must be less than size(). If there is no item at
343       position i, 0 is returned.
344
345       Unlike remove(), this function does not call deleteItem() for the
346       removed item.
347
348       See also remove() and at().
349

QDataStream & QPtrVector::write ( QDataStream & s, QPtrCollection::Item item )

351       const [virtual protected]
352       Writes a vector item, item, to the stream s and returns a reference to
353       the stream.
354
355       The default implementation does nothing.
356
357       See also read().
358
359

SEE ALSO

361       http://doc.trolltech.com/qptrvector.html
362       http://www.trolltech.com/faq/tech.html
363
365       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
366       license file included in the distribution for a complete license
367       statement.
368

AUTHOR

370       Generated automatically from the source code.
371

BUGS

373       If you find a bug in Qt, please report it as described in
374       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
375       help you. Thank you.
376
377       The definitive Qt documentation is provided in HTML format; it is
378       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
379       web browser. This man page is provided as a convenience for those users
380       who prefer man pages, although this format is not officially supported
381       by Trolltech.
382
383       If you find errors in this manual page, please report them to qt-
384       bugs@trolltech.com.  Please include the name of the manual page
385       (qptrvector.3qt) and the Qt version (3.3.8).
386
387
388
389Trolltech AS                    2 February 2007                QPtrVector(3qt)
Impressum