Q3Dict Class Reference
[Qt3Support module]

Detailed Description

The Q3Dict class is a template class that provides a dictionary based on QString keys.

Q3Dict is implemented as a template class. Define a template instance Q3Dict<X> to create a dictionary that operates on pointers to X (X *).

A dictionary is a collection of key-value pairs. The key is a QString used for insertion, removal and lookup. The value is a pointer. Dictionaries provide very fast insertion and lookup.

If you want to use non-Unicode, plain 8-bit char* keys, use the Q3AsciiDict template. A Q3Dict has the same performance as a Q3AsciiDict. If you want to have a dictionary that maps QStrings to QStrings use QMap.

The size() of the dictionary is very important. In order to get good performance, you should use a suitably large prime number. Suitable means equal to or larger than the maximum expected number of dictionary items. Size is set in the constructor but may be changed with resize().

Items are inserted with insert(); 0 pointers cannot be inserted. Items are removed with remove(). All the items in a dictionary can be removed with clear(). The number of items in the dictionary is returned by count(). If the dictionary contains no items isEmpty() returns TRUE. You can change an item's value with replace(). Items are looked up with operator[](), or with find() which return a pointer to the value or 0 if the given key does not exist. You can take an item out of the dictionary with take().

Calling setAutoDelete(TRUE) for a dictionary tells it to delete items that are removed. The default behavior is not to delete items when they are removed.

When an item is inserted, the key is converted (hashed) to an integer index into an internal hash array. This makes lookup very fast.

Items with equal keys are allowed. When inserting two items with the same key, only the last inserted item will be accessible (last in, first out) until it is removed.

The Q3DictIterator class can traverse the dictionary, but only in an arbitrary order. Multiple iterators may independently traverse the same dictionary.

When inserting an item into a dictionary, only the pointer is copied, not the item itself, i.e. a shallow copy is made. It is possible to make the dictionary copy all of the item's data (a deep copy) when an item is inserted. insert() calls the virtual function Q3PtrCollection::newItem() for the item to be inserted. Inherit a dictionary and reimplement newItem() if you want deep copies.

When removing a dictionary item, the virtual function Q3PtrCollection::deleteItem() is called. Q3Dict's default implementation is to delete the item if auto-deletion is enabled.

See also Q3DictIterator, Q3AsciiDict, Q3IntDict, and Q3PtrDict.

Member Function Documentation

 Q3Dict<char> dict;
     ...
 if ( dict.find( key ) )
     dict.remove( key );
 dict.insert( key, item );