From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qdict.html | 399 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 doc/html/qdict.html (limited to 'doc/html/qdict.html') diff --git a/doc/html/qdict.html b/doc/html/qdict.html new file mode 100644 index 0000000..04c3047 --- /dev/null +++ b/doc/html/qdict.html @@ -0,0 +1,399 @@ + + + + + +QDict Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

QDict Class Reference

+ +

The QDict class is a template class that provides a +dictionary based on QString keys. +More... +

#include <qdict.h> +

Inherits QPtrCollection. +

List of all member functions. +

Public Members

+ +

Important Inherited Members

+ +

Protected Members

+ +

Detailed Description

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

+ + +

+

QMap is an STL-compatible alternative to this class. +

QDict is implemented as a template class. Define a template +instance QDict<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 +QAsciiDict template. A QDict has the same performance as a +QAsciiDict. 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 behaviour 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 QDictIterator 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 QPtrCollection::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 +QPtrCollection::deleteItem() is called. QDict's default +implementation is to delete the item if auto-deletion is enabled. +

Example #1: +

+    QDict<QLineEdit> fields; // QString keys, QLineEdit* values
+    fields.insert( "forename", new QLineEdit( this ) );
+    fields.insert( "surname", new QLineEdit( this ) );
+
+    fields["forename"]->setText( "Homer" );
+    fields["surname"]->setText( "Simpson" );
+
+    QDictIterator<QLineEdit> it( fields ); // See QDictIterator
+    for( ; it.current(); ++it )
+        cout << it.currentKey() << ": " << it.current()->text() << endl;
+    cout << endl;
+
+    if ( fields["forename"] && fields["surname"] )
+        cout << fields["forename"]->text() << " " 
+            << fields["surname"]->text() << endl;  // Prints "Homer Simpson"
+
+    fields.remove( "forename" ); // Does not delete the line edit
+    if ( ! fields["forename"] )
+        cout << "forename is not in the dictionary" << endl;
+
+ +In this example we use a dictionary to keep track of the line +edits we're using. We insert each line edit into the dictionary +with a unique name and then access the line edits via the +dictionary. +

Example #2: +

+    QStringList styleList = QStyleFactory::styles();
+    styleList.sort();
+    QDict<int> letterDict( 17, FALSE );
+    for ( QStringList::Iterator it = styleList.begin(); it != styleList.end(); ++it ) {
+        QString styleName = *it;
+        QString styleAccel = styleName;
+        if ( letterDict[styleAccel.left(1)] ) {
+            for ( uint i = 0; i < styleAccel.length(); i++ ) {
+                if ( ! letterDict[styleAccel.mid( i, 1 )] ) {
+                    styleAccel = styleAccel.insert( i, '&' );
+                    letterDict.insert(styleAccel.mid( i, 1 ), (const int *)1);
+                    break;
+                }
+            }
+        } else {
+            styleAccel = "&" + styleAccel;
+            letterDict.insert(styleAccel.left(1), (const int *)1);
+        }
+        (void) new QAction( styleName, QIconSet(), styleAccel, parent );
+    }
+
+ +In the example we are using the dictionary to provide fast random +access to the keys, and we don't care what the values are. The +example is used to generate a menu of QStyles, each with a unique +accelerator key (or no accelerator if there are no unused letters +left). +

We first obtain the list of available styles, then sort them so +that the menu items will be ordered alphabetically. Next we create +a dictionary of int pointers. The keys in the dictionary are each +one character long, representing letters that have been used for +accelerators. We iterate through our list of style names. If the +first letter of the style name is in the dictionary, i.e. has been +used, we iterate over all the characters in the style name to see +if we can find a letter that hasn't been used. If we find an +unused letter we put the accelerator ampersand (&) in front of it +and add that letter to the dictionary. If we can't find an unused +letter the style will simply have no accelerator. If the first +letter of the style name is not in the dictionary we use it for +the accelerator and add it to the dictionary. Finally we create a +QAction for each style. +

See also QDictIterator, QAsciiDict, QIntDict, QPtrDict, Collection Classes, and Non-GUI Classes. + +

Member Function Documentation

+

QDict::QDict ( int size = 17, bool caseSensitive = TRUE ) +

+ +

Constructs a dictionary optimized for less than size entries. +

We recommend setting size to a suitably large prime number +(e.g. a prime that's slightly larger than the expected number of +entries). This makes the hash distribution better which will lead +to faster lookup. +

If caseSensitive is TRUE (the default), keys which differ only +by case are considered different. + +

QDict::QDict ( const QDict<type> & dict ) +

+ +

Constructs a copy of dict. +

Each item in dict is inserted into this dictionary. Only the +pointers are copied (shallow copy). + +

QDict::~QDict () +

+ +

Removes all items from the dictionary and destroys it. If +setAutoDelete() is TRUE, each value is deleted. All iterators that +access this dictionary will be reset. +

See also setAutoDelete(). + +

bool QPtrCollection::autoDelete () const +

+ +

Returns the setting of the auto-delete option. The default is FALSE. +

See also setAutoDelete(). + +

void QDict::clear () [virtual] +

+ +

Removes all items from the dictionary. +

The removed items are deleted if auto-deletion is enabled. +

All dictionary iterators that operate on the dictionary are reset. +

See also remove(), take(), and setAutoDelete(). + +

Reimplemented from QPtrCollection. +

uint QDict::count () const [virtual] +

+ +

Returns the number of items in the dictionary. +

See also isEmpty(). + +

Reimplemented from QPtrCollection. +

type * QDict::find ( const QString & key ) const +

+ +

Returns the item with key key, or 0 if the key does not exist +in the dictionary. +

If there are two or more items with equal keys, then the most +recently inserted item will be found. +

Equivalent to the [] operator. +

See also operator[](). + +

void QDict::insert ( const QString & key, const type * item ) +

+ +

Inserts the key key with value item into the dictionary. +

Multiple items can have the same key, in which case only the last +item will be accessible using operator[](). +

item may not be 0. +

See also replace(). + +

Example: themes/themes.cpp. +

bool QDict::isEmpty () const +

+ +

Returns TRUE if the dictionary is empty, i.e. count() == 0; +otherwise returns FALSE. +

See also count(). + +

QDict<type> & QDict::operator= ( const QDict<type> & dict ) +

+ +

Assigns dict to this dictionary and returns a reference to this +dictionary. +

This dictionary is first cleared, then each item in dict is +inserted into this dictionary. Only the pointers are copied +(shallow copy), unless newItem() has been reimplemented. + +

type * QDict::operator[] ( const QString & key ) const +

+ +

Returns the item with key key, or 0 if the key does not +exist in the dictionary. +

If there are two or more items with equal keys, then the most +recently inserted item will be found. +

Equivalent to the find() function. +

See also find(). + +

QDataStream & QDict::read ( QDataStream & s, QPtrCollection::Item & item ) [virtual protected] +

+ +

Reads a dictionary item from the stream s and returns a +reference to the stream. +

The default implementation sets item to 0. +

See also write(). + +

bool QDict::remove ( const QString & key ) +

+ +

Removes the item with key from the dictionary. Returns TRUE if +successful, i.e. if the item is in the dictionary; otherwise +returns FALSE. +

If there are two or more items with equal keys, then the last item +that was inserted will be removed. +

The removed item is deleted if auto-deletion is enabled. +

All dictionary iterators that refer to the removed item will be +set to point to the next item in the dictionary's traversal order. +

See also take(), clear(), and setAutoDelete(). + +

void QDict::replace ( const QString & key, const type * item ) +

+ +

Replaces the value of the key, key with item. +

If the item does not already exist, it will be inserted. +

item may not be 0. +

Equivalent to: +

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

If there are two or more items with equal keys, then the last item +that was inserted will be replaced. +

See also insert(). + +

void QDict::resize ( uint newsize ) +

+ +

Changes the size of the hash table to newsize. The contents of +the dictionary are preserved, but all iterators on the dictionary +become invalid. + +

void QPtrCollection::setAutoDelete ( bool enable ) +

+ +

Sets the collection to auto-delete its contents if enable is +TRUE and to never delete them if enable is FALSE. +

If auto-deleting is turned on, all the items in a collection are +deleted when the collection itself is deleted. This is convenient +if the collection has the only pointer to the items. +

The default setting is FALSE, for safety. If you turn it on, be +careful about copying the collection - you might find yourself +with two collections deleting the same items. +

Note that the auto-delete setting may also affect other functions +in subclasses. For example, a subclass that has a remove() +function will remove the item from its data structure, and if +auto-delete is enabled, will also delete the item. +

See also autoDelete(). + +

Examples: grapher/grapher.cpp, scribble/scribble.cpp, and table/bigtable/main.cpp. +

uint QDict::size () const +

+ +

Returns the size of the internal hash array (as specified in the +constructor). +

See also count(). + +

void QDict::statistics () const +

+ +

Debugging-only function that prints out the dictionary +distribution using qDebug(). + +

type * QDict::take ( const QString & key ) +

+ +

Takes the item with key out of the dictionary without deleting +it (even if auto-deletion is enabled). +

If there are two or more items with equal keys, then the last item +that was inserted will be taken. +

Returns a pointer to the item taken out, or 0 if the key does not +exist in the dictionary. +

All dictionary iterators that refer to the taken item will be set +to point to the next item in the dictionary traversal order. +

See also remove(), clear(), and setAutoDelete(). + +

QDataStream & QDict::write ( QDataStream & s, QPtrCollection::Item ) const [virtual protected] +

+ +

Writes a dictionary item to the stream s and returns a +reference to the stream. +

See also read(). + + +

+This file is part of the Qt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
Qt 3.3.8
+
+ -- cgit v1.2.1