diff options
Diffstat (limited to 'doc/man/man3/qptrdict.3qt')
| -rw-r--r-- | doc/man/man3/qptrdict.3qt | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/doc/man/man3/qptrdict.3qt b/doc/man/man3/qptrdict.3qt new file mode 100644 index 0000000..684e420 --- /dev/null +++ b/doc/man/man3/qptrdict.3qt @@ -0,0 +1,315 @@ +'\" t +.TH QPtrDict 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*- +.\" Copyright 1992-2007 Trolltech ASA. All rights reserved. See the +.\" license file included in the distribution for a complete license +.\" statement. +.\" +.ad l +.nh +.SH NAME +QPtrDict \- Template class that provides a dictionary based on void* keys +.SH SYNOPSIS +\fC#include <qptrdict.h>\fR +.PP +Inherits QPtrCollection. +.PP +.SS "Public Members" +.in +1c +.ti -1c +.BI "\fBQPtrDict\fR ( int size = 17 )" +.br +.ti -1c +.BI "\fBQPtrDict\fR ( const QPtrDict<type> & dict )" +.br +.ti -1c +.BI "\fB~QPtrDict\fR ()" +.br +.ti -1c +.BI "QPtrDict<type> & \fBoperator=\fR ( const QPtrDict<type> & dict )" +.br +.ti -1c +.BI "virtual uint \fBcount\fR () const" +.br +.ti -1c +.BI "uint \fBsize\fR () const" +.br +.ti -1c +.BI "bool \fBisEmpty\fR () const" +.br +.ti -1c +.BI "void \fBinsert\fR ( void * key, const type * item )" +.br +.ti -1c +.BI "void \fBreplace\fR ( void * key, const type * item )" +.br +.ti -1c +.BI "bool \fBremove\fR ( void * key )" +.br +.ti -1c +.BI "type * \fBtake\fR ( void * key )" +.br +.ti -1c +.BI "type * \fBfind\fR ( void * key ) const" +.br +.ti -1c +.BI "type * \fBoperator[]\fR ( void * key ) const" +.br +.ti -1c +.BI "virtual void \fBclear\fR ()" +.br +.ti -1c +.BI "void \fBresize\fR ( uint newsize )" +.br +.ti -1c +.BI "void \fBstatistics\fR () const" +.br +.in -1c +.SS "Important Inherited Members" +.in +1c +.ti -1c +.BI "bool \fBautoDelete\fR () const" +.br +.ti -1c +.BI "void \fBsetAutoDelete\fR ( bool enable )" +.br +.in -1c +.SS "Protected Members" +.in +1c +.ti -1c +.BI "virtual QDataStream & \fBread\fR ( QDataStream & s, QPtrCollection::Item & item )" +.br +.ti -1c +.BI "virtual QDataStream & \fBwrite\fR ( QDataStream & s, QPtrCollection::Item ) const" +.br +.in -1c +.SH DESCRIPTION +The QPtrDict class is a template class that provides a dictionary based on void* keys. +.PP +QPtrDict is implemented as a template class. Define a template instance QPtrDict<X> to create a dictionary that operates on pointers to X (X*). +.PP +A dictionary is a collection of key-value pairs. The key is a void* used for insertion, removal and lookup. The value is a pointer. Dictionaries provide very fast insertion and lookup. +.PP +Example: +.PP +.nf +.br + QPtrDict<char> fields; // void* keys, char* values +.br +.br + QLineEdit *le1 = new QLineEdit( this ); +.br + le1->setText( "Simpson" ); +.br + QLineEdit *le2 = new QLineEdit( this ); +.br + le2->setText( "Homer" ); +.br + QLineEdit *le3 = new QLineEdit( this ); +.br + le3->setText( "45" ); +.br +.br + fields.insert( le1, "Surname" ); +.br + fields.insert( le2, "Forename" ); +.br + fields.insert( le3, "Age" ); +.br +.br + QPtrDictIterator<char> it( fields ); +.br + for( ; it.current(); ++it ) +.br + cout << it.current() << endl; +.br + cout << endl; +.br +.br + if ( fields[le1] ) // Prints "Surname: Simpson" +.br + cout << fields[le1] << ": " << le1->text() << endl; +.br +.br + if ( fields[le2] ) // Prints "Forename: Homer" +.br + cout << fields[le2] << ": " << le2->text() << endl; +.br +.br +.br + fields.remove( le1 ); // Removes le1 from the dictionary +.br + cout << le1->text() << endl; // Prints "Simpson" +.br +.fi +In this example we use a dictionary to add an extra property (a char*) to the line edits we're using. +.PP +See QDict for full details, including the choice of dictionary size, and how deletions are handled. +.PP +See also QPtrDictIterator, QDict, QAsciiDict, QIntDict, Collection Classes, Collection Classes, and Non-GUI Classes. +.SH MEMBER FUNCTION DOCUMENTATION +.SH "QPtrDict::QPtrDict ( int size = 17 )" +Constructs a dictionary using an internal hash array with the size \fIsize\fR. +.PP +Setting \fIsize\fR to a suitably large prime number (equal to or greater than the expected number of entries) makes the hash distribution better and improves lookup performance. +.SH "QPtrDict::QPtrDict ( const QPtrDict<type> & dict )" +Constructs a copy of \fIdict\fR. +.PP +Each item in \fIdict\fR is inserted into this dictionary. Only the pointers are copied (shallow copy). +.SH "QPtrDict::~QPtrDict ()" +Removes all items from the dictionary and destroys it. +.PP +All iterators that access this dictionary will be reset. +.PP +See also setAutoDelete(). +.SH "bool QPtrCollection::autoDelete () const" +Returns the setting of the auto-delete option. The default is FALSE. +.PP +See also setAutoDelete(). +.SH "void QPtrDict::clear ()\fC [virtual]\fR" +Removes all items from the dictionary. +.PP +The removed items are deleted if auto-deletion is enabled. +.PP +All dictionary iterators that access this dictionary will be reset. +.PP +See also remove(), take(), and setAutoDelete(). +.PP +Reimplemented from QPtrCollection. +.SH "uint QPtrDict::count () const\fC [virtual]\fR" +Returns the number of items in the dictionary. +.PP +See also isEmpty(). +.PP +Reimplemented from QPtrCollection. +.SH "type * QPtrDict::find ( void * key ) const" +Returns the item associated with \fIkey\fR, or 0 if the key does not exist in the dictionary. +.PP +If there are two or more items with equal keys, then the most recently inserted item will be found. +.PP +Equivalent to operator[]. +.PP +See also operator[](). +.SH "void QPtrDict::insert ( void * key, const type * item )" +Inserts the \fIkey\fR with the \fIitem\fR into the dictionary. +.PP +Multiple items can have the same key, in which case only the last item will be accessible using operator[](). +.PP +\fIitem\fR may not be 0. +.PP +See also replace(). +.SH "bool QPtrDict::isEmpty () const" +Returns TRUE if the dictionary is empty; otherwise returns FALSE. +.PP +See also count(). +.SH "QPtrDict<type> & QPtrDict::operator= ( const QPtrDict<type> & dict )" +Assigns \fIdict\fR to this dictionary and returns a reference to this dictionary. +.PP +This dictionary is first cleared and then each item in \fIdict\fR is inserted into the dictionary. Only the pointers are copied (shallow copy), unless newItem() has been reimplemented. +.SH "type * QPtrDict::operator[] ( void * key ) const" +Returns the item associated with \fIkey\fR, or 0 if the key does not exist in the dictionary. +.PP +If there are two or more items with equal keys, then the most recently inserted item will be found. +.PP +Equivalent to the find() function. +.PP +See also find(). +.SH "QDataStream & QPtrDict::read ( QDataStream & s, QPtrCollection::Item & item )\fC [virtual protected]\fR" +Reads a dictionary item from the stream \fIs\fR and returns a reference to the stream. +.PP +The default implementation sets \fIitem\fR to 0. +.PP +See also write(). +.SH "bool QPtrDict::remove ( void * key )" +Removes the item associated with \fIkey\fR from the dictionary. Returns TRUE if successful, i.e. if \fIkey\fR is in the dictionary; otherwise returns FALSE. +.PP +If there are two or more items with equal keys, then the most recently inserted item will be removed. +.PP +The removed item is deleted if auto-deletion is enabled. +.PP +All dictionary iterators that refer to the removed item will be set to point to the next item in the dictionary traversal order. +.PP +See also take(), clear(), and setAutoDelete(). +.SH "void QPtrDict::replace ( void * key, const type * item )" +If the dictionary has key \fIkey\fR, this key's item is replaced with \fIitem\fR. If the dictionary doesn't contain key \fIkey\fR, \fIitem\fR is inserted into the dictionary using key \fIkey\fR. +.PP +\fIitem\fR may not be 0. +.PP +Equivalent to +.PP +.nf +.br + QPtrDict<ItemType> dict; +.br + ... +.br + if ( dict.find( key ) ) +.br + dict.remove( key ); +.br + dict.insert( key, item ); +.br +.fi +.PP +If there are two or more items with equal keys, then the most recently inserted item will be replaced. +.PP +See also insert(). +.SH "void QPtrDict::resize ( uint newsize )" +Changes the size of the hash table to \fInewsize\fR. The contents of the dictionary are preserved, but all iterators on the dictionary become invalid. +.SH "void QPtrCollection::setAutoDelete ( bool enable )" +Sets the collection to auto-delete its contents if \fIenable\fR is TRUE and to never delete them if \fIenable\fR is FALSE. +.PP +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. +.PP +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. +.PP +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. +.PP +See also autoDelete(). +.PP +Examples: +.)l grapher/grapher.cpp, scribble/scribble.cpp, and table/bigtable/main.cpp. +.SH "uint QPtrDict::size () const" +Returns the size of the internal hash table (as specified in the constructor). +.PP +See also count(). +.SH "void QPtrDict::statistics () const" +Debugging-only function that prints out the dictionary distribution using qDebug(). +.SH "type * QPtrDict::take ( void * key )" +Takes the item associated with \fIkey\fR out of the dictionary without deleting it (even if auto-deletion is enabled). +.PP +If there are two or more items with equal keys, then the most recently inserted item will be removed. +.PP +Returns a pointer to the item taken out, or 0 if the key does not exist in the dictionary. +.PP +All dictionary iterators that refer to the taken item will be set to point to the next item in the dictionary traversal order. +.PP +See also remove(), clear(), and setAutoDelete(). +.SH "QDataStream & QPtrDict::write ( QDataStream & s, QPtrCollection::Item ) const\fC [virtual protected]\fR" +Writes a dictionary item to the stream \fIs\fR and returns a reference to the stream. +.PP +See also read(). + +.SH "SEE ALSO" +.BR http://doc.trolltech.com/qptrdict.html +.BR http://www.trolltech.com/faq/tech.html +.SH COPYRIGHT +Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the +license file included in the distribution for a complete license +statement. +.SH AUTHOR +Generated automatically from the source code. +.SH BUGS +If you find a bug in Qt, please report it as described in +.BR http://doc.trolltech.com/bughowto.html . +Good bug reports help us to help you. Thank you. +.P +The definitive Qt documentation is provided in HTML format; it is +located at $QTDIR/doc/html and can be read using Qt Assistant or with +a web browser. This man page is provided as a convenience for those +users who prefer man pages, although this format is not officially +supported by Trolltech. +.P +If you find errors in this manual page, please report them to +.BR qt-bugs@trolltech.com . +Please include the name of the manual page (qptrdict.3qt) and the Qt +version (3.3.8). |