1QMap(3qt) QMap(3qt)
2
6 QMap - Value-based template class that provides a dictionary
7
9 #include <qmap.h>
10 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 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
68 The QMap class is a value-based template class that provides a
69 dictionary.
70 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 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 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 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 A copy constructor
91 An assignment operator
93 A default constructor, i.e. a constructor that does not take any
95 arguments.
96 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 The class used for the key requires that the operator< is implemented
102 to define ordering of the keys.
103 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 Example:
111 #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 Program output:
154 JD001: Doe, John earns 50000
156 JW002: Williams, Jane earns 80000
157 SH001: Hind, Sasha earns 50000
158 TJ001: Jones, Tom earns 60000
159 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 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 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 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 QMap<QString,QString> map;
186 map["Clinton"] = "Bill";
187 str << map["Clinton"] << map["Bush"] << endl;
188 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 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 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 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 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 There are a couple of ways of inserting new items into the map. One
215 uses the insert() method; the other uses operator[]:
216 QMap<QString, QString> map;
218 map["Clinton"] = "Bill";
219 map.insert( "Bush", "George" );
220 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 See also QMapIterator, Qt Template Library Classes, Implicitly and
227 Explicitly Shared Classes, and Non-GUI Classes.
228 Member Type Documentation
231 The map's const iterator type, Qt style.
232
234 The map's iterator type, Qt style.
235
237 Corresponds to QPair<key_type, mapped_type>, Qt style.
238
240 The map's const iterator type.
241
243 Const pointer to value_type.
244
246 Const reference to value_type.
247
249 The map's iterator type.
250
252 The map's key type.
253
255 The map's data type.
256
258 Pointer to value_type.
259
261 Reference to value_type.
262
264 An unsigned integral type, used to represent various sizes.
265
267 Corresponds to QPair<key_type, mapped_type>.
268
271 Constructs an empty map.
272
274 Constructs a copy of m.
275 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
282 Constructs a copy of m.
283
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
292 Returns an iterator pointing to the first element in the map. This
293 iterator equals end() if the map is empty.
294 The items in the map are traversed in the order defined by
296 operator<(Key, Key).
297 See also end() and QMapIterator.
299
301 This is an overloaded member function, provided for convenience. It
302 behaves essentially like the above function.
303 See also end() and QMapConstIterator.
305
307 Removes all items from the map.
308 See also remove().
310
312 Returns an iterator pointing to the first element in the map. This
313 iterator equals end() if the map is empty.
314 The items in the map are traversed in the order defined by
316 operator<(Key, Key).
317 See also constEnd() and QMapConstIterator.
319
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 This iterator equals constBegin() if the map is empty.
327 See also constBegin() and QMapConstIterator.
329
331 Returns TRUE if the map contains an item with key k; otherwise returns
332 FALSE.
333
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 This function is provided for STL compatibility.
339
341 This is an overloaded member function, provided for convenience. It
342 behaves essentially like the above function.
343 Returns the number of items in the map.
345 See also isEmpty().
347
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
355 Returns TRUE if the map contains no items; otherwise returns FALSE.
356 This function is provided for STL compatibility. It is equivalent to
358 isEmpty().
359 See also size().
361
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 This iterator equals begin() if the map is empty.
369 See also begin() and QMapIterator.
371
373 This is an overloaded member function, provided for convenience. It
374 behaves essentially like the above function.
375
377 Removes the item associated with the iterator it from the map.
378 This function is provided for STL compatibility. It is equivalent to
380 remove().
381 See also clear().
383
385 This is an overloaded member function, provided for convenience. It
386 behaves essentially like the above function.
387 Removes the item with the key k from the map.
389
391 Returns an iterator pointing to the element with key k in the map.
392 Returns end() if no key matched.
394 See also QMapIterator.
396
398 This is an overloaded member function, provided for convenience. It
399 behaves essentially like the above function.
400 Returns an iterator pointing to the element with key k in the map.
402 Returns end() if no key matched.
404 See also QMapConstIterator.
406
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
416 This is an overloaded member function, provided for convenience. It
417 behaves essentially like the above function.
418 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 See also replace().
427
429 Returns TRUE if the map contains no items; otherwise returns FALSE.
430 See also count().
432
434 Returns a list of all the keys in the map, in order.
435
437 Assigns m to this map and returns a reference to this map.
438 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
444 This is an overloaded member function, provided for convenience. It
445 behaves essentially like the above function.
446 Assigns m to this map and returns a reference to this map.
448 All iterators of the current map become invalidated by this operation.
450
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 You can use this operator both for reading and writing:
457 QMap<QString, QString> map;
459 map["Clinton"] = "Bill";
460 stream << map["Clinton"];
461
463 This is an overloaded member function, provided for convenience. It
464 behaves essentially like the above function.
465 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 Returns the value associated with the key k. If no such key is present,
472 a reference to an empty item is returned.
473
475 Removes the item associated with the iterator it from the map.
476 See also clear().
478
480 This is an overloaded member function, provided for convenience. It
481 behaves essentially like the above function.
482 Removes the item with the key k from the map.
484
486 Replaces the value of the element with key k, with the value v.
487 See also insert() and remove().
489
491 Returns the number of items in the map.
492 This function is provided for STL compatibility. It is equivalent to
494 count().
495 See also empty().
497
499 Returns a list of all the values in the map, in key order.
500
503 Writes the map m to the stream s. The types Key and T must implement
504 the streaming operator as well.
505
507 Reads the map m from the stream s. The types Key and T must implement
508 the streaming operator as well.
509
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
521 Generated automatically from the source code.
522
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 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 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).
537Trolltech AS 2 February 2007 QMap(3qt)