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.
459 lines
13 KiB
459 lines
13 KiB
/****************************************************************************
|
|
**
|
|
** TQPtrDict and TQPtrDictIterator 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.
|
|
**
|
|
**********************************************************************/
|
|
|
|
|
|
/*****************************************************************************
|
|
TQPtrDict documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class TQPtrDict
|
|
\brief The TQPtrDict class is a template class that provides a dictionary based on void* keys.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
\important autoDelete setAutoDelete
|
|
|
|
TQPtrDict is implemented as a template class. Define a template
|
|
instance TQPtrDict\<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
|
|
void* used for insertion, removal and lookup. The value is a
|
|
pointer. Dictionaries provide very fast insertion and lookup.
|
|
|
|
Example:
|
|
\code
|
|
TQPtrDict<char> fields; // void* keys, char* values
|
|
|
|
TQLineEdit *le1 = new TQLineEdit( this );
|
|
le1->setText( "Simpson" );
|
|
TQLineEdit *le2 = new TQLineEdit( this );
|
|
le2->setText( "Homer" );
|
|
TQLineEdit *le3 = new TQLineEdit( this );
|
|
le3->setText( "45" );
|
|
|
|
fields.insert( le1, "Surname" );
|
|
fields.insert( le2, "Forename" );
|
|
fields.insert( le3, "Age" );
|
|
|
|
TQPtrDictIterator<char> it( fields );
|
|
for( ; it.current(); ++it )
|
|
cout << it.current() << endl;
|
|
cout << endl;
|
|
|
|
if ( fields[le1] ) // Prints "Surname: Simpson"
|
|
cout << fields[le1] << ": " << le1->text() << endl;
|
|
if ( fields[le2] ) // Prints "Forename: Homer"
|
|
cout << fields[le2] << ": " << le2->text() << endl;
|
|
|
|
fields.remove( le1 ); // Removes le1 from the dictionary
|
|
cout << le1->text() << endl; // Prints "Simpson"
|
|
\endcode
|
|
In this example we use a dictionary to add an extra property (a
|
|
char*) to the line edits we're using.
|
|
|
|
See TQDict for full details, including the choice of dictionary
|
|
size, and how deletions are handled.
|
|
|
|
\sa TQPtrDictIterator, TQDict, TQAsciiDict, TQIntDict,
|
|
\link collection.html Collection Classes\endlink
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn TQPtrDict::TQPtrDict( int size )
|
|
|
|
Constructs a dictionary using an internal hash array with the 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 and improves lookup performance.
|
|
*/
|
|
|
|
/*!
|
|
\fn TQPtrDict::TQPtrDict( const TQPtrDict<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 TQPtrDict::~TQPtrDict()
|
|
|
|
Removes all items from the dictionary and destroys it.
|
|
|
|
All iterators that access this dictionary will be reset.
|
|
|
|
\sa setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn TQPtrDict<type> &TQPtrDict::operator=(const TQPtrDict<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 the dictionary. Only the pointers are copied
|
|
(shallow copy), unless newItem() has been reimplemented.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint TQPtrDict::count() const
|
|
|
|
Returns the number of items in the dictionary.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint TQPtrDict::size() const
|
|
|
|
Returns the size of the internal hash table (as specified in the
|
|
constructor).
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void TQPtrDict::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 TQPtrDict::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty; otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void TQPtrDict::insert( void *key, const type *item )
|
|
|
|
Inserts the \a key with the \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 TQPtrDict::replace( void *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
|
|
TQPtrDict<ItemType> 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 TQPtrDict::remove( void *key )
|
|
|
|
Removes the item associated with \a key from the dictionary.
|
|
Returns TRUE if successful, i.e. if \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
|
|
TQPtrCollection::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 traversal order.
|
|
|
|
\sa take(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *TQPtrDict::take( void *key )
|
|
|
|
Takes the item associated with \a key out of the dictionary
|
|
without deleting it (even if \link TQPtrCollection::setAutoDelete()
|
|
auto-deletion\endlink is enabled).
|
|
|
|
If there are two or more items with equal keys, then the most
|
|
recently inserted item will be removed.
|
|
|
|
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 TQPtrDict::clear()
|
|
|
|
Removes all items from the dictionary.
|
|
|
|
The removed items are deleted if \link
|
|
TQPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
|
|
|
|
All dictionary iterators that access this dictionary will be
|
|
reset.
|
|
|
|
\sa remove(), take(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *TQPtrDict::find( void *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 *TQPtrDict::operator[]( void *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 TQPtrDict::statistics() const
|
|
|
|
Debugging-only function that prints out the dictionary
|
|
distribution using tqDebug().
|
|
*/
|
|
|
|
/*!
|
|
\fn TQDataStream& TQPtrDict::read( TQDataStream &s, TQPtrCollection::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 TQDataStream& TQPtrDict::write( TQDataStream &s, TQPtrCollection::Item ) const
|
|
|
|
Writes a dictionary item to the stream \a s and returns a
|
|
reference to the stream.
|
|
|
|
\sa read()
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
TQPtrDictIterator documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class TQPtrDictIterator tqptrdict.h
|
|
\brief The TQPtrDictIterator class provides an iterator for TQPtrDict collections.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
TQPtrDictIterator is implemented as a template class. Define a
|
|
template instance TQPtrDictIterator\<X\> to create a dictionary
|
|
iterator that operates on TQPtrDict\<X\> (dictionary of X*).
|
|
|
|
Example:
|
|
\code
|
|
TQPtrDict<char> fields;
|
|
|
|
TQLineEdit *le1 = new TQLineEdit( this );
|
|
le1->setText( "Simpson" );
|
|
TQLineEdit *le2 = new TQLineEdit( this );
|
|
le2->setText( "Homer" );
|
|
TQLineEdit *le3 = new TQLineEdit( this );
|
|
le3->setText( "45" );
|
|
|
|
fields.insert( le1, "Surname" );
|
|
fields.insert( le2, "Forename" );
|
|
fields.insert( le3, "Age" );
|
|
|
|
TQPtrDictIterator<char> it( fields );
|
|
for( ; it.current(); ++it ) {
|
|
TQLineEdit *le = (TQLineEdit)it.currentKey();
|
|
cout << it.current() << ": " << le->text() << endl;
|
|
}
|
|
cout << endl;
|
|
|
|
// Output (random order):
|
|
// Forename: Homer
|
|
// Age: 45
|
|
// Surname: Simpson
|
|
\endcode
|
|
In the example we insert some line edits into a dictionary,
|
|
associating a string with each. We then iterate over the
|
|
dictionary printing the associated strings.
|
|
|
|
Multiple iterators may independently traverse the same dictionary.
|
|
A TQPtrDict knows about all the iterators that are operating on the
|
|
dictionary. When an item is removed from the dictionary, TQPtrDict
|
|
updates all iterators that refer the removed item to point to the
|
|
next item in the traversing order.
|
|
|
|
\sa TQPtrDict
|
|
*/
|
|
|
|
/*!
|
|
\fn TQPtrDictIterator::TQPtrDictIterator( const TQPtrDict<type> &dict )
|
|
|
|
Constructs an iterator for \a dict. The current iterator item is
|
|
set to point on the first item in the \a dict.
|
|
*/
|
|
|
|
/*!
|
|
\fn TQPtrDictIterator::~TQPtrDictIterator()
|
|
|
|
Destroys the iterator.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint TQPtrDictIterator::count() const
|
|
|
|
Returns the number of items in the dictionary this iterator
|
|
operates on.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool TQPtrDictIterator::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty; otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *TQPtrDictIterator::toFirst()
|
|
|
|
Sets the current iterator item to point to the first item in the
|
|
dictionary and returns a pointer to the item. If the dictionary is
|
|
empty, it sets the current item to 0 and returns 0.
|
|
*/
|
|
|
|
/*!
|
|
\fn TQPtrDictIterator::operator type *() const
|
|
|
|
Cast operator. Returns a pointer to the current iterator item.
|
|
Same as current().
|
|
*/
|
|
|
|
/*!
|
|
\fn type *TQPtrDictIterator::current() const
|
|
|
|
Returns a pointer to the current iterator item's value.
|
|
*/
|
|
|
|
/*!
|
|
\fn void *TQPtrDictIterator::currentKey() const
|
|
|
|
Returns the current iterator item's key.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *TQPtrDictIterator::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 *TQPtrDictIterator::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 *TQPtrDictIterator::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.
|
|
*/
|