diff options
Diffstat (limited to 'doc/qmap.doc')
| -rw-r--r-- | doc/qmap.doc | 902 |
1 files changed, 902 insertions, 0 deletions
diff --git a/doc/qmap.doc b/doc/qmap.doc new file mode 100644 index 000000000..89f874425 --- /dev/null +++ b/doc/qmap.doc @@ -0,0 +1,902 @@ +/**************************************************************************** +** +** QMap and QMapIterator 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 retquirements 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. +** +**********************************************************************/ + + +/***************************************************************************** + QMap documentation + *****************************************************************************/ + +/*! + \class QMap qmap.h + \brief The QMap class is a value-based template class that + provides a dictionary. + + \ingroup qtl + \ingroup tools + \ingroup shared + \mainclass + + QMap is a Qt implementation of an STL-like map container. It can + be used in your application if the standard \c map is not + available on all your target platforms. QMap is part of the \link + qtl.html Qt Template Library\endlink. + + QMap\<Key, Data\> defines a template instance to create a + dictionary with keys of type Key and values of type Data. QMap + does not store pointers to the members of the map; instead, it + holds a copy of every member. For this reason, QMap is + value-based, whereas QPtrList and QDict are pointer-based. + + QMap contains and manages a collection of objects of type Data + with associated key values of type Key and provides iterators that + allow the contained objects to be addressed. QMap owns the + contained items. + + Some classes cannot be used within a QMap. For example everything + derived from QObject and thus all classes that implement widgets. + Only values can be used in a QMap. To qualify as a value, the + class must provide + + \list + \i A copy constructor + \i An assignment operator + \i A default constructor, i.e. a constructor that does not take + any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases, this is sufficient. + + The class used for the key retquires that the \c operator< is + implemented to define ordering of the keys. + + QMap's function naming is consistent with the other Qt classes + (e.g., count(), isEmpty()). QMap also provides extra functions for + compatibility with STL algorithms, such as size() and empty(). + Programmers already familiar with the STL \c map can use these + the STL-like functions if preferred. + + Example: + \target qmap-eg + \code + #include <qstring.h> + #include <qmap.h> + #include <qstring.h> + + class Employee + { + public: + Employee(): sn(0) {} + Employee( const QString& forename, const QString& surname, int salary ) + : fn(forename), sn(surname), sal(salary) + { } + + QString forename() const { return fn; } + QString surname() const { return sn; } + int salary() const { return sal; } + void setSalary( int salary ) { sal = salary; } + + private: + QString fn; + QString sn; + int sal; + }; + + int main(int argc, char **argv) + { + QApplication app( argc, argv ); + + typedef QMap<QString, Employee> EmployeeMap; + EmployeeMap map; + + map["JD001"] = Employee("John", "Doe", 50000); + map["JW002"] = Employee("Jane", "Williams", 80000); + map["TJ001"] = Employee("Tom", "Jones", 60000); + + Employee sasha( "Sasha", "Hind", 50000 ); + map["SH001"] = sasha; + sasha.setSalary( 40000 ); + + EmployeeMap::Iterator it; + for ( it = map.begin(); it != map.end(); ++it ) { + printf( "%s: %s, %s earns %d\n", + it.key().latin1(), + it.data().surname().latin1(), + it.data().forename().latin1(), + it.data().salary() ); + } + return 0; + } + \endcode + + Program output: + \code + JD001: Doe, John earns 50000 + JW002: Williams, Jane earns 80000 + SH001: Hind, Sasha earns 50000 + TJ001: Jones, Tom earns 60000 + \endcode + + The latest changes to Sasha's salary did not affect the value in + the list because the map created a copy of Sasha's entry. In + addition, notice that the items are sorted alphabetically (by key) + when iterating over the map. + + There are several ways to find items in a map. The begin() and + end() functions return iterators to the beginning and end of the + map. The advantage of using an iterator is that you can move + forward or backward by incrementing/decrementing the iterator. + The iterator returned by end() points to the element which is one + past the last element in the container. The past-the-end iterator + is still associated with the map it belongs to, however it is \e + not dereferenceable; operator*() will not return a well-defined + value. If the map is empty, the iterator returned by begin() will + equal the iterator returned by end(). + + Another way to find an element in the map is by using the find() + function. This returns an iterator pointing to the desired item or + to the end() iterator if no such element exists. + + Another approach uses the operator[]. But be warned: if the map + does not contain an entry for the element you are looking for, + operator[] inserts a default value. If you do not know that the + element you are searching for is really in the list, you should + not use operator[]. The following example illustrates this: + + \code + QMap<QString,QString> map; + map["Clinton"] = "Bill"; + str << map["Clinton"] << map["Bush"] << endl; + \endcode + + The code fragment will print out "Clinton", "". Since the value + associated with the "Bush" key did not exist, the map inserted a + default value (in this case, an empty string). If you are not + sure whether a certain element is in the map, you should use + find() and iterators instead. + + If you just want to know whether a certain key is contained in the + map, use the contains() function. In addition, count() tells you + how many keys are in the map. + + It is safe to have multiple iterators at the same time. If some + member of the map is removed, only iterators pointing to the + removed member become invalid; inserting in the map does not + invalidate any iterators. + + Since QMap is value-based, there is no need to be concerned about + deleting items in the map. The map holds its own copies and will + free them if the corresponding member or the map itself is + deleted. + + QMap is implicitly shared. This means you can just make copies of + the map in time O(1). If multiple QMap instances share the same + data and one is modifying the map's data, this modifying instance + makes a copy and modifies its private copy: so it does not affect + other instances. If a QMap is being used in a multi-threaded + program, you must protect all access to the map. See \l QMutex. + + There are a couple of ways of inserting new items into the map. + One uses the insert() method; the other uses operator[]: + \code + QMap<QString, QString> map; + map["Clinton"] = "Bill"; + map.insert( "Bush", "George" ); + \endcode + + Items can also be removed from the map in several ways. One way is + to pass an iterator to remove(). Another way is to pass a key + value to remove(), which will delete the entry with the requested + key. In addition you can clear the entire map using the clear() + method. + + \sa QMapIterator +*/ + + +/*! \enum QMap::key_type + The map's key type. */ +/*! \enum QMap::mapped_type + The map's data type. */ +/*! \enum QMap::value_type + Corresponds to QPair\<key_type, mapped_type\>. */ +/*! \enum QMap::ValueType + Corresponds to QPair\<key_type, mapped_type\>, Qt style.*/ +/*! \enum QMap::pointer + Pointer to value_type.*/ +/*! \enum QMap::const_pointer + Const pointer to value_type.*/ +/*! \enum QMap::reference + Reference to value_type.*/ +/*! \enum QMap::const_reference + Const reference to value_type.*/ +/*! \enum QMap::size_type + An unsigned integral type, used to represent various sizes. */ +/*! \enum QMap::iterator + The map's iterator type.*/ +/*! \enum QMap::Iterator + The map's iterator type, Qt style. */ +/*! \enum QMap::const_iterator + The map's const iterator type.*/ +/*! \enum QMap::ConstIterator + The map's const iterator type, Qt style.*/ +/*! \enum QMap::difference_type + \internal */ +/*! \enum QMap::Priv + \internal */ + +/*! + \fn QMap::QMap() + + Constructs an empty map. +*/ + +/*! + \fn QMap::QMap( const QMap<Key,T>& m ) + + Constructs a copy of \a m. + + This operation costs O(1) time because QMap is implicitly shared. + This makes returning a QMap from a function very fast. If a shared + instance is modified, it will be copied (copy-on-write), and this + takes O(n) time. +*/ + +/*! + \fn QMap::QMap( const std::map<Key,T>& m ) + + Constructs a copy of \a m. +*/ + +/*! + \fn QMap<Key,T>& QMap::operator= ( const std::map<Key,T>& m ) + + \overload + + Assigns \a m to this map and returns a reference to this map. + + All iterators of the current map become invalidated by this + operation. +*/ + +/*! + \fn QMap::~QMap() + + Destroys the map. References to the values in the map and all + iterators of this map become invalidated. Since QMap is highly + tuned for performance you won't see warnings if you use invalid + iterators, because it is not possible for an iterator to check + whether it is valid or not. +*/ + +/*! + \fn QMap<Key, T>& QMap::operator= (const QMap<Key, T>& m) + + Assigns \a m to this map and returns a reference to this map. + + All iterators of the current map become invalidated by this + operation. The cost of such an assignment is O(1), because QMap is + implicitly shared. +*/ + +/*! + \fn T& QMap::operator[] ( const Key& k ) + + Returns the value associated with the key \a k. If no such key is + present, an empty item is inserted with this key and a reference + to the empty item is returned. + + You can use this operator both for reading and writing: + \code + QMap<QString, QString> map; + map["Clinton"] = "Bill"; + stream << map["Clinton"]; + \endcode +*/ + +/*! + \fn void QMap::clear() + + Removes all items from the map. + + \sa remove() +*/ + +/*! + \fn Iterator QMap::find( const Key& k ) + + Returns an iterator pointing to the element with key \a k in the + map. + + Returns end() if no key matched. + + \sa QMapIterator +*/ + +/*! + \fn ConstIterator QMap::find( const Key& k ) const + + \overload + + Returns an iterator pointing to the element with key \a k in the + map. + + Returns end() if no key matched. + + \sa QMapConstIterator +*/ + +/*! + \fn Iterator QMap::begin() + + Returns an iterator pointing to the first element in the map. This + iterator equals end() if the map is empty. + + The items in the map are traversed in the order defined by + operator\<(Key, Key). + + \sa end() QMapIterator +*/ + +/*! + \fn ConstIterator QMap::begin() const + + \overload + + \sa end() QMapConstIterator +*/ + +/*! + \fn ConstIterator QMap::constBegin() const + + Returns an iterator pointing to the first element in the map. This + iterator equals end() if the map is empty. + + The items in the map are traversed in the order defined by + operator\<(Key, Key). + + \sa constEnd() QMapConstIterator +*/ + +/*! + \fn Iterator QMap::end() + + The iterator returned by end() points to the element which is one + past the last element in the container. The past-the-end iterator + is still associated with the map it belongs to, but it is \e not + dereferenceable; operator*() will not return a well-defined value. + + This iterator equals begin() if the map is empty. + + \sa begin() QMapIterator +*/ + +/*! + \fn ConstIterator QMap::end() const + + \overload +*/ + +/*! + \fn ConstIterator QMap::constEnd() const + + The iterator returned by end() points to the element which is one + past the last element in the container. The past-the-end iterator + is still associated with the map it belongs to, but it is \e not + dereferenceable; operator*() will not return a well-defined value. + + This iterator equals constBegin() if the map is empty. + + \sa constBegin() QMapConstIterator +*/ + +/*! + \fn void QMap::detach() + + If the map does not share its data with another QMap instance, + nothing happens; otherwise the function creates a new copy of this + map and detaches from the shared one. This function is called + whenever the map is modified. The implicit sharing mechanism is + implemented this way. +*/ + + +/*! + \fn QDataStream& operator>>( QDataStream& s, QMap<Key,T>& m ) + + \relates QMap + + Reads the map \a m from the stream \a s. The types \e Key and \e T + must implement the streaming operator as well. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const QMap<Key,T>& m ) + + \relates QMap + + Writes the map \a m to the stream \a s. The types \e Key and \e T + must implement the streaming operator as well. +*/ + +/*! + \fn size_type QMap::size() const + + Returns the number of items in the map. + + This function is provided for STL compatibility. It is equivalent + to count(). + + \sa empty() +*/ + +/*! + \fn bool QMap::empty() const + + Returns TRUE if the map contains no items; otherwise returns + FALSE. + + This function is provided for STL compatibility. It is equivalent + to isEmpty(). + + \sa size() +*/ + +/*! + \fn QPair<iterator,bool> QMap::insert( const value_type& x ) + + \overload + + Inserts the (key, value) pair \a x into the map. \a x is a QPair + whose \c first element is a key to be inserted and whose \c second + element is the associated value to be inserted. Returns a pair + whose \c first element is an iterator pointing to the inserted + item and whose \c second element is a bool indicating TRUE if \a x + was inserted and FALSE if it was not inserted, e.g. because it was + already present. + + \sa replace() +*/ + +/*! + \fn void QMap::erase( iterator it ) + + Removes the item associated with the iterator \a it from the map. + + This function is provided for STL compatibility. It is equivalent + to remove(). + + \sa clear() +*/ + +/*! + \fn void QMap::erase( const key_type& k ) + + \overload + + Removes the item with the key \a k from the map. +*/ + +/*! + \fn size_type QMap::count( const key_type& k ) const + + Returns the number of items whose key is \a k. Since QMap does not + allow duplicate keys, the return value is always 0 or 1. + + This function is provided for STL compatibility. +*/ + +/*! + \fn Iterator QMap::replace( const Key& k, const T& v ) + + Replaces the value of the element with key \a k, with the value \a + v. + + \sa insert() remove() +*/ + +/*! + \fn const T& QMap::operator[] ( const Key& k ) const + + \overload + + \warning This function differs from the non-const version of the + same function. It will \e not insert an empty value if the key \a + k does not exist. This may lead to logic errors in your program. + You should check if the element exists before calling this + function. + + Returns the value associated with the key \a k. If no such key is + present, a reference to an empty item is returned. +*/ + +/*! + \fn uint QMap::count() const + + \overload + + Returns the number of items in the map. + + \sa isEmpty() +*/ + +/*! + \fn bool QMap::isEmpty() const + + Returns TRUE if the map contains no items; otherwise returns + FALSE. + + \sa count() +*/ + +/*! + \fn Iterator QMap::insert( const Key& key, const T& value, bool overwrite ) + + Inserts a new item with the key, \a key, and a value of \a value. + If there is already an item whose key is \a key, that item's value + is replaced with \a value, unless \a overwrite is FALSE (it is + TRUE by default). In this case an iterator to this item is + returned, else an iterator to the new item is returned. + +*/ + +/*! + \fn void QMap::remove( iterator it ) + + Removes the item associated with the iterator \a it from the map. + + \sa clear() +*/ + +/*! + \fn void QMap::remove( const Key& k ) + + \overload + + Removes the item with the key \a k from the map. +*/ + +/*! + \fn bool QMap::contains( const Key& k ) const + + Returns TRUE if the map contains an item with key \a k; otherwise + returns FALSE. +*/ + + +/***************************************************************************** + QMapIterator documentation + *****************************************************************************/ + +/*! + \class QMapIterator qmap.h + \brief The QMapIterator class provides an iterator for QMap. + + \ingroup qtl + \ingroup tools + + You cannot create an iterator by yourself. Instead, you must ask a + map to give you one. An iterator is as big as a pointer; on 32-bit + machines that means 4 bytes, on 64-bit machines, 8 bytes. That + makes copying iterators very fast. Iterators behave in a similar + way to pointers, and they are almost as fast as pointers. See the + \link qmap.html#qmap-eg QMap example\endlink. + + QMap is highly optimized for performance and memory usage, but the + trade-off is that you must be more careful. The only way to + traverse a map is to use iterators. QMap does not know about its + iterators, and the iterators don't even know to which map they + belong. That makes things fast but a bit dangerous because it is + up to you to make sure that the iterators you are using are still + valid. QDictIterator will be able to give warnings, whereas + QMapIterator may end up in an undefined state. + + For every Iterator there is also a ConstIterator. You must use the + ConstIterator to access a QMap in a const environment or if the + reference or pointer to the map is itself const. Its semantics are + the same, but it only returns const references to the item it + points to. + + \sa QMap QMapConstIterator +*/ + +/*! \enum QMapIterator::iterator_category + The type of iterator category, \c std::bidirectional_iterator_tag. */ +/*! \enum QMapIterator::value_type + The type of value. */ +/*! \enum QMapIterator::pointer + Pointer to value_type. */ +/*! \enum QMapIterator::reference + Reference to value_type. */ +/*! \enum QMapIterator::difference_type + \internal */ +/*! \enum QMapIterator::NodePtr + \internal */ + +/*! + \fn QMapIterator::QMapIterator() + + Creates an uninitialized iterator. +*/ + +/*! + \fn QMapIterator::QMapIterator (QMapNode<K, T> * p) + + Constructs an iterator starting at node \a p. +*/ + +/*! + \fn QMapIterator::QMapIterator( const QMapIterator<K,T>& it ) + + Constructs a copy of the iterator, \a it. +*/ + +/*! + \fn QMapIterator<K,T>& QMapIterator::operator++() + + Prefix ++ makes the succeeding item current and returns an + iterator pointing to the new current item. The iterator cannot + check whether it reached the end of the map. Incrementing the + iterator returned by end() causes undefined results. +*/ + +/*! + \fn QMapIterator<K,T> QMapIterator::operator++(int) + + \overload + + Postfix ++ makes the succeeding item current and returns an + iterator pointing to the new current item. The iterator cannot + check whether it reached the end of the map. Incrementing the + iterator returned by end() causes undefined results. +*/ + +/*! + \fn QMapIterator<K,T>& QMapIterator::operator--() + + Prefix -- makes the previous item current and returns an iterator + pointing to the new current item. The iterator cannot check + whether it reached the beginning of the map. Decrementing the + iterator returned by begin() causes undefined results. +*/ + +/*! + \fn QMapIterator<K,T> QMapIterator::operator--(int) + + \overload + + Postfix -- makes the previous item current and returns an iterator + pointing to the new current item. The iterator cannot check + whether it reached the beginning of the map. Decrementing the + iterator returned by begin() causes undefined results. +*/ + +/*! + \fn T& QMapIterator::operator*() + + Dereference operator. Returns a reference to the current item's + data. The same as data(). +*/ + +/*! + \fn const T& QMapIterator::operator*() const + + \overload + + Dereference operator. Returns a const reference to the current + item's data. The same as data(). +*/ + +/*! + \fn bool QMapIterator::operator==( const QMapIterator<K,T>& it ) const + + Compares the iterator to the \a it iterator and returns TRUE if + they point to the same item; otherwise returns FALSE. +*/ + +/*! + \fn bool QMapIterator::operator!=( const QMapIterator<K,T>& it ) const + + Compares the iterator to the \a it iterator and returns FALSE if + they point to the same item; otherwise returns TRUE. +*/ + +/*! + \fn T& QMapIterator::data() + + Returns a reference to the current item's data. +*/ + +/*! + \fn const T& QMapIterator::data() const + + \overload + + Returns a const reference to the current item's data. +*/ + +/*! + \fn const K& QMapIterator::key() const + + Returns a const reference to the current item's key. +*/ + +/*! + \fn QValueList<Key> QMap::keys() const + + Returns a list of all the keys in the map, in order. +*/ + +/*! + \fn QValueList<T> QMap::values() const + + Returns a list of all the values in the map, in key order. +*/ + +/***************************************************************************** + QMapConstIterator documentation + *****************************************************************************/ + +/*! + \class QMapConstIterator qmap.h + \brief The QMapConstIterator class provides an iterator for QMap. + + \ingroup qtl + \ingroup tools + + In contrast to QMapIterator, this class is used to iterate over a + const map. It does not allow you to modify the values of the map + because this would break the const semantics. + + For more information on QMap iterators, see \l{QMapIterator} and + the \link qmap.html#qmap-eg QMap example\endlink. + + \sa QMap QMapIterator +*/ + +/*! \enum QMapConstIterator::iterator_category + The type of iterator category, \c std::bidirectional_iterator_tag. */ +/*! \enum QMapConstIterator::value_type + The type of const value. */ +/*! \enum QMapConstIterator::pointer + Const pointer to value_type. */ +/*! \enum QMapConstIterator::reference + Const reference to value_type. */ +/*! \enum QMapConstIterator::difference_type + \internal */ +/*! \enum QMapConstIterator::NodePtr + \internal */ + + +/*! + \fn QMapConstIterator::QMapConstIterator() + + Constructs an uninitialized iterator. +*/ + +/*! + \fn QMapConstIterator::QMapConstIterator (QMapNode<K, T> * p) + + Constructs an iterator starting at node \a p. +*/ + +/*! + \fn QMapConstIterator::QMapConstIterator( const QMapConstIterator<K,T>& it ) + + Constructs a copy of the iterator, \a it. +*/ + +/*! + \fn QMapConstIterator::QMapConstIterator( const QMapIterator<K,T>& it ) + + Constructs a copy of the iterator, \a it. +*/ + +/*! + \fn QMapConstIterator<K,T>& QMapConstIterator::operator++() + + Prefix ++ makes the succeeding item current and returns an + iterator pointing to the new current item. The iterator cannot + check whether it reached the end of the map. Incrementing the + iterator returned by end() causes undefined results. +*/ + +/*! + \fn QMapConstIterator<K,T> QMapConstIterator::operator++(int) + + \overload + + Postfix ++ makes the succeeding item current and returns an + iterator pointing to the new current item. The iterator cannot + check whether it reached the end of the map. Incrementing the + iterator returned by end() causes undefined results. +*/ + +/*! + \fn QMapConstIterator<K,T>& QMapConstIterator::operator--() + + Prefix -- makes the previous item current and returns an iterator + pointing to the new current item. The iterator cannot check + whether it reached the beginning of the map. Decrementing the + iterator returned by begin() causes undefined results. +*/ + +/*! + \fn QMapConstIterator<K,T> QMapConstIterator::operator--(int) + + \overload + + Postfix -- makes the previous item current and returns an iterator + pointing to the new current item. The iterator cannot check + whether it reached the beginning of the map. Decrementing the + iterator returned by begin() causes undefined results. +*/ + +/*! + \fn const T& QMapConstIterator::operator*() const + + Dereference operator. Returns a const reference to the current + item's data. The same as data(). +*/ + +/*! + \fn bool QMapConstIterator::operator==( const QMapConstIterator<K,T>& it ) const + + Compares the iterator to the \a it iterator and returns TRUE if + they point to the same item; otherwise returns FALSE. +*/ + +/*! + \fn bool QMapConstIterator::operator!=( const QMapConstIterator<K,T>& it ) const + + Compares the iterator to the \a it iterator and returns FALSE if + they point to the same item; otherwise returns TRUE. +*/ + +/*! + \fn const T& QMapConstIterator::data() const + + Returns a const reference to the current item's data. +*/ + +/*! + \fn const K& QMapConstIterator::key() const + + Returns a const reference to the current item's key. +*/ |