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.
450 lines
12 KiB
450 lines
12 KiB
/****************************************************************************
|
|
**
|
|
** QIntDict and QIntDictIterator class documentation
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the Qt 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 Qt 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.
|
|
**
|
|
**********************************************************************/
|
|
|
|
|
|
/*****************************************************************************
|
|
QIntDict documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QIntDict ntqintdict.h
|
|
\brief The QIntDict class is a template class that provides a dictionary based on long keys.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
\important autoDelete setAutoDelete
|
|
|
|
QMap is an STL-compatible alternative to this class.
|
|
|
|
QIntDict is implemented as a template class. Define a template
|
|
instance QIntDict\<X\> to create a dictionary that operates on
|
|
pointers to X (X*).
|
|
|
|
A dictionary is a collection of key-value pairs. The key is an \c
|
|
long used for insertion, removal and lookup. The value is a
|
|
pointer. Dictionaries provide very fast insertion and lookup.
|
|
|
|
Example:
|
|
\code
|
|
QIntDict<QLineEdit> fields; // long int keys, QLineEdit* values
|
|
for ( int i = 0; i < 3; i++ )
|
|
fields.insert( i, new QLineEdit( this ) );
|
|
|
|
fields[0]->setText( "Homer" );
|
|
fields[1]->setText( "Simpson" );
|
|
fields[2]->setText( "45" );
|
|
|
|
QIntDictIterator<QLineEdit> it( fields );
|
|
for ( ; it.current(); ++it )
|
|
cout << it.currentKey() << ": " << it.current()->text() << endl;
|
|
|
|
for ( int i = 0; i < 3; i++ )
|
|
cout << fields[i]->text() << " "; // Prints "Homer Simpson 45"
|
|
cout << endl;
|
|
|
|
fields.remove( 1 ); // Does not delete the line edit
|
|
for ( int i = 0; i < 3; i++ )
|
|
if ( fields[i] )
|
|
cout << fields[i]->text() << " "; // Prints "Homer 45"
|
|
\endcode
|
|
|
|
See QDict for full details, including the choice of dictionary
|
|
size, and how deletions are handled.
|
|
|
|
\sa QIntDictIterator, QDict, QAsciiDict, QPtrDict,
|
|
\link collection.html Collection Classes\endlink
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn QIntDict::QIntDict( int size )
|
|
|
|
Constructs a dictionary using an internal hash array of size \a
|
|
size.
|
|
|
|
Setting \a size to a suitably large prime number (equal to or
|
|
greater than the expected number of entries) makes the hash
|
|
distribution better which leads to faster lookup.
|
|
*/
|
|
|
|
/*!
|
|
\fn QIntDict::QIntDict( const QIntDict<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 QIntDict::~QIntDict()
|
|
|
|
Removes all items from the dictionary and destroys it.
|
|
|
|
All iterators that access this dictionary will be reset.
|
|
|
|
\sa setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn QIntDict<type> &QIntDict::operator=(const QIntDict<type> &dict)
|
|
|
|
Assigns \a dict to this dictionary and returns a reference to this
|
|
dictionary.
|
|
|
|
This dictionary is first cleared and 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 QIntDict::count() const
|
|
|
|
Returns the number of items in the dictionary.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QIntDict::size() const
|
|
|
|
Returns the size of the internal hash array (as specified in the
|
|
constructor).
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QIntDict::resize( uint newsize )
|
|
|
|
Changes the size of the hashtable to \a newsize. The contents of
|
|
the dictionary are preserved, but all iterators on the dictionary
|
|
become invalid.
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QIntDict::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty; otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QIntDict::insert( long key, const type *item )
|
|
|
|
Insert item \a item into the dictionary using key \a key.
|
|
|
|
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 QIntDict::replace( long key, const type *item )
|
|
|
|
If the dictionary has key \a key, this key's item is replaced with
|
|
\a item. If the dictionary doesn't contain key \a key, \a item is
|
|
inserted into the dictionary using key \a key.
|
|
|
|
\a item may not be 0.
|
|
|
|
Equivalent to:
|
|
\code
|
|
QIntDict<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 most
|
|
recently inserted item will be replaced.
|
|
|
|
\sa insert()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QIntDict::remove( long key )
|
|
|
|
Removes the item associated with \a key from the dictionary.
|
|
Returns TRUE if successful, i.e. if the \a key is in the
|
|
dictionary; otherwise returns FALSE.
|
|
|
|
If there are two or more items with equal keys, then the most
|
|
recently inserted item 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 *QIntDict::take( long key )
|
|
|
|
Takes the item associated 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 most
|
|
recently inserted item 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's traversing order.
|
|
|
|
\sa remove(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QIntDict::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 access this dictionary will be reset.
|
|
|
|
\sa remove(), take(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QIntDict::find( long key ) const
|
|
|
|
Returns the item associated with \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 operator[].
|
|
|
|
\sa operator[]()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QIntDict::operator[]( long key ) const
|
|
|
|
Returns the item associated with \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 QIntDict::statistics() const
|
|
|
|
Debugging-only function that prints out the dictionary
|
|
distribution using qDebug().
|
|
*/
|
|
|
|
/*!
|
|
\fn QDataStream& QIntDict::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& QIntDict::write( QDataStream &s, QPtrCollection::Item ) const
|
|
|
|
Writes a dictionary item to the stream \a s and returns a
|
|
reference to the stream.
|
|
|
|
\sa read()
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
QIntDictIterator documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QIntDictIterator ntqintdict.h
|
|
\brief The QIntDictIterator class provides an iterator for QIntDict collections.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
QIntDictIterator is implemented as a template class. Define a
|
|
template instance QIntDictIterator\<X\> to create a dictionary
|
|
iterator that operates on QIntDict\<X\> (dictionary of X*).
|
|
|
|
Example:
|
|
\code
|
|
QIntDict<QLineEdit> fields;
|
|
for ( int i = 0; i < 3; i++ )
|
|
fields.insert( i, new QLineEdit( this ) );
|
|
|
|
fields[0]->setText( "Homer" );
|
|
fields[1]->setText( "Simpson" );
|
|
fields[2]->setText( "45" );
|
|
|
|
QIntDictIterator<QLineEdit> it( fields );
|
|
for ( ; it.current(); ++it )
|
|
cout << it.currentKey() << ": " << it.current()->text() << endl;
|
|
|
|
// Output (random order):
|
|
// 0: Homer
|
|
// 1: Simpson
|
|
// 2: 45
|
|
\endcode
|
|
|
|
Note that the traversal order is arbitrary; you are not guaranteed the
|
|
order shown above.
|
|
|
|
Multiple iterators may independently traverse the same dictionary.
|
|
A QIntDict knows about all the iterators that are operating on the
|
|
dictionary. When an item is removed from the dictionary, QIntDict
|
|
updates all iterators that refer the removed item to point to the
|
|
next item in the traversal order.
|
|
|
|
\sa QIntDict
|
|
*/
|
|
|
|
/*!
|
|
\fn QIntDictIterator::QIntDictIterator( const QIntDict<type> &dict )
|
|
|
|
Constructs an iterator for \a dict. The current iterator item is
|
|
set to point to the 'first' item in the \a dict. The first item
|
|
refers to the first item in the dictionary's arbitrary internal
|
|
ordering.
|
|
*/
|
|
|
|
/*!
|
|
\fn QIntDictIterator::~QIntDictIterator()
|
|
|
|
Destroys the iterator.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QIntDictIterator::count() const
|
|
|
|
Returns the number of items in the dictionary this iterator
|
|
operates over.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QIntDictIterator::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty; otherwise eturns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QIntDictIterator::toFirst()
|
|
|
|
Sets the current iterator item to point to the first item in the
|
|
dictionary and returns a pointer to the item. The first item
|
|
refers to the first item in the dictionary's arbitrary internal
|
|
ordering. If the dictionary is empty it sets the current item to
|
|
0 and returns 0.
|
|
*/
|
|
|
|
/*!
|
|
\fn QIntDictIterator::operator type *() const
|
|
|
|
Cast operator. Returns a pointer to the current iterator item.
|
|
Same as current().
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QIntDictIterator::current() const
|
|
|
|
Returns a pointer to the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn long QIntDictIterator::currentKey() const
|
|
|
|
Returns the key for the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QIntDictIterator::operator()()
|
|
|
|
Makes the succeeding 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 *QIntDictIterator::operator++()
|
|
|
|
Prefix ++ makes the succeeding 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 *QIntDictIterator::operator+=( uint jump )
|
|
|
|
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.
|
|
*/
|