src/qt3support/tools/q3ptrlist.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \class Q3PtrList
  44     \brief The Q3PtrList class is a template class that provides a list.
  45     \compat
  46
  47     Q3ValueList is an STL-compatible alternative to this class.
  48
  49     Define a template instance Q3PtrList\<X\> to create a list that
  50     operates on pointers to X (X*).
  51
  52     The list class is indexable and has a \link at() current
  53     index\endlink and a \link current() current item\endlink. The
  54     first item corresponds to index position 0. The current index is
  55     -1 if the current item is 0.
  56
  57     Items are inserted with prepend(), insert() or append(). Items are
  58     removed with remove(), removeRef(), removeFirst() and
  59     removeLast(). You can search for an item using find(), findNext(),
  60     findRef() or findNextRef(). The list can be sorted with sort().
  61     You can count the number of occurrences of an item with contains()
  62     or containsRef(). You can get a pointer to the current item with
  63     current(), to an item at a particular index position in the list
  64     with at() or to the first or last item with getFirst() and
  65     getLast(). You can also iterate over the list with first(),
  66     last(), next() and prev() (which all update current()). The list's
  67     deletion property is set with setAutoDelete().
  68
  69     \target example
  70     Example:
  71     \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0
  72
  73     The output is
  74     \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1
  75
  76     Q3PtrList has several member functions for traversing the list, but
  77     using a Q3PtrListIterator can be more practical. Multiple list
  78     iterators may traverse the same list, independently of each other
  79     and of the current list item.
  80
  81     In the example above we make the call setAutoDelete(true).
  82     Enabling auto-deletion tells the list to delete items that are
  83     removed. The default is to not delete items when they are removed
  84     but this would cause a memory leak in the example because there
  85     are no other references to the list items.
  86
  87     When inserting an item into a list only the pointer is copied, not
  88     the item itself, i.e. a shallow copy. It is possible to make the
  89     list copy all of the item's data (deep copy) when an item is
  90     inserted. insert(), inSort() and append() call the virtual
  91     function Q3PtrCollection::newItem() for the item to be inserted.
  92     Inherit a list and reimplement newItem() to have deep copies.
  93
  94     When removing an item from a list, the virtual function
  95     Q3PtrCollection::deleteItem() is called. Q3PtrList's default
  96     implementation is to delete the item if auto-deletion is enabled.
  97
  98     The virtual function compareItems() can be reimplemented to
  99     compare two list items. This function is called from all list
 100     functions that need to compare list items, for instance
 101     remove(const type*). If you only want to deal with pointers, there
 102     are functions that compare pointers instead, for instance
 103     removeRef(const type*). These functions are somewhat faster than
 104     those that call compareItems().
 105
 106     List items are stored as \c void* in an internal Q3LNode, which
 107     also holds pointers to the next and previous list items. The
 108     functions currentNode(), removeNode(), and takeNode() operate
 109     directly on the Q3LNode, but they should be used with care. The
 110     data component of the node is available through Q3LNode::getData().
 111
 112     The Q3StrList class is a list of \c char*.
 113     It reimplements newItem(), deleteItem() and compareItems(). (But
 114     see QStringList for a list of Unicode QStrings.)
 115
 116     \sa Q3PtrListIterator
 117 */
 118
 119
 120 /*!
 121     \fn Q3PtrList::Q3PtrList()
 122
 123     Constructs an empty list.
 124 */
 125
 126 /*!
 127     \fn Q3PtrList::Q3PtrList( const Q3PtrList<type> &list )
 128
 129     Constructs a copy of \a list.
 130
 131     Each item in \a list is \link append() appended\endlink to this
 132     list. Only the pointers are copied (shallow copy).
 133 */
 134
 135 /*!
 136     \fn Q3PtrList::~Q3PtrList()
 137
 138     Removes all items from the list and destroys the list.
 139
 140     All list iterators that access this list will be reset.
 141
 142     \sa setAutoDelete()
 143 */
 144
 145 /*!
 146     \fn Q3PtrList<type> &Q3PtrList::operator=(const Q3PtrList<type> &list)
 147
 148     Assigns \a list to this list and returns a reference to this list.
 149
 150     This list is first cleared and then each item in \a list is \link
 151     append() appended\endlink to this list. Only the pointers are
 152     copied (shallow copy) unless newItem() has been reimplemented.
 153 */
 154
 155 /*!
 156     \fn bool Q3PtrList::operator==(const Q3PtrList<type> &list ) const
 157
 158     Compares this list with \a list. Returns TRUE if the lists contain
 159     the same data; otherwise returns FALSE.
 160 */
 161
 162 /*!
 163     \fn uint Q3PtrList::count() const
 164
 165     Returns the number of items in the list.
 166
 167     \sa isEmpty()
 168 */
 169
 170 /*!
 171     \fn bool Q3PtrList::operator!=(const Q3PtrList<type> &list ) const
 172
 173     Compares this list with \a list. Returns TRUE if the lists contain
 174     different data; otherwise returns FALSE.
 175 */
 176
 177
 178 /*!
 179     \fn void Q3PtrList::sort()
 180
 181     Sorts the list by the result of the virtual compareItems()
 182     function.
 183
 184     The heap sort algorithm is used for sorting. It sorts n items with
 185     O(n*log n) comparisons. This is the asymptotic optimal solution of
 186     the sorting problem.
 187
 188     If the items in your list support operator<() and operator==(),
 189     you might be better off with Q3SortedList because it implements the
 190     compareItems() function for you using these two operators.
 191
 192     \sa inSort()
 193 */
 194
 195 /*!
 196     \fn bool Q3PtrList::isEmpty() const
 197
 198     Returns TRUE if the list is empty; otherwise returns FALSE.
 199
 200     \sa count()
 201 */
 202
 203 /*!
 204     \fn bool Q3PtrList::insert( uint index, const type *item )
 205
 206     Inserts the \a item at position \a index in the list.
 207
 208     Returns TRUE if successful, i.e. if \a index is in range;
 209     otherwise returns FALSE. The valid range is 0 to count()
 210     (inclusively). The item is appended if \a index == count().
 211
 212     The inserted item becomes the current list item.
 213
 214     \a item must not be 0.
 215
 216     \sa append(), current(), replace()
 217 */
 218
 219 /*!
 220     \fn bool Q3PtrList::replace( uint index, const type *item )
 221
 222     Replaces the item at position \a index with the new \a item.
 223
 224     Returns TRUE if successful, i.e. \a index is in the range 0 to
 225     count()-1.
 226
 227     \sa append(), current(), insert()
 228 */
 229
 230 /*!
 231     \fn void Q3PtrList::inSort( const type *item )
 232
 233     Inserts the \a item at its sorted position in the list.
 234
 235     The sort order depends on the virtual compareItems() function. All
 236     items must be inserted with inSort() to maintain the sorting
 237     order.
 238
 239     The inserted item becomes the current list item.
 240
 241     \a item must not be 0.
 242
 243     \warning Using inSort() is slow. An alternative, especially if you
 244     have lots of items, is to simply append() or insert() them and
 245     then use sort(). inSort() takes up to O(n) compares. That means
 246     inserting n items in your list will need O(n^2) compares whereas
 247     sort() only needs O(n*log n) for the same task. So use inSort()
 248     only if you already have a presorted list and want to insert just
 249     a few additional items.
 250
 251     \sa insert(), compareItems(), current(), sort()
 252 */
 253
 254 /*!
 255     \fn void Q3PtrList::append( const type *item )
 256
 257     Inserts the \a item at the end of the list.
 258
 259     The inserted item becomes the current list item. This is
 260     equivalent to \c{insert( count(), item )}.
 261
 262     \a item must not be 0.
 263
 264     \sa insert(), current(), prepend()
 265 */
 266
 267 /*!
 268     \fn void Q3PtrList::prepend( const type *item )
 269
 270     Inserts the \a item at the start of the list.
 271
 272     The inserted item becomes the current list item. This is
 273     equivalent to \c{insert( 0, item )}.
 274
 275     \a item must not be 0.
 276
 277     \sa append(), insert(), current()
 278 */
 279
 280 /*!
 281     \fn bool Q3PtrList::remove( uint index )
 282
 283     Removes the item at position \a index in the list.
 284
 285     Returns TRUE if successful, i.e. if \a index is in range;
 286     otherwise returns FALSE. The valid range is \c{0..(count() - 1)}
 287     inclusive.
 288
 289     The removed item is deleted if \link setAutoDelete()
 290     auto-deletion\endlink is enabled.
 291
 292     The item after the removed item becomes the new current list item
 293     if the removed item is not the last item in the list. If the last
 294     item is removed, the new last item becomes the current item.
 295
 296     All list iterators that refer to the removed item will be set to
 297     point to the new current item.
 298
 299     \sa take(), clear(), setAutoDelete(), current() removeRef()
 300 */
 301
 302 /*!
 303     \fn bool Q3PtrList::remove()
 304
 305     \overload
 306
 307     Removes the current list item.
 308
 309     Returns TRUE if successful, i.e. if the current item isn't 0;
 310     otherwise returns FALSE.
 311
 312     The removed item is deleted if \link setAutoDelete()
 313     auto-deletion\endlink is enabled.
 314
 315     The item after the removed item becomes the new current list item
 316     if the removed item is not the last item in the list. If the last
 317     item is removed, the new last item becomes the current item. The
 318     current item is set to 0 if the list becomes empty.
 319
 320     All list iterators that refer to the removed item will be set to
 321     point to the new current item.
 322
 323     \sa take(), clear(), setAutoDelete(), current() removeRef()
 324 */
 325
 326 /*!
 327     \fn bool Q3PtrList::remove( const type *item )
 328
 329     \overload
 330
 331     Removes the first occurrence of \a item from the list.
 332
 333     Returns TRUE if successful, i.e. if \a item is in the list;
 334     otherwise returns FALSE.
 335
 336     The removed item is deleted if \link setAutoDelete()
 337     auto-deletion\endlink is enabled.
 338
 339     The compareItems() function is called when searching for the item
 340     in the list. If compareItems() is not reimplemented, it is more
 341     efficient to call removeRef().
 342
 343     If \a item is NULL then the current item is removed from the list.
 344
 345     The item after the removed item becomes the new current list item
 346     if the removed item is not the last item in the list. If the last
 347     item is removed, the new last item becomes the current item. The
 348     current item is set to 0 if the list becomes empty.
 349
 350     All list iterators that refer to the removed item will be set to
 351     point to the new current item.
 352
 353     \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(),
 354     current()
 355 */
 356
 357 /*!
 358     \fn bool Q3PtrList::removeRef( const type *item )
 359
 360     Removes the first occurrence of \a item from the list.
 361
 362     Returns TRUE if successful, i.e. if \a item is in the list;
 363     otherwise returns FALSE.
 364
 365     The removed item is deleted if \link setAutoDelete()
 366     auto-deletion\endlink is enabled.
 367
 368     Equivalent to:
 369     \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2
 370
 371     The item after the removed item becomes the new current list item
 372     if the removed item is not the last item in the list. If the last
 373     item is removed, the new last item becomes the current item. The
 374     current item is set to 0 if the list becomes empty.
 375
 376     All list iterators that refer to the removed item will be set to
 377     point to the new current item.
 378
 379     \sa remove(), clear(), setAutoDelete(), current()
 380 */
 381
 382 /*!
 383     \fn void Q3PtrList::removeNode( Q3LNode *node )
 384
 385     Removes the \a node from the list.
 386
 387     This node must exist in the list, otherwise the program may crash.
 388
 389     The removed item is deleted if \link setAutoDelete()
 390     auto-deletion\endlink is enabled.
 391
 392     The first item in the list will become the new current list item.
 393     The current item is set to 0 if the list becomes empty.
 394
 395     All list iterators that refer to the removed item will be set to
 396     point to the item succeeding this item or to the preceding item if
 397     the removed item was the last item.
 398
 399     \warning Do not call this function unless you are an expert.
 400
 401     \sa takeNode(), currentNode() remove() removeRef()
 402 */
 403
 404 /*!
 405     \fn bool Q3PtrList::removeFirst()
 406
 407     Removes the first item from the list. Returns TRUE if successful,
 408     i.e. if the list isn't empty; otherwise returns FALSE.
 409
 410     The removed item is deleted if \link setAutoDelete()
 411     auto-deletion\endlink is enabled.
 412
 413     The first item in the list becomes the new current list item. The
 414     current item is set to 0 if the list becomes empty.
 415
 416     All list iterators that refer to the removed item will be set to
 417     point to the new current item.
 418
 419     \sa removeLast(), setAutoDelete(), current() remove()
 420 */
 421
 422 /*!
 423     \fn bool Q3PtrList::removeLast()
 424
 425     Removes the last item from the list. Returns TRUE if successful,
 426     i.e. if the list isn't empty; otherwise returns FALSE.
 427
 428     The removed item is deleted if \link setAutoDelete()
 429     auto-deletion\endlink is enabled.
 430
 431     The last item in the list becomes the new current list item. The
 432     current item is set to 0 if the list becomes empty.
 433
 434     All list iterators that refer to the removed item will be set to
 435     point to the new current item.
 436
 437     \sa removeFirst(), setAutoDelete(), current()
 438 */
 439
 440 /*!
 441     \fn type *Q3PtrList::take( uint index )
 442
 443     Takes the item at position \a index out of the list without
 444     deleting it (even if \link setAutoDelete() auto-deletion\endlink
 445     is enabled).
 446
 447     Returns a pointer to the item taken out of the list, or 0 if the
 448     index is out of range. The valid range is \c{0..(count() - 1)}
 449     inclusive.
 450
 451     The item after the removed item becomes the new current list item
 452     if the removed item is not the last item in the list. If the last
 453     item is removed, the new last item becomes the current item. The
 454     current item is set to 0 if the list becomes empty.
 455
 456     All list iterators that refer to the taken item will be set to
 457     point to the new current item.
 458
 459     \sa remove(), clear(), current()
 460 */
 461
 462 /*!
 463     \fn type *Q3PtrList::take()
 464
 465     \overload
 466
 467     Takes the current item out of the list without deleting it (even
 468     if \link setAutoDelete() auto-deletion\endlink is enabled).
 469
 470     Returns a pointer to the item taken out of the list, or 0 if
 471     the current item is 0.
 472
 473     The item after the removed item becomes the new current list item
 474     if the removed item is not the last item in the list. If the last
 475     item is removed, the new last item becomes the current item. The
 476     current item is set to 0 if the list becomes empty.
 477
 478     All list iterators that refer to the taken item will be set to
 479     point to the new current item.
 480
 481     \sa remove(), clear(), current()
 482 */
 483
 484 /*!
 485     \fn type *Q3PtrList::takeNode( Q3LNode *node )
 486
 487     Takes the \a node out of the list without deleting its item (even
 488     if \link setAutoDelete() auto-deletion\endlink is enabled).
 489     Returns a pointer to the item taken out of the list.
 490
 491     This node must exist in the list, otherwise the program may crash.
 492
 493     The first item in the list becomes the new current list item.
 494
 495     All list iterators that refer to the taken item will be set to
 496     point to the item succeeding this item or to the preceding item if
 497     the taken item was the last item.
 498
 499     \warning Do not call this function unless you are an expert.
 500
 501     \sa removeNode(), currentNode()
 502 */
 503
 504 /*!
 505     \fn void Q3PtrList::clear()
 506
 507     Removes all items from the list.
 508
 509     The removed items are deleted if \link setAutoDelete()
 510     auto-deletion\endlink is enabled.
 511
 512     All list iterators that access this list will be reset.
 513
 514     \sa remove(), take(), setAutoDelete()
 515 */
 516
 517 /*!
 518     \fn int Q3PtrList::find( const type *item )
 519
 520     Finds the first occurrence of \a item in the list.
 521
 522     If the item is found, the list sets the current item to point to
 523     the found item and returns the index of this item. If the item is
 524     not found, the list sets the current item to 0, the current
 525     index to -1, and returns -1.
 526
 527     The compareItems() function is called when searching for the item
 528     in the list. If compareItems() is not reimplemented, it is more
 529     efficient to call findRef().
 530
 531     \sa findNext(), findRef(), compareItems(), current()
 532 */
 533
 534 /*!
 535     \fn int Q3PtrList::findNext( const type *item )
 536
 537     Finds the next occurrence of \a item in the list, starting from
 538     the current list item.
 539
 540     If the item is found, the list sets the current item to point to
 541     the found item and returns the index of this item. If the item is
 542     not found, the list sets the current item to 0, the current
 543     index to -1, and returns -1.
 544
 545     The compareItems() function is called when searching for the item
 546     in the list. If compareItems() is not reimplemented, it is more
 547     efficient to call findNextRef().
 548
 549     \sa find(), findNextRef(), compareItems(), current()
 550 */
 551
 552 /*!
 553     \fn int Q3PtrList::findRef( const type *item )
 554
 555     Finds the first occurrence of \a item in the list.
 556
 557     If the item is found, the list sets the current item to point to
 558     the found item and returns the index of this item. If the item is
 559     not found, the list sets the current item to 0, the current
 560     index to -1, and returns -1.
 561
 562     Calling this function is much faster than find() because find()
 563     compares \a item with each list item using compareItems(), whereas
 564     this function only compares the pointers.
 565
 566     \sa findNextRef(), find(), current()
 567 */
 568
 569 /*!
 570     \fn int Q3PtrList::findNextRef( const type *item )
 571
 572     Finds the next occurrence of \a item in the list, starting from
 573     the current list item.
 574
 575     If the item is found, the list sets the current item to point to
 576     the found item and returns the index of this item. If the item is
 577     not found, the list sets the current item to 0, the current
 578     index to -1, and returns -1.
 579
 580     Calling this function is much faster than findNext() because
 581     findNext() compares \a item with each list item using
 582     compareItems(), whereas this function only compares the pointers.
 583
 584     \sa findRef(), findNext(), current()
 585 */
 586
 587 /*!
 588     \fn uint Q3PtrList::contains( const type *item ) const
 589
 590     Returns the number of occurrences of \a item in the list.
 591
 592     The compareItems() function is called when looking for the \a item
 593     in the list. If compareItems() is not reimplemented, it is more
 594     efficient to call containsRef().
 595
 596     This function does not affect the current list item.
 597
 598     \sa containsRef(), compareItems()
 599 */
 600
 601 /*!
 602     \fn uint Q3PtrList::containsRef( const type *item ) const
 603
 604     Returns the number of occurrences of \a item in the list.
 605
 606     Calling this function is much faster than contains() because
 607     contains() compares \a item with each list item using
 608     compareItems(), whereas his function only compares the pointers.
 609
 610     This function does not affect the current list item.
 611
 612     \sa contains()
 613 */
 614
 615 /*!
 616     \fn type *Q3PtrList::at( uint index )
 617
 618     Returns a pointer to the item at position \a index in the list, or
 619     0 if the index is out of range.
 620
 621     Sets the current list item to this item if \a index is valid. The
 622     valid range is \c{0..(count() - 1)} inclusive.
 623
 624     This function is very efficient. It starts scanning from the first
 625     item, last item, or current item, whichever is closest to \a
 626     index.
 627
 628     \sa current()
 629 */
 630
 631 /*!
 632     \fn int Q3PtrList::at() const
 633
 634     \overload
 635
 636     Returns the index of the current list item. The returned value is
 637     -1 if the current item is 0.
 638
 639     \sa current()
 640 */
 641
 642 /*!
 643     \fn type *Q3PtrList::current() const
 644
 645     Returns a pointer to the current list item. The current item may
 646     be 0 (implies that the current index is -1).
 647
 648     \sa at()
 649 */
 650
 651 /*!
 652     \fn Q3LNode *Q3PtrList::currentNode() const
 653
 654     Returns a pointer to the current list node.
 655
 656     The node can be kept and removed later using removeNode(). The
 657     advantage is that the item can be removed directly without
 658     searching the list.
 659
 660     \warning Do not call this function unless you are an expert.
 661
 662     \sa removeNode(), takeNode(), current()
 663 */
 664
 665 /*!
 666     \fn type *Q3PtrList::getFirst() const
 667
 668     Returns a pointer to the first item in the list, or 0 if the list
 669     is empty.
 670
 671     This function does not affect the current list item.
 672
 673     \sa first(), getLast()
 674 */
 675
 676 /*!
 677     \fn type *Q3PtrList::getLast() const
 678
 679     Returns a pointer to the last item in the list, or 0 if the list
 680     is empty.
 681
 682     This function does not affect the current list item.
 683
 684     \sa last(), getFirst()
 685 */
 686
 687 /*!
 688     \fn type *Q3PtrList::first()
 689
 690     Returns a pointer to the first item in the list and makes this the
 691     current list item; returns 0 if the list is empty.
 692
 693     \sa getFirst(), last(), next(), prev(), current()
 694 */
 695
 696 /*!
 697     \fn type *Q3PtrList::last()
 698
 699     Returns a pointer to the last item in the list and makes this the
 700     current list item; returns 0 if the list is empty.
 701
 702     \sa getLast(), first(), next(), prev(), current()
 703 */
 704
 705 /*!
 706     \fn type *Q3PtrList::next()
 707
 708     Returns a pointer to the item succeeding the current item. Returns
 709     0 if the current item is 0 or equal to the last item.
 710
 711     Makes the succeeding item current. If the current item before this
 712     function call was the last item, the current item will be set to
 713     0. If the current item was 0, this function does nothing.
 714
 715     \sa first(), last(), prev(), current()
 716 */
 717
 718 /*!
 719     \fn type *Q3PtrList::prev()
 720
 721     Returns a pointer to the item preceding the current item. Returns
 722     0 if the current item is 0 or equal to the first item.
 723
 724     Makes the preceding item current. If the current item before this
 725     function call was the first item, the current item will be set to
 726     0. If the current item was 0, this function does nothing.
 727
 728     \sa first(), last(), next(), current()
 729 */
 730
 731 /*!
 732     \fn void Q3PtrList::toVector( Q3GVector *vec ) const
 733
 734     Stores all list items in the vector \a vec.
 735
 736     The vector must be of the same item type, otherwise the result
 737     will be undefined.
 738 */
 739
 740 /*!
 741     \typedef Q3PtrList::iterator
 742
 743     \internal
 744 */
 745
 746 /*!
 747     \typedef Q3PtrList::Iterator
 748
 749     \internal
 750 */
 751
 752 /*!
 753     \typedef Q3PtrList::ConstIterator
 754
 755     \internal
 756 */
 757
 758 /*!
 759     \typedef Q3PtrList::const_iterator
 760
 761     \internal
 762 */
 763
 764 /*!
 765     \fn Q3PtrList::constBegin() const
 766
 767     \internal
 768 */
 769
 770 /*!
 771     \fn Q3PtrList::constEnd() const
 772
 773     \internal
 774 */
 775
 776 /*!
 777     \fn Q3PtrList::erase(Iterator)
 778
 779     \internal
 780 */
 781
 782
 783 /*****************************************************************************
 784   Q3PtrListIterator documentation
 785  *****************************************************************************/
 786
 787 /*!
 788     \class Q3PtrListIterator
 789     \brief The Q3PtrListIterator class provides an iterator for
 790     Q3PtrList collections.
 791     \compat
 792
 793     Define a template instance Q3PtrListIterator\<X\> to create a list
 794     iterator that operates on Q3PtrList\<X\> (list of X*).
 795
 796     The following example is similar to the
 797     example in the Q3PtrList class documentation,
 798     but it uses Q3PtrListIterator. The class Employee is
 799     defined there.
 800
 801     \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3
 802
 803     The output is
 804     \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4
 805
 806     Using a list iterator is a more robust way of traversing the list
 807     than using the Q3PtrList member functions \link Q3PtrList::first()
 808     first\endlink(), \link Q3PtrList::next() next\endlink(), \link
 809     Q3PtrList::current() current\endlink(), etc., as many iterators can
 810     traverse the same list independently.
 811
 812     An iterator has its own current list item and can get the next and
 813     previous list items. It doesn't modify the list in any way.
 814
 815     When an item is removed from the list, all iterators that point to
 816     that item are updated to point to Q3PtrList::current() instead to
 817     avoid dangling references.
 818
 819     \sa Q3PtrList
 820 */
 821
 822 /*!
 823     \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList<type> &list )
 824
 825     Constructs an iterator for \a list. The current iterator item is
 826     set to point on the first item in the \a list.
 827 */
 828
 829 /*!
 830     \fn Q3PtrListIterator::~Q3PtrListIterator()
 831
 832     Destroys the iterator.
 833 */
 834
 835 /*!
 836     \fn uint Q3PtrListIterator::count() const
 837
 838     Returns the number of items in the list this iterator operates on.
 839
 840     \sa isEmpty()
 841 */
 842
 843 /*!
 844     \fn bool Q3PtrListIterator::isEmpty() const
 845
 846     Returns TRUE if the list is empty; otherwise returns FALSE.
 847
 848     \sa count()
 849 */
 850
 851 /*!
 852     \fn bool Q3PtrListIterator::atFirst() const
 853
 854     Returns TRUE if the current iterator item is the first list item;
 855     otherwise returns FALSE.
 856
 857     \sa toFirst(), atLast()
 858 */
 859
 860 /*!
 861     \fn bool Q3PtrListIterator::atLast() const
 862
 863     Returns TRUE if the current iterator item is the last list item;
 864     otherwise returns FALSE.
 865
 866     \sa toLast(), atFirst()
 867 */
 868
 869 /*!
 870     \fn type *Q3PtrListIterator::toFirst()
 871
 872     Sets the current iterator item to point to the first list item and
 873     returns a pointer to the item. Sets the current item to 0 and
 874     returns 0 if the list is empty.
 875
 876     \sa toLast(), atFirst()
 877 */
 878
 879 /*!
 880     \fn type *Q3PtrListIterator::toLast()
 881
 882     Sets the current iterator item to point to the last list item and
 883     returns a pointer to the item. Sets the current item to 0 and
 884     returns 0 if the list is empty.
 885
 886     \sa toFirst(), atLast()
 887 */
 888
 889 /*!
 890     \fn Q3PtrListIterator::operator type *() const
 891
 892     Cast operator. Returns a pointer to the current iterator item.
 893     Same as current().
 894 */
 895
 896 /*!
 897     \fn type *Q3PtrListIterator::operator*()
 898
 899     Asterisk operator. Returns a pointer to the current iterator item.
 900     Same as current().
 901 */
 902
 903 /*!
 904     \fn type *Q3PtrListIterator::current() const
 905
 906     Returns a pointer to the current iterator item. If the iterator is
 907     positioned before the first item in the list or after the last
 908     item in the list, 0 is returned.
 909 */
 910
 911 /*!
 912     \fn type *Q3PtrListIterator::operator()()
 913
 914     Makes the succeeding item current and returns the original current
 915     item.
 916
 917     If the current iterator item was the last item in the list or if
 918     it was 0, 0 is returned.
 919 */
 920
 921 /*!
 922     \fn type *Q3PtrListIterator::operator++()
 923
 924     Prefix ++ makes the succeeding item current and returns the new
 925     current item.
 926
 927     If the current iterator item was the last item in the list or if
 928     it was 0, 0 is returned.
 929 */
 930
 931 /*!
 932     \fn type *Q3PtrListIterator::operator+=( uint jump )
 933
 934     Sets the current item to the item \a jump positions after the
 935     current item and returns a pointer to that item.
 936
 937     If that item is beyond the last item or if the list is empty, it
 938     sets the current item to 0 and returns 0
 939 */
 940
 941 /*!
 942     \fn type *Q3PtrListIterator::operator--()
 943
 944     Prefix - makes the preceding item current and returns the new
 945     current item.
 946
 947     If the current iterator item was the first item in the list or if
 948     it was 0, 0 is returned.
 949 */
 950
 951 /*!
 952     \fn type *Q3PtrListIterator::operator-=( uint jump )
 953
 954     Returns the item \a jump positions before the current item or 0
 955     if it is beyond the first item. Makes this the current item.
 956 */
 957
 958 /*!
 959     \fn Q3PtrListIterator<type>& Q3PtrListIterator::operator=( const Q3PtrListIterator<type> &it )
 960
 961     Assignment. Makes a copy of the iterator \a it and returns a
 962     reference to this iterator.
 963 */
 964
 965 /*!
 966     \class Q3StrList
 967     \brief The Q3StrList class provides a doubly-linked list of char*.
 968     \compat
 969
 970     If you want a string list of \l{QString}s use QStringList.
 971
 972     This class is a Q3PtrList\<char\> instance (a list of char*).
 973
 974     Q3StrList can make deep or shallow copies of the strings that are
 975     inserted.
 976
 977     A deep copy means that memory is allocated for the string and then
 978     the string data is copied into that memory. A shallow copy is just
 979     a copy of the pointer value and not of the string data itself.
 980
 981     The disadvantage of shallow copies is that because a pointer can
 982     be deleted only once, the program must put all strings in a
 983     central place and know when it is safe to delete them (i.e. when
 984     the strings are no longer referenced by other parts of the
 985     program). This can make the program more complex. The advantage of
 986     shallow copies is that they consume far less memory than deep
 987     copies. It is also much faster to copy a pointer (typically 4 or 8
 988     bytes) than to copy string data.
 989
 990     A Q3StrList that operates on deep copies will, by default, turn on
 991     auto-deletion (see setAutoDelete()). Thus, by default Q3StrList
 992     will deallocate any string copies it allocates.
 993
 994     The virtual compareItems() function is reimplemented and does a
 995     case-sensitive string comparison. The inSort() function will
 996     insert strings in sorted order. In general it is fastest to insert
 997     the strings as they come and sort() at the end; inSort() is useful
 998     when you just have to add a few extra strings to an already sorted
 999     list.
1000
1001     The Q3StrListIterator class is an iterator for Q3StrList.
1002 */
1003
1004 /*!
1005     \fn Q3StrList::operator QList<QByteArray>() const
1006
1007     Automatically converts a Q3StrList into a QList<QByteArray>.
1008 */
1009
1010 /*!
1011     \fn Q3StrList::Q3StrList( bool deepCopies )
1012
1013     Constructs an empty list of strings. Will make deep copies of all
1014     inserted strings if \a deepCopies is TRUE, or use shallow copies
1015     if \a deepCopies is FALSE.
1016 */
1017
1018 /*!
1019     \fn Q3StrList::Q3StrList(const Q3StrList &list)
1020     \fn Q3StrList::Q3StrList(const QList<QByteArray> &list)
1021
1022     Constructs a copy of \a list.
1023 */
1024
1025 /*!
1026     \fn Q3StrList::~Q3StrList()
1027
1028     Destroys the list. All strings are removed.
1029 */
1030
1031 /*!
1032     \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list)
1033     \fn Q3StrList &Q3StrList::operator=(const QList<QByteArray> &list)
1034
1035     Assigns \a list to this list and returns a reference to this list.
1036 */
1037
1038 /*!
1039     \class Q3StrIList
1040     \brief The Q3StrIList class provides a doubly-linked list of char*
1041     with case-insensitive comparison.
1042     \compat
1043
1044     This class is a Q3PtrList\<char\> instance (a list of char*).
1045
1046     Q3StrIList is identical to Q3StrList except that the virtual
1047     compareItems() function is reimplemented to compare strings
1048     case-insensitively. The inSort() function inserts strings in a
1049     sorted order. In general it is fastest to insert the strings as
1050     they come and sort() at the end; inSort() is useful when you just
1051     have to add a few extra strings to an already sorted list.
1052
1053     The Q3StrListIterator class works for Q3StrIList.
1054
1055     \sa QStringList
1056 */
1057
1058 /*!
1059     \fn Q3StrIList::Q3StrIList( bool deepCopies )
1060
1061     Constructs a list of strings. Will make deep copies of all
1062     inserted strings if \a deepCopies is TRUE, or use shallow copies
1063     if \a deepCopies is FALSE.
1064 */
1065
1066 /*!
1067     \fn Q3StrIList::~Q3StrIList()
1068
1069     Destroys the list. All strings are removed.
1070 */
1071
1072 /*!
1073     \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1,
1074                                     Q3PtrCollection::Item item2 )
1075
1076     This virtual function compares two list items.
1077
1078     Returns:
1079     \list
1080     \i zero if \a item1 == \a item2
1081     \i nonzero if \a item1 != \a item2
1082     \endlist
1083
1084     This function returns \e int rather than \e bool so that
1085     reimplementations can return three values and use it to sort by:
1086
1087     \list
1088     \i 0 if \a item1 == \a item2
1089     \i \> 0 (positive integer) if \a item1 \> \a item2
1090     \i \< 0 (negative integer) if \a item1 \< \a item2
1091     \endlist
1092
1093     inSort() requires that compareItems() is implemented as described
1094     here.
1095
1096     This function should not modify the list because some const
1097     functions call compareItems().
1098
1099     The default implementation compares the pointers.
1100 */
1101
1102 /*!
1103     \fn QDataStream& Q3PtrList::read( QDataStream& s,
1104                                     Q3PtrCollection::Item& item )
1105
1106     Reads a list item from the stream \a s and returns a reference to
1107     the stream.
1108
1109     The default implementation sets \a item to 0.
1110
1111     \sa write()
1112 */
1113
1114 /*!
1115     \fn QDataStream& Q3PtrList::write( QDataStream& s,
1116                                         Q3PtrCollection::Item item ) const
1117
1118     Writes a list item, \a item to the stream \a s and returns a
1119     reference to the stream.
1120
1121     The default implementation does nothing.
1122
1123     \sa read()
1124 */
1125
1126 /*! \fn iterator Q3PtrList::begin()
1127 \internal
1128 */
1129 /*! \fn const_iterator Q3PtrList::begin() const
1130 \internal
1131 */
1132 /*! \fn iterator Q3PtrList::end()
1133 \internal
1134 */
1135 /*! \fn const_iterator Q3PtrList::end() const
1136 \internal
1137 */
1138
1139 /*!
1140     \class Q3StrListIterator
1141     \brief The Q3StrListIterator class is an iterator for the Q3StrList
1142     and Q3StrIList classes.
1143     \compat
1144
1145     This class is a Q3PtrListIterator\<char\> instance. It can traverse
1146     the strings in the Q3StrList and Q3StrIList classes.
1147 */
1148
1149
1150 /*
1151     \class Q3PtrListAutoDelete
1152     \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data.
1153     \compat
1154
1155     A Q3PtrListAutoDelete is identical to a Q3PtrList with
1156     setAutoDelete(TRUE).
1157 */