1QPtrList(3qt)                                                    QPtrList(3qt)
2
3
4

NAME

6       QPtrList - Template class that provides a list
7

SYNOPSIS

9       #include <qptrlist.h>
10
11       Inherits QPtrCollection.
12
13       Inherited by QObjectList, QSortedList, and QStrList.
14
15   Public Members
16       QPtrList ()
17       QPtrList ( const QPtrList<type> & list )
18       ~QPtrList ()
19       QPtrList<type> & operator= ( const QPtrList<type> & list )
20       bool operator== ( const QPtrList<type> & list ) const
21       bool operator!= ( const QPtrList<type> & list ) const
22       virtual uint count () const
23       bool isEmpty () const
24       bool insert ( uint index, const type * item )
25       void inSort ( const type * item )
26       void prepend ( const type * item )
27       void append ( const type * item )
28       bool remove ( uint index )
29       bool remove ()
30       bool remove ( const type * item )
31       bool removeRef ( const type * item )
32       void removeNode ( QLNode * node )
33       bool removeFirst ()
34       bool removeLast ()
35       type * take ( uint index )
36       type * take ()
37       type * takeNode ( QLNode * node )
38       virtual void clear ()
39       void sort ()
40       int find ( const type * item )
41       int findNext ( const type * item )
42       int findRef ( const type * item )
43       int findNextRef ( const type * item )
44       uint contains ( const type * item ) const
45       uint containsRef ( const type * item ) const
46       bool replace ( uint index, const type * item )
47       type * at ( uint index )
48       int at () const
49       type * current () const
50       QLNode * currentNode () const
51       type * getFirst () const
52       type * getLast () const
53       type * first ()
54       type * last ()
55       type * next ()
56       type * prev ()
57       void toVector ( QGVector * vec ) const
58
59   Important Inherited Members
60       bool autoDelete () const
61       void setAutoDelete ( bool enable )
62
63   Protected Members
64       virtual int compareItems ( QPtrCollection::Item item1,
65           QPtrCollection::Item item2 )
66       virtual QDataStream & read ( QDataStream & s, QPtrCollection::Item &
67           item )
68       virtual QDataStream & write ( QDataStream & s, QPtrCollection::Item
69           item ) const
70

DESCRIPTION

72       The QPtrList class is a template class that provides a list.
73
74       QValueList is an STL-compatible alternative to this class.
75
76       Define a template instance QPtrList<X> to create a list that operates
77       on pointers to X (X*).
78
79       The list class is indexable and has a current index and a current item.
80       The first item corresponds to index position 0. The current index is -1
81       if the current item is 0.
82
83       Items are inserted with prepend(), insert() or append(). Items are
84       removed with remove(), removeRef(), removeFirst() and removeLast(). You
85       can search for an item using find(), findNext(), findRef() or
86       findNextRef(). The list can be sorted with sort(). You can count the
87       number of occurrences of an item with contains() or containsRef(). You
88       can get a pointer to the current item with current(), to an item at a
89       particular index position in the list with at() or to the first or last
90       item with getFirst() and getLast(). You can also iterate over the list
91       with first(), last(), next() and prev() (which all update current()).
92       The list's deletion property is set with setAutoDelete().
93
94       Example:
95
96           class Employee
97           {
98           public:
99               Employee() : sn( 0 ) { }
100               Employee( const QString& forename, const QString& surname, int salary )
101                   : fn( forename ), sn( surname ), sal( salary )
102               { }
103               void setSalary( int salary ) { sal = salary; }
104               QString forename() const { return fn; }
105               QString surname() const { return sn; }
106               int salary() const { return sal; }
107           private:
108               QString fn;
109               QString sn;
110               int sal;
111           };
112           QPtrList<Employee> list;
113           list.setAutoDelete( TRUE ); // the list owns the objects
114           list.append( new Employee("John", "Doe", 50000) );
115           list.append( new Employee("Jane", "Williams", 80000) );
116           list.append( new Employee("Tom", "Jones", 60000) );
117           Employee *employee;
118           for ( employee = list.first(); employee; employee = list.next() )
119               cout << employee->surname().latin1() << ", " <<
120                       employee->forename().latin1() << " earns " <<
121                       employee->salary() << endl;
122           cout << endl;
123           // very inefficient for big lists
124           for ( uint i = 0; i < list.count(); ++i )
125               if ( list.at(i) )
126                   cout << list.at( i )->surname().latin1() << endl;
127
128       The output is
129
130           Doe, John earns 50000
131           Williams, Jane earns 80000
132           Jones, Tom earns 60000
133           Doe
134           Williams
135           Jones
136
137       QPtrList has several member functions for traversing the list, but
138       using a QPtrListIterator can be more practical. Multiple list iterators
139       may traverse the same list, independently of each other and of the
140       current list item.
141
142       In the example above we make the call setAutoDelete(TRUE). Enabling
143       auto-deletion tells the list to delete items that are removed. The
144       default is to not delete items when they are removed but this would
145       cause a memory leak in the example because there are no other
146       references to the list items.
147
148       When inserting an item into a list only the pointer is copied, not the
149       item itself, i.e. a shallow copy. It is possible to make the list copy
150       all of the item's data (deep copy) when an item is inserted. insert(),
151       inSort() and append() call the virtual function
152       QPtrCollection::newItem() for the item to be inserted. Inherit a list
153       and reimplement newItem() to have deep copies.
154
155       When removing an item from a list, the virtual function
156       QPtrCollection::deleteItem() is called. QPtrList's default
157       implementation is to delete the item if auto-deletion is enabled.
158
159       The virtual function compareItems() can be reimplemented to compare two
160       list items. This function is called from all list functions that need
161       to compare list items, for instance remove(const type*). If you only
162       want to deal with pointers, there are functions that compare pointers
163       instead, for instance removeRef(const type*). These functions are
164       somewhat faster than those that call compareItems().
165
166       List items are stored as void* in an internal QLNode, which also holds
167       pointers to the next and previous list items. The functions
168       currentNode(), removeNode(), and takeNode() operate directly on the
169       QLNode, but they should be used with care. The data component of the
170       node is available through QLNode::getData().
171
172       The QStrList class defined in qstrlist.h is a list of char*. It
173       reimplements newItem(), deleteItem() and compareItems(). (But see
174       QStringList for a list of Unicode QStrings.)
175
176       See also QPtrListIterator, Collection Classes, and Non-GUI Classes.
177

MEMBER FUNCTION DOCUMENTATION

QPtrList::QPtrList ()

180       Constructs an empty list.
181

QPtrList::QPtrList ( const QPtrList<type> & list )

183       Constructs a copy of list.
184
185       Each item in list is appended to this list. Only the pointers are
186       copied (shallow copy).
187

QPtrList::~QPtrList ()

189       Removes all items from the list and destroys the list.
190
191       All list iterators that access this list will be reset.
192
193       See also setAutoDelete().
194

void QPtrList::append ( const type * item )

196       Inserts the item at the end of the list.
197
198       The inserted item becomes the current list item. This is equivalent to
199       insert( count(), item ).
200
201       item must not be 0.
202
203       See also insert(), current(), and prepend().
204
205       Examples:
206

type * QPtrList::at ( uint index )

208       Returns a pointer to the item at position index in the list, or 0 if
209       the index is out of range.
210
211       Sets the current list item to this item if index is valid. The valid
212       range is 0..(count() - 1) inclusive.
213
214       This function is very efficient. It starts scanning from the first
215       item, last item, or current item, whichever is closest to index.
216
217       See also current().
218
219       Examples:
220

int QPtrList::at () const

222       This is an overloaded member function, provided for convenience. It
223       behaves essentially like the above function.
224
225       Returns the index of the current list item. The returned value is -1 if
226       the current item is 0.
227
228       See also current().
229

bool QPtrCollection::autoDelete () const

231       Returns the setting of the auto-delete option. The default is FALSE.
232
233       See also setAutoDelete().
234

void QPtrList::clear () [virtual]

236       Removes all items from the list.
237
238       The removed items are deleted if auto-deletion is enabled.
239
240       All list iterators that access this list will be reset.
241
242       See also remove(), take(), and setAutoDelete().
243
244       Reimplemented from QPtrCollection.
245

int QPtrList::compareItems ( QPtrCollection::Item item1, QPtrCollection::Item

247       item2 ) [virtual protected]
248       This virtual function compares two list items.
249
250       Returns:
251
252       zero if item1 == item2
253
254       nonzero if item1 != item2
255
256       This function returns int rather than bool so that reimplementations
257       can return three values and use it to sort by:
258
259       0 if item1 == item2
260
261       > 0 (positive integer) if item1 > item2
262
263       < 0 (negative integer) if item1 < item2
264
265       inSort() requires that compareItems() is implemented as described here.
266
267       This function should not modify the list because some const functions
268       call compareItems().
269
270       The default implementation compares the pointers.
271

uint QPtrList::contains ( const type * item ) const

273       Returns the number of occurrences of item in the list.
274
275       The compareItems() function is called when looking for the item in the
276       list. If compareItems() is not reimplemented, it is more efficient to
277       call containsRef().
278
279       This function does not affect the current list item.
280
281       See also containsRef() and compareItems().
282

uint QPtrList::containsRef ( const type * item ) const

284       Returns the number of occurrences of item in the list.
285
286       Calling this function is much faster than contains() because contains()
287       compares item with each list item using compareItems(), whereas his
288       function only compares the pointers.
289
290       This function does not affect the current list item.
291
292       See also contains().
293

uint QPtrList::count () const [virtual]

295       Returns the number of items in the list.
296
297       See also isEmpty().
298
299       Examples:
300
301       Reimplemented from QPtrCollection.
302

type * QPtrList::current () const

304       Returns a pointer to the current list item. The current item may be 0
305       (implies that the current index is -1).
306
307       See also at().
308

QLNode * QPtrList::currentNode () const

310       Returns a pointer to the current list node.
311
312       The node can be kept and removed later using removeNode(). The
313       advantage is that the item can be removed directly without searching
314       the list.
315
316       Warning: Do not call this function unless you are an expert.
317
318       See also removeNode(), takeNode(), and current().
319

int QPtrList::find ( const type * item )

321       Finds the first occurrence of item in the list.
322
323       If the item is found, the list sets the current item to point to the
324       found item and returns the index of this item. If the item is not
325       found, the list sets the current item to 0, the current index to -1,
326       and returns -1.
327
328       The compareItems() function is called when searching for the item in
329       the list. If compareItems() is not reimplemented, it is more efficient
330       to call findRef().
331
332       See also findNext(), findRef(), compareItems(), and current().
333

int QPtrList::findNext ( const type * item )

335       Finds the next occurrence of item in the list, starting from the
336       current list item.
337
338       If the item is found, the list sets the current item to point to the
339       found item and returns the index of this item. If the item is not
340       found, the list sets the current item to 0, the current index to -1,
341       and returns -1.
342
343       The compareItems() function is called when searching for the item in
344       the list. If compareItems() is not reimplemented, it is more efficient
345       to call findNextRef().
346
347       See also find(), findNextRef(), compareItems(), and current().
348

int QPtrList::findNextRef ( const type * item )

350       Finds the next occurrence of item in the list, starting from the
351       current list item.
352
353       If the item is found, the list sets the current item to point to the
354       found item and returns the index of this item. If the item is not
355       found, the list sets the current item to 0, the current index to -1,
356       and returns -1.
357
358       Calling this function is much faster than findNext() because findNext()
359       compares item with each list item using compareItems(), whereas this
360       function only compares the pointers.
361
362       See also findRef(), findNext(), and current().
363

int QPtrList::findRef ( const type * item )

365       Finds the first occurrence of item in the list.
366
367       If the item is found, the list sets the current item to point to the
368       found item and returns the index of this item. If the item is not
369       found, the list sets the current item to 0, the current index to -1,
370       and returns -1.
371
372       Calling this function is much faster than find() because find()
373       compares item with each list item using compareItems(), whereas this
374       function only compares the pointers.
375
376       See also findNextRef(), find(), and current().
377

type * QPtrList::first ()

379       Returns a pointer to the first item in the list and makes this the
380       current list item; returns 0 if the list is empty.
381
382       See also getFirst(), last(), next(), prev(), and current().
383
384       Examples:
385

type * QPtrList::getFirst () const

387       Returns a pointer to the first item in the list, or 0 if the list is
388       empty.
389
390       This function does not affect the current list item.
391
392       See also first() and getLast().
393

type * QPtrList::getLast () const

395       Returns a pointer to the last item in the list, or 0 if the list is
396       empty.
397
398       This function does not affect the current list item.
399
400       See also last() and getFirst().
401

void QPtrList::inSort ( const type * item )

403       Inserts the item at its sorted position in the list.
404
405       The sort order depends on the virtual compareItems() function. All
406       items must be inserted with inSort() to maintain the sorting order.
407
408       The inserted item becomes the current list item.
409
410       item must not be 0.
411
412       Warning: Using inSort() is slow. An alternative, especially if you have
413       lots of items, is to simply append() or insert() them and then use
414       sort(). inSort() takes up to O(n) compares. That means inserting n
415       items in your list will need O(n^2) compares whereas sort() only needs
416       O(n*log n) for the same task. So use inSort() only if you already have
417       a presorted list and want to insert just a few additional items.
418
419       See also insert(), compareItems(), current(), and sort().
420

bool QPtrList::insert ( uint index, const type * item )

422       Inserts the item at position index in the list.
423
424       Returns TRUE if successful, i.e. if index is in range; otherwise
425       returns FALSE. The valid range is 0 to count() (inclusively). The item
426       is appended if index == count().
427
428       The inserted item becomes the current list item.
429
430       item must not be 0.
431
432       See also append(), current(), and replace().
433

bool QPtrList::isEmpty () const

435       Returns TRUE if the list is empty; otherwise returns FALSE.
436
437       See also count().
438

type * QPtrList::last ()

440       Returns a pointer to the last item in the list and makes this the
441       current list item; returns 0 if the list is empty.
442
443       See also getLast(), first(), next(), prev(), and current().
444

type * QPtrList::next ()

446       Returns a pointer to the item succeeding the current item. Returns 0 if
447       the current item is 0 or equal to the last item.
448
449       Makes the succeeding item current. If the current item before this
450       function call was the last item, the current item will be set to 0. If
451       the current item was 0, this function does nothing.
452
453       See also first(), last(), prev(), and current().
454
455       Examples:
456

bool QPtrList::operator!= ( const QPtrList<type> & list ) const

458       Compares this list with list. Returns TRUE if the lists contain
459       different data; otherwise returns FALSE.
460

QPtrList<type> & QPtrList::operator= ( const QPtrList<type> & list )

462       Assigns list to this list and returns a reference to this list.
463
464       This list is first cleared and then each item in list is appended to
465       this list. Only the pointers are copied (shallow copy) unless newItem()
466       has been reimplemented.
467

bool QPtrList::operator== ( const QPtrList<type> & list ) const

469       Compares this list with list. Returns TRUE if the lists contain the
470       same data; otherwise returns FALSE.
471

void QPtrList::prepend ( const type * item )

473       Inserts the item at the start of the list.
474
475       The inserted item becomes the current list item. This is equivalent to
476       insert( 0, item ).
477
478       item must not be 0.
479
480       See also append(), insert(), and current().
481

type * QPtrList::prev ()

483       Returns a pointer to the item preceding the current item. Returns 0 if
484       the current item is 0 or equal to the first item.
485
486       Makes the preceding item current. If the current item before this
487       function call was the first item, the current item will be set to 0. If
488       the current item was 0, this function does nothing.
489
490       See also first(), last(), next(), and current().
491

QDataStream & QPtrList::read ( QDataStream & s, QPtrCollection::Item & item )

493       [virtual protected]
494       Reads a list item from the stream s and returns a reference to the
495       stream.
496
497       The default implementation sets item to 0.
498
499       See also write().
500

bool QPtrList::remove ( uint index )

502       Removes the item at position index in the list.
503
504       Returns TRUE if successful, i.e. if index is in range; otherwise
505       returns FALSE. The valid range is 0..(count() - 1) inclusive.
506
507       The removed item is deleted if auto-deletion is enabled.
508
509       The item after the removed item becomes the new current list item if
510       the removed item is not the last item in the list. If the last item is
511       removed, the new last item becomes the current item.
512
513       All list iterators that refer to the removed item will be set to point
514       to the new current item.
515
516       See also take(), clear(), setAutoDelete(), current(), and removeRef().
517

bool QPtrList::remove ()

519       This is an overloaded member function, provided for convenience. It
520       behaves essentially like the above function.
521
522       Removes the current list item.
523
524       Returns TRUE if successful, i.e. if the current item isn't 0; otherwise
525       returns FALSE.
526
527       The removed item is deleted if auto-deletion is enabled.
528
529       The item after the removed item becomes the new current list item if
530       the removed item is not the last item in the list. If the last item is
531       removed, the new last item becomes the current item. The current item
532       is set to 0 if the list becomes empty.
533
534       All list iterators that refer to the removed item will be set to point
535       to the new current item.
536
537       See also take(), clear(), setAutoDelete(), current(), and removeRef().
538

bool QPtrList::remove ( const type * item )

540       This is an overloaded member function, provided for convenience. It
541       behaves essentially like the above function.
542
543       Removes the first occurrence of item from the list.
544
545       Returns TRUE if successful, i.e. if item is in the list; otherwise
546       returns FALSE.
547
548       The removed item is deleted if auto-deletion is enabled.
549
550       The compareItems() function is called when searching for the item in
551       the list. If compareItems() is not reimplemented, it is more efficient
552       to call removeRef().
553
554       If item is NULL then the current item is removed from the list.
555
556       The item after the removed item becomes the new current list item if
557       the removed item is not the last item in the list. If the last item is
558       removed, the new last item becomes the current item. The current item
559       is set to 0 if the list becomes empty.
560
561       All list iterators that refer to the removed item will be set to point
562       to the new current item.
563
564       See also removeRef(), take(), clear(), setAutoDelete(), compareItems(),
565       and current().
566

bool QPtrList::removeFirst ()

568       Removes the first item from the list. Returns TRUE if successful, i.e.
569       if the list isn't empty; otherwise returns FALSE.
570
571       The removed item is deleted if auto-deletion is enabled.
572
573       The first item in the list becomes the new current list item. The
574       current item is set to 0 if the list becomes empty.
575
576       All list iterators that refer to the removed item will be set to point
577       to the new current item.
578
579       See also removeLast(), setAutoDelete(), current(), and remove().
580

bool QPtrList::removeLast ()

582       Removes the last item from the list. Returns TRUE if successful, i.e.
583       if the list isn't empty; otherwise returns FALSE.
584
585       The removed item is deleted if auto-deletion is enabled.
586
587       The last item in the list becomes the new current list item. The
588       current item is set to 0 if the list becomes empty.
589
590       All list iterators that refer to the removed item will be set to point
591       to the new current item.
592
593       See also removeFirst(), setAutoDelete(), and current().
594

void QPtrList::removeNode ( QLNode * node )

596       Removes the node from the list.
597
598       This node must exist in the list, otherwise the program may crash.
599
600       The removed item is deleted if auto-deletion is enabled.
601
602       The first item in the list will become the new current list item. The
603       current item is set to 0 if the list becomes empty.
604
605       All list iterators that refer to the removed item will be set to point
606       to the item succeeding this item or to the preceding item if the
607       removed item was the last item.
608
609       Warning: Do not call this function unless you are an expert.
610
611       See also takeNode(), currentNode(), remove(), and removeRef().
612

bool QPtrList::removeRef ( const type * item )

614       Removes the first occurrence of item from the list.
615
616       Returns TRUE if successful, i.e. if item is in the list; otherwise
617       returns FALSE.
618
619       The removed item is deleted if auto-deletion is enabled.
620
621       Equivalent to:
622
623               if ( list.findRef( item ) != -1 )
624                   list.remove();
625
626       The item after the removed item becomes the new current list item if
627       the removed item is not the last item in the list. If the last item is
628       removed, the new last item becomes the current item. The current item
629       is set to 0 if the list becomes empty.
630
631       All list iterators that refer to the removed item will be set to point
632       to the new current item.
633
634       See also remove(), clear(), setAutoDelete(), and current().
635

bool QPtrList::replace ( uint index, const type * item )

637       Replaces the item at position index with the new item.
638
639       Returns TRUE if successful, i.e. index is in the range 0 to count()-1.
640
641       See also append(), current(), and insert().
642

void QPtrCollection::setAutoDelete ( bool enable )

644       Sets the collection to auto-delete its contents if enable is TRUE and
645       to never delete them if enable is FALSE.
646
647       If auto-deleting is turned on, all the items in a collection are
648       deleted when the collection itself is deleted. This is convenient if
649       the collection has the only pointer to the items.
650
651       The default setting is FALSE, for safety. If you turn it on, be careful
652       about copying the collection - you might find yourself with two
653       collections deleting the same items.
654
655       Note that the auto-delete setting may also affect other functions in
656       subclasses. For example, a subclass that has a remove() function will
657       remove the item from its data structure, and if auto-delete is enabled,
658       will also delete the item.
659
660       See also autoDelete().
661
662       Examples:
663

void QPtrList::sort ()

665       Sorts the list by the result of the virtual compareItems() function.
666
667       The heap sort algorithm is used for sorting. It sorts n items with
668       O(n*log n) comparisons. This is the asymptotic optimal solution of the
669       sorting problem.
670
671       If the items in your list support operator<() and operator==(), you
672       might be better off with QSortedList because it implements the
673       compareItems() function for you using these two operators.
674
675       See also inSort().
676

type * QPtrList::take ( uint index )

678       Takes the item at position index out of the list without deleting it
679       (even if auto-deletion is enabled).
680
681       Returns a pointer to the item taken out of the list, or 0 if the index
682       is out of range. The valid range is 0..(count() - 1) inclusive.
683
684       The item after the removed item becomes the new current list item if
685       the removed item is not the last item in the list. If the last item is
686       removed, the new last item becomes the current item. The current item
687       is set to 0 if the list becomes empty.
688
689       All list iterators that refer to the taken item will be set to point to
690       the new current item.
691
692       See also remove(), clear(), and current().
693
694       Examples:
695

type * QPtrList::take ()

697       This is an overloaded member function, provided for convenience. It
698       behaves essentially like the above function.
699
700       Takes the current item out of the list without deleting it (even if
701       auto-deletion is enabled).
702
703       Returns a pointer to the item taken out of the list, or 0 if the
704       current item is 0.
705
706       The item after the removed item becomes the new current list item if
707       the removed item is not the last item in the list. If the last item is
708       removed, the new last item becomes the current item. The current item
709       is set to 0 if the list becomes empty.
710
711       All list iterators that refer to the taken item will be set to point to
712       the new current item.
713
714       See also remove(), clear(), and current().
715

type * QPtrList::takeNode ( QLNode * node )

717       Takes the node out of the list without deleting its item (even if auto-
718       deletion is enabled). Returns a pointer to the item taken out of the
719       list.
720
721       This node must exist in the list, otherwise the program may crash.
722
723       The first item in the list becomes the new current list item.
724
725       All list iterators that refer to the taken item will be set to point to
726       the item succeeding this item or to the preceding item if the taken
727       item was the last item.
728
729       Warning: Do not call this function unless you are an expert.
730
731       See also removeNode() and currentNode().
732

void QPtrList::toVector ( QGVector * vec ) const

734       Stores all list items in the vector vec.
735
736       The vector must be of the same item type, otherwise the result will be
737       undefined.
738

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

740       const [virtual protected]
741       Writes a list item, item to the stream s and returns a reference to the
742       stream.
743
744       The default implementation does nothing.
745
746       See also read().
747
748

SEE ALSO

750       http://doc.trolltech.com/qptrlist.html
751       http://www.trolltech.com/faq/tech.html
752
754       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
755       license file included in the distribution for a complete license
756       statement.
757

AUTHOR

759       Generated automatically from the source code.
760

BUGS

762       If you find a bug in Qt, please report it as described in
763       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
764       help you. Thank you.
765
766       The definitive Qt documentation is provided in HTML format; it is
767       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
768       web browser. This man page is provided as a convenience for those users
769       who prefer man pages, although this format is not officially supported
770       by Trolltech.
771
772       If you find errors in this manual page, please report them to qt-
773       bugs@trolltech.com.  Please include the name of the manual page
774       (qptrlist.3qt) and the Qt version (3.3.8).
775
776
777
778Trolltech AS                    2 February 2007                  QPtrList(3qt)
Impressum