You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
249 lines
8.7 KiB
249 lines
8.7 KiB
/****************************************************************************
|
|
**
|
|
** 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 requirements 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
|
|
|
|
*/
|