qtools/qlist.doc

   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   \ingroup collection
 937   \ingroup tools
 938
 939   This class is a QList\<char\> instance (a list of char*).
 940
 941   QStrList can make deep or shallow copies of the strings that are inserted.
 942
 943   A deep copy means to allocate space for the string and then copy the string
 944   data into it.  A shallow copy is just a copy of the pointer value and not
 945   the string data.
 946
 947   The disadvantage with shallow copies is that since a pointer can only
 948   be deleted once, the program must put all strings in a central place and
 949   know when it is safe to delete them (i.e. when the strings are no longer
 950   referenced by other parts of the program).  This can make the program
 951   more complex.  The advantage of shallow copies is that shallow copies
 952   consume far less memory than deep copies.  It is also much faster
 953   to copy a pointer (typically 4 or 8 bytes) than to copy string data.
 954
 955   A QStrList that operates on deep copies will by default turn on
 956   auto-deletion (see setAutoDelete()). Thus, by default, QStrList will
 957   deallocate any string copies it allocates.
 958
 959   The virtual compareItems() function is reimplemented and does a case
 960   sensitive string comparison. The inSort() function will insert
 961   strings in a sorted order.
 962
 963   The QStrListIterator class is an iterator for QStrList.
 964 */
 965
 966 /*!
 967   \fn QStrList::QStrList( bool deepCopies )
 968   Constructs an empty list of strings.  Will make deep copies of all inserted
 969   strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
 970   is FALSE.
 971 */
 972
 973 /*!
 974   \fn QStrList::QStrList( const QStrList &list )
 975   Constructs a copy of \e list.
 976
 977   If \e list has deep copies, this list will also get deep copies.
 978   Only the pointers are copied (shallow copy) if the other list does not
 979   use deep copies.
 980 */
 981
 982 /*!
 983   \fn QStrList::~QStrList()
 984   Destroys the list.  All strings are removed.
 985 */
 986
 987 /*!
 988   \fn QStrList& QStrList::operator=( const QStrList& list )
 989   Assigns \e list to this list and returns a reference to this list.
 990
 991   If \e list has deep copies, this list will also get deep copies.
 992   Only the pointers are copied (shallow copy) if the other list does not
 993   use deep copies.
 994 */
 995
 996
 997 /*****************************************************************************
 998   QStrIList documentation
 999  *****************************************************************************/
1000
1001 /*!
1002   \class QStrIList qstrlist.h
1003   \brief The QStrIList class provides a doubly linked list of \c char* with
1004 case insensitive compare.
1005
1006   \ingroup collection
1007   \ingroup tools
1008
1009   This class is a QList\<char\> instance (a list of char*).
1010
1011   QStrIList is similar to QStrList except that it is case insensitive.
1012   The virtual compareItems() function is reimplemented and does a
1013   case insensitive string comparison.
1014   The inSort() function will insert strings in a sorted order.
1015
1016   The QStrListIterator class is an iterator for QStrList.
1017 */
1018
1019 /*!
1020   \fn QStrIList::QStrIList( bool deepCopies )
1021   Constructs a list of strings.  Will make deep copies of all inserted
1022   strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
1023   is FALSE.
1024 */
1025
1026 /*!
1027   \fn QStrIList::~QStrIList()
1028   Destroys the list.  All strings are removed.
1029 */
1030
1031
1032 /*****************************************************************************
1033   QStrListIterator documentation
1034  *****************************************************************************/
1035
1036 /*!
1037   \class QStrListIterator qstrlist.h
1038   \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes.
1039
1040   \ingroup tools
1041
1042   This class is a QListIterator\<char\> instance.
1043   It can traverse the strings in the QStrList and QStrIList classes.
1044 */