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.
575 lines
28 KiB
575 lines
28 KiB
14 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qmap.doc:41 -->
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
|
<title>QMap Class</title>
|
||
|
|
<style type="text/css"><!--
|
||
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
||
|
|
a:link { color: #004faf; text-decoration: none }
|
||
|
|
a:visited { color: #672967; text-decoration: none }
|
||
|
|
body { background: #ffffff; color: black; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
|
<tr bgcolor="#E5E5E5">
|
||
|
|
<td valign=center>
|
||
|
|
<a href="index.html">
|
||
|
|
<font color="#004faf">Home</font></a>
|
||
|
|
| <a href="classes.html">
|
||
|
|
<font color="#004faf">All Classes</font></a>
|
||
|
|
| <a href="mainclasses.html">
|
||
|
|
<font color="#004faf">Main Classes</font></a>
|
||
|
|
| <a href="annotated.html">
|
||
|
|
<font color="#004faf">Annotated</font></a>
|
||
|
|
| <a href="groups.html">
|
||
|
|
<font color="#004faf">Grouped Classes</font></a>
|
||
|
|
| <a href="functions.html">
|
||
|
|
<font color="#004faf">Functions</font></a>
|
||
|
|
</td>
|
||
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QMap Class Reference</h1>
|
||
|
|
|
||
|
|
<p>The QMap class is a value-based template class that
|
||
|
|
provides a dictionary.
|
||
|
|
<a href="#details">More...</a>
|
||
|
|
<p><tt>#include <<a href="qmap-h.html">qmap.h</a>></tt>
|
||
|
|
<p><a href="qmap-members.html">List of all member functions.</a>
|
||
|
|
<h2>Public Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>typedef Key <a href="#key_type"><b>key_type</b></a></li>
|
||
|
|
<li class=fn>typedef T <a href="#mapped_type"><b>mapped_type</b></a></li>
|
||
|
|
<li class=fn>typedef QPair<const key_type, mapped_type> <a href="#value_type"><b>value_type</b></a></li>
|
||
|
|
<li class=fn>typedef value_type * <a href="#pointer"><b>pointer</b></a></li>
|
||
|
|
<li class=fn>typedef const value_type * <a href="#const_pointer"><b>const_pointer</b></a></li>
|
||
|
|
<li class=fn>typedef value_type & <a href="#reference"><b>reference</b></a></li>
|
||
|
|
<li class=fn>typedef const value_type & <a href="#const_reference"><b>const_reference</b></a></li>
|
||
|
|
<li class=fn>typedef size_t <a href="#size_type"><b>size_type</b></a></li>
|
||
|
|
<li class=fn>typedef QMapIterator<Key, T> <a href="#iterator"><b>iterator</b></a></li>
|
||
|
|
<li class=fn>typedef QMapConstIterator<Key, T> <a href="#const_iterator"><b>const_iterator</b></a></li>
|
||
|
|
<li class=fn>typedef QPair<iterator, bool> <b>insert_pair</b></li>
|
||
|
|
<li class=fn>typedef QMapIterator<Key, T> <a href="#Iterator"><b>Iterator</b></a></li>
|
||
|
|
<li class=fn>typedef QMapConstIterator<Key, T> <a href="#ConstIterator"><b>ConstIterator</b></a></li>
|
||
|
|
<li class=fn>typedef T <a href="#ValueType"><b>ValueType</b></a></li>
|
||
|
|
<li class=fn><a href="#QMap"><b>QMap</b></a> ()</li>
|
||
|
|
<li class=fn><a href="#QMap-2"><b>QMap</b></a> ( const QMap<Key, T> & m )</li>
|
||
|
|
<li class=fn><a href="#QMap-3"><b>QMap</b></a> ( const std::map<Key, T> & m )</li>
|
||
|
|
<li class=fn><a href="#~QMap"><b>~QMap</b></a> ()</li>
|
||
|
|
<li class=fn>QMap<Key, T> & <a href="#operator-eq"><b>operator=</b></a> ( const QMap<Key, T> & m )</li>
|
||
|
|
<li class=fn>QMap<Key, T> & <a href="#operator-eq-2"><b>operator=</b></a> ( const std::map<Key, T> & m )</li>
|
||
|
|
<li class=fn>iterator <a href="#begin"><b>begin</b></a> ()</li>
|
||
|
|
<li class=fn>iterator <a href="#end"><b>end</b></a> ()</li>
|
||
|
|
<li class=fn>const_iterator <a href="#begin-2"><b>begin</b></a> () const</li>
|
||
|
|
<li class=fn>const_iterator <a href="#end-2"><b>end</b></a> () const</li>
|
||
|
|
<li class=fn>const_iterator <a href="#constBegin"><b>constBegin</b></a> () const</li>
|
||
|
|
<li class=fn>const_iterator <a href="#constEnd"><b>constEnd</b></a> () const</li>
|
||
|
|
<li class=fn>iterator <a href="#replace"><b>replace</b></a> ( const Key & k, const T & v )</li>
|
||
|
|
<li class=fn>size_type <a href="#size"><b>size</b></a> () const</li>
|
||
|
|
<li class=fn>bool <a href="#empty"><b>empty</b></a> () const</li>
|
||
|
|
<li class=fn>QPair<iterator, bool> <a href="#insert-2"><b>insert</b></a> ( const value_type & x )</li>
|
||
|
|
<li class=fn>void <a href="#erase"><b>erase</b></a> ( iterator it )</li>
|
||
|
|
<li class=fn>void <a href="#erase-2"><b>erase</b></a> ( const key_type & k )</li>
|
||
|
|
<li class=fn>size_type <a href="#count"><b>count</b></a> ( const key_type & k ) const</li>
|
||
|
|
<li class=fn>T & <a href="#operator[]"><b>operator[]</b></a> ( const Key & k )</li>
|
||
|
|
<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li>
|
||
|
|
<li class=fn>iterator <a href="#find"><b>find</b></a> ( const Key & k )</li>
|
||
|
|
<li class=fn>const_iterator <a href="#find-2"><b>find</b></a> ( const Key & k ) const</li>
|
||
|
|
<li class=fn>const T & <a href="#operator[]-2"><b>operator[]</b></a> ( const Key & k ) const</li>
|
||
|
|
<li class=fn>bool <a href="#contains"><b>contains</b></a> ( const Key & k ) const</li>
|
||
|
|
<li class=fn>size_type <a href="#count-2"><b>count</b></a> () const</li>
|
||
|
|
<li class=fn>QValueList<Key> <a href="#keys"><b>keys</b></a> () const</li>
|
||
|
|
<li class=fn>QValueList<T> <a href="#values"><b>values</b></a> () const</li>
|
||
|
|
<li class=fn>bool <a href="#isEmpty"><b>isEmpty</b></a> () const</li>
|
||
|
|
<li class=fn>iterator <a href="#insert"><b>insert</b></a> ( const Key & key, const T & value, bool overwrite = TRUE )</li>
|
||
|
|
<li class=fn>void <a href="#remove"><b>remove</b></a> ( iterator it )</li>
|
||
|
|
<li class=fn>void <a href="#remove-2"><b>remove</b></a> ( const Key & k )</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Protected Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>void <a href="#detach"><b>detach</b></a> ()</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Related Functions</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>QDataStream & <a href="#operator-gt-gt"><b>operator>></b></a> ( QDataStream & s, QMap<Key, T> & m )</li>
|
||
|
|
<li class=fn>QDataStream & <a href="#operator-lt-lt"><b>operator<<</b></a> ( QDataStream & s, const QMap<Key, T> & m )</li>
|
||
|
|
</ul>
|
||
|
|
<hr><a name="details"></a><h2>Detailed Description</h2>
|
||
|
|
|
||
|
|
|
||
|
|
The QMap class is a value-based template class that
|
||
|
|
provides a dictionary.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p> QMap is a Qt implementation of an STL-like map container. It can
|
||
|
|
be used in your application if the standard <tt>map</tt> is not
|
||
|
|
available on all your target platforms. QMap is part of the <a href="qtl.html">Qt Template Library</a>.
|
||
|
|
<p> 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 <a href="qptrlist.html">QPtrList</a> and <a href="qdict.html">QDict</a> are pointer-based.
|
||
|
|
<p> 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.
|
||
|
|
<p> Some classes cannot be used within a QMap. For example everything
|
||
|
|
derived from <a href="qobject.html">QObject</a> and thus all classes that implement widgets.
|
||
|
|
Only values can be used in a QMap. To qualify as a value, the
|
||
|
|
class must provide
|
||
|
|
<p> <ul>
|
||
|
|
<li> A copy constructor
|
||
|
|
<li> An assignment operator
|
||
|
|
<li> A default constructor, i.e. a constructor that does not take
|
||
|
|
any arguments.
|
||
|
|
</ul>
|
||
|
|
<p> 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.
|
||
|
|
<p> The class used for the key requires that the <tt>operator<</tt> is
|
||
|
|
implemented to define ordering of the keys.
|
||
|
|
<p> QMap's function naming is consistent with the other Qt classes
|
||
|
|
(e.g., <a href="#count">count</a>(), <a href="#isEmpty">isEmpty</a>()). QMap also provides extra functions for
|
||
|
|
compatibility with STL algorithms, such as <a href="#size">size</a>() and <a href="#empty">empty</a>().
|
||
|
|
Programmers already familiar with the STL <tt>map</tt> can use these
|
||
|
|
the STL-like functions if preferred.
|
||
|
|
<p> Example:
|
||
|
|
<a name="qmap-eg"></a>
|
||
|
|
<pre>
|
||
|
|
#include <<a href="qstring-h.html">qstring.h</a>>
|
||
|
|
#include <<a href="qmap-h.html">qmap.h</a>>
|
||
|
|
#include <<a href="qstring-h.html">qstring.h</a>>
|
||
|
|
|
||
|
|
class Employee
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
Employee(): sn(0) {}
|
||
|
|
Employee( const <a href="qstring.html">QString</a>& forename, const <a href="qstring.html">QString</a>& surname, int salary )
|
||
|
|
: fn(forename), sn(surname), sal(salary)
|
||
|
|
{ }
|
||
|
|
|
||
|
|
<a href="qstring.html">QString</a> forename() const { return fn; }
|
||
|
|
<a href="qstring.html">QString</a> surname() const { return sn; }
|
||
|
|
int salary() const { return sal; }
|
||
|
|
void setSalary( int salary ) { sal = salary; }
|
||
|
|
|
||
|
|
private:
|
||
|
|
<a href="qstring.html">QString</a> fn;
|
||
|
|
<a href="qstring.html">QString</a> sn;
|
||
|
|
int sal;
|
||
|
|
};
|
||
|
|
|
||
|
|
int main(int argc, char **argv)
|
||
|
|
{
|
||
|
|
<a href="qapplication.html">QApplication</a> 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::<a href="#Iterator">Iterator</a> 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;
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Program output:
|
||
|
|
<pre>
|
||
|
|
JD001: Doe, John earns 50000
|
||
|
|
JW002: Williams, Jane earns 80000
|
||
|
|
SH001: Hind, Sasha earns 50000
|
||
|
|
TJ001: Jones, Tom earns 60000
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> 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.
|
||
|
|
<p> There are several ways to find items in a map. The <a href="#begin">begin</a>() and
|
||
|
|
<a href="#end">end</a>() 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 <em>not</em> dereferenceable; <a href="qsize.html#operator*-4">operator*</a>() will not return a well-defined
|
||
|
|
value. If the map is empty, the iterator returned by begin() will
|
||
|
|
equal the iterator returned by end().
|
||
|
|
<p> Another way to find an element in the map is by using the <a href="#find">find</a>()
|
||
|
|
function. This returns an iterator pointing to the desired item or
|
||
|
|
to the end() iterator if no such element exists.
|
||
|
|
<p> 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:
|
||
|
|
<p> <pre>
|
||
|
|
QMap<QString,QString> map;
|
||
|
|
map["Clinton"] = "Bill";
|
||
|
|
str << map["Clinton"] << map["Bush"] << endl;
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> 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.
|
||
|
|
<p> If you just want to know whether a certain key is contained in the
|
||
|
|
map, use the <a href="#contains">contains</a>() function. In addition, <a href="#count">count</a>() tells you
|
||
|
|
how many keys are in the map.
|
||
|
|
<p> 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.
|
||
|
|
<p> 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.
|
||
|
|
<p> QMap is <a href="shclass.html#implicitly-shared">implicitly shared</a>. 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 <a href="qmutex.html">QMutex</a>.
|
||
|
|
<p> There are a couple of ways of inserting new items into the map.
|
||
|
|
One uses the <a href="#insert">insert</a>() method; the other uses operator[]:
|
||
|
|
<pre>
|
||
|
|
QMap<QString, QString> map;
|
||
|
|
map["Clinton"] = "Bill";
|
||
|
|
map.<a href="#insert">insert</a>( "Bush", "George" );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Items can also be removed from the map in several ways. One way is
|
||
|
|
to pass an iterator to <a href="#remove">remove</a>(). 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 <a href="#clear">clear</a>()
|
||
|
|
method.
|
||
|
|
<p> <p>See also <a href="qmapiterator.html">QMapIterator</a>, <a href="qtl.html">Qt Template Library Classes</a>, <a href="shared.html">Implicitly and Explicitly Shared Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
|
||
|
|
|
||
|
|
<hr><h2>Member Type Documentation</h2>
|
||
|
|
<h3 class=fn><a name="ConstIterator"></a>QMap::ConstIterator</h3>
|
||
|
|
The map's const iterator type, Qt style.
|
||
|
|
<h3 class=fn><a name="Iterator"></a>QMap::Iterator</h3>
|
||
|
|
The map's iterator type, Qt style.
|
||
|
|
<h3 class=fn><a name="ValueType"></a>QMap::ValueType</h3>
|
||
|
|
Corresponds to <a href="qpair.html">QPair</a><key_type, mapped_type>, Qt style.
|
||
|
|
<h3 class=fn><a name="const_iterator"></a>QMap::const_iterator</h3>
|
||
|
|
The map's const iterator type.
|
||
|
|
<h3 class=fn><a name="const_pointer"></a>QMap::const_pointer</h3>
|
||
|
|
Const pointer to value_type.
|
||
|
|
<h3 class=fn><a name="const_reference"></a>QMap::const_reference</h3>
|
||
|
|
Const reference to value_type.
|
||
|
|
<h3 class=fn><a name="iterator"></a>QMap::iterator</h3>
|
||
|
|
The map's iterator type.
|
||
|
|
<h3 class=fn><a name="key_type"></a>QMap::key_type</h3>
|
||
|
|
The map's key type.
|
||
|
|
<h3 class=fn><a name="mapped_type"></a>QMap::mapped_type</h3>
|
||
|
|
The map's data type.
|
||
|
|
<h3 class=fn><a name="pointer"></a>QMap::pointer</h3>
|
||
|
|
Pointer to value_type.
|
||
|
|
<h3 class=fn><a name="reference"></a>QMap::reference</h3>
|
||
|
|
Reference to value_type.
|
||
|
|
<h3 class=fn><a name="size_type"></a>QMap::size_type</h3>
|
||
|
|
An unsigned integral type, used to represent various sizes.
|
||
|
|
<h3 class=fn><a name="value_type"></a>QMap::value_type</h3>
|
||
|
|
Corresponds to <a href="qpair.html">QPair</a><key_type, mapped_type>.
|
||
|
|
<hr><h2>Member Function Documentation</h2>
|
||
|
|
<h3 class=fn><a name="QMap"></a>QMap::QMap ()
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Constructs an empty map.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="QMap-2"></a>QMap::QMap ( const <a href="qmap.html">QMap</a><Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Constructs a copy of <em>m</em>.
|
||
|
|
<p> This operation costs O(1) time because QMap is <a href="shclass.html#implicitly-shared">implicitly shared</a>.
|
||
|
|
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.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="QMap-3"></a>QMap::QMap ( const std::map<Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Constructs a copy of <em>m</em>.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="~QMap"></a>QMap::~QMap ()
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> 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.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#iterator">iterator</a> <a name="begin"></a>QMap::begin ()
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns an iterator pointing to the first element in the map. This
|
||
|
|
iterator equals <a href="#end">end</a>() if the map is empty.
|
||
|
|
<p> The items in the map are traversed in the order defined by
|
||
|
|
operator<(Key, Key).
|
||
|
|
<p> <p>See also <a href="#end">end</a>() and <a href="qmapiterator.html">QMapIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#const_iterator">const_iterator</a> <a name="begin-2"></a>QMap::begin () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> <p>See also <a href="#end">end</a>() and <a href="qmapconstiterator.html">QMapConstIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="clear"></a>QMap::clear ()
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Removes all items from the map.
|
||
|
|
<p> <p>See also <a href="#remove">remove</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#const_iterator">const_iterator</a> <a name="constBegin"></a>QMap::constBegin () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns an iterator pointing to the first element in the map. This
|
||
|
|
iterator equals <a href="#end">end</a>() if the map is empty.
|
||
|
|
<p> The items in the map are traversed in the order defined by
|
||
|
|
operator<(Key, Key).
|
||
|
|
<p> <p>See also <a href="#constEnd">constEnd</a>() and <a href="qmapconstiterator.html">QMapConstIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#const_iterator">const_iterator</a> <a name="constEnd"></a>QMap::constEnd () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> The iterator returned by <a href="#end">end</a>() 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 <em>not</em>
|
||
|
|
dereferenceable; <a href="qsize.html#operator*-4">operator*</a>() will not return a well-defined value.
|
||
|
|
<p> This iterator equals <a href="#constBegin">constBegin</a>() if the map is empty.
|
||
|
|
<p> <p>See also <a href="#constBegin">constBegin</a>() and <a href="qmapconstiterator.html">QMapConstIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="contains"></a>QMap::contains ( const Key & k ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns TRUE if the map contains an item with key <em>k</em>; otherwise
|
||
|
|
returns FALSE.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#size_type">size_type</a> <a name="count"></a>QMap::count ( const <a href="qmap.html#key_type">key_type</a> & k ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the number of items whose key is <em>k</em>. Since QMap does not
|
||
|
|
allow duplicate keys, the return value is always 0 or 1.
|
||
|
|
<p> This function is provided for STL compatibility.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#size_type">size_type</a> <a name="count-2"></a>QMap::count () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns the number of items in the map.
|
||
|
|
<p> <p>See also <a href="#isEmpty">isEmpty</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="detach"></a>QMap::detach ()<tt> [protected]</tt>
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> 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 <a href="shclass.html#implicit-sharing">implicit sharing</a> mechanism is
|
||
|
|
implemented this way.
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="empty"></a>QMap::empty () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns TRUE if the map contains no items; otherwise returns
|
||
|
|
FALSE.
|
||
|
|
<p> This function is provided for STL compatibility. It is equivalent
|
||
|
|
to <a href="#isEmpty">isEmpty</a>().
|
||
|
|
<p> <p>See also <a href="#size">size</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#iterator">iterator</a> <a name="end"></a>QMap::end ()
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> The iterator returned by <a href="#end">end</a>() 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 <em>not</em>
|
||
|
|
dereferenceable; <a href="qsize.html#operator*-4">operator*</a>() will not return a well-defined value.
|
||
|
|
<p> This iterator equals <a href="#begin">begin</a>() if the map is empty.
|
||
|
|
<p> <p>See also <a href="#begin">begin</a>() and <a href="qmapiterator.html">QMapIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#const_iterator">const_iterator</a> <a name="end-2"></a>QMap::end () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p>
|
||
|
|
<h3 class=fn>void <a name="erase"></a>QMap::erase ( <a href="qmap.html#iterator">iterator</a> it )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Removes the item associated with the iterator <em>it</em> from the map.
|
||
|
|
<p> This function is provided for STL compatibility. It is equivalent
|
||
|
|
to <a href="#remove">remove</a>().
|
||
|
|
<p> <p>See also <a href="#clear">clear</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="erase-2"></a>QMap::erase ( const <a href="qmap.html#key_type">key_type</a> & k )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Removes the item with the key <em>k</em> from the map.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#iterator">iterator</a> <a name="find"></a>QMap::find ( const Key & k )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns an iterator pointing to the element with key <em>k</em> in the
|
||
|
|
map.
|
||
|
|
<p> Returns <a href="#end">end</a>() if no key matched.
|
||
|
|
<p> <p>See also <a href="qmapiterator.html">QMapIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#const_iterator">const_iterator</a> <a name="find-2"></a>QMap::find ( const Key & k ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns an iterator pointing to the element with key <em>k</em> in the
|
||
|
|
map.
|
||
|
|
<p> Returns <a href="#end">end</a>() if no key matched.
|
||
|
|
<p> <p>See also <a href="qmapconstiterator.html">QMapConstIterator</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#iterator">iterator</a> <a name="insert"></a>QMap::insert ( const Key & key, const T & value, bool overwrite = TRUE )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Inserts a new item with the key, <em>key</em>, and a value of <em>value</em>.
|
||
|
|
If there is already an item whose key is <em>key</em>, that item's value
|
||
|
|
is replaced with <em>value</em>, unless <em>overwrite</em> 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.
|
||
|
|
<p>
|
||
|
|
<h3 class=fn><a href="qpair.html">QPair</a><iterator, bool> <a name="insert-2"></a>QMap::insert ( const <a href="qmap.html#value_type">value_type</a> & x )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Inserts the (key, value) pair <em>x</em> into the map. <em>x</em> is a <a href="qpair.html">QPair</a>
|
||
|
|
whose <tt>first</tt> element is a key to be inserted and whose <tt>second</tt>
|
||
|
|
element is the associated value to be inserted. Returns a pair
|
||
|
|
whose <tt>first</tt> element is an iterator pointing to the inserted
|
||
|
|
item and whose <tt>second</tt> element is a bool indicating TRUE if <em>x</em>
|
||
|
|
was inserted and FALSE if it was not inserted, e.g. because it was
|
||
|
|
already present.
|
||
|
|
<p> <p>See also <a href="#replace">replace</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="isEmpty"></a>QMap::isEmpty () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns TRUE if the map contains no items; otherwise returns
|
||
|
|
FALSE.
|
||
|
|
<p> <p>See also <a href="#count">count</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qvaluelist.html">QValueList</a><Key> <a name="keys"></a>QMap::keys () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns a list of all the keys in the map, in order.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html">QMap</a><Key, T> & <a name="operator-eq"></a>QMap::operator= ( const <a href="qmap.html">QMap</a><Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Assigns <em>m</em> to this map and returns a reference to this map.
|
||
|
|
<p> All iterators of the current map become invalidated by this
|
||
|
|
operation. The cost of such an assignment is O(1), because QMap is
|
||
|
|
<a href="shclass.html#implicitly-shared">implicitly shared</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html">QMap</a><Key, T> & <a name="operator-eq-2"></a>QMap::operator= ( const std::map<Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Assigns <em>m</em> to this map and returns a reference to this map.
|
||
|
|
<p> All iterators of the current map become invalidated by this
|
||
|
|
operation.
|
||
|
|
|
||
|
|
<h3 class=fn>T & <a name="operator[]"></a>QMap::operator[] ( const Key & k )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the value associated with the key <em>k</em>. If no such key is
|
||
|
|
present, an empty item is inserted with this key and a reference
|
||
|
|
to the empty item is returned.
|
||
|
|
<p> You can use this operator both for reading and writing:
|
||
|
|
<pre>
|
||
|
|
QMap<QString, QString> map;
|
||
|
|
map["Clinton"] = "Bill";
|
||
|
|
stream << map["Clinton"];
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 class=fn>const T & <a name="operator[]-2"></a>QMap::operator[] ( const Key & k ) const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> <b>Warning:</b> This function differs from the non-const version of the
|
||
|
|
same function. It will <em>not</em> insert an empty value if the key <em>k</em> does not exist. This may lead to logic errors in your program.
|
||
|
|
You should check if the element exists before calling this
|
||
|
|
function.
|
||
|
|
<p> Returns the value associated with the key <em>k</em>. If no such key is
|
||
|
|
present, a reference to an empty item is returned.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="remove"></a>QMap::remove ( <a href="qmap.html#iterator">iterator</a> it )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Removes the item associated with the iterator <em>it</em> from the map.
|
||
|
|
<p> <p>See also <a href="#clear">clear</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="remove-2"></a>QMap::remove ( const Key & k )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Removes the item with the key <em>k</em> from the map.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#iterator">iterator</a> <a name="replace"></a>QMap::replace ( const Key & k, const T & v )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Replaces the value of the element with key <em>k</em>, with the value <em>v</em>.
|
||
|
|
<p> <p>See also <a href="#insert">insert</a>() and <a href="#remove">remove</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qmap.html#size_type">size_type</a> <a name="size"></a>QMap::size () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the number of items in the map.
|
||
|
|
<p> This function is provided for STL compatibility. It is equivalent
|
||
|
|
to <a href="#count">count</a>().
|
||
|
|
<p> <p>See also <a href="#empty">empty</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> <a name="values"></a>QMap::values () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns a list of all the values in the map, in key order.
|
||
|
|
|
||
|
|
<hr><h2>Related Functions</h2>
|
||
|
|
<h3 class=fn><a href="qdatastream.html">QDataStream</a> & <a name="operator-lt-lt"></a>operator<< ( <a href="qdatastream.html">QDataStream</a> & s, const <a href="qmap.html">QMap</a><Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<p> Writes the map <em>m</em> to the stream <em>s</em>. The types <em>Key</em> and <em>T</em>
|
||
|
|
must implement the streaming operator as well.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qdatastream.html">QDataStream</a> & <a name="operator-gt-gt"></a>operator>> ( <a href="qdatastream.html">QDataStream</a> & s, <a href="qmap.html">QMap</a><Key, T> & m )
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<p> Reads the map <em>m</em> from the stream <em>s</em>. The types <em>Key</em> and <em>T</em>
|
||
|
|
must implement the streaming operator as well.
|
||
|
|
|
||
|
|
<!-- eof -->
|
||
|
|
<hr><p>
|
||
|
|
This file is part of the <a href="index.html">Qt toolkit</a>.
|
||
|
|
Copyright © 1995-2007
|
||
|
|
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
||
|
|
<table width=100% cellspacing=0 border=0><tr>
|
||
|
|
<td>Copyright © 2007
|
||
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
||
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|