1QPtrList(3qt) QPtrList(3qt)
2
6 QPtrList - Template class that provides a list
7
9 #include <qptrlist.h>
10 Inherits QPtrCollection.
12 Inherited by QObjectList, QSortedList, and QStrList.
14 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 Important Inherited Members
60 bool autoDelete () const
61 void setAutoDelete ( bool enable )
62 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
72 The QPtrList class is a template class that provides a list.
73 QValueList is an STL-compatible alternative to this class.
75 Define a template instance QPtrList<X> to create a list that operates
77 on pointers to X (X*).
78 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 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 Example:
95 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 The output is
129 Doe, John earns 50000
131 Williams, Jane earns 80000
132 Jones, Tom earns 60000
133 Doe
134 Williams
135 Jones
136 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 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 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 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 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 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 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 See also QPtrListIterator, Collection Classes, and Non-GUI Classes.
177
180 Constructs an empty list.
181
183 Constructs a copy of list.
184 Each item in list is appended to this list. Only the pointers are
186 copied (shallow copy).
187
189 Removes all items from the list and destroys the list.
190 All list iterators that access this list will be reset.
192 See also setAutoDelete().
194
196 Inserts the item at the end of the list.
197 The inserted item becomes the current list item. This is equivalent to
199 insert( count(), item ).
200 item must not be 0.
202 See also insert(), current(), and prepend().
204 Examples:
206
208 Returns a pointer to the item at position index in the list, or 0 if
209 the index is out of range.
210 Sets the current list item to this item if index is valid. The valid
212 range is 0..(count() - 1) inclusive.
213 This function is very efficient. It starts scanning from the first
215 item, last item, or current item, whichever is closest to index.
216 See also current().
218 Examples:
220
222 This is an overloaded member function, provided for convenience. It
223 behaves essentially like the above function.
224 Returns the index of the current list item. The returned value is -1 if
226 the current item is 0.
227 See also current().
229
231 Returns the setting of the auto-delete option. The default is FALSE.
232 See also setAutoDelete().
234
236 Removes all items from the list.
237 The removed items are deleted if auto-deletion is enabled.
239 All list iterators that access this list will be reset.
241 See also remove(), take(), and setAutoDelete().
243 Reimplemented from QPtrCollection.
245
247 item2 ) [virtual protected]
248 This virtual function compares two list items.
249 Returns:
251 zero if item1 == item2
253 nonzero if item1 != item2
255 This function returns int rather than bool so that reimplementations
257 can return three values and use it to sort by:
258 0 if item1 == item2
260 > 0 (positive integer) if item1 > item2
262 < 0 (negative integer) if item1 < item2
264 inSort() requires that compareItems() is implemented as described here.
266 This function should not modify the list because some const functions
268 call compareItems().
269 The default implementation compares the pointers.
271
273 Returns the number of occurrences of item in the list.
274 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 This function does not affect the current list item.
280 See also containsRef() and compareItems().
282
284 Returns the number of occurrences of item in the list.
285 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 This function does not affect the current list item.
291 See also contains().
293
295 Returns the number of items in the list.
296 See also isEmpty().
298 Examples:
300 Reimplemented from QPtrCollection.
302
304 Returns a pointer to the current list item. The current item may be 0
305 (implies that the current index is -1).
306 See also at().
308
310 Returns a pointer to the current list node.
311 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 Warning: Do not call this function unless you are an expert.
317 See also removeNode(), takeNode(), and current().
319
321 Finds the first occurrence of item in the list.
322 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 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 See also findNext(), findRef(), compareItems(), and current().
333
335 Finds the next occurrence of item in the list, starting from the
336 current list item.
337 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 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 See also find(), findNextRef(), compareItems(), and current().
348
350 Finds the next occurrence of item in the list, starting from the
351 current list item.
352 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 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 See also findRef(), findNext(), and current().
363
365 Finds the first occurrence of item in the list.
366 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 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 See also findNextRef(), find(), and current().
377
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 See also getFirst(), last(), next(), prev(), and current().
383 Examples:
385
387 Returns a pointer to the first item in the list, or 0 if the list is
388 empty.
389 This function does not affect the current list item.
391 See also first() and getLast().
393
395 Returns a pointer to the last item in the list, or 0 if the list is
396 empty.
397 This function does not affect the current list item.
399 See also last() and getFirst().
401
403 Inserts the item at its sorted position in the list.
404 The sort order depends on the virtual compareItems() function. All
406 items must be inserted with inSort() to maintain the sorting order.
407 The inserted item becomes the current list item.
409 item must not be 0.
411 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 See also insert(), compareItems(), current(), and sort().
420
422 Inserts the item at position index in the list.
423 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 The inserted item becomes the current list item.
429 item must not be 0.
431 See also append(), current(), and replace().
433
435 Returns TRUE if the list is empty; otherwise returns FALSE.
436 See also count().
438
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 See also getLast(), first(), next(), prev(), and current().
444
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 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 See also first(), last(), prev(), and current().
454 Examples:
456
458 Compares this list with list. Returns TRUE if the lists contain
459 different data; otherwise returns FALSE.
460
462 Assigns list to this list and returns a reference to this list.
463 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
469 Compares this list with list. Returns TRUE if the lists contain the
470 same data; otherwise returns FALSE.
471
473 Inserts the item at the start of the list.
474 The inserted item becomes the current list item. This is equivalent to
476 insert( 0, item ).
477 item must not be 0.
479 See also append(), insert(), and current().
481
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 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 See also first(), last(), next(), and current().
491
493 [virtual protected]
494 Reads a list item from the stream s and returns a reference to the
495 stream.
496 The default implementation sets item to 0.
498 See also write().
500
502 Removes the item at position index in the list.
503 Returns TRUE if successful, i.e. if index is in range; otherwise
505 returns FALSE. The valid range is 0..(count() - 1) inclusive.
506 The removed item is deleted if auto-deletion is enabled.
508 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 All list iterators that refer to the removed item will be set to point
514 to the new current item.
515 See also take(), clear(), setAutoDelete(), current(), and removeRef().
517
519 This is an overloaded member function, provided for convenience. It
520 behaves essentially like the above function.
521 Removes the current list item.
523 Returns TRUE if successful, i.e. if the current item isn't 0; otherwise
525 returns FALSE.
526 The removed item is deleted if auto-deletion is enabled.
528 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 All list iterators that refer to the removed item will be set to point
535 to the new current item.
536 See also take(), clear(), setAutoDelete(), current(), and removeRef().
538
540 This is an overloaded member function, provided for convenience. It
541 behaves essentially like the above function.
542 Removes the first occurrence of item from the list.
544 Returns TRUE if successful, i.e. if item is in the list; otherwise
546 returns FALSE.
547 The removed item is deleted if auto-deletion is enabled.
549 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 If item is NULL then the current item is removed from the list.
555 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 All list iterators that refer to the removed item will be set to point
562 to the new current item.
563 See also removeRef(), take(), clear(), setAutoDelete(), compareItems(),
565 and current().
566
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 The removed item is deleted if auto-deletion is enabled.
572 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 All list iterators that refer to the removed item will be set to point
577 to the new current item.
578 See also removeLast(), setAutoDelete(), current(), and remove().
580
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 The removed item is deleted if auto-deletion is enabled.
586 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 All list iterators that refer to the removed item will be set to point
591 to the new current item.
592 See also removeFirst(), setAutoDelete(), and current().
594
596 Removes the node from the list.
597 This node must exist in the list, otherwise the program may crash.
599 The removed item is deleted if auto-deletion is enabled.
601 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 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 Warning: Do not call this function unless you are an expert.
610 See also takeNode(), currentNode(), remove(), and removeRef().
612
614 Removes the first occurrence of item from the list.
615 Returns TRUE if successful, i.e. if item is in the list; otherwise
617 returns FALSE.
618 The removed item is deleted if auto-deletion is enabled.
620 Equivalent to:
622 if ( list.findRef( item ) != -1 )
624 list.remove();
625 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 All list iterators that refer to the removed item will be set to point
632 to the new current item.
633 See also remove(), clear(), setAutoDelete(), and current().
635
637 Replaces the item at position index with the new item.
638 Returns TRUE if successful, i.e. index is in the range 0 to count()-1.
640 See also append(), current(), and insert().
642
644 Sets the collection to auto-delete its contents if enable is TRUE and
645 to never delete them if enable is FALSE.
646 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 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 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 See also autoDelete().
661 Examples:
663
665 Sorts the list by the result of the virtual compareItems() function.
666 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 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 See also inSort().
676
678 Takes the item at position index out of the list without deleting it
679 (even if auto-deletion is enabled).
680 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 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 All list iterators that refer to the taken item will be set to point to
690 the new current item.
691 See also remove(), clear(), and current().
693 Examples:
695
697 This is an overloaded member function, provided for convenience. It
698 behaves essentially like the above function.
699 Takes the current item out of the list without deleting it (even if
701 auto-deletion is enabled).
702 Returns a pointer to the item taken out of the list, or 0 if the
704 current item is 0.
705 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 All list iterators that refer to the taken item will be set to point to
712 the new current item.
713 See also remove(), clear(), and current().
715
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 This node must exist in the list, otherwise the program may crash.
722 The first item in the list becomes the new current list item.
724 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 Warning: Do not call this function unless you are an expert.
730 See also removeNode() and currentNode().
732
734 Stores all list items in the vector vec.
735 The vector must be of the same item type, otherwise the result will be
737 undefined.
738
740 const [virtual protected]
741 Writes a list item, item to the stream s and returns a reference to the
742 stream.
743 The default implementation does nothing.
745 See also read().
747
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
759 Generated automatically from the source code.
760
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 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 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).
775Trolltech AS 2 February 2007 QPtrList(3qt)