![]() |
| ||
Classes - Annotated - Tree - Functions - Home - Structure |
The QMap class is a value-based template class that provides a dictionary. More...
#include <qmap.h>
QMap is a Qt implementation of an STL-like map container. It can be used in your application if the standard map<> is not available. QMap is part of the Qt Template Library.
QMap 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
elements. For more relaxed ownership semantics, see QPtrCollection and
friends which are pointer-based containers.
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
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.
QMap uses an STL-like syntax to manipulate and address the
objects it contains. For historical reasons, QMap contains
additional functions which essentially perform the same task. It is
recommended that the STL-like functions be used in application code
to ease the transition to a future version of Qt. See this document for more information.
The class used for the key requires that the operator< is implemented
to define ordering of the keys.
Example:
Program output:
As you can see, the latest changes to Joe's salary did not affect
the value in the list because the map created a copy of Joe's
entry. In addition, notice that the items are sorted alphabetically
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 getting an iterator is that you can now move
forward or backward from this position 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 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().
Since end() returns a past-the-end iterator, the size() of the list
is equal to end() - begin().
Another way to find an element in the map is by using the find()
function. It 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:
The code fragment will print out "Torben", "". Since the value
associated with the "Ettrich" 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,
the count() function is what you are looking for. In addition,
size() tells you how many keys there are currently 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
elements in the map. The map holds its own copies and will free
them if the corresponding member or the map itself is deleted. You
can force the map to free all its item with clear().
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; it thus does not affect
other instances. From a developer's point of view you can think
that a QMap and a copy of this map have nothing to do with each
other. If a QMap is being used in a multi-threaded program, you must
protect all access to the map. See QMutex.
There are several ways of inserting new elements into the map. One
uses the insert() method; the other one uses operator[] like this:
Items can also be removed from the map in several ways. The first is
to pass an iterator to erase(). The other is to pass a key
value to erase(), which will delete the entry with the requested
key. In addition you can clear the entire map using the clear()
method.
See also QMapIterator.
This operation costs O(1) time because QMap is shared implicitly. The
first instance of applying modifications to a shared list will create a
copy that takes in turn O(n) time. However, returning a QMap from a
function is very fast.
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 impossible for an iterator to check whether it is
valid or not.
See also end() and QMapIterator.
See also end() and QMapConstIterator.
See also erase().
Use count() instead.
Use size() instead.
See also isEmpty().
See also begin() and QMapIterator.
See also begin() and QMapConstIterator.
See also clear() and QMapIterator.
See also clear().
Returns end() if no key matched.
See also QMapIterator.
Returns end() if no key matched.
See also QMapConstIterator.
Inserts x into the map. x is a QPair<> whose first
element is a key to be inserted and whose second element is the
associated value to be inserted. Returns a pair<> whose first
element is an iterator pointing at the inserted item and whose second element is a bool indicating TRUE if x was inserted and
FALSE if it was not inserted because it was already present.
Use insert() instead.
See also iterator.
Use empty() instead.
See also size().
All iterators of the current map become invalidated by this
operation. The cost of such an assignment is O(1), because QMap is
shared implicitly.
All iterators of the current map become invalidated by this
operation.
You can use this operator both for reading and writing:
Warning: This function differs from the non-const version of the
same function. It will not insert an empty value if the key 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 k. If no such
key is present, a reference to an empty item is returned.
Use erase() instead.
See also clear().
See also insert(), remove() and QMapIterator.
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit,
copyright © 1995-2001
Trolltech, all rights reserved.
#include <qmap.h>
#include <qstring.h>
#include <stdio.h>
class Employee
{
public:
Employee(): s(0) {}
Employee( const QString& name, int salary )
: n(name), s(salary)
{}
QString name() const { return n; }
int salary() const { return s; }
void setSalary( int salary ) { s = salary; }
private:
QString n;
int s;
};
int main()
{
typedef QMap<QString,Employee> EmployeeMap;
EmployeeMap map; // map of Employee
map["Gates"] = Employee("Bill", 50000);
map["Ballmer"] = Employee("Steve",80000);
map[ "Sommer"] = Employee("Ron", 60000);
Employee joe( "Joe", 50000 );
map["Doe"] = joe ;
joe.setSalary( 4000 );
EmployeeMap::Iterator it;
for( it = map.begin(); it != map.end(); ++it )
printf( "%s, %s earns %d\n", it.key().latin1(), it.data().name().latin1(), it.data().salary() );
return 0;
}
Ballmer, Steve earns 80000
Doe, Joe earns 50000
Gates, Bill earns 50000
Sommer, Ron earns 60000
QMap<QString,QString> map;
map["Weis"] = "Torben";
str << map["Weis"] << map["Ettrich"] << endl;
QMap<QString,QString> map;
map["Weis"] = "Torben";
map.insert( qMakePair( "Berton","Dave" ) );
;
Member Type Documentation
QMap::const_iterator
The map's const iterator type.
QMap::const_pointer
Const pointer to value_type.
QMap::const_reference
Const reference to value_type.
QMap::iterator
The map's iterator type.
QMap::key_type
The map's key type.
QMap::mapped_type
The map's data type.
QMap::pointer
Pointer to value_type.
QMap::reference
Reference to value_type.
QMap::size_type
An unsigned integral type, used to represent various sizes.
QMap::value_type
Corresponds to QPairMember Function Documentation
QMap::QMap ()
Constructs an empty map.
QMap::QMap ( const QMap<Key, T> & m )
Constructs a copy of m.
QMap::QMap ( const std::map<Key, T> & m )
Constructs a copy of m.
QMap::~QMap ()
iterator QMap::begin ()
Returns an iterator pointing to the first element in the map. This
iterator equals end() if the map is empty.
const_iterator QMap::begin () const
Returns an iterator pointing to the first element in the map. This
iterator equals end() if the map is empty.
void QMap::clear ()
Removes all items from the map.
bool QMap::contains ( const Key & k ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
size_type QMap::count ( const key_type & k )
Returns the number of elements whose key are k. The return value is either 0 or 1.
size_type QMap::count () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
void QMap::detach () [protected]
If the map does not share its data with another QMap instance, nothing happens; otherwise the function creates a new copy of this
data and detaches from the shared one. This function is called
whenever the map is modified. The implicit sharing mechanism is
implemented this way.
bool QMap::empty () const
Returns TRUE if and only if the map's size is zero.
iterator QMap::end ()
Returns an iterator pointing behind the last element in the map. This
iterator equals begin() if the map is empty.
const_iterator QMap::end () const
Returns an iterator pointing behind the last element in the map. This
iterator equals begin() if the map is empty.
void QMap::erase ( iterator it )
Removes the item at position it in the map.
void QMap::erase ( const key_type & k )
Removes the item with the key k.
iterator QMap::find ( const Key & k )
Finds the key k in the map.
const_iterator QMap::find ( const Key & k ) const
Finds the key k in the map.
QPair<iterator, bool> QMap::insert ( const value_type & x )
iterator QMap::insert ( const Key & key, const T & value, bool overwrite = TRUE )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
bool QMap::isEmpty () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
QMap<Key, T> & QMap::operator= ( const QMap<Key, T> & m )
Assigns m to this map and returns a reference to this map.
QMap<Key, T> & QMap::operator= ( const std::map<Key, T> & m )
Assigns m to this map and returns a reference to this map.
T & QMap::operator[] ( const Key & k )
Returns the value associated with the key k. If no such
key is present, an empty item is inserted with this key
and a reference to the item is returned.
QMap<QString,QString> map;
map[ "Weis" ] = "Torben";
stream << map[ "Weis" ];
const T & QMap::operator[] ( const Key & k ) const
void QMap::remove ( const Key & k )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
iterator QMap::replace ( const Key & k, const T & v )
Replaces the value with key k from the map if possible, and
inserts the new value v with key k in the map.
size_type QMap::size () const
Returns the number of elements in the map.
Related Functions
QDataStream & operator<< ( QDataStream & s, const QMap<Key, T> & m )
Writes a map to the stream. The types Key and T must implement
the streaming operator as well.
QDataStream & operator>> ( QDataStream & s, QMap<Key, T> & m )
Reads a map from the stream. The types Key and T must implement
the streaming operator as well.
Copyright © 2001 Trolltech Trademarks