diff options
Diffstat (limited to 'doc/collect.doc')
| -rw-r--r-- | doc/collect.doc | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/doc/collect.doc b/doc/collect.doc new file mode 100644 index 000000000..604740d72 --- /dev/null +++ b/doc/collect.doc @@ -0,0 +1,248 @@ +/**************************************************************************** +** +** Qt collection classes documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial 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 WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + +/*! +\defgroup collection + +\title Collection Classes + +\keyword collection classes +\keyword persistent data + +A collection class is a container which holds a number of items in a +data structure and provides various operations to manipulate the +contents of the collection, such as insert item, remove item, find +item, etc. + +Qt has several value-based and several pointer-based collection +classes. The pointer-based collection classes work with pointers to +items, while the value-based classes store copies of their items. The +value-based collections are very similar to STL container classes, and +can be used with STL algorithms and containers. See the \link +qt-template-lib.html Qt Template Library\endlink documentation for +details. + +The value-based collections are: +\list +\i \l QValueList, a value-based list. +\i \l QValueVector, a value-based vector. +\i \l QValueStack, a value-based stack. +\i \l QMap, a value-based dictionary (associative array). +\endlist + +The pointer-based collections are: +\list +\i \l QCache and \l QIntCache, LRU (least recently used) caches. +\i \l QDict, \l QIntDict and \l QPtrDict dictionaries. +\i \l QPtrList, a doubly linked list. +\i \l QPtrQueue, a FIFO (first in, first out) queue. +\i \l QPtrStack, a LIFO (last in, first out) stack. +\i \l QPtrVector, a vector. +\endlist + +\l QMemArray is exceptional; it is neither pointer nor value based, +but memory based. For maximum efficiency with the simple data types +usually used in arrays, it uses bitwise operations to copy and compare +array elements. + +Some of these classes have corresponding iterators. An iterator +is a class for traversing the items in a collection: +\list +\i \link QCacheIterator QCacheIterator\endlink and + \link QIntCacheIterator QIntCacheIterator\endlink +\i \link QDictIterator QDictIterator\endlink, + \link QIntDictIterator QIntDictIterator\endlink, and + \link QPtrDictIterator QPtrDictIterator\endlink +\i \link QPtrListIterator QPtrListIterator\endlink +\i \link QValueListIterator QValueListIterator\endlink, and + \link QValueListConstIterator QValueListConstIterator\endlink +\i \link QMapIterator QMapIterator\endlink, and + \link QMapConstIterator QMapConstIterator\endlink +\endlist + +The value-based collections plus algorithms operating on them are +grouped together in the \link qt-template-lib.html Qt Template +Library\endlink; see also the \link qtl.html Qt Template +Library Classes\endlink. + +The rest of this page dicusses the pointer-based containers. + +\section1 Architecture of the pointer-based containers + +There are four internal base classes for the pointer-based +containers (QGCache, QGDict, QGList and QGVector) that operate on +void pointers. A thin template layer implements the actual +collections by casting item pointers to and from void pointers. + +This strategy allows Qt's templates to be very economical on space +(instantiating one of these templates adds only inlinable calls to +the base classes), without hurting performance. + +\section1 A QPtrList Example + +This example shows how to store Employee items in a list and prints +them out in reverse order: + +\code + #include <qptrlist.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; + }; + + int main() + { + QPtrList<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) ); + + QPtrListIterator<Employee> it(list); // iterator for employee list + for ( it.toLast(); it.current(); --it) ) { + Employee *emp = it.current(); + printf( "%s earns %d\n", emp->name(), emp->salary() ); + } + + return 0; + } +\endcode + +Program output: +\code + Ron earns 60000 + Steve earns 80000 + Bill earns 50000 +\endcode + +\section1 Managing Collection Items + +All pointer-based collections inherit the \l QPtrCollection base class. +This class only knows about the number of items in the collection and +the deletion strategy. + +By default, items in a collection are not deleted when they are +removed from the collection. The \l QPtrCollection::setAutoDelete() +function specifies the deletion strategy. In the list example, we +enable auto-deletion to make the list delete the items when they are +removed from the list. + +When inserting an item into a collection, only the pointer is copied, +not the item itself. This is called a shallow copy. It is possible to +make the collection copy all of the item's data (known as a deep copy) +when an item is inserted. All collection functions that insert an +item call the virtual function \l QPtrCollection::newItem() for the item +to be inserted. Inherit a collection and reimplement it if you want +to have deep copies in your collection. + +When removing an item from a list, the virtual function +\l{QPtrCollection::deleteItem()} is called. The default implementation +in all collection classes deletes the item if auto-deletion is +enabled. + +\section1 Usage + +A pointer-based collection class, such as QPtrList\<type\>, defines a +collection of \e pointers to \e type objects. The pointer (*) is +implicit. + +We discuss \l QPtrList here, but the same techniques apply to all +pointer-based collection classes and all collection class iterators. + +Template instantiation: +\code + QPtrList<Employee> list; // wherever the list is used +\endcode + +The item's class or type, Employee in our example, must be defined prior +to the list definition. + +\code + // Does not work: Employee is not defined + class Employee; + QPtrList<Employee> list; + + // This works: Employee is defined before it is used + class Employee { + ... + }; + QPtrList<Employee> list; +\endcode + +\section1 Iterators + +Although \l QPtrList has member functions to traverse the list, it can +often be better to make use of an iterator. \l QPtrListIterator is very +safe and can traverse lists that are being modified at the same time. +Multiple iterators can work independently on the same collection. + +A QPtrList has an internal list of all the iterators that are +currently operating on it. When a list entry is removed, the list +updates all iterators accordingly. + +The \l QDict and \l QCache collections have no traversal functions. To +traverse these collections, you must use \l QDictIterator or \l +QCacheIterator. + +\section1 Predefined Collections + +Qt has the following predefined collection classes: +\list +\i String lists: \l QStrList, \l QStrIList (\l qstrlist.h) and + \l QStringList (\l qstringlist.h) +\i String vectors: QStrVec and QStrIVec (qstrvec.h); these are obsolete +\endlist + +In almost all cases you would choose \l QStringList, a value +list of implicitly shared QString Unicode strings. QPtrStrList and +QPtrStrIList store only char pointers, not the strings themselves. + +\section1 List of Pointer-based Collection Classes and Related +Iterator Classes + +*/ |