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.
476 lines
14 KiB
476 lines
14 KiB
/****************************************************************************
|
|
**
|
|
** QAsciiDict and QAsciiDictIterator 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.
|
|
**
|
|
**********************************************************************/
|
|
|
|
|
|
/*****************************************************************************
|
|
QAsciiDict documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QAsciiDict ntqasciidict.h
|
|
\brief The QAsciiDict class is a template class that provides a dictionary based on char* keys.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
\important autoDelete setAutoDelete
|
|
|
|
QAsciiDict is implemented as a template class. Define a template
|
|
instance QAsciiDict\<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
|
|
char* used for insertion, removal and lookup. The value is a
|
|
pointer. Dictionaries provide very fast insertion and lookup.
|
|
|
|
QAsciiDict cannot handle Unicode keys; use the QDict template
|
|
instead, which uses \l TQString keys. A QDict has the same
|
|
performace as a QAsciiDict.
|
|
|
|
Example:
|
|
\code
|
|
QAsciiDict<QLineEdit> fields; // char* keys, QLineEdit* values
|
|
fields.insert( "forename", new QLineEdit( this ) );
|
|
fields.insert( "surname", new QLineEdit( this ) );
|
|
|
|
fields["forename"]->setText( "Homer" );
|
|
fields["surname"]->setText( "Simpson" );
|
|
|
|
QAsciiDictIterator<QLineEdit> it( fields ); // See QAsciiDictIterator
|
|
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. See QPtrDict, QIntDict and QDict.
|
|
|
|
See QDict for full details, including the choice of dictionary
|
|
size, and how deletions are handled.
|
|
|
|
\sa QAsciiDictIterator, QDict, QIntDict, QPtrDict,
|
|
\link collection.html Collection Classes\endlink
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn QAsciiDict::QAsciiDict( int size, bool caseSensitive, bool copyKeys )
|
|
|
|
Constructs a dictionary optimized for less than \a size entries.
|
|
|
|
We recommend setting \a size 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.
|
|
|
|
When \a caseSensitive 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.
|
|
|
|
If \a copyKeys is TRUE (the default), the dictionary copies keys
|
|
using strcpy(); if it is FALSE, the dictionary just copies the
|
|
pointers.
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiDict::QAsciiDict( const QAsciiDict<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 QAsciiDict::~QAsciiDict()
|
|
|
|
Removes all items from the dictionary and destroys it.
|
|
|
|
The items are deleted if auto-delete is enabled.
|
|
|
|
All iterators that access this dictionary will be reset.
|
|
|
|
\sa setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiDict<type> &QAsciiDict::operator=(const QAsciiDict<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 QAsciiDict::count() const
|
|
|
|
Returns the number of items in the dictionary.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QAsciiDict::size() const
|
|
|
|
Returns the size of the internal hash array (as specified in the
|
|
constructor).
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QAsciiDict::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 QAsciiDict::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty, i.e. count() == 0;
|
|
otherwise it returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QAsciiDict::insert( const char *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 QAsciiDict::replace( const char *key, const type *item )
|
|
|
|
Replaces an item that has a key equal to \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
|
|
QAsciiDict<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 QAsciiDict::remove( const char *key )
|
|
|
|
Removes the item associated with \a key from the dictionary.
|
|
Returns TRUE if successful, i.e. if the key existed 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 traversal order.
|
|
|
|
\sa take(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDict::take( const char *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 traversal order.
|
|
|
|
\sa remove(), clear(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QAsciiDict::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 dictionary are reset.
|
|
|
|
\sa remove(), take(), setAutoDelete()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDict::find( const char *key ) const
|
|
|
|
Returns the item associated with \a key, or 0 if the key does not
|
|
exist in the dictionary.
|
|
|
|
This function uses an internal hashing algorithm to optimize
|
|
lookup.
|
|
|
|
If there are two or more items with equal keys, then the item that
|
|
was most recently inserted will be found.
|
|
|
|
Equivalent to the [] operator.
|
|
|
|
\sa operator[]()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDict::operator[]( const char *key ) const
|
|
|
|
Returns the item associated with \a key, or 0 if the key does
|
|
not exist in the dictionary.
|
|
|
|
This function uses an internal hashing algorithm to optimize
|
|
lookup.
|
|
|
|
If there are two or more items with equal keys, then the item that
|
|
was most recently inserted will be found.
|
|
|
|
Equivalent to the find() function.
|
|
|
|
\sa find()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QAsciiDict::statistics() const
|
|
|
|
Debugging-only function that prints out the dictionary
|
|
distribution using tqDebug().
|
|
*/
|
|
|
|
/*!
|
|
\fn QDataStream& QAsciiDict::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& QAsciiDict::write( QDataStream &s,
|
|
QPtrCollection::Item ) const
|
|
|
|
Writes a dictionary item to the stream \a s and returns a
|
|
reference to the stream.
|
|
|
|
\sa read()
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
QAsciiDictIterator documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QAsciiDictIterator ntqasciidict.h
|
|
\brief The QAsciiDictIterator class provides an iterator for QAsciiDict collections.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
QAsciiDictIterator is implemented as a template class. Define a
|
|
template instance QAsciiDictIterator\<X\> to create a dictionary
|
|
iterator that operates on QAsciiDict\<X\> (dictionary of X*).
|
|
|
|
Example:
|
|
\code
|
|
QAsciiDict<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" );
|
|
|
|
QAsciiDictIterator<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 line edits into a dictionary, then
|
|
iterate over the dictionary printing the strings associated with
|
|
those line edits.
|
|
|
|
Note that the traversal order is arbitrary; you are not guaranteed
|
|
any particular order.
|
|
|
|
Multiple iterators may independently traverse the same dictionary.
|
|
A QAsciiDict knows about all the iterators that are operating on
|
|
the dictionary. When an item is removed from the dictionary,
|
|
QAsciiDict updates all the iterators that are referring to the
|
|
removed item to point to the next item in the (arbitrary)
|
|
traversal order.
|
|
|
|
\sa QAsciiDict
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiDictIterator::QAsciiDictIterator( const QAsciiDict<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 QAsciiDictIterator::~QAsciiDictIterator()
|
|
|
|
Destroys the iterator.
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QAsciiDictIterator::count() const
|
|
|
|
Returns the number of items in the dictionary this iterator
|
|
operates over.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QAsciiDictIterator::isEmpty() const
|
|
|
|
Returns TRUE if the dictionary is empty, i.e. count() == 0,
|
|
otherwise returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDictIterator::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 QAsciiDictIterator::operator type *() const
|
|
|
|
Cast operator. Returns a pointer to the current iterator item.
|
|
Same as current().
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDictIterator::current() const
|
|
|
|
Returns a pointer to the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn const char *QAsciiDictIterator::currentKey() const
|
|
|
|
Returns a pointer to the key for the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiDictIterator::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 *QAsciiDictIterator::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 *QAsciiDictIterator::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.
|
|
*/
|