Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# Collection Classes

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.

TQt 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 TQt Template Library documentation for details.

The value-based collections are:

- TQValueList, a value-based list.
- TQValueVector, a value-based vector.
- TQValueStack, a value-based stack.
- TQMap, a value-based dictionary (associative array).

The pointer-based collections are:

- TQCache and TQIntCache, LRU (least recently used) caches.
- TQDict, TQIntDict and TQPtrDict dictionaries.
- TQPtrList, a doubly linked list.
- TQPtrQueue, a FIFO (first in, first out) queue.
- TQPtrStack, a LIFO (last in, first out) stack.
- TQPtrVector, a vector.

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:

- TQCacheIterator and TQIntCacheIterator
- TQDictIterator, TQIntDictIterator, and TQPtrDictIterator
- TQPtrListIterator
- TQValueListIterator, and TQValueListConstIterator
- TQMapIterator, and TQMapConstIterator

The value-based collections plus algorithms operating on them are grouped together in the TQt Template Library; see also the TQt Template Library Classes.

The rest of this page dicusses the pointer-based containers.

## 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 TQt's templates to be very economical on space (instantiating one of these templates adds only inlinable calls to the base classes), without hurting performance.

## A TQPtrList Example

This example shows how to store Employee items in a list and prints them out in reverse order:

        #include <ntqptrlist.h>
        #include <ntqstring.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:
            TQString     n;
            int         s;
        };

        int main()
        {
            TQPtrList<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) );

            TQPtrListIterator<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;
        }

Program output:

        Ron earns 60000
        Steve earns 80000
        Bill earns 50000

## Managing Collection Items

All pointer-based collections inherit the 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 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 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 TQPtrCollection::deleteItem() is called. The default implementation in all collection classes deletes the item if auto-deletion is enabled.

## Usage

A pointer-based collection class, such as TQPtrList<type>, defines a collection of pointers to type objects. The pointer (*) is implicit.

We discuss TQPtrList here, but the same techniques apply to all pointer-based collection classes and all collection class iterators.

Template instantiation:

        TQPtrList<Employee> list;            // wherever the list is used

The item's class or type, Employee in our example, must be defined prior to the list definition.

        // Does not work: Employee is not defined
        class Employee;
        TQPtrList<Employee> list;

        // This works: Employee is defined before it is used
        class Employee {
            ...
        };
        TQPtrList<Employee> list;

## Iterators

Although TQPtrList has member functions to traverse the list, it can often be better to make use of an iterator. 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 TQDict and TQCache collections have no traversal functions. To traverse these collections, you must use TQDictIterator or TQCacheIterator.

## Predefined Collections

TQt has the following predefined collection classes:

- String lists: TQStrList, TQStrIList (ntqstrlist.h) and TQStringList (ntqstringlist.h)
- String vectors: TQStrVec and TQStrIVec (ntqstrvec.h); these are obsolete

In almost all cases you would choose TQStringList, a value list of implicitly shared TQString Unicode strings. TQPtrStrList and TQPtrStrIList store only char pointers, not the strings themselves.

## List of Pointer-based Collection Classes and Related Iterator Classes

TQAsciiCache | Template class that provides a cache based on char* keys
TQAsciiCacheIterator | Iterator for TQAsciiCache collections
TQAsciiDict | Template class that provides a dictionary based on char* keys
TQAsciiDictIterator | Iterator for TQAsciiDict collections
TQBitArray | Array of bits
TQBitVal | Internal class, used with TQBitArray
TQBuffer | I/O device that operates on a TQByteArray
TQByteArray | Array of bytes
TQCache | Template class that provides a cache based on TQString keys
TQCacheIterator | Iterator for TQCache collections
TQCString | Abstraction of the classic C zero-terminated char array (char *)
TQDict | Template class that provides a dictionary based on TQString keys
TQDictIterator | Iterator for TQDict collections
TQIntCache | Template class that provides a cache based on long keys
TQIntCacheIterator | Iterator for TQIntCache collections
TQIntDict | Template class that provides a dictionary based on long keys
TQIntDictIterator | Iterator for TQIntDict collections
TQObjectList | TQPtrList of TQObjects
TQObjectListIterator | Iterator for TQObjectLists
TQPtrCollection | The base class of most pointer-based TQt collections
TQPtrDict | Template class that provides a dictionary based on void* keys
TQPtrDictIterator | Iterator for TQPtrDict collections
TQPtrList | Template class that provides a list
TQPtrListIterator | Iterator for TQPtrList collections
TQPtrQueue | Template class that provides a queue
TQStrIList | Doubly-linked list of char* with case-insensitive comparison
TQStrList | Doubly-linked list of char*