diff options
Diffstat (limited to 'trunk/qtools/qvaluelist.doc')
| -rw-r--r-- | trunk/qtools/qvaluelist.doc | 772 |
1 files changed, 0 insertions, 772 deletions
diff --git a/trunk/qtools/qvaluelist.doc b/trunk/qtools/qvaluelist.doc deleted file mode 100644 index e4621d5..0000000 --- a/trunk/qtools/qvaluelist.doc +++ /dev/null @@ -1,772 +0,0 @@ -/**************************************************************************** -** -** -** QValueList and QValueListIterator class documentation -** -** Copyright (C) 1992-2000 Trolltech AS. All rights reserved. -** -** This file is part of the Qt GUI Toolkit. -** -** This file may be distributed under the terms of the Q Public License -** as defined by Trolltech AS of Norway and appearing in the file -** LICENSE.QPL included in the packaging of this file. -** -** This file may be distributed and/or modified under the terms of the -** GNU General Public License version 2 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. -** -** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition -** licenses may use this file in accordance with the Qt Commercial License -** Agreement provided with the Software. -** -** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE -** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -** -** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for -** information about Qt Commercial License Agreements. -** See http://www.trolltech.com/qpl/ for QPL licensing information. -** See http://www.trolltech.com/gpl/ for GPL licensing information. -** -** Contact info@trolltech.com if any conditions of this licensing are -** not clear to you. -** -**********************************************************************/ - - -/***************************************************************************** - QValueList documentation - *****************************************************************************/ - -/*! - \class QValueList qvaluelist.h - \brief The QValueList class is a value based template class that provides doubly linked lists. - - \ingroup qtl - \ingroup tools - \ingroup shared - - Define a template instance QValueList\<X\> to create a list of values which all - have the class X. Please notice that QValueList does not store pointers to the - members of the list. It holds a copy of every member. That is the reason why this - kind of classes are called "value based" while QList and QDict are "reference based". - - Some classes can not be used within a QValueList, for example everything - derived from QObject and thus all classes that implement widgets. - Only values can be used in a QValueList. To qualify as a value, the class - must provide - <ul> - <li>a copy constructor, - <li>an assignment operator and - <li> a default constructor, i.e. a constructor that does not take any arguments. - </ul> - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many cases, - this is sufficient. - - 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().latin1() ); - } - \endcode - - Program output: - \code - Bill earns 50000 - Steve earns 80000 - Ron earns 60000 - Joe earns 50000 - \endcode - - As you can see, the latest changes to Joes salary did not affect the value - in the list because the list created a copy of Joes entry. - - There are three ways of finding items in the list. The first one is by using - the at() function. It returns an iterator. The advantages of - getting an iterator is that you can now move forward or backward from this - position by incrementing/decrementing the iterator. To get the amount of - items in the list call count(). Valid indices are 0..count(). - - The second way of accessing a list is with operator[]. That means you can address - it like an array. The return value is a reference to the value stored in the list. - There exist two versions of this operator. The first one is const and returns a - const reference to the value. The second on is non const and returns a non const - reference to the value. It is up to your compiler to choose the correct one. - - The third method is to use the functions begin() and end(). - With a simple for loop as shown in the example you can iterate over the complete list. - It is save to have multiple iterators at the same time. If some member of the list is - removed then only iterators pointing to the removed member become invalid. Inserting in - the list does not invalidate any iterator. For convenience the function last() returns - an iterator for the last and first() for the first element in the list. - - In addition you can search items in the list with the find() function. It exists in a const - and a non const version. It starts searching from the beginning of the list, but another - flavor of the find() function allows you to specify where searching should start. - If you just want to know wether a certain item is at least once in the list, then you - can use the contains() function. - - Since QValueList is value based there is no need to care about deleting elements in the - list. The list holds its own copies and will free them if the corresponding member or - the list itself is deleted. You can force the list to free all of its item with clear(). - - QValueList is implicitly shared. That means you can just make copies of the list - in time O(1). If multiple QValueList instances share the same data and one - is doing a modification of the lists data then this modifying instance makes a copy - and modifies its private copy. So it does not affect the other instances. - From a developers point of view you can think that a QValueList and a copy of this - list have nothing to do with each other. Developers may only notice that copying is - very fast. People known to a CPUs MMU architecture will know this pattern as "copy on write". - - There exist three functions to insert items in the list. append() - inserts an item at the end, prepend() inserts at the beginning - and insert() inserts in front of the position given by an iterator. - - Items can be removed from the list in two ways. The first is to pass an iterator to - the remove(). The other possibility is to pass a value to remove() which will - delete all members which match this value. - - Lists can be sorted with the algorithms provided by the <a - href="qtl.html">Qt Template Library</a>, for example with - qHeapSort(): - - Example: - \code - QValueList l; - l.append( 5 ); - l.append( 8 ); - l.append( 3 ); - l.append( 4 ); - qHeapSort( l ); - \endcode - - \sa QValueListIterator -*/ - - -/*! - \fn QValueList::QValueList() - Constructs an empty list. -*/ - -/*! - \fn QValueList::QValueList( const QValueList<T>& l ) - Constructs a copy of \e l. - - This operation costs O(1) time since QValueList is implicit shared. - The first instance applying modifications to a shared list will create - a copy which takes in turn O(n) time. However returning a QValueList from - a function is very fast. -*/ - -/*! - \fn QValueList::~QValueList() - Destroys the list. References to the values in the list and all iterators - of this list become invalidated. Since QValueList is highly tuned for performance - you wont see warnings if you use invalid iterators, - because it is impossible for - an iterator to check wether it is valid or not. -*/ - -/*! - \fn QValueList<T>& QValueList::operator= ( const QValueList<T>& l ) - Assigns \e l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this operation. - The cost of such an assignment is O(1) since QValueList is implicitly shared. -*/ - -/*! - \fn QValueList<T> QValueList::operator+ ( const QValueList<T>& l ) const - Creates a new list and fills it with the elements of this list. Then the - elements of \e l are appended. - - Returns the new list. -*/ - -/*! - \fn QValueList<T>& QValueList::operator+= ( const QValueList<T>& l ) - Adds \e list to this list. - - Returns a reference to this list. -*/ - -/*! - \fn bool QValueList::operator== ( const QValueList<T>& l ) const - Compares both lists. - - Returns TRUE if both list are equal. -*/ - -/*! - \fn bool QValueList::operator!= ( const QValueList<T>& l ) const - Compares both lists. - - Returns TRUE if both list are unequal. -*/ - -/*! - \fn QValueList<T>& QValueList::operator+= ( const T& x ) - Adds the value \e x to the end of the list. - - Returns a reference to the list. -*/ - -/*! - \fn QValueList<T>& QValueList::operator<< ( const T& x ) - Adds the value \e x to the end of the list. - - Returns a reference to the list. -*/ - -/*! - \fn const T& QValueList::operator[] ( uint i ) const - Returns a const reference to the item with index \e i in the list. - It is up to you to check wether this item really exists. You can do that easily - with the count() function. However this operator does not check wether \e i - is in range and will deliver undefined results if it does not exist. -*/ - -/*! - \fn T& QValueList::operator[] ( uint i ) - Returns a reference to the item with index \e i in the list. - It is up to you to check wether this item really exists. You can do that easily - with the count() function. However this operator does not check wether \e i - is in range and will deliver undefined results if it does not exist. - In contrast to the const operator[] you may manipulate the value returned by this - operator. -*/ - -/*! - \fn uint QValueList::count() const - Returns the number of items in the list. - \sa isEmpty() -*/ - -/*! - \fn bool QValueList::isEmpty() const - Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE - otherwise. - \sa count() -*/ - -/*! - \fn Iterator QValueList::insert( Iterator it, const T& x ) - Inserts the value \e x in front of the iterator \e it. - - Returns an iterator pointing at the inserted item. - - \sa append(), prepend() -*/ - -/*! - \fn Iterator QValueList::append( const T& x ) - Inserts the value \e x at the end of the list. - - Returns an iterator pointing at the inserted item. - - \sa insert(), prepend() -*/ - -/*! - \fn Iterator QValueList::prepend( const T& x ) - Inserts the value \e x at the beginning of the list. - - Returns an iterator pointing at the inserted item. - - \sa insert(), append() -*/ - -/*! - \fn Iterator QValueList::remove( Iterator it ) - Removes the item at position \e it in the list. - - Returns an iterator pointing to the item following the - removed on or end() if the last item was deleted. - - \sa clear() -*/ - -/*! - \fn void QValueList::remove( const T& x ) - Removes all items which have the value \e x. - - \sa clear() -*/ - -/*! - \fn void QValueList::clear() - Removes all items from the list. - - \sa remove() -*/ - -/*! - \fn Iterator QValueList::find( const T& x ) - Finds the first occurrence of \e x in the list. - - Returns end() if no item did match. -*/ - -/*! - \fn ConstIterator QValueList::find( const T& x ) const - Finds the first occurrence of \e x in the list. - - Returns end() if no item did match. -*/ - -/*! - \fn Iterator QValueList::find( Iterator it, const T& x ) - Finds the first occurrence of \e x in the list starting at - the position given by \e it. - - Returns end() if no item did match. -*/ - -/*! - \fn ConstIterator QValueList::find( ConstIterator it, const T& x ) const - Finds the first occurrence of \e x in the list starting at - the position given by \e it. - - Returns end() if no item did match. -*/ - -/*! - \fn uint QValueList::contains( const T& x ) const - Counts and returns the number of occurrences of the value \e x in the list. -*/ - -/*! - \fn int QValueList::findIndex( const T& x ) const - Returns the first index of the value \e x in the list or -1 if no such value - can be found in the list. -*/ - -/*! - \fn Iterator QValueList::at( uint i ) - Returns an iterator pointing to the item at position \e i in the list, or - end() if the index is out of range. -*/ - -/*! - \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. -*/ |