/**************************************************************************** ** ** TQt collection classes documentation ** ** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. ** ** This file is part of the TQt 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 TQt 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 TQt Template Library\endlink documentation for details. The value-based collections are: \list \i \l TQValueList, a value-based list. \i \l TQValueVector, a value-based vector. \i \l TQValueStack, a value-based stack. \i \l TQMap, a value-based dictionary (associative array). \endlist The pointer-based collections are: \list \i \l TQCache and \l TQIntCache, LRU (least recently used) caches. \i \l TQDict, \l TQIntDict and \l TQPtrDict dictionaries. \i \l TQPtrList, a doubly linked list. \i \l TQPtrQueue, a FIFO (first in, first out) queue. \i \l TQPtrStack, a LIFO (last in, first out) stack. \i \l TQPtrVector, a vector. \endlist \l TQMemArray 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 TQCacheIterator TQCacheIterator\endlink and \link TQIntCacheIterator TQIntCacheIterator\endlink \i \link TQDictIterator TQDictIterator\endlink, \link TQIntDictIterator TQIntDictIterator\endlink, and \link TQPtrDictIterator TQPtrDictIterator\endlink \i \link TQPtrListIterator TQPtrListIterator\endlink \i \link TQValueListIterator TQValueListIterator\endlink, and \link TQValueListConstIterator TQValueListConstIterator\endlink \i \link TQMapIterator TQMapIterator\endlink, and \link TQMapConstIterator TQMapConstIterator\endlink \endlist The value-based collections plus algorithms operating on them are grouped together in the \link qt-template-lib.html TQt Template Library\endlink; see also the \link ntqtl.html TQt 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 (TQGCache, TQGDict, TQGList and TQGVector) 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 TQPtrList Example This example shows how to store Employee items in a list and prints them out in reverse order: \code #include #include #include 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: TQString n; int s; }; int main() { TQPtrList 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) ); TQPtrListIterator 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 TQPtrCollection 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 TQPtrCollection::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 TQPtrCollection::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{TQPtrCollection::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 TQPtrList\, defines a collection of \e pointers to \e type objects. The pointer (*) is implicit. We discuss \l TQPtrList here, but the same techniques apply to all pointer-based collection classes and all collection class iterators. Template instantiation: \code TQPtrList 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; TQPtrList list; // This works: Employee is defined before it is used class Employee { ... }; TQPtrList list; \endcode \section1 Iterators Although \l TQPtrList has member functions to traverse the list, it can often be better to make use of an iterator. \l TQPtrListIterator 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 TQPtrList 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 TQDict and \l TQCache collections have no traversal functions. To traverse these collections, you must use \l TQDictIterator or \l TQCacheIterator. \section1 Predefined Collections Qt has the following predefined collection classes: \list \i String lists: \l TQStrList, \l TQStrIList (\l tqstrlist.h) and \l TQStringList (\l tqstringlist.h) \i String vectors: TQStrVec and TQStrIVec (tqstrvec.h); these are obsolete \endlist In almost all cases you would choose \l TQStringList, a value list of implicitly shared TQString Unicode strings. TQPtrStrList and TQPtrStrIList store only char pointers, not the strings themselves. \section1 List of Pointer-based Collection Classes and Related Iterator Classes */