You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
318 lines
11 KiB
318 lines
11 KiB
'\" t
|
|
.TH QAsciiDict 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
|
|
QAsciiDict \- Template class that provides a dictionary based on char* keys
|
|
.SH SYNOPSIS
|
|
\fC#include <qasciidict.h>\fR
|
|
.PP
|
|
Inherits QPtrCollection.
|
|
.PP
|
|
.SS "Public Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "\fBQAsciiDict\fR ( int size = 17, bool caseSensitive = TRUE, bool copyKeys = TRUE )"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fBQAsciiDict\fR ( const QAsciiDict<type> & dict )"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fB~QAsciiDict\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "QAsciiDict<type> & \fBoperator=\fR ( const QAsciiDict<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 ( const char * key, const type * item )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBreplace\fR ( const char * key, const type * item )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBremove\fR ( const char * key )"
|
|
.br
|
|
.ti -1c
|
|
.BI "type * \fBtake\fR ( const char * key )"
|
|
.br
|
|
.ti -1c
|
|
.BI "type * \fBfind\fR ( const char * key ) const"
|
|
.br
|
|
.ti -1c
|
|
.BI "type * \fBoperator[]\fR ( const char * 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 QAsciiDict class is a template class that provides a dictionary based on char* keys.
|
|
.PP
|
|
QAsciiDict is implemented as a template class. Define a template instance QAsciiDict<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 char* used for insertion, removal and lookup. The value is a pointer. Dictionaries provide very fast insertion and lookup.
|
|
.PP
|
|
QAsciiDict cannot handle Unicode keys; use the QDict template instead, which uses QString keys. A QDict has the same performace as a QAsciiDict.
|
|
.PP
|
|
Example:
|
|
.PP
|
|
.nf
|
|
.br
|
|
QAsciiDict<QLineEdit> fields; // char* keys, QLineEdit* values
|
|
.br
|
|
fields.insert( "forename", new QLineEdit( this ) );
|
|
.br
|
|
fields.insert( "surname", new QLineEdit( this ) );
|
|
.br
|
|
.br
|
|
fields["forename"]->setText( "Homer" );
|
|
.br
|
|
fields["surname"]->setText( "Simpson" );
|
|
.br
|
|
.br
|
|
QAsciiDictIterator<QLineEdit> it( fields ); // See QAsciiDictIterator
|
|
.br
|
|
for( ; it.current(); ++it )
|
|
.br
|
|
cout << it.currentKey() << ": " << it.current()->text() << endl;
|
|
.br
|
|
cout << endl;
|
|
.br
|
|
.br
|
|
if ( fields["forename"] && fields["surname"] )
|
|
.br
|
|
cout << fields["forename"]->text() << " "
|
|
.br
|
|
.br
|
|
<< fields["surname"]->text() << endl; // Prints "Homer Simpson"
|
|
.br
|
|
.br
|
|
fields.remove( "forename" ); // Does not delete the line edit
|
|
.br
|
|
if ( ! fields["forename"] )
|
|
.br
|
|
cout << "forename is not in the dictionary" << endl;
|
|
.br
|
|
.fi
|
|
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. See QPtrDict, QIntDict and QDict.
|
|
.PP
|
|
See QDict for full details, including the choice of dictionary size, and how deletions are handled.
|
|
.PP
|
|
See also QAsciiDictIterator, QDict, QIntDict, QPtrDict, Collection Classes, Collection Classes, and Non-GUI Classes.
|
|
.SH MEMBER FUNCTION DOCUMENTATION
|
|
.SH "QAsciiDict::QAsciiDict ( int size = 17, bool caseSensitive = TRUE, bool copyKeys = TRUE )"
|
|
Constructs a dictionary optimized for less than \fIsize\fR entries.
|
|
.PP
|
|
We recommend setting \fIsize\fR to a suitably large prime number (a bit larger than the expected number of entries). This makes the hash distribution better and will improve lookup performance.
|
|
.PP
|
|
When \fIcaseSensitive\fR is TRUE (the default) QAsciiDict treats" abc" and "Abc" as different keys; when it is FALSE "abc" and" Abc" are the same. Case-insensitive comparison only considers the 26 letters in US-ASCII.
|
|
.PP
|
|
If \fIcopyKeys\fR is TRUE (the default), the dictionary copies keys using strcpy(); if it is FALSE, the dictionary just copies the pointers.
|
|
.SH "QAsciiDict::QAsciiDict ( const QAsciiDict<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 "QAsciiDict::~QAsciiDict ()"
|
|
Removes all items from the dictionary and destroys it.
|
|
.PP
|
|
The items are deleted if auto-delete is enabled.
|
|
.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 QAsciiDict::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 operate on dictionary are reset.
|
|
.PP
|
|
See also remove(), take(), and setAutoDelete().
|
|
.PP
|
|
Reimplemented from QPtrCollection.
|
|
.SH "uint QAsciiDict::count () const\fC [virtual]\fR"
|
|
Returns the number of items in the dictionary.
|
|
.PP
|
|
See also isEmpty().
|
|
.PP
|
|
Reimplemented from QPtrCollection.
|
|
.SH "type * QAsciiDict::find ( const char * key ) const"
|
|
Returns the item associated with \fIkey\fR, or 0 if the key does not exist in the dictionary.
|
|
.PP
|
|
This function uses an internal hashing algorithm to optimize lookup.
|
|
.PP
|
|
If there are two or more items with equal keys, then the item that was most recently inserted will be found.
|
|
.PP
|
|
Equivalent to the [] operator.
|
|
.PP
|
|
See also operator[]().
|
|
.SH "void QAsciiDict::insert ( const char * 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 QAsciiDict::isEmpty () const"
|
|
Returns TRUE if the dictionary is empty, i.e. count() == 0; otherwise it returns FALSE.
|
|
.PP
|
|
See also count().
|
|
.SH "QAsciiDict<type> & QAsciiDict::operator= ( const QAsciiDict<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 this dictionary. Only the pointers are copied (shallow copy) unless newItem() has been reimplemented().
|
|
.SH "type * QAsciiDict::operator[] ( const char * key ) const"
|
|
Returns the item associated with \fIkey\fR, or 0 if the key does not exist in the dictionary.
|
|
.PP
|
|
This function uses an internal hashing algorithm to optimize lookup.
|
|
.PP
|
|
If there are two or more items with equal keys, then the item that was most recently inserted will be found.
|
|
.PP
|
|
Equivalent to the find() function.
|
|
.PP
|
|
See also find().
|
|
.SH "QDataStream & QAsciiDict::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 QAsciiDict::remove ( const char * key )"
|
|
Removes the item associated with \fIkey\fR from the dictionary. Returns TRUE if successful, i.e. if the key existed 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 QAsciiDict::replace ( const char * key, const type * item )"
|
|
Replaces an item that has a key equal to \fIkey\fR with \fIitem\fR.
|
|
.PP
|
|
If the item does not already exist, it will be inserted.
|
|
.PP
|
|
\fIitem\fR may not be 0.
|
|
.PP
|
|
Equivalent to:
|
|
.PP
|
|
.nf
|
|
.br
|
|
QAsciiDict<char> 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 QAsciiDict::resize ( uint newsize )"
|
|
Changes the size of the hashtable 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 QAsciiDict::size () const"
|
|
Returns the size of the internal hash array (as specified in the constructor).
|
|
.PP
|
|
See also count().
|
|
.SH "void QAsciiDict::statistics () const"
|
|
Debugging-only function that prints out the dictionary distribution using qDebug().
|
|
.SH "type * QAsciiDict::take ( const char * 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 taken.
|
|
.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 & QAsciiDict::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/qasciidict.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 (qasciidict.3qt) and the Qt
|
|
version (3.3.8).
|