Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | ![]() |
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 the Qt Template Library for more information.
The class used for the key requires that the operator< is implemented
to define ordering of the keys.
Program output:
As you can see, 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 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. 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:
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 count() function. 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, Qt Template Library, Implicitly and Explicitly Shared Classes and Non-GUI Classes.
This operation costs O(1) time because QMap is implicitly shared. The
first instance of applying modifications to a shared map 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 not possible for an iterator to check whether it is
valid or not.
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).
See also end() and QMapIterator.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
See also end() and QMapConstIterator.
See also erase().
Use count() instead.
Use size() instead.
See also isEmpty().
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.
This iterator equals begin() if the map is empty.
See also begin() and QMapIterator.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
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.
This iterator equals begin() if the map is empty.
See also begin() and QMapConstIterator.
See also clear() and QMapIterator.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Removes the item with the key k.
See also clear().
Returns an iterator pointing to the element with key k in the map.
Returns end() if no key matched.
See also QMapIterator.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator pointing to the element with key k in the map.
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 to 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 QMap::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
implicitly shared.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Assigns m to this map and returns a reference to this map.
All iterators of the current map become invalidated by this
operation.
You can use this operator both for reading and writing:
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
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() and iterator.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use erase() instead.
See also clear().
See also insert(), remove() and QMapIterator.
This file is part of the Qt toolkit,
copyright © 1995-2001
Trolltech, all rights reserved.
#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["JD002"] = 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;
}
JD001: Doe, John earns 50000
JW002: Williams, Jane earns 80000
SH001: Hind, Sasha earns 50000
TJ001: Jones, Tom earns 60000
QMap<QString,QString> map;
map["Clinton"] = "Bill";
str << map["Clinton"] << map["Bush"] << endl;
QMap<QString,QString> map;
map["Clinton"] = "Bill";
map.insert( qMakePair("Bush", "George") );
Member Type Documentation
QMap::ConstIterator
The map's const iterator type, QTL style.
QMap::Iterator
The map's iterator type, QTL style.
QMap::ValueType
Corresponds to QPairQMap::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 ()
const_iterator QMap::begin () const
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 is 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
map 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 the map's size is zero; otherwise returns FALSE.
iterator QMap::end ()
const_iterator QMap::end () const
void QMap::erase ( iterator it )
Removes the item at iterator position it in the map.
void QMap::erase ( const key_type & k )
iterator QMap::find ( const Key & k )
const_iterator QMap::find ( const Key & k ) const
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 )
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["Clinton"] = "Bill";
stream << map["Clinton"];
const T & QMap::operator[] ( const Key & k ) const
void QMap::remove ( iterator it )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
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 the map m to the stream s. The types Key and T
must implement the streaming operator as well.
QDataStream & operator>> ( QDataStream & s, QMap<Key, T> & m )
Reads the map m from the stream s. The types Key and T
must implement the streaming operator as well.
Copyright © 2001
Trolltech Trademarks