1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 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 */