qlist.doc

doxygen(一个自动从源代码生成文档的工具)的源代码

  \ingroup collection
  \ingroup tools

  Define a template instance QListIterator\<X\> to create a list iterator
  that operates on QList\<X\> (list of X*).

  Example:
  \code
    #include <qlist.h>
    #include <qstring.h>
    #include <stdio.h>

    class Employee
    {
    public:
        Employee( const char *name, int salary ) { n=name; s=salary; }
        const char *name()   const		 { return n; }
        int	    salary() const		 { return s; }
    private:
        QString     n;
        int         s;
    };

    void main()
    {
	QList<Employee> list;		  // list of pointers to Employee
	list.setAutoDelete( TRUE );	  // delete items when they are removed

	list.append( new Employee("Bill", 50000) );
	list.append( new Employee("Steve",80000) );
	list.append( new Employee("Ron",  60000) );

	QListIterator<Employee> it(list); // iterator for employee list
	for ( ; it.current(); ++it ) {
	    Employee *emp = it.current();
	    printf( "%s earns %d\n", emp->name().latin1(), emp->salary() );
        }
    }
  \endcode

  Program output:
  \code
	Bill earns 50000
	Steve earns 80000
	Ron earns 60000
  \endcode

  Although QList has member functions to traverse the doubly linked list
  structure, using a list iterator is a much more robust way of traversing
  the list, because multiple list iterators can operate on the same list,
  independent of each other and independent of the QList's current item.
  An iterator has its own current list item and can get the next and
  previous list items.  It can only traverse the list, never modify it.

  A QList knows about all list iterators that are operating on the list.
  When an item is removed from the list, the list update all iterators
  that are pointing the removed item to point to the new current list item.

  Example:
  \code
    #include <qlist.h>
    #include <qstring.h>
    #include <stdio.h>

    class Employee
    {
	...	// same as above
    };

    void main()
    {
	QList<Employee> list;		  // list of pointers to Employee
	list.setAutoDelete( TRUE );	  // delete items when they are removed

	list.append( new Employee("Bill", 50000) );
	list.append( new Employee("Steve",80000) );
	list.append( new Employee("Ron",  60000) );

	QListIterator<Employee> it(list);

	list.at( 1 );			  // current list item: "Steve"
        it.toLast();			  // it: "Ron"
	--it;				  // it: "Steve"

	  // Now, both the list and the iterator are referring the same item

	list.remove();
	printf( "%s\n", it.current()->name().latin1() );
    }
  \endcode

  Program output:
  \code
	Ron
  \endcode

  \sa QList, \link collection.html collection classes\endlink
*/

/*!
  \fn QListIterator::QListIterator( const QList<type> &list )
  Constructs an iterator for \e list.  The current iterator item is
  set to point on the first item in the \e list.
*/

/*!
  \fn QListIterator::~QListIterator()
  Destroys the iterator.
*/

/*!
  \fn uint QListIterator::count() const
  Returns the number of items in the list this iterator operates on.
  \sa isEmpty()
*/

/*!
  \fn bool QListIterator::isEmpty() const
  Returns TRUE if the list is empty, i.e. count() == 0, otherwise FALSE.
  \sa count()
*/

/*!
  \fn bool QListIterator::atFirst() const
  Returns TRUE if the current iterator item is the first list item, otherwise
  FALSE.
  \sa toFirst(), atLast()
*/

/*!
  \fn bool QListIterator::atLast() const
  Returns TRUE if the current iterator item is the last list item, otherwise
  FALSE.
  \sa toLast(), atFirst()
*/

/*!
  \fn type *QListIterator::toFirst()
  Sets the current iterator item to point to the first list item and returns
  a pointer to the item.  Sets the current item to null and returns null
  if the list is empty.
  \sa toLast(), atFirst()
*/

/*!
  \fn type *QListIterator::toLast()
  Sets the current iterator item to point to the last list item and returns
  a pointer to the item.  Sets the current item to null and returns null
  if the list is empty.
  \sa toFirst(), atLast()
*/

/*!
  \fn QListIterator::operator type *() const
  Cast operator. Returns a pointer to the current iterator item.
  Same as current().
*/

/*!
  \fn type *QListIterator::operator*()
  Asterix operator. Returns a pointer to the current iterator item.
  Same as current().
*/

/*!
  \fn type *QListIterator::current() const
  Returns a pointer to the current iterator item.
*/

/*!
  \fn type *QListIterator::operator()()
  Makes the succeeding item current and returns the original current item.

  If the current iterator item was the last item in the list or if it was
  null, null is returned.
*/

/*!
  \fn char *QStrListIterator::operator()()
  Makes the succeeding item current and returns the original current item.

  If the current iterator item was the last item in the list or if it was
  null, null is returned.
*/

/*!
  \fn type *QListIterator::operator++()
  Prefix ++ makes the succeeding item current and returns the new current
  item.

  If the current iterator item was the last item in the list or if it was
  null, null is returned.
*/

/*!
  \fn type *QListIterator::operator+=( uint jump )
  Sets the current item to the item \e jump positions after the current item,
  and returns a pointer to that item.

  If that item is beyond the last item or if the dictionary is  empty,
  it sets the current item to null and  returns null
*/

/*!
  \fn type *QListIterator::operator--()
  Prefix -- makes the preceding item current and returns the new current
  item.

  If the current iterator item was the first item in the list or if it was
  null, null is returned.
*/

/*!
  \fn type *QListIterator::operator-=( uint jump )
  Returns the item \e jump positions before the current item, or null if
  it is beyond the first item.  Makes this the current item.
*/

/*!
  \fn QListIterator<type>& QListIterator::operator=( const QListIterator<type> &it )
  Assignment.  Makes a copy of the iterator \a it and returns a reference
  to this iterator.
*/


/*****************************************************************************
  QStrList documentation
 *****************************************************************************/

typedef QList<char> QStrList

/*!
  \class QStrList qstrlist.h
  \brief The QStrList class provides a doubly linked list of \c char*.

  \inherit QList

  \ingroup collection
  \ingroup tools

  This class is a QList\<char\> instance (a list of char*).

  QStrList can make deep or shallow copies of the strings that are inserted.

  A deep copy means to allocate space for the string and then copy the string
  data into it.  A shallow copy is just a copy of the pointer value and not
  the string data.

  The disadvantage with shallow copies is that since a pointer can only
  be deleted once, the program must put all strings in a central place and
  know when it is safe to delete them (i.e. when the strings are no longer
  referenced by other parts of the program).  This can make the program
  more complex.  The advantage of shallow copies is that shallow copies
  consume far less memory than deep copies.  It is also much faster
  to copy a pointer (typically 4 or 8 bytes) than to copy string data.

  A QStrList that operates on deep copies will by default turn on
  auto-deletion (see setAutoDelete()). Thus, by default, QStrList will
  deallocate any string copies it allocates.

  The virtual compareItems() function is reimplemented and does a case
  sensitive string comparison. The inSort() function will insert
  strings in a sorted order.

  The QStrListIterator class is an iterator for QStrList.
*/

/*!
  \fn QStrList::QStrList( bool deepCopies )
  Constructs an empty list of strings.  Will make deep copies of all inserted
  strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
  is FALSE.
*/

/*!
  \fn QStrList::QStrList( const QStrList &list )
  Constructs a copy of \e list.

  If \e list has deep copies, this list will also get deep copies.
  Only the pointers are copied (shallow copy) if the other list does not
  use deep copies.
*/

/*!
  \fn QStrList::~QStrList()
  Destroys the list.  All strings are removed.
*/

/*!
  \fn QStrList& QStrList::operator=( const QStrList& list )
  Assigns \e list to this list and returns a reference to this list.

  If \e list has deep copies, this list will also get deep copies.
  Only the pointers are copied (shallow copy) if the other list does not
  use deep copies.
*/


/*****************************************************************************
  QStrIList documentation
 *****************************************************************************/

/*!
  \class QStrIList qstrlist.h
  \brief The QStrIList class provides a doubly linked list of \c char* with
case insensitive compare.

  \ingroup collection
  \ingroup tools

  This class is a QList\<char\> instance (a list of char*).

  QStrIList is similar to QStrList except that it is case insensitive.
  The virtual compareItems() function is reimplemented and does a
  case insensitive string comparison.
  The inSort() function will insert strings in a sorted order.

  The QStrListIterator class is an iterator for QStrList.
*/

/*!
  \fn QStrIList::QStrIList( bool deepCopies )
  Constructs a list of strings.  Will make deep copies of all inserted
  strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
  is FALSE.
*/

/*!
  \fn QStrIList::~QStrIList()
  Destroys the list.  All strings are removed.
*/


/*****************************************************************************
  QStrListIterator documentation
 *****************************************************************************/

/*!
  \class QStrListIterator qstrlist.h
  \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes.

  \inherit QListIterator

  \ingroup tools

  This class is a QListIterator\<char\> instance.
  It can traverse the strings in the QStrList and QStrIList classes.
*/