|
1 /**************************************************************************** |
|
2 ** |
|
3 ** |
|
4 ** QList and QListIterator class documentation |
|
5 ** |
|
6 ** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. |
|
7 ** |
|
8 ** This file is part of the Qt GUI Toolkit. |
|
9 ** |
|
10 ** This file may be distributed under the terms of the Q Public License |
|
11 ** as defined by Trolltech AS of Norway and appearing in the file |
|
12 ** LICENSE.QPL included in the packaging of this file. |
|
13 ** |
|
14 ** This file may be distributed and/or modified under the terms of the |
|
15 ** GNU General Public License version 2 as published by the Free Software |
|
16 ** Foundation and appearing in the file LICENSE.GPL included in the |
|
17 ** packaging of this file. |
|
18 ** |
|
19 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition |
|
20 ** licenses may use this file in accordance with the Qt Commercial License |
|
21 ** Agreement provided with the Software. |
|
22 ** |
|
23 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE |
|
24 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
|
25 ** |
|
26 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for |
|
27 ** information about Qt Commercial License Agreements. |
|
28 ** See http://www.trolltech.com/qpl/ for QPL licensing information. |
|
29 ** See http://www.trolltech.com/gpl/ for GPL licensing information. |
|
30 ** |
|
31 ** Contact info@trolltech.com if any conditions of this licensing are |
|
32 ** not clear to you. |
|
33 ** |
|
34 **********************************************************************/ |
|
35 |
|
36 |
|
37 /***************************************************************************** |
|
38 QList documentation |
|
39 *****************************************************************************/ |
|
40 |
|
41 /*! |
|
42 \class QList qlist.h |
|
43 \brief The QList class is a template class that provides doubly linked lists. |
|
44 |
|
45 \ingroup collection |
|
46 \ingroup tools |
|
47 |
|
48 In Qt 2.0 QList is only implemented as a template class. Define a |
|
49 template instance QList\<X\> to create a list that operates on pointers |
|
50 to X, or X*. |
|
51 |
|
52 Example: |
|
53 \code |
|
54 #include <qlist.h> |
|
55 #include <qstring.h> |
|
56 #include <stdio.h> |
|
57 |
|
58 class Employee |
|
59 { |
|
60 public: |
|
61 Employee( const QString& name, int salary ) { n=name; s=salary; } |
|
62 QString name() const { return n; } |
|
63 int salary() const { return s; } |
|
64 private: |
|
65 QString n; |
|
66 int s; |
|
67 }; |
|
68 |
|
69 void main() |
|
70 { |
|
71 QList<Employee> list; // list of pointers to Employee |
|
72 list.setAutoDelete( TRUE ); // delete items when they are removed |
|
73 |
|
74 list.append( new Employee("Bill", 50000) ); |
|
75 list.append( new Employee("Steve",80000) ); |
|
76 list.append( new Employee("Ron", 60000) ); |
|
77 |
|
78 Employee *emp; |
|
79 for ( emp=list.first(); emp != 0; emp=list.next() ) |
|
80 printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); |
|
81 } |
|
82 \endcode |
|
83 |
|
84 Program output: |
|
85 \code |
|
86 Bill earns 50000 |
|
87 Steve earns 80000 |
|
88 Ron earns 60000 |
|
89 \endcode |
|
90 |
|
91 The list class is indexable and has a \link at() current index\endlink |
|
92 and a \link current() current item\endlink. The first item corresponds |
|
93 to index 0. The current index is -1 if the current item is null. |
|
94 |
|
95 QList has several member functions for traversing the list, but using |
|
96 a QListIterator can be more practical. Multiple list iterators may |
|
97 traverse the same list, independent of each other and independent of |
|
98 the current list item. |
|
99 |
|
100 In the example above, we make the call setAutoDelete(TRUE). |
|
101 Enabling auto-deletion tells the list to delete items that are removed |
|
102 from the list. The default is to not delete items when they are |
|
103 removed, but that would cause a memory leak in our example since we have |
|
104 no other references to the list items. |
|
105 |
|
106 List items are stored as \c void* in an internal QLNode, which also |
|
107 holds pointers to the next and previous list items. The functions |
|
108 currentNode(), removeNode() and takeNode() operate directly on the |
|
109 QLNode, but they should be used with care. |
|
110 |
|
111 When inserting an item into a list, only the pointer is copied, not the |
|
112 item itself. This is called a shallow copy. It is possible to make the |
|
113 list copy all of the item's data (known as a deep copy) when an item is |
|
114 inserted. insert(), inSort() and append() call the virtual function |
|
115 QCollection::newItem() for the item to be inserted. |
|
116 Inherit a list and reimplement it if you want deep copies. |
|
117 |
|
118 When removing an item from a list, the virtual function |
|
119 QCollection::deleteItem() is called. QList's default implementation |
|
120 is to delete the item if auto-deletion is enabled. |
|
121 |
|
122 The virtual function QGList::compareItems() can be reimplemented to |
|
123 compare two list items. This function is called from all list functions |
|
124 that need to compare list items, for instance remove(const type*). |
|
125 If you only want to deal with pointers, there are functions that |
|
126 compare pointers instead, for instance removeRef(const type*). |
|
127 These functions are somewhat faster than those that call compareItems(). |
|
128 |
|
129 The QStrList class in qstrlist.h is a list of \c char*. QStrList is |
|
130 a good example of a list that reimplements newItem(), deleteItem() and |
|
131 compareItems() |
|
132 |
|
133 \sa QListIterator, \link collection.html Collection Classes\endlink |
|
134 */ |
|
135 |
|
136 |
|
137 /*! |
|
138 \fn QList::QList() |
|
139 Constructs an empty list. |
|
140 */ |
|
141 |
|
142 /*! |
|
143 \fn QList::QList( const QList<type> &list ) |
|
144 Constructs a copy of \e list. |
|
145 |
|
146 Each item in \e list is \link append() appended\endlink to this list. |
|
147 Only the pointers are copied (shallow copy). |
|
148 */ |
|
149 |
|
150 /*! |
|
151 \fn QList::~QList() |
|
152 Removes all items from the list and destroys the list. |
|
153 |
|
154 All list iterators that access this list will be reset. |
|
155 |
|
156 \sa setAutoDelete() |
|
157 */ |
|
158 |
|
159 /*! |
|
160 \fn QList<type> &QList::operator=(const QList<type> &list) |
|
161 Assigns \e list to this list and returns a reference to this list. |
|
162 |
|
163 This list is first cleared, then each item in \e list is |
|
164 \link append() appended\endlink to this list. Only the pointers are copied |
|
165 (shallow copy), unless newItem() has been reimplemented(). |
|
166 */ |
|
167 |
|
168 /*! |
|
169 \fn bool QList::operator==(const QList<type> &list ) const |
|
170 |
|
171 Compares this list with \a list. Retruns TRUE if the lists |
|
172 contain the same data, else FALSE. |
|
173 */ |
|
174 |
|
175 /*! |
|
176 \fn uint QList::count() const |
|
177 Returns the number of items in the list. |
|
178 \sa isEmpty() |
|
179 */ |
|
180 |
|
181 /*! |
|
182 \fn void QList::sort() |
|
183 |
|
184 Sorts the list by the result of the virtual compareItems() function. |
|
185 |
|
186 The Heap-Sort algorithm is used for sorting. It sorts n items with |
|
187 O(n*log n) compares. This is the asymptotic optimal solution of the |
|
188 sorting problem. |
|
189 |
|
190 If the items in your list support operator< and operator== then you |
|
191 might be better off with QSortedList since it implements the |
|
192 compareItems() function for you using these two operators. |
|
193 |
|
194 \sa inSort() |
|
195 */ |
|
196 |
|
197 /*! |
|
198 \fn bool QList::isEmpty() const |
|
199 Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE |
|
200 otherwise. |
|
201 \sa count() |
|
202 */ |
|
203 |
|
204 /*! |
|
205 \fn bool QList::insert( uint index, const type *item ) |
|
206 Inserts the \e item at the position \e index in the list. |
|
207 |
|
208 Returns TRUE if successful, or FALSE if \e index is out of range. |
|
209 The valid range is <code>0 .. count()</code> inclusive. |
|
210 The item is appended if \e index == count(). |
|
211 |
|
212 The inserted item becomes the current list item. |
|
213 |
|
214 The \e item must not be a null pointer. |
|
215 |
|
216 \sa append(), current() |
|
217 */ |
|
218 |
|
219 /*! |
|
220 \fn void QList::inSort( const type *item ) |
|
221 Inserts the \e item at its sorted position in the list. |
|
222 |
|
223 The sort order depends on the virtual QGList::compareItems() function. |
|
224 All items must be inserted with inSort() to maintain the sorting order. |
|
225 |
|
226 The inserted item becomes the current list item. |
|
227 |
|
228 The \e item must not be a null pointer. |
|
229 |
|
230 Please note that inSort is slow. If you want to insert lots of items |
|
231 in a list and sort after inserting then you should use sort(). |
|
232 inSort() takes up to O(n) compares. That means inserting n items in |
|
233 your list will need O(n^2) compares while sort() only needs O(n*logn) |
|
234 for the same task. So you inSort() only if you already have a pre-sorted |
|
235 list and want to insert only few additional items. |
|
236 |
|
237 \sa insert(), QGList::compareItems(), current(), sort() |
|
238 */ |
|
239 |
|
240 /*! |
|
241 \fn void QList::append( const type *item ) |
|
242 Inserts the \e item at the end of the list. |
|
243 |
|
244 The inserted item becomes the current list item. |
|
245 This is equivalent to \c insert(count(),item). |
|
246 |
|
247 |
|
248 The \e item must not be a null pointer. |
|
249 |
|
250 \sa insert(), current(), prepend() |
|
251 */ |
|
252 |
|
253 /*! |
|
254 \fn void QList::prepend( const type *item ) |
|
255 |
|
256 Inserts the \e item at the start of the list. |
|
257 |
|
258 The inserted item becomes the current list item. |
|
259 This is equivalent to \c insert(0,item). |
|
260 |
|
261 The \e item must not be a null pointer. |
|
262 |
|
263 \sa append(), insert(), current() |
|
264 */ |
|
265 |
|
266 /*! |
|
267 \fn bool QList::remove( uint index ) |
|
268 Removes the item at position \e index in the list. |
|
269 |
|
270 Returns TRUE if successful, or FALSE if \e index is out of range. |
|
271 The valid range is <code>0 .. (count() - 1)</code> inclusive. |
|
272 |
|
273 The removed item is deleted if \link QCollection::setAutoDelete() |
|
274 auto-deletion\endlink is enabled. |
|
275 |
|
276 The item after the removed item becomes the new current list item if |
|
277 the removed item is not the last item in the list. If the last item |
|
278 is removed, the new last item becomes the current item in Qt 2.x. |
|
279 In 3.0, the current item will be set to null. The current item is |
|
280 set to null if the list becomes empty. |
|
281 |
|
282 All list iterators that refer to the removed item will be set to point |
|
283 to the new current item. |
|
284 |
|
285 \sa take(), clear(), setAutoDelete(), current() removeRef() |
|
286 */ |
|
287 |
|
288 /*! |
|
289 \fn bool QList::remove() |
|
290 Removes the current list item. |
|
291 |
|
292 Returns TRUE if successful, or FALSE if the current item is null. |
|
293 |
|
294 The removed item is deleted if \link QCollection::setAutoDelete() |
|
295 auto-deletion\endlink is enabled. |
|
296 |
|
297 The item after the removed item becomes the new current list item if |
|
298 the removed item is not the last item in the list. If the last item |
|
299 is removed, the new last item becomes the current item in Qt 2.x. |
|
300 In 3.0, the current item will be set to null. The current item is |
|
301 set to null if the list becomes empty. |
|
302 |
|
303 All list iterators that refer to the removed item will be set to point |
|
304 to the new current item. |
|
305 |
|
306 \sa take(), clear(), setAutoDelete(), current() removeRef() |
|
307 */ |
|
308 |
|
309 /*! |
|
310 \fn bool QList::remove( const type *item ) |
|
311 Removes the first occurrence of \e item from the list. |
|
312 |
|
313 Returns TRUE if successful, or FALSE if the item could not be found in the |
|
314 list. |
|
315 |
|
316 The removed item is deleted if \link QCollection::setAutoDelete() |
|
317 auto-deletion\endlink is enabled. |
|
318 |
|
319 The compareItems() function is called when searching for the item |
|
320 in the list. If compareItems() is not reimplemented, it is more |
|
321 efficient to call removeRef(). |
|
322 |
|
323 The item after the removed item becomes the new current list item if |
|
324 the removed item is not the last item in the list. If the last item |
|
325 is removed, the new last item becomes the current item in Qt 2.x. |
|
326 In 3.0, the current item will be set to null. The current item is |
|
327 set to null if the list becomes empty. |
|
328 |
|
329 All list iterators that refer to the removed item will be set to point |
|
330 to the new current item. |
|
331 |
|
332 \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), current() |
|
333 */ |
|
334 |
|
335 /*! |
|
336 \fn bool QList::removeRef( const type *item ) |
|
337 Removes the first occurrence of \e item from the list. |
|
338 |
|
339 Returns TRUE if successful, or FALSE if the item cannot be found in the |
|
340 list. |
|
341 |
|
342 The removed item is deleted if \link QCollection::setAutoDelete() |
|
343 auto-deletion\endlink is enabled. |
|
344 |
|
345 The list is scanned until the pointer \e item is found. It is removed |
|
346 if it is found. |
|
347 |
|
348 Equivalent to: |
|
349 \code |
|
350 if ( list.findRef(item) != -1 ) |
|
351 list.remove(); |
|
352 \endcode |
|
353 |
|
354 The item after the removed item becomes the new current list item if |
|
355 the removed item is not the last item in the list. If the last item |
|
356 is removed, the new last item becomes the current item in Qt 2.x. |
|
357 In 3.0, the current item will be set to null. The current item is |
|
358 set to null if the list becomes empty. |
|
359 |
|
360 All list iterators that refer to the removed item will be set to point |
|
361 to the new current item. |
|
362 |
|
363 \sa remove(), clear(), setAutoDelete(), current() |
|
364 */ |
|
365 |
|
366 /*! |
|
367 \fn void QList::removeNode( QLNode *node ) |
|
368 Removes the \e node from the list. |
|
369 |
|
370 This node must exist in the list, otherwise the program may crash. |
|
371 |
|
372 The removed item is deleted if \link QCollection::setAutoDelete() |
|
373 auto-deletion\endlink is enabled. |
|
374 |
|
375 The first item in the list will become the new current list item. |
|
376 The current item is set to null if the list becomes empty. |
|
377 |
|
378 All list iterators that refer to the removed item will be set to point to |
|
379 the item succeeding this item, or the preceding item if the removed item |
|
380 was the last item. |
|
381 |
|
382 \warning Do not call this function unless you are an expert. |
|
383 |
|
384 \sa takeNode(), currentNode() remove() removeRef() |
|
385 */ |
|
386 |
|
387 /*! |
|
388 \fn bool QList::removeFirst() |
|
389 Removes the first item from the list. |
|
390 Returns TRUE if successful, or FALSE if the list is empty. |
|
391 |
|
392 The removed item is deleted if \link QCollection::setAutoDelete() |
|
393 auto-deletion\endlink is enabled. |
|
394 |
|
395 The first item in the list becomes the new current list item. |
|
396 The current item is set to null if the list becomes empty. |
|
397 |
|
398 All list iterators that refer to the removed item will be set to point |
|
399 to the new current item. |
|
400 |
|
401 \sa removeLast(), setAutoDelete(), current() remove() |
|
402 */ |
|
403 |
|
404 /*! |
|
405 \fn bool QList::removeLast() |
|
406 Removes the last item from the list. |
|
407 Returns TRUE if successful, or FALSE if the list is empty. |
|
408 |
|
409 The removed item is deleted if \link QCollection::setAutoDelete() |
|
410 auto-deletion\endlink is enabled. |
|
411 |
|
412 The last item in the list becomes the new current list item. |
|
413 The current item is set to null if the list becomes empty. |
|
414 |
|
415 All list iterators that refer to the removed item will be set to point |
|
416 to the new current item. |
|
417 |
|
418 \sa removeFirst(), setAutoDelete(), current() |
|
419 */ |
|
420 |
|
421 /*! |
|
422 \fn type *QList::take( uint index ) |
|
423 Takes the item at position \e index out of the list without |
|
424 deleting it (even if \link QCollection::setAutoDelete() |
|
425 auto-deletion\endlink is enabled). |
|
426 |
|
427 Returns a pointer to the item taken out of the list, or null if |
|
428 the index is out of range. |
|
429 The valid range is <code>0 .. (count() - 1)</code> inclusive. |
|
430 |
|
431 The item after the taken item becomes the new current list item if |
|
432 the taken item is not the last item in the list. If the last item |
|
433 is taken, the new last item becomes the current item in Qt 2.x. In |
|
434 3.0, the current item will be set to null. The current item is set |
|
435 to null if the list becomes empty. |
|
436 |
|
437 All list iterators that refer to the taken item will be set to point to |
|
438 the new current item. |
|
439 |
|
440 \sa remove(), clear(), current() |
|
441 */ |
|
442 |
|
443 /*! |
|
444 \fn type *QList::take() |
|
445 Takes the current item out of the list without deleting it (even if |
|
446 \link QCollection::setAutoDelete() auto-deletion\endlink is enabled). |
|
447 Returns a pointer to the item taken out of the list, or null if |
|
448 the current item is null. |
|
449 |
|
450 The item after the taken item becomes the new current list item if |
|
451 the taken item is not the last item in the list. If the last item |
|
452 is taken, the new last item becomes the current item in Qt 2.x. In |
|
453 3.0, the current item will be set to null. The current item is set |
|
454 to null if the list becomes empty. |
|
455 |
|
456 All list iterators that refer to the taken item will be set to point to |
|
457 the new current item. |
|
458 |
|
459 \sa remove(), clear(), current() |
|
460 */ |
|
461 |
|
462 /*! |
|
463 \fn type *QList::takeNode( QLNode *node ) |
|
464 Takes the \e node out of the list without deleting its item (even if |
|
465 \link QCollection::setAutoDelete() auto-deletion\endlink is enabled). |
|
466 Returns a pointer to the item taken out of the list. |
|
467 |
|
468 This node must exist in the list, otherwise the program may crash. |
|
469 |
|
470 The first item in the list becomes the new current list item. |
|
471 |
|
472 All list iterators that refer to the taken item will be set to point to |
|
473 the item succeeding this item, or the preceding item if the taken item |
|
474 was the last item. |
|
475 |
|
476 \warning Do not call this function unless you are an expert. |
|
477 |
|
478 \sa removeNode(), currentNode() |
|
479 */ |
|
480 |
|
481 /*! |
|
482 \fn void QList::clear() |
|
483 Removes all items from the list. |
|
484 |
|
485 The removed items are deleted if \link QCollection::setAutoDelete() |
|
486 auto-deletion\endlink is enabled. |
|
487 |
|
488 All list iterators that access this list will be reset. |
|
489 |
|
490 \sa remove(), take(), setAutoDelete() |
|
491 */ |
|
492 |
|
493 /*! |
|
494 \fn int QList::find( const type *item ) |
|
495 Finds the first occurrence of \e item in the list. |
|
496 |
|
497 If the item is found, the list sets the current item to point to |
|
498 the found item and returns the index of this item. |
|
499 If the item is not found, the list sets the current item to null, |
|
500 the current index to -1 and returns -1. |
|
501 |
|
502 The compareItems() function is called when searching for the item |
|
503 in the list. If compareItems() is not reimplemented, it is more |
|
504 efficient to call findRef(). |
|
505 |
|
506 \sa findNext(), findRef(), compareItems(), current() |
|
507 */ |
|
508 |
|
509 /*! |
|
510 \fn int QList::findNext( const type *item ) |
|
511 Finds the next occurrence of \e item in the list, starting from |
|
512 the current list item. |
|
513 |
|
514 If the item is found, the list sets the current item to point to |
|
515 the found item and returns the index of this item. |
|
516 If the item is not found, the list sets the current item to null, |
|
517 the current index to -1 and returns -1. |
|
518 |
|
519 The compareItems() function is called when searching for the item |
|
520 in the list. If compareItems() is not reimplemented, it is more |
|
521 efficient to call findNextRef(). |
|
522 |
|
523 \sa find(), findNextRef(), compareItems(), current() |
|
524 */ |
|
525 |
|
526 /*! |
|
527 \fn int QList::findRef( const type *item ) |
|
528 Finds the first occurrence of \e item in the list. |
|
529 |
|
530 If the item is found, the list sets the current item to point to |
|
531 the found item and returns the index of this item. |
|
532 If the item is not found, the list sets the current item to null, |
|
533 the current index to -1 and returns -1. |
|
534 |
|
535 Calling this function is must faster than find(), because find() |
|
536 compares \e item with each list item using compareItems(). |
|
537 This function only compares the pointers. |
|
538 |
|
539 \sa findNextRef(), find(), current() |
|
540 */ |
|
541 |
|
542 /*! |
|
543 \fn int QList::findNextRef( const type *item ) |
|
544 Finds the next occurrence of \e item in the list, starting from the |
|
545 current list item. |
|
546 |
|
547 If the item is found, the list sets the current item to point to |
|
548 the found item and returns the index of this item. |
|
549 If the item is not found, the list sets the current item to null, |
|
550 the current index to -1 and returns -1. |
|
551 |
|
552 Calling this function is must faster than findNext(), because findNext() |
|
553 compares \e item with each list item using compareItems(). |
|
554 This function only compares the pointers. |
|
555 |
|
556 \sa findRef(), findNext(), current() |
|
557 */ |
|
558 |
|
559 /*! |
|
560 \fn uint QList::contains( const type *item ) const |
|
561 Counts and returns the number of occurrences of \e item in the list. |
|
562 |
|
563 The compareItems() function is called when looking for the \e item |
|
564 in the list. If compareItems() is not reimplemented, it is more |
|
565 efficient to call containsRef(). |
|
566 |
|
567 Does not affect the current list item. |
|
568 |
|
569 \sa containsRef(), compareItems() |
|
570 */ |
|
571 |
|
572 /*! |
|
573 \fn uint QList::containsRef( const type *item ) const |
|
574 Counts and returns the number of occurrences of \e item in the list. |
|
575 |
|
576 Calling this function is must faster than contains(), because contains() |
|
577 compares \e item with each list item using compareItems(). |
|
578 This function only compares the pointers. |
|
579 |
|
580 Does not affect the current list item. |
|
581 |
|
582 \sa contains() |
|
583 */ |
|
584 |
|
585 /*! |
|
586 \fn type *QList::at( uint index ) |
|
587 Returns a pointer to the item at position \e index in the list, or |
|
588 null if the index is out of range. |
|
589 |
|
590 Sets the current list item to this item if \e index is valid. |
|
591 The valid range is <code>0 .. (count() - 1)</code> inclusive. |
|
592 |
|
593 This function is very efficient. It starts scanning from the first |
|
594 item, last item or current item, whichever is closest to \e index. |
|
595 |
|
596 \sa current() |
|
597 */ |
|
598 |
|
599 /*! |
|
600 \fn int QList::at() const |
|
601 Returns the index of the current list item. The returned value is -1 |
|
602 if the current item is null. |
|
603 \sa current() |
|
604 */ |
|
605 |
|
606 /*! |
|
607 \fn type *QList::current() const |
|
608 Returns a pointer to the current list item. The current item may be |
|
609 null (implies that the current index is -1). |
|
610 \sa at() |
|
611 */ |
|
612 |
|
613 /*! |
|
614 \fn QLNode *QList::currentNode() const |
|
615 Returns a pointer to the current list node. |
|
616 |
|
617 The node can be kept and removed later using removeNode(). |
|
618 The advantage is that the item can be removed directly without |
|
619 searching the list. |
|
620 |
|
621 \warning Do not call this function unless you are an expert. |
|
622 |
|
623 \sa removeNode(), takeNode(), current() |
|
624 */ |
|
625 |
|
626 /*! |
|
627 \fn type *QList::getFirst() const |
|
628 Returns a pointer to the first item in the list, or null if the |
|
629 list is empty. |
|
630 |
|
631 Does not affect the current list item. |
|
632 |
|
633 \sa first(), getLast() |
|
634 */ |
|
635 |
|
636 /*! |
|
637 \fn type *QList::getLast() const |
|
638 Returns a pointer to the last item in the list, or null if the |
|
639 list is empty. |
|
640 |
|
641 Does not affect the current list item. |
|
642 |
|
643 \sa last(), getFirst() |
|
644 */ |
|
645 |
|
646 /*! |
|
647 \fn type *QList::first() |
|
648 Returns a pointer to the first item in the list and makes this the |
|
649 current list item, or null if the list is empty. |
|
650 \sa getFirst(), last(), next(), prev(), current() |
|
651 */ |
|
652 |
|
653 /*! |
|
654 \fn type *QList::last() |
|
655 Returns a pointer to the last item in the list and makes this the |
|
656 current list item, or null if the list is empty. |
|
657 \sa getLast(), first(), next(), prev(), current() |
|
658 */ |
|
659 |
|
660 /*! |
|
661 \fn type *QList::next() |
|
662 Returns a pointer to the item succeeding the current item. |
|
663 Returns null if the current item is null or equal to the last item. |
|
664 |
|
665 Makes the succeeding item current. If the current item before this |
|
666 function call was the last item, the current item will be set to null. |
|
667 If the current item was null, this function does nothing. |
|
668 |
|
669 \sa first(), last(), prev(), current() |
|
670 */ |
|
671 |
|
672 /*! |
|
673 \fn type *QList::prev() |
|
674 Returns a pointer to the item preceding the current item. |
|
675 Returns null if the current item is null or equal to the first item. |
|
676 |
|
677 Makes the preceding item current. If the current item before this |
|
678 function call was the first item, the current item will be set to null. |
|
679 If the current item was null, this function does nothing. |
|
680 |
|
681 \sa first(), last(), next(), current() |
|
682 */ |
|
683 |
|
684 /*! |
|
685 \fn void QList::toVector( QGVector *vec ) const |
|
686 Stores all list items in the vector \e vec. |
|
687 |
|
688 The vector must be have the same item type, otherwise the result |
|
689 will be undefined. |
|
690 */ |
|
691 |
|
692 |
|
693 /***************************************************************************** |
|
694 QListIterator documentation |
|
695 *****************************************************************************/ |
|
696 |
|
697 /*! |
|
698 \class QListIterator qlist.h |
|
699 \brief The QListIterator class provides an iterator for QList collections. |
|
700 |
|
701 \ingroup collection |
|
702 \ingroup tools |
|
703 |
|
704 Define a template instance QListIterator\<X\> to create a list iterator |
|
705 that operates on QList\<X\> (list of X*). |
|
706 |
|
707 Example: |
|
708 \code |
|
709 #include <qlist.h> |
|
710 #include <qstring.h> |
|
711 #include <stdio.h> |
|
712 |
|
713 class Employee |
|
714 { |
|
715 public: |
|
716 Employee( const char *name, int salary ) { n=name; s=salary; } |
|
717 const char *name() const { return n; } |
|
718 int salary() const { return s; } |
|
719 private: |
|
720 QString n; |
|
721 int s; |
|
722 }; |
|
723 |
|
724 void main() |
|
725 { |
|
726 QList<Employee> list; // list of pointers to Employee |
|
727 list.setAutoDelete( TRUE ); // delete items when they are removed |
|
728 |
|
729 list.append( new Employee("Bill", 50000) ); |
|
730 list.append( new Employee("Steve",80000) ); |
|
731 list.append( new Employee("Ron", 60000) ); |
|
732 |
|
733 QListIterator<Employee> it(list); // iterator for employee list |
|
734 for ( ; it.current(); ++it ) { |
|
735 Employee *emp = it.current(); |
|
736 printf( "%s earns %d\n", emp->name().latin1(), emp->salary() ); |
|
737 } |
|
738 } |
|
739 \endcode |
|
740 |
|
741 Program output: |
|
742 \code |
|
743 Bill earns 50000 |
|
744 Steve earns 80000 |
|
745 Ron earns 60000 |
|
746 \endcode |
|
747 |
|
748 Although QList has member functions to traverse the doubly linked list |
|
749 structure, using a list iterator is a much more robust way of traversing |
|
750 the list, because multiple list iterators can operate on the same list, |
|
751 independent of each other and independent of the QList's current item. |
|
752 An iterator has its own current list item and can get the next and |
|
753 previous list items. It can only traverse the list, never modify it. |
|
754 |
|
755 A QList knows about all list iterators that are operating on the list. |
|
756 When an item is removed from the list, the list update all iterators |
|
757 that are pointing the removed item to point to the new current list item. |
|
758 |
|
759 Example: |
|
760 \code |
|
761 #include <qlist.h> |
|
762 #include <qstring.h> |
|
763 #include <stdio.h> |
|
764 |
|
765 class Employee |
|
766 { |
|
767 ... // same as above |
|
768 }; |
|
769 |
|
770 void main() |
|
771 { |
|
772 QList<Employee> list; // list of pointers to Employee |
|
773 list.setAutoDelete( TRUE ); // delete items when they are removed |
|
774 |
|
775 list.append( new Employee("Bill", 50000) ); |
|
776 list.append( new Employee("Steve",80000) ); |
|
777 list.append( new Employee("Ron", 60000) ); |
|
778 |
|
779 QListIterator<Employee> it(list); |
|
780 |
|
781 list.at( 1 ); // current list item: "Steve" |
|
782 it.toLast(); // it: "Ron" |
|
783 --it; // it: "Steve" |
|
784 |
|
785 // Now, both the list and the iterator are referring the same item |
|
786 |
|
787 list.remove(); |
|
788 printf( "%s\n", it.current()->name().latin1() ); |
|
789 } |
|
790 \endcode |
|
791 |
|
792 Program output: |
|
793 \code |
|
794 Ron |
|
795 \endcode |
|
796 |
|
797 \sa QList, \link collection.html collection classes\endlink |
|
798 */ |
|
799 |
|
800 /*! |
|
801 \fn QListIterator::QListIterator( const QList<type> &list ) |
|
802 Constructs an iterator for \e list. The current iterator item is |
|
803 set to point on the first item in the \e list. |
|
804 */ |
|
805 |
|
806 /*! |
|
807 \fn QListIterator::~QListIterator() |
|
808 Destroys the iterator. |
|
809 */ |
|
810 |
|
811 /*! |
|
812 \fn uint QListIterator::count() const |
|
813 Returns the number of items in the list this iterator operates on. |
|
814 \sa isEmpty() |
|
815 */ |
|
816 |
|
817 /*! |
|
818 \fn bool QListIterator::isEmpty() const |
|
819 Returns TRUE if the list is empty, i.e. count() == 0, otherwise FALSE. |
|
820 \sa count() |
|
821 */ |
|
822 |
|
823 /*! |
|
824 \fn bool QListIterator::atFirst() const |
|
825 Returns TRUE if the current iterator item is the first list item, otherwise |
|
826 FALSE. |
|
827 \sa toFirst(), atLast() |
|
828 */ |
|
829 |
|
830 /*! |
|
831 \fn bool QListIterator::atLast() const |
|
832 Returns TRUE if the current iterator item is the last list item, otherwise |
|
833 FALSE. |
|
834 \sa toLast(), atFirst() |
|
835 */ |
|
836 |
|
837 /*! |
|
838 \fn type *QListIterator::toFirst() |
|
839 Sets the current iterator item to point to the first list item and returns |
|
840 a pointer to the item. Sets the current item to null and returns null |
|
841 if the list is empty. |
|
842 \sa toLast(), atFirst() |
|
843 */ |
|
844 |
|
845 /*! |
|
846 \fn type *QListIterator::toLast() |
|
847 Sets the current iterator item to point to the last list item and returns |
|
848 a pointer to the item. Sets the current item to null and returns null |
|
849 if the list is empty. |
|
850 \sa toFirst(), atLast() |
|
851 */ |
|
852 |
|
853 /*! |
|
854 \fn QListIterator::operator type *() const |
|
855 Cast operator. Returns a pointer to the current iterator item. |
|
856 Same as current(). |
|
857 */ |
|
858 |
|
859 /*! |
|
860 \fn type *QListIterator::operator*() |
|
861 Asterix operator. Returns a pointer to the current iterator item. |
|
862 Same as current(). |
|
863 */ |
|
864 |
|
865 /*! |
|
866 \fn type *QListIterator::current() const |
|
867 Returns a pointer to the current iterator item. |
|
868 */ |
|
869 |
|
870 /*! |
|
871 \fn type *QListIterator::operator()() |
|
872 Makes the succeeding item current and returns the original current item. |
|
873 |
|
874 If the current iterator item was the last item in the list or if it was |
|
875 null, null is returned. |
|
876 */ |
|
877 |
|
878 /*! |
|
879 \fn char *QStrListIterator::operator()() |
|
880 Makes the succeeding item current and returns the original current item. |
|
881 |
|
882 If the current iterator item was the last item in the list or if it was |
|
883 null, null is returned. |
|
884 */ |
|
885 |
|
886 /*! |
|
887 \fn type *QListIterator::operator++() |
|
888 Prefix ++ makes the succeeding item current and returns the new current |
|
889 item. |
|
890 |
|
891 If the current iterator item was the last item in the list or if it was |
|
892 null, null is returned. |
|
893 */ |
|
894 |
|
895 /*! |
|
896 \fn type *QListIterator::operator+=( uint jump ) |
|
897 Sets the current item to the item \e jump positions after the current item, |
|
898 and returns a pointer to that item. |
|
899 |
|
900 If that item is beyond the last item or if the dictionary is empty, |
|
901 it sets the current item to null and returns null |
|
902 */ |
|
903 |
|
904 /*! |
|
905 \fn type *QListIterator::operator--() |
|
906 Prefix -- makes the preceding item current and returns the new current |
|
907 item. |
|
908 |
|
909 If the current iterator item was the first item in the list or if it was |
|
910 null, null is returned. |
|
911 */ |
|
912 |
|
913 /*! |
|
914 \fn type *QListIterator::operator-=( uint jump ) |
|
915 Returns the item \e jump positions before the current item, or null if |
|
916 it is beyond the first item. Makes this the current item. |
|
917 */ |
|
918 |
|
919 /*! |
|
920 \fn QListIterator<type>& QListIterator::operator=( const QListIterator<type> &it ) |
|
921 Assignment. Makes a copy of the iterator \a it and returns a reference |
|
922 to this iterator. |
|
923 */ |
|
924 |
|
925 |
|
926 /***************************************************************************** |
|
927 QStrList documentation |
|
928 *****************************************************************************/ |
|
929 |
|
930 typedef QList<char> QStrList |
|
931 |
|
932 /*! |
|
933 \class QStrList qstrlist.h |
|
934 \brief The QStrList class provides a doubly linked list of \c char*. |
|
935 |
|
936 \inherit QList |
|
937 |
|
938 \ingroup collection |
|
939 \ingroup tools |
|
940 |
|
941 This class is a QList\<char\> instance (a list of char*). |
|
942 |
|
943 QStrList can make deep or shallow copies of the strings that are inserted. |
|
944 |
|
945 A deep copy means to allocate space for the string and then copy the string |
|
946 data into it. A shallow copy is just a copy of the pointer value and not |
|
947 the string data. |
|
948 |
|
949 The disadvantage with shallow copies is that since a pointer can only |
|
950 be deleted once, the program must put all strings in a central place and |
|
951 know when it is safe to delete them (i.e. when the strings are no longer |
|
952 referenced by other parts of the program). This can make the program |
|
953 more complex. The advantage of shallow copies is that shallow copies |
|
954 consume far less memory than deep copies. It is also much faster |
|
955 to copy a pointer (typically 4 or 8 bytes) than to copy string data. |
|
956 |
|
957 A QStrList that operates on deep copies will by default turn on |
|
958 auto-deletion (see setAutoDelete()). Thus, by default, QStrList will |
|
959 deallocate any string copies it allocates. |
|
960 |
|
961 The virtual compareItems() function is reimplemented and does a case |
|
962 sensitive string comparison. The inSort() function will insert |
|
963 strings in a sorted order. |
|
964 |
|
965 The QStrListIterator class is an iterator for QStrList. |
|
966 */ |
|
967 |
|
968 /*! |
|
969 \fn QStrList::QStrList( bool deepCopies ) |
|
970 Constructs an empty list of strings. Will make deep copies of all inserted |
|
971 strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies |
|
972 is FALSE. |
|
973 */ |
|
974 |
|
975 /*! |
|
976 \fn QStrList::QStrList( const QStrList &list ) |
|
977 Constructs a copy of \e list. |
|
978 |
|
979 If \e list has deep copies, this list will also get deep copies. |
|
980 Only the pointers are copied (shallow copy) if the other list does not |
|
981 use deep copies. |
|
982 */ |
|
983 |
|
984 /*! |
|
985 \fn QStrList::~QStrList() |
|
986 Destroys the list. All strings are removed. |
|
987 */ |
|
988 |
|
989 /*! |
|
990 \fn QStrList& QStrList::operator=( const QStrList& list ) |
|
991 Assigns \e list to this list and returns a reference to this list. |
|
992 |
|
993 If \e list has deep copies, this list will also get deep copies. |
|
994 Only the pointers are copied (shallow copy) if the other list does not |
|
995 use deep copies. |
|
996 */ |
|
997 |
|
998 |
|
999 /***************************************************************************** |
|
1000 QStrIList documentation |
|
1001 *****************************************************************************/ |
|
1002 |
|
1003 /*! |
|
1004 \class QStrIList qstrlist.h |
|
1005 \brief The QStrIList class provides a doubly linked list of \c char* with |
|
1006 case insensitive compare. |
|
1007 |
|
1008 \ingroup collection |
|
1009 \ingroup tools |
|
1010 |
|
1011 This class is a QList\<char\> instance (a list of char*). |
|
1012 |
|
1013 QStrIList is similar to QStrList except that it is case insensitive. |
|
1014 The virtual compareItems() function is reimplemented and does a |
|
1015 case insensitive string comparison. |
|
1016 The inSort() function will insert strings in a sorted order. |
|
1017 |
|
1018 The QStrListIterator class is an iterator for QStrList. |
|
1019 */ |
|
1020 |
|
1021 /*! |
|
1022 \fn QStrIList::QStrIList( bool deepCopies ) |
|
1023 Constructs a list of strings. Will make deep copies of all inserted |
|
1024 strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies |
|
1025 is FALSE. |
|
1026 */ |
|
1027 |
|
1028 /*! |
|
1029 \fn QStrIList::~QStrIList() |
|
1030 Destroys the list. All strings are removed. |
|
1031 */ |
|
1032 |
|
1033 |
|
1034 /***************************************************************************** |
|
1035 QStrListIterator documentation |
|
1036 *****************************************************************************/ |
|
1037 |
|
1038 /*! |
|
1039 \class QStrListIterator qstrlist.h |
|
1040 \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes. |
|
1041 |
|
1042 \inherit QListIterator |
|
1043 |
|
1044 \ingroup tools |
|
1045 |
|
1046 This class is a QListIterator\<char\> instance. |
|
1047 It can traverse the strings in the QStrList and QStrIList classes. |
|
1048 */ |