qvaluelist.doc

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

  \fn ConstIterator QValueList::at( uint i ) const
  Returns an iterator pointing to the item at position \e i in the list, or
  end() if the index is out of range.
*/

/*!
  \fn T& QValueList::first()
  Returns a reference to the first item in the list or the item
  referenced by end()
  if no such items exists. Please note that you may not change
  the value the end() Iterator is pointing to.

  \sa begin(), last()
*/

/*!
  \fn const T& QValueList::first() const
  Returns a reference to the first item in the list or the item
  referenced by end() if
  no such items exists.

  \sa begin(), last()
*/

/*!
  \fn Iterator QValueList::fromLast()
  Returns an iterator pointing to the last element in the list or
  end() if no such item exists.

  \sa last()
*/

/*!
  \fn ConstIterator QValueList::fromLast() const
  Returns an iterator pointing to the last element in the list or
  end() if no such item exists.

  \sa last()
*/

/*!
  \fn T& QValueList::last()
  Returns a reference to the last item in the list or the item
  referenced by end() if no
  such item exists. Please note that you may not change
  the value the end() Iterator is pointing to.

  \sa end(), first(), fromLast()
*/

/*!
  \fn const T& QValueList::last() const
  Returns a reference to the last item in the list or the item
  referenced by end() if no such item exists.

  \sa end(), first(), fromLast()
*/

/*!
  \fn Iterator QValueList::begin()
  Returns an iterator pointing to the first element in the list. This
  iterator equals end() if the list is empty;
  \sa first(), end()
*/

/*!
  \fn ConstIterator QValueList::begin() const
  Returns an iterator pointing to the first element in the list. This
  iterator equals end() if the list is empty;
  \sa first(), end()
*/

/*!
  \fn Iterator QValueList::end()
  Returns an iterator pointing behind the last element in the list. This
  iterator equals begin() if the list is empty.

  \sa last(), begin()
*/

/*!
  \fn ConstIterator QValueList::end() const
  Returns an iterator pointing behind the last element in the list. This
  iterator equals begin() if the list is empty.

  \sa last(), begin()
*/

/*!
  \fn void QValueList::detach()
  If the list does not share its data with another QValueList instance, then nothing
  happens, otherwise the function creates a new copy of this data and detaches
  from the shared one. This function is called whenever the list is modified.
  The implicit sharing mechanism is implemented this way.
*/

/*!
  \fn QDataStream& operator>>( QDataStream& s, QValueList<T>& l )
  \relates QValueList
  Reads a list from the stream. The type \e T stored in the list must implement
  the streaming operator, too.
*/

/*!
  \fn QDataStream& operator<<( QDataStream& s, const QValueList<T>& l )
  \relates QValueList
  Writes a list to the stream. The type \e T stored in the list must implement
  the streaming operator, too.
*/

/*****************************************************************************
  QValueListIterator documentation
 *****************************************************************************/

/*!
  \class QValueListIterator qvaluelist.h
  \brief The QValueListIterator class provides an iterator for QValueList.

  \ingroup qtl
  \ingroup tools

  You can not create an iterator by yourself. Instead you have to
  ask a list to give you one. An iterator has only the size of a pointer.
  On 32 bit machines that means 4 bytes otherwise 8 bytes. That makes them
  very fast. In fact they resemble the semantics of pointers as good as possible
  and they are almost as fast as usual pointers.

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

    class Employee
    {
    public:
	Employee(): s(0) {}
	Employee( const QString& name, int salary )
	    : n(name), s(salary)
	{}

	QString     name()   const		{ return n; }
	int	    salary() const		{ return s; }
	void	    setSalary( int salary )	{ s = salary; }
    private:
	QString     n;
	int         s;
    };

    void main()
	{
	    typedef QValueList<Employee> EmployeeList;
	    EmployeeList list;		// list of Employee

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

	    Employee joe( "Joe", 50000 );
	    list.append( joe );
	    joe.setSalary( 4000 );
	
	    EmployeeList::Iterator it;
	    for( it = list.begin(); it != list.end(); ++it )
		printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() );
	}
  \endcode

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

  In contrast to QList there are no built in functions in QValueList to
  traverse the list. The only way to do this is to use iterators.
  QValueList is highly optimized for performance and memory usage.
  On the other hand that means that you have to be a bit more careful
  by what you are doing. QValueList does not know about all its iterators
  and the iterators dont even know to which list they belong. That makes
  things fast and slim but a bit dangerous because it is up to you to make
  sure that iterators you are using are still valid. QListIterator will be able
  to give warnings while QValueListIterator may end up in an undefined state.

  For every Iterator there is a ConstIterator. When accessing a QValueList
  in a const environment or if the reference or pointer to the list is itself
  const, then you have to use the ConstIterator. Its semantics are the same,
  but it returns only const references to the item it points to.

  \sa QValueList, QValueListConstIterator
*/

/*!
  \fn QValueListIterator::QValueListIterator()
  Creates un uninitialized iterator.
*/

/*!
  \fn QValueListIterator::QValueListIterator( NodePtr p )
  Internal function.
*/

/*!
  \fn QValueListIterator::QValueListIterator( const QValueListIterator<T>& it )
  Constructs a copy of the iterator \e it.
*/

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

/* Unfortunately not with MSVC
  \fn T *QValueListIterator::operator->()
  Pointer operator. Returns a pointer to the current iterator item.
  The great advantage of this operator is that you can treat the
  iterator like a pointer.

  Example:
  \code
	QValueList<int>::Iterator it = list.begin();
	for( ; it != end(); ++it )
		it->show();
  \endcode
*/

/*!
  \fn T& QValueListIterator::operator*()
  Asterix operator. Returns a reference to the current iterator item.
*/

/*!
  \fn const T& QValueListIterator::operator*() const
  Asterix operator. Returns a reference to the current iterator item.
*/

/*!
  \fn QValueListIterator<T>& QValueListIterator::operator++()
  Prefix ++ makes the succeeding item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the end of the list. Incrementing
  the iterator as returned by end() causes undefined results.
*/

/*!
  \fn QValueListIterator<T> QValueListIterator::operator++(int)
  Postfix ++ makes the succeeding item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the end of the list. Incrementing
  the iterator as returned by end() causes undefined results.
*/

/*!
  \fn QValueListIterator<T>& QValueListIterator::operator--()
  Prefix -- makes the previous item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the beginning of the list. Decrementing
  the iterator as returned by begin() causes undefined results.
*/

/*!
  \fn QValueListIterator<T> QValueListIterator::operator--(int)
  Postfix -- makes the previous item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the beginning of the list. Decrementing
  the iterator as returned by begin() causes undefined results.
*/

/*!
  \fn bool QValueListIterator::operator==( const QValueListIterator<T>& it ) const
  Compares both iterators and returns TRUE if they point to the same item.
*/

/*!
  \fn bool QValueListIterator::operator!=( const QValueListIterator<T>& it ) const
  Compares both iterators and returns TRUE if they point to different items.
*/

/*****************************************************************************
  QValueListConstIterator documentation
 *****************************************************************************/

/*!
  \class QValueListConstIterator qvaluelist.h
  \brief The QValueListConstIterator class provides an iterator for QValueList.

  \ingroup qtl
  \ingroup tools

  In contrast to QValueListIterator this class is used to iterate over a const
  list. It does not allow to modify the values of the list since this would
  break the const semantics.

  For more informations on QValueList iterators see QValueListIterator.

  \sa QValueListIterator, QValueList
*/

/*!
  \fn QValueListConstIterator::QValueListConstIterator()
  Creates un uninitialized iterator.
*/

/*!
  \fn QValueListConstIterator::QValueListConstIterator( NodePtr p )
  Internal function.
*/

/*!
  \fn QValueListConstIterator::QValueListConstIterator( const QValueListConstIterator<T>& it )
  Constructs a copy of the iterator \e it.
*/

/*!
  \fn QValueListConstIterator::QValueListConstIterator( const QValueListIterator<T>& it )
  Constructs a copy of the iterator \e it.
*/

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

/* Unfortunately not with MSVC
  \fn const T *QValueListConstIterator::operator->()
  Pointer operator. Returns a pointer to the current iterator item.
  The great advantage of this operator is that you can treat the
  iterator like a pointer.

  Example:
  \code
	QValueList<int>::Iterator it = list.begin();
	for( ; it != end(); ++it )
		it->show();
  \endcode
*/

/*!
  \fn const T& QValueListConstIterator::operator*() const
  Asterix operator. Returns a reference to the current iterator item.
*/

/*!
  \fn QValueListConstIterator<T>& QValueListConstIterator::operator++()
  Prefix ++ makes the succeeding item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the end of the list. Incrementing
  the iterator as returned by end() causes undefined results.
*/

/*!
  \fn QValueListConstIterator<T> QValueListConstIterator::operator++(int)
  Postfix ++ makes the succeeding item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the end of the list. Incrementing
  the iterator as returned by end() causes undefined results.
*/

/*!
  \fn QValueListConstIterator<T>& QValueListConstIterator::operator--()
  Prefix -- makes the previous item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the beginning of the list. Decrementing
  the iterator as returned by begin() causes undefined results.
*/

/*!
  \fn QValueListConstIterator<T> QValueListConstIterator::operator--(int)
  Postfix -- makes the previous item current and returns
  an iterator pointing to the new current item.
  The iterator can not check wether it reached the beginning of the list. Decrementing
  the iterator as returned by begin() causes undefined results.
*/

/*!
  \fn bool QValueListConstIterator::operator==( const QValueListConstIterator<T>& it ) const
  Compares both iterators and returns TRUE if they point to the same item.
*/

/*!
  \fn bool QValueListConstIterator::operator!=( const QValueListConstIterator<T>& it ) const
  Compares both iterators and returns TRUE if they point to different items.
*/