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.
558 lines
17 KiB
558 lines
17 KiB
/****************************************************************************
|
|
**
|
|
** QDict and QDictIterator class documentation
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the TQt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free TQt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
|
|
/*****************************************************************************
|
|
QDict documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QDict
|
|
\brief The QDict class is a template class that provides a
|
|
dictionary based on TQString keys.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
\mainclass
|
|
|
|
\important autoDelete setAutoDelete
|
|
|
|
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
|
|
TQString 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 \c 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:
|
|
\code
|
|
QDict<QLineEdit> fields; // TQString 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;
|
|
\endcode
|
|
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:
|
|
\code
|
|
QStringList styleList = QStyleFactory::styles();
|
|
styleList.sort();
|
|
QDict<int> letterDict( 17, FALSE );
|
|
for ( QStringList::Iterator it = styleList.begin(); it != styleList.end(); ++it ) {
|
|
TQString styleName = *it;
|
|
TQString 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 );
|
|
}
|
|
\endcode
|
|
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.
|
|
|
|
\sa QDictIterator, QAsciiDict, QIntDict, QPtrDict
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn QDict::QDict( int size, bool caseSensitive )
|
|
|
|
Constructs a dictionary optimized for less than \a size entries.
|
|
|
|
We recommend setting \a 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 \a caseSensitive is TRUE (the default), keys which differ only
|
|
by case are considered different.
|
|
*/
|
|
|
|
/*!
|
|
\fn QDict::QDict( const QDict<type> &dict )
|
|
|
|
Constructs a copy of \a dict.
|
|
|
|
Each item in \a dict is inserted into this dictionary. Only the
|
|
pointers are copied (shallow copy).
|
|
*/
|
|
|
|
/*!
|
|
\fn 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.
|
|
|
|
\sa setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn QDict<type> &QDict::operator=(const QDict<type> &dict)
|
|
|
|
Assigns \a dict to this dictionary and returns a reference to this
|
|
dictionary.
|
|
|
|
This dictionary is first cleared, then each item in \a dict is
|
|
inserted into this dictionary. Only the pointers are copied
|
|
(shallow copy), unless newItem() has been reimplemented.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QDict::count() const
|
|
|
|
Returns the number of items in the dictionary.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QDict::size() const
|
|
|
|
Returns the size of the internal hash array (as specified in the
|
|
constructor).
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QDict::resize( uint newsize )
|
|
|
|
Changes the size of the hash table to \a newsize. The contents of
|
|
the dictionary are preserved, but all iterators on the dictionary
|
|
become invalid.
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QDict::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty, i.e. count() == 0;
|
|
otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QDict::insert( const TQString &key, const type *item )
|
|
|
|
Inserts the key \a key with value \a item into the dictionary.
|
|
|
|
Multiple items can have the same key, in which case only the last
|
|
item will be accessible using \l operator[]().
|
|
|
|
\a item may not be 0.
|
|
|
|
\sa replace()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QDict::replace( const TQString &key, const type *item )
|
|
|
|
Replaces the value of the key, \a key with \a item.
|
|
|
|
If the item does not already exist, it will be inserted.
|
|
|
|
\a item may not be 0.
|
|
|
|
Equivalent to:
|
|
\code
|
|
QDict<char> dict;
|
|
...
|
|
if ( dict.find( key ) )
|
|
dict.remove( key );
|
|
dict.insert( key, item );
|
|
\endcode
|
|
|
|
If there are two or more items with equal keys, then the last item
|
|
that was inserted will be replaced.
|
|
|
|
\sa insert()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QDict::remove( const TQString &key )
|
|
|
|
Removes the item with \a 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 \link
|
|
QPtrCollection::setAutoDelete() auto-deletion\endlink 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.
|
|
|
|
\sa take(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDict::take( const TQString &key )
|
|
|
|
Takes the item with \a key out of the dictionary without deleting
|
|
it (even if \link QPtrCollection::setAutoDelete()
|
|
auto-deletion\endlink 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.
|
|
|
|
\sa remove(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QDict::clear()
|
|
|
|
Removes all items from the dictionary.
|
|
|
|
The removed items are deleted if \link
|
|
QPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
|
|
|
|
All dictionary iterators that operate on the dictionary are reset.
|
|
|
|
\sa remove(), take(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDict::find( const TQString &key ) const
|
|
|
|
Returns the item with key \a 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.
|
|
|
|
\sa operator[]()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDict::operator[]( const TQString &key ) const
|
|
|
|
Returns the item with key \a 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.
|
|
|
|
\sa find()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QDict::statistics() const
|
|
|
|
Debugging-only function that prints out the dictionary
|
|
distribution using tqDebug().
|
|
*/
|
|
|
|
/*!
|
|
\fn QDataStream& QDict::read( QDataStream &s, QPtrCollection::Item &item )
|
|
|
|
Reads a dictionary item from the stream \a s and returns a
|
|
reference to the stream.
|
|
|
|
The default implementation sets \a item to 0.
|
|
|
|
\sa write()
|
|
*/
|
|
|
|
/*!
|
|
\fn QDataStream& QDict::write( QDataStream &s, QPtrCollection::Item ) const
|
|
|
|
Writes a dictionary item to the stream \a s and returns a
|
|
reference to the stream.
|
|
|
|
\sa read()
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
QDictIterator documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QDictIterator ntqdict.h
|
|
\brief The QDictIterator class provides an iterator for QDict collections.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
QDictIterator is implemented as a template class. Define a
|
|
template instance QDictIterator\<X\> to create a dictionary
|
|
iterator that operates on QDict\<X\> (dictionary of X*).
|
|
|
|
The traversal order is arbitrary; when we speak of the "first",
|
|
"last" and "next" item we are talking in terms of this arbitrary
|
|
order.
|
|
|
|
Multiple iterators may independently traverse the same dictionary.
|
|
A QDict knows about all the iterators that are operating on the
|
|
dictionary. When an item is removed from the dictionary, QDict
|
|
updates all iterators that are referring to the removed item to
|
|
point to the next item in the (arbitrary) traversal order.
|
|
|
|
Example:
|
|
\code
|
|
QDict<QLineEdit> fields;
|
|
fields.insert( "forename", new QLineEdit( this ) );
|
|
fields.insert( "surname", new QLineEdit( this ) );
|
|
fields.insert( "age", new QLineEdit( this ) );
|
|
|
|
fields["forename"]->setText( "Homer" );
|
|
fields["surname"]->setText( "Simpson" );
|
|
fields["age"]->setText( "45" );
|
|
|
|
QDictIterator<QLineEdit> it( fields );
|
|
for( ; it.current(); ++it )
|
|
cout << it.currentKey() << ": " << it.current()->text() << endl;
|
|
cout << endl;
|
|
|
|
// Output (random order):
|
|
// age: 45
|
|
// surname: Simpson
|
|
// forename: Homer
|
|
\endcode
|
|
In the example we insert some pointers to line edits into a
|
|
dictionary, then iterate over the dictionary printing the strings
|
|
associated with the line edits.
|
|
|
|
\sa QDict
|
|
*/
|
|
|
|
/*!
|
|
\fn QDictIterator::QDictIterator( const QDict<type> &dict )
|
|
|
|
Constructs an iterator for \a dict. The current iterator item is
|
|
set to point to the first item in the dictionary, \a dict. First
|
|
in this context means first in the arbitrary traversal order.
|
|
*/
|
|
|
|
/*!
|
|
\fn QDictIterator::~QDictIterator()
|
|
|
|
Destroys the iterator.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QDictIterator::count() const
|
|
|
|
Returns the number of items in the dictionary over which the
|
|
iterator is operating.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QDictIterator::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty, i.e. count() == 0;
|
|
otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDictIterator::toFirst()
|
|
|
|
Resets the iterator, making the first item the first current item.
|
|
First in this context means first in the arbitrary traversal
|
|
order. Returns a pointer to this item.
|
|
|
|
If the dictionary is empty it sets the current item to 0 and
|
|
returns 0.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDictIterator::operator*()
|
|
\internal
|
|
*/
|
|
|
|
/*!
|
|
\fn QDictIterator::operator type*() const
|
|
|
|
Cast operator. Returns a pointer to the current iterator item.
|
|
Same as current().
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn type *QDictIterator::current() const
|
|
|
|
Returns a pointer to the current iterator item's value.
|
|
*/
|
|
|
|
/*!
|
|
\fn TQString QDictIterator::currentKey() const
|
|
|
|
Returns the current iterator item's key.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDictIterator::operator()()
|
|
|
|
Makes the next item current and returns the original current item.
|
|
|
|
If the current iterator item was the last item in the dictionary
|
|
or if it was 0, 0 is returned.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDictIterator::operator++()
|
|
|
|
Prefix ++ makes the next item current and returns the new current
|
|
item.
|
|
|
|
If the current iterator item was the last item in the dictionary
|
|
or if it was 0, 0 is returned.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QDictIterator::operator+=( uint jump )
|
|
\internal
|
|
Sets the current item to the item \a jump positions after the current item,
|
|
and returns a pointer to that item.
|
|
|
|
If that item is beyond the last item or if the dictionary is empty,
|
|
it sets the current item to 0 and returns 0.
|
|
*/
|