1QMap(3qt)                                                            QMap(3qt)
2
3
4

NAME

6       QMap - Value-based template class that provides a dictionary
7

SYNOPSIS

9       #include <qmap.h>
10
11   Public Members
12       typedef Key key_type
13       typedef T mapped_type
14       typedef QPair<const key_type, mapped_type> value_type
15       typedef value_type * pointer
16       typedef const value_type * const_pointer
17       typedef value_type & reference
18       typedef const value_type & const_reference
19       typedef size_t size_type
20       typedef QMapIterator<Key, T> iterator
21       typedef QMapConstIterator<Key, T> const_iterator
22       typedef QPair<iterator, bool> insert_pair
23       typedef QMapIterator<Key, T> Iterator
24       typedef QMapConstIterator<Key, T> ConstIterator
25       typedef T ValueType
26       QMap ()
27       QMap ( const QMap<Key, T> & m )
28       QMap ( const std::map<Key, T> & m )
29       ~QMap ()
30       QMap<Key, T> & operator= ( const QMap<Key, T> & m )
31       QMap<Key, T> & operator= ( const std::map<Key, T> & m )
32       iterator begin ()
33       iterator end ()
34       const_iterator begin () const
35       const_iterator end () const
36       const_iterator constBegin () const
37       const_iterator constEnd () const
38       iterator replace ( const Key & k, const T & v )
39       size_type size () const
40       bool empty () const
41       QPair<iterator, bool> insert ( const value_type & x )
42       void erase ( iterator it )
43       void erase ( const key_type & k )
44       size_type count ( const key_type & k ) const
45       T & operator[] ( const Key & k )
46       void clear ()
47       iterator find ( const Key & k )
48       const_iterator find ( const Key & k ) const
49       const T & operator[] ( const Key & k ) const
50       bool contains ( const Key & k ) const
51       size_type count () const
52       QValueList<Key> keys () const
53       QValueList<T> values () const
54       bool isEmpty () const
55       iterator insert ( const Key & key, const T & value, bool overwrite =
56           TRUE )
57       void remove ( iterator it )
58       void remove ( const Key & k )
59
60   Protected Members
61       void detach ()
62
64       QDataStream & operator>> ( QDataStream & s, QMap<Key, T> & m )
65       QDataStream & operator<< ( QDataStream & s, const QMap<Key, T> & m )
66

DESCRIPTION

68       The QMap class is a value-based template class that provides a
69       dictionary.
70
71       QMap is a Qt implementation of an STL-like map container. It can be
72       used in your application if the standard map is not available on all
73       your target platforms. QMap is part of the Qt Template Library.
74
75       QMap<Key, Data> defines a template instance to create a dictionary with
76       keys of type Key and values of type Data. QMap does not store pointers
77       to the members of the map; instead, it holds a copy of every member.
78       For this reason, QMap is value-based, whereas QPtrList and QDict are
79       pointer-based.
80
81       QMap contains and manages a collection of objects of type Data with
82       associated key values of type Key and provides iterators that allow the
83       contained objects to be addressed. QMap owns the contained items.
84
85       Some classes cannot be used within a QMap. For example everything
86       derived from QObject and thus all classes that implement widgets. Only
87       values can be used in a QMap. To qualify as a value, the class must
88       provide
89
90       A copy constructor
91
92       An assignment operator
93
94       A default constructor, i.e. a constructor that does not take any
95       arguments.
96
97       Note that C++ defaults to field-by-field assignment operators and copy
98       constructors if no explicit version is supplied. In many cases, this is
99       sufficient.
100
101       The class used for the key requires that the operator< is implemented
102       to define ordering of the keys.
103
104       QMap's function naming is consistent with the other Qt classes (e.g.,
105       count(), isEmpty()). QMap also provides extra functions for
106       compatibility with STL algorithms, such as size() and empty().
107       Programmers already familiar with the STL map can use these the STL-
108       like functions if preferred.
109
110       Example:
111
112           #include <qstring.h>
113           #include <qmap.h>
114           #include <qstring.h>
115           class Employee
116           {
117           public:
118               Employee(): sn(0) {}
119               Employee( const QString& forename, const QString& surname, int salary )
120                   : fn(forename), sn(surname), sal(salary)
121               { }
122               QString forename() const { return fn; }
123               QString surname() const { return sn; }
124               int salary() const { return sal; }
125               void setSalary( int salary ) { sal = salary; }
126           private:
127               QString fn;
128               QString sn;
129               int sal;
130           };
131           int main(int argc, char **argv)
132           {
133               QApplication app( argc, argv );
134               typedef QMap<QString, Employee> EmployeeMap;
135               EmployeeMap map;
136               map["JD001"] = Employee("John", "Doe", 50000);
137               map["JW002"] = Employee("Jane", "Williams", 80000);
138               map["TJ001"] = Employee("Tom", "Jones", 60000);
139               Employee sasha( "Sasha", "Hind", 50000 );
140               map["SH001"] = sasha;
141               sasha.setSalary( 40000 );
142               EmployeeMap::Iterator it;
143               for ( it = map.begin(); it != map.end(); ++it ) {
144                   printf( "%s: %s, %s earns %d\n",
145                           it.key().latin1(),
146                           it.data().surname().latin1(),
147                           it.data().forename().latin1(),
148                           it.data().salary() );
149               }
150               return 0;
151           }
152
153       Program output:
154
155           JD001: Doe, John earns 50000
156           JW002: Williams, Jane earns 80000
157           SH001: Hind, Sasha earns 50000
158           TJ001: Jones, Tom earns 60000
159
160       The latest changes to Sasha's salary did not affect the value in the
161       list because the map created a copy of Sasha's entry. In addition,
162       notice that the items are sorted alphabetically (by key) when iterating
163       over the map.
164
165       There are several ways to find items in a map. The begin() and end()
166       functions return iterators to the beginning and end of the map. The
167       advantage of using an iterator is that you can move forward or backward
168       by incrementing/decrementing the iterator. The iterator returned by
169       end() points to the element which is one past the last element in the
170       container. The past-the-end iterator is still associated with the map
171       it belongs to, however it is not dereferenceable; operator*() will not
172       return a well-defined value. If the map is empty, the iterator returned
173       by begin() will equal the iterator returned by end().
174
175       Another way to find an element in the map is by using the find()
176       function. This returns an iterator pointing to the desired item or to
177       the end() iterator if no such element exists.
178
179       Another approach uses the operator[]. But be warned: if the map does
180       not contain an entry for the element you are looking for, operator[]
181       inserts a default value. If you do not know that the element you are
182       searching for is really in the list, you should not use operator[]. The
183       following example illustrates this:
184
185               QMap<QString,QString> map;
186               map["Clinton"] = "Bill";
187               str << map["Clinton"] << map["Bush"] << endl;
188
189       The code fragment will print out "Clinton", "". Since the value
190       associated with the "Bush" key did not exist, the map inserted a
191       default value (in this case, an empty string). If you are not sure
192       whether a certain element is in the map, you should use find() and
193       iterators instead.
194
195       If you just want to know whether a certain key is contained in the map,
196       use the contains() function. In addition, count() tells you how many
197       keys are in the map.
198
199       It is safe to have multiple iterators at the same time. If some member
200       of the map is removed, only iterators pointing to the removed member
201       become invalid; inserting in the map does not invalidate any iterators.
202
203       Since QMap is value-based, there is no need to be concerned about
204       deleting items in the map. The map holds its own copies and will free
205       them if the corresponding member or the map itself is deleted.
206
207       QMap is implicitly shared. This means you can just make copies of the
208       map in time O(1). If multiple QMap instances share the same data and
209       one is modifying the map's data, this modifying instance makes a copy
210       and modifies its private copy: so it does not affect other instances.
211       If a QMap is being used in a multi-threaded program, you must protect
212       all access to the map. See QMutex.
213
214       There are a couple of ways of inserting new items into the map. One
215       uses the insert() method; the other uses operator[]:
216
217           QMap<QString, QString> map;
218           map["Clinton"] = "Bill";
219           map.insert( "Bush", "George" );
220
221       Items can also be removed from the map in several ways. One way is to
222       pass an iterator to remove(). Another way is to pass a key value to
223       remove(), which will delete the entry with the requested key. In
224       addition you can clear the entire map using the clear() method.
225
226       See also QMapIterator, Qt Template Library Classes, Implicitly and
227       Explicitly Shared Classes, and Non-GUI Classes.
228
229   Member Type Documentation

QMap::ConstIterator

231       The map's const iterator type, Qt style.
232

QMap::Iterator

234       The map's iterator type, Qt style.
235

QMap::ValueType

237       Corresponds to QPair<key_type, mapped_type>, Qt style.
238

QMap::const_iterator

240       The map's const iterator type.
241

QMap::const_pointer

243       Const pointer to value_type.
244

QMap::const_reference

246       Const reference to value_type.
247

QMap::iterator

249       The map's iterator type.
250

QMap::key_type

252       The map's key type.
253

QMap::mapped_type

255       The map's data type.
256

QMap::pointer

258       Pointer to value_type.
259

QMap::reference

261       Reference to value_type.
262

QMap::size_type

264       An unsigned integral type, used to represent various sizes.
265

QMap::value_type

267       Corresponds to QPair<key_type, mapped_type>.
268

MEMBER FUNCTION DOCUMENTATION

QMap::QMap ()

271       Constructs an empty map.
272

QMap::QMap ( const QMap<Key, T> & m )

274       Constructs a copy of m.
275
276       This operation costs O(1) time because QMap is implicitly shared. This
277       makes returning a QMap from a function very fast. If a shared instance
278       is modified, it will be copied (copy-on-write), and this takes O(n)
279       time.
280

QMap::QMap ( const std::map<Key, T> & m )

282       Constructs a copy of m.
283

QMap::~QMap ()

285       Destroys the map. References to the values in the map and all iterators
286       of this map become invalidated. Since QMap is highly tuned for
287       performance you won't see warnings if you use invalid iterators,
288       because it is not possible for an iterator to check whether it is valid
289       or not.
290

iterator QMap::begin ()

292       Returns an iterator pointing to the first element in the map. This
293       iterator equals end() if the map is empty.
294
295       The items in the map are traversed in the order defined by
296       operator<(Key, Key).
297
298       See also end() and QMapIterator.
299

const_iterator QMap::begin () const

301       This is an overloaded member function, provided for convenience. It
302       behaves essentially like the above function.
303
304       See also end() and QMapConstIterator.
305

void QMap::clear ()

307       Removes all items from the map.
308
309       See also remove().
310

const_iterator QMap::constBegin () const

312       Returns an iterator pointing to the first element in the map. This
313       iterator equals end() if the map is empty.
314
315       The items in the map are traversed in the order defined by
316       operator<(Key, Key).
317
318       See also constEnd() and QMapConstIterator.
319

const_iterator QMap::constEnd () const

321       The iterator returned by end() points to the element which is one past
322       the last element in the container. The past-the-end iterator is still
323       associated with the map it belongs to, but it is not dereferenceable;
324       operator*() will not return a well-defined value.
325
326       This iterator equals constBegin() if the map is empty.
327
328       See also constBegin() and QMapConstIterator.
329

bool QMap::contains ( const Key & k ) const

331       Returns TRUE if the map contains an item with key k; otherwise returns
332       FALSE.
333

size_type QMap::count ( const key_type & k ) const

335       Returns the number of items whose key is k. Since QMap does not allow
336       duplicate keys, the return value is always 0 or 1.
337
338       This function is provided for STL compatibility.
339

size_type QMap::count () const

341       This is an overloaded member function, provided for convenience. It
342       behaves essentially like the above function.
343
344       Returns the number of items in the map.
345
346       See also isEmpty().
347

void QMap::detach () [protected]

349       If the map does not share its data with another QMap instance, nothing
350       happens; otherwise the function creates a new copy of this map and
351       detaches from the shared one. This function is called whenever the map
352       is modified. The implicit sharing mechanism is implemented this way.
353

bool QMap::empty () const

355       Returns TRUE if the map contains no items; otherwise returns FALSE.
356
357       This function is provided for STL compatibility. It is equivalent to
358       isEmpty().
359
360       See also size().
361

iterator QMap::end ()

363       The iterator returned by end() points to the element which is one past
364       the last element in the container. The past-the-end iterator is still
365       associated with the map it belongs to, but it is not dereferenceable;
366       operator*() will not return a well-defined value.
367
368       This iterator equals begin() if the map is empty.
369
370       See also begin() and QMapIterator.
371

const_iterator QMap::end () const

373       This is an overloaded member function, provided for convenience. It
374       behaves essentially like the above function.
375

void QMap::erase ( iterator it )

377       Removes the item associated with the iterator it from the map.
378
379       This function is provided for STL compatibility. It is equivalent to
380       remove().
381
382       See also clear().
383

void QMap::erase ( const key_type & k )

385       This is an overloaded member function, provided for convenience. It
386       behaves essentially like the above function.
387
388       Removes the item with the key k from the map.
389

iterator QMap::find ( const Key & k )

391       Returns an iterator pointing to the element with key k in the map.
392
393       Returns end() if no key matched.
394
395       See also QMapIterator.
396

const_iterator QMap::find ( const Key & k ) const

398       This is an overloaded member function, provided for convenience. It
399       behaves essentially like the above function.
400
401       Returns an iterator pointing to the element with key k in the map.
402
403       Returns end() if no key matched.
404
405       See also QMapConstIterator.
406

iterator QMap::insert ( const Key & key, const T & value, bool overwrite =

408       TRUE )
409       Inserts a new item with the key, key, and a value of value. If there is
410       already an item whose key is key, that item's value is replaced with
411       value, unless overwrite is FALSE (it is TRUE by default). In this case
412       an iterator to this item is returned, else an iterator to the new item
413       is returned.
414

QPair<iterator, bool> QMap::insert ( const value_type & x )

416       This is an overloaded member function, provided for convenience. It
417       behaves essentially like the above function.
418
419       Inserts the (key, value) pair x into the map. x is a QPair whose first
420       element is a key to be inserted and whose second element is the
421       associated value to be inserted. Returns a pair whose first element is
422       an iterator pointing to the inserted item and whose second element is a
423       bool indicating TRUE if x was inserted and FALSE if it was not
424       inserted, e.g. because it was already present.
425
426       See also replace().
427

bool QMap::isEmpty () const

429       Returns TRUE if the map contains no items; otherwise returns FALSE.
430
431       See also count().
432

QValueList<Key> QMap::keys () const

434       Returns a list of all the keys in the map, in order.
435

QMap<Key, T> & QMap::operator= ( const QMap<Key, T> & m )

437       Assigns m to this map and returns a reference to this map.
438
439       All iterators of the current map become invalidated by this operation.
440       The cost of such an assignment is O(1), because QMap is implicitly
441       shared.
442

QMap<Key, T> & QMap::operator= ( const std::map<Key, T> & m )

444       This is an overloaded member function, provided for convenience. It
445       behaves essentially like the above function.
446
447       Assigns m to this map and returns a reference to this map.
448
449       All iterators of the current map become invalidated by this operation.
450

T & QMap::operator[] ( const Key & k )

452       Returns the value associated with the key k. If no such key is present,
453       an empty item is inserted with this key and a reference to the empty
454       item is returned.
455
456       You can use this operator both for reading and writing:
457
458           QMap<QString, QString> map;
459           map["Clinton"] = "Bill";
460           stream << map["Clinton"];
461

const T & QMap::operator[] ( const Key & k ) const

463       This is an overloaded member function, provided for convenience. It
464       behaves essentially like the above function.
465
466       Warning: This function differs from the non-const version of the same
467       function. It will not insert an empty value if the key k does not
468       exist. This may lead to logic errors in your program. You should check
469       if the element exists before calling this function.
470
471       Returns the value associated with the key k. If no such key is present,
472       a reference to an empty item is returned.
473

void QMap::remove ( iterator it )

475       Removes the item associated with the iterator it from the map.
476
477       See also clear().
478

void QMap::remove ( const Key & k )

480       This is an overloaded member function, provided for convenience. It
481       behaves essentially like the above function.
482
483       Removes the item with the key k from the map.
484

iterator QMap::replace ( const Key & k, const T & v )

486       Replaces the value of the element with key k, with the value v.
487
488       See also insert() and remove().
489

size_type QMap::size () const

491       Returns the number of items in the map.
492
493       This function is provided for STL compatibility. It is equivalent to
494       count().
495
496       See also empty().
497

QValueList<T> QMap::values () const

499       Returns a list of all the values in the map, in key order.
500

QDataStream & operator<< ( QDataStream & s, const QMap<Key, T> & m )

503       Writes the map m to the stream s. The types Key and T must implement
504       the streaming operator as well.
505

QDataStream & operator>> ( QDataStream & s, QMap<Key, T> & m )

507       Reads the map m from the stream s. The types Key and T must implement
508       the streaming operator as well.
509
510

SEE ALSO

512       http://doc.trolltech.com/qmap.html
513       http://www.trolltech.com/faq/tech.html
514
516       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
517       license file included in the distribution for a complete license
518       statement.
519

AUTHOR

521       Generated automatically from the source code.
522

BUGS

524       If you find a bug in Qt, please report it as described in
525       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
526       help you. Thank you.
527
528       The definitive Qt documentation is provided in HTML format; it is
529       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
530       web browser. This man page is provided as a convenience for those users
531       who prefer man pages, although this format is not officially supported
532       by Trolltech.
533
534       If you find errors in this manual page, please report them to qt-
535       bugs@trolltech.com.  Please include the name of the manual page
536       (qmap.3qt) and the Qt version (3.3.8).
537
538
539
540Trolltech AS                    2 February 2007                      QMap(3qt)
Impressum