source: trunk/src/corelib/tools/qhash.cpp@ 651

Last change on this file since 651 was 651, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.2 sources.

File size: 52.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "qhash.h"
43
44#ifdef truncate
45#undef truncate
46#endif
47
48#include <qbitarray.h>
49#include <qstring.h>
50#include <stdlib.h>
51#ifdef QT_QHASH_DEBUG
52#include <qstring.h>
53#endif
54
55QT_BEGIN_NAMESPACE
56
57/*
58 These functions are based on Peter J. Weinberger's hash function
59 (from the Dragon Book). The constant 24 in the original function
60 was replaced with 23 to produce fewer collisions on input such as
61 "a", "aa", "aaa", "aaaa", ...
62*/
63
64static uint hash(const uchar *p, int n)
65{
66 uint h = 0;
67 uint g;
68
69 while (n--) {
70 h = (h << 4) + *p++;
71 if ((g = (h & 0xf0000000)) != 0)
72 h ^= g >> 23;
73 h &= ~g;
74 }
75 return h;
76}
77
78static uint hash(const QChar *p, int n)
79{
80 uint h = 0;
81 uint g;
82
83 while (n--) {
84 h = (h << 4) + (*p++).unicode();
85 if ((g = (h & 0xf0000000)) != 0)
86 h ^= g >> 23;
87 h &= ~g;
88 }
89 return h;
90}
91
92uint qHash(const QByteArray &key)
93{
94 return hash(reinterpret_cast<const uchar *>(key.constData()), key.size());
95}
96
97uint qHash(const QString &key)
98{
99 return hash(key.unicode(), key.size());
100}
101
102uint qHash(const QStringRef &key)
103{
104 return hash(key.unicode(), key.size());
105}
106
107uint qHash(const QBitArray &bitArray)
108{
109 int m = bitArray.d.size() - 1;
110 uint result = hash(reinterpret_cast<const uchar *>(bitArray.d.constData()), qMax(0, m));
111
112 // deal with the last 0 to 7 bits manually, because we can't trust that
113 // the padding is initialized to 0 in bitArray.d
114 int n = bitArray.size();
115 if (n & 0x7)
116 result = ((result << 4) + bitArray.d.at(m)) & ((1 << n) - 1);
117 return result;
118}
119
120/*
121 The prime_deltas array is a table of selected prime values, even
122 though it doesn't look like one. The primes we are using are 1,
123 2, 5, 11, 17, 37, 67, 131, 257, ..., i.e. primes in the immediate
124 surrounding of a power of two.
125
126 The primeForNumBits() function returns the prime associated to a
127 power of two. For example, primeForNumBits(8) returns 257.
128*/
129
130static const uchar prime_deltas[] = {
131 0, 0, 1, 3, 1, 5, 3, 3, 1, 9, 7, 5, 3, 9, 25, 3,
132 1, 21, 3, 21, 7, 15, 9, 5, 3, 29, 15, 0, 0, 0, 0, 0
133};
134
135static inline int primeForNumBits(int numBits)
136{
137 return (1 << numBits) + prime_deltas[numBits];
138}
139
140/*
141 Returns the smallest integer n such that
142 primeForNumBits(n) >= hint.
143*/
144static int countBits(int hint)
145{
146 int numBits = 0;
147 int bits = hint;
148
149 while (bits > 1) {
150 bits >>= 1;
151 numBits++;
152 }
153
154 if (numBits >= (int)sizeof(prime_deltas)) {
155 numBits = sizeof(prime_deltas) - 1;
156 } else if (primeForNumBits(numBits) < hint) {
157 ++numBits;
158 }
159 return numBits;
160}
161
162/*
163 A QHash has initially around pow(2, MinNumBits) buckets. For
164 example, if MinNumBits is 4, it has 17 buckets.
165*/
166const int MinNumBits = 4;
167
168QHashData QHashData::shared_null = {
169 0, 0, Q_BASIC_ATOMIC_INITIALIZER(1), 0, 0, MinNumBits, 0, 0, true, false, 0
170};
171
172void *QHashData::allocateNode()
173{
174 return allocateNode(0);
175}
176
177void *QHashData::allocateNode(int nodeAlign)
178{
179 void *ptr = strictAlignment ? qMallocAligned(nodeSize, nodeAlign) : qMalloc(nodeSize);
180 Q_CHECK_PTR(ptr);
181 return ptr;
182}
183
184void QHashData::freeNode(void *node)
185{
186 if (strictAlignment)
187 qFreeAligned(node);
188 else
189 qFree(node);
190}
191
192QHashData *QHashData::detach_helper(void (*node_duplicate)(Node *, void *), int nodeSize)
193{
194 return detach_helper2( node_duplicate, 0, nodeSize, 0 );
195}
196
197QHashData *QHashData::detach_helper2(void (*node_duplicate)(Node *, void *),
198 void (*node_delete)(Node *),
199 int nodeSize,
200 int nodeAlign)
201{
202 union {
203 QHashData *d;
204 Node *e;
205 };
206 d = new QHashData;
207 d->fakeNext = 0;
208 d->buckets = 0;
209 d->ref = 1;
210 d->size = size;
211 d->nodeSize = nodeSize;
212 d->userNumBits = userNumBits;
213 d->numBits = numBits;
214 d->numBuckets = numBuckets;
215 d->sharable = true;
216 d->strictAlignment = nodeAlign > 8;
217 d->reserved = 0;
218
219 if (numBuckets) {
220 QT_TRY {
221 d->buckets = new Node *[numBuckets];
222 } QT_CATCH(...) {
223 // restore a consistent state for d
224 d->numBuckets = 0;
225 // roll back
226 d->free_helper(node_delete);
227 QT_RETHROW;
228 }
229
230 Node *this_e = reinterpret_cast<Node *>(this);
231 for (int i = 0; i < numBuckets; ++i) {
232 Node **nextNode = &d->buckets[i];
233 Node *oldNode = buckets[i];
234 while (oldNode != this_e) {
235 QT_TRY {
236 Node *dup = static_cast<Node *>(allocateNode(nodeAlign));
237
238 QT_TRY {
239 node_duplicate(oldNode, dup);
240 } QT_CATCH(...) {
241 freeNode( dup );
242 QT_RETHROW;
243 }
244
245 dup->h = oldNode->h;
246 *nextNode = dup;
247 nextNode = &dup->next;
248 oldNode = oldNode->next;
249 } QT_CATCH(...) {
250 // restore a consistent state for d
251 *nextNode = e;
252 d->numBuckets = i+1;
253 // roll back
254 d->free_helper(node_delete);
255 QT_RETHROW;
256 }
257 }
258 *nextNode = e;
259 }
260 }
261 return d;
262}
263
264void QHashData::free_helper(void (*node_delete)(Node *))
265{
266 if (node_delete) {
267 Node *this_e = reinterpret_cast<Node *>(this);
268 Node **bucket = reinterpret_cast<Node **>(this->buckets);
269
270 int n = numBuckets;
271 while (n--) {
272 Node *cur = *bucket++;
273 while (cur != this_e) {
274 Node *next = cur->next;
275 node_delete(cur);
276 freeNode(cur);
277 cur = next;
278 }
279 }
280 }
281 delete [] buckets;
282 delete this;
283}
284
285QHashData::Node *QHashData::nextNode(Node *node)
286{
287 union {
288 Node *next;
289 Node *e;
290 QHashData *d;
291 };
292 next = node->next;
293 Q_ASSERT_X(next, "QHash", "Iterating beyond end()");
294 if (next->next)
295 return next;
296
297 int start = (node->h % d->numBuckets) + 1;
298 Node **bucket = d->buckets + start;
299 int n = d->numBuckets - start;
300 while (n--) {
301 if (*bucket != e)
302 return *bucket;
303 ++bucket;
304 }
305 return e;
306}
307
308QHashData::Node *QHashData::previousNode(Node *node)
309{
310 union {
311 Node *e;
312 QHashData *d;
313 };
314
315 e = node;
316 while (e->next)
317 e = e->next;
318
319 int start;
320 if (node == e)
321 start = d->numBuckets - 1;
322 else
323 start = node->h % d->numBuckets;
324
325 Node *sentinel = node;
326 Node **bucket = d->buckets + start;
327 while (start >= 0) {
328 if (*bucket != sentinel) {
329 Node *prev = *bucket;
330 while (prev->next != sentinel)
331 prev = prev->next;
332 return prev;
333 }
334
335 sentinel = e;
336 --bucket;
337 --start;
338 }
339 Q_ASSERT_X(start >= 0, "QHash", "Iterating backward beyond begin()");
340 return e;
341}
342
343/*
344 If hint is negative, -hint gives the approximate number of
345 buckets that should be used for the hash table. If hint is
346 nonnegative, (1 << hint) gives the approximate number
347 of buckets that should be used.
348*/
349void QHashData::rehash(int hint)
350{
351 if (hint < 0) {
352 hint = countBits(-hint);
353 if (hint < MinNumBits)
354 hint = MinNumBits;
355 userNumBits = hint;
356 while (primeForNumBits(hint) < (size >> 1))
357 ++hint;
358 } else if (hint < MinNumBits) {
359 hint = MinNumBits;
360 }
361
362 if (numBits != hint) {
363 Node *e = reinterpret_cast<Node *>(this);
364 Node **oldBuckets = buckets;
365 int oldNumBuckets = numBuckets;
366
367 int nb = primeForNumBits(hint);
368 buckets = new Node *[nb];
369 numBits = hint;
370 numBuckets = nb;
371 for (int i = 0; i < numBuckets; ++i)
372 buckets[i] = e;
373
374 for (int i = 0; i < oldNumBuckets; ++i) {
375 Node *firstNode = oldBuckets[i];
376 while (firstNode != e) {
377 uint h = firstNode->h;
378 Node *lastNode = firstNode;
379 while (lastNode->next != e && lastNode->next->h == h)
380 lastNode = lastNode->next;
381
382 Node *afterLastNode = lastNode->next;
383 Node **beforeFirstNode = &buckets[h % numBuckets];
384 while (*beforeFirstNode != e)
385 beforeFirstNode = &(*beforeFirstNode)->next;
386 lastNode->next = *beforeFirstNode;
387 *beforeFirstNode = firstNode;
388 firstNode = afterLastNode;
389 }
390 }
391 delete [] oldBuckets;
392 }
393}
394
395void QHashData::destroyAndFree()
396{
397 free_helper(0);
398}
399
400#ifdef QT_QHASH_DEBUG
401
402void QHashData::dump()
403{
404 qDebug("Hash data (ref = %d, size = %d, nodeSize = %d, userNumBits = %d, numBits = %d, numBuckets = %d)",
405 int(ref), size, nodeSize, userNumBits, numBits,
406 numBuckets);
407 qDebug(" %p (fakeNode = %p)", this, fakeNext);
408 for (int i = 0; i < numBuckets; ++i) {
409 QString line;
410 Node *n = buckets[i];
411 if (n != reinterpret_cast<Node *>(this)) {
412 line.sprintf("%d:", i);
413 while (n != reinterpret_cast<Node *>(this)) {
414 line += QString().sprintf(" -> [%p]", n);
415 if (!n) {
416 line += " (CORRUPT)";
417 break;
418 }
419 n = n->next;
420 }
421 qDebug(qPrintable(line));
422 }
423 }
424}
425
426void QHashData::checkSanity()
427{
428 if (fakeNext)
429 qFatal("Fake next isn't 0");
430
431 for (int i = 0; i < numBuckets; ++i) {
432 Node *n = buckets[i];
433 Node *p = n;
434 if (!n)
435 qFatal("%d: Bucket entry is 0", i);
436 if (n != reinterpret_cast<Node *>(this)) {
437 while (n != reinterpret_cast<Node *>(this)) {
438 if (!n->next)
439 qFatal("%d: Next of %p is 0, should be %p", i, n, this);
440 n = n->next;
441 }
442 }
443 }
444}
445#endif
446
447/*!
448 \fn uint qHash(const QPair<T1, T2> &key)
449 \since 4.3
450 \relates QHash
451
452 Returns the hash value for the \a key.
453
454 Types \c T1 and \c T2 must be supported by qHash().
455*/
456
457/*! \fn uint qHash(char key)
458 \relates QHash
459
460 Returns the hash value for the \a key.
461*/
462
463/*! \fn uint qHash(uchar key)
464 \relates QHash
465
466 Returns the hash value for the \a key.
467*/
468
469/*! \fn uint qHash(signed char key)
470 \relates QHash
471
472 Returns the hash value for the \a key.
473*/
474
475/*! \fn uint qHash(ushort key)
476 \relates QHash
477
478 Returns the hash value for the \a key.
479*/
480
481/*! \fn uint qHash(short key)
482 \relates QHash
483
484 Returns the hash value for the \a key.
485*/
486
487/*! \fn uint qHash(uint key)
488 \relates QHash
489
490 Returns the hash value for the \a key.
491*/
492
493/*! \fn uint qHash(int key)
494 \relates QHash
495
496 Returns the hash value for the \a key.
497*/
498
499/*! \fn uint qHash(ulong key)
500 \relates QHash
501
502 Returns the hash value for the \a key.
503*/
504
505/*! \fn uint qHash(long key)
506 \relates QHash
507
508 Returns the hash value for the \a key.
509*/
510
511/*! \fn uint qHash(quint64 key)
512 \relates QHash
513
514 Returns the hash value for the \a key.
515*/
516
517/*! \fn uint qHash(qint64 key)
518 \relates QHash
519
520 Returns the hash value for the \a key.
521*/
522
523/*! \fn uint qHash(QChar key)
524 \relates QHash
525
526 Returns the hash value for the \a key.
527*/
528
529/*! \fn uint qHash(const QByteArray &key)
530 \fn uint qHash(const QBitArray &key)
531 \relates QHash
532
533 Returns the hash value for the \a key.
534*/
535
536/*! \fn uint qHash(const QString &key)
537 \relates QHash
538
539 Returns the hash value for the \a key.
540*/
541
542/*! \fn uint qHash(const T *key)
543 \relates QHash
544
545 Returns the hash value for the \a key.
546*/
547
548/*!
549 \class QHash
550 \brief The QHash class is a template class that provides a hash-table-based dictionary.
551
552 \ingroup tools
553 \ingroup shared
554
555 \reentrant
556
557 QHash\<Key, T\> is one of Qt's generic \l{container classes}. It
558 stores (key, value) pairs and provides very fast lookup of the
559 value associated with a key.
560
561 QHash provides very similar functionality to QMap. The
562 differences are:
563
564 \list
565 \i QHash provides faster lookups than QMap. (See \l{Algorithmic
566 Complexity} for details.)
567 \i When iterating over a QMap, the items are always sorted by
568 key. With QHash, the items are arbitrarily ordered.
569 \i The key type of a QMap must provide operator<(). The key
570 type of a QHash must provide operator==() and a global
571 hash function called qHash() (see the related non-member
572 functions).
573 \endlist
574
575 Here's an example QHash with QString keys and \c int values:
576 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 0
577
578 To insert a (key, value) pair into the hash, you can use operator[]():
579
580 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 1
581
582 This inserts the following three (key, value) pairs into the
583 QHash: ("one", 1), ("three", 3), and ("seven", 7). Another way to
584 insert items into the hash is to use insert():
585
586 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 2
587
588 To look up a value, use operator[]() or value():
589
590 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 3
591
592 If there is no item with the specified key in the hash, these
593 functions return a \l{default-constructed value}.
594
595 If you want to check whether the hash contains a particular key,
596 use contains():
597
598 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 4
599
600 There is also a value() overload that uses its second argument as
601 a default value if there is no item with the specified key:
602
603 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 5
604
605 In general, we recommend that you use contains() and value()
606 rather than operator[]() for looking up a key in a hash. The
607 reason is that operator[]() silently inserts an item into the
608 hash if no item exists with the same key (unless the hash is
609 const). For example, the following code snippet will create 1000
610 items in memory:
611
612 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 6
613
614 To avoid this problem, replace \c hash[i] with \c hash.value(i)
615 in the code above.
616
617 If you want to navigate through all the (key, value) pairs stored
618 in a QHash, you can use an iterator. QHash provides both
619 \l{Java-style iterators} (QHashIterator and QMutableHashIterator)
620 and \l{STL-style iterators} (QHash::const_iterator and
621 QHash::iterator). Here's how to iterate over a QHash<QString,
622 int> using a Java-style iterator:
623
624 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 7
625
626 Here's the same code, but using an STL-style iterator:
627
628 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 8
629
630 QHash is unordered, so an iterator's sequence cannot be assumed
631 to be predictable. If ordering by key is required, use a QMap.
632
633 Normally, a QHash allows only one value per key. If you call
634 insert() with a key that already exists in the QHash, the
635 previous value is erased. For example:
636
637 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 9
638
639 However, you can store multiple values per key by using
640 insertMulti() instead of insert() (or using the convenience
641 subclass QMultiHash). If you want to retrieve all
642 the values for a single key, you can use values(const Key &key),
643 which returns a QList<T>:
644
645 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 10
646
647 The items that share the same key are available from most
648 recently to least recently inserted. A more efficient approach is
649 to call find() to get the iterator for the first item with a key
650 and iterate from there:
651
652 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 11
653
654 If you only need to extract the values from a hash (not the keys),
655 you can also use \l{foreach}:
656
657 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 12
658
659 Items can be removed from the hash in several ways. One way is to
660 call remove(); this will remove any item with the given key.
661 Another way is to use QMutableHashIterator::remove(). In addition,
662 you can clear the entire hash using clear().
663
664 QHash's key and value data types must be \l{assignable data
665 types}. You cannot, for example, store a QWidget as a value;
666 instead, store a QWidget *. In addition, QHash's key type must
667 provide operator==(), and there must also be a global qHash()
668 function that returns a hash value for an argument of the key's
669 type.
670
671 Here's a list of the C++ and Qt types that can serve as keys in a
672 QHash: any integer type (char, unsigned long, etc.), any pointer
673 type, QChar, QString, and QByteArray. For all of these, the \c
674 <QHash> header defines a qHash() function that computes an
675 adequate hash value. If you want to use other types as the key,
676 make sure that you provide operator==() and a qHash()
677 implementation.
678
679 Example:
680 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 13
681
682 The qHash() function computes a numeric value based on a key. It
683 can use any algorithm imaginable, as long as it always returns
684 the same value if given the same argument. In other words, if
685 \c{e1 == e2}, then \c{qHash(e1) == qHash(e2)} must hold as well.
686 However, to obtain good performance, the qHash() function should
687 attempt to return different hash values for different keys to the
688 largest extent possible.
689
690 In the example above, we've relied on Qt's global qHash(const
691 QString &) to give us a hash value for the employee's name, and
692 XOR'ed this with the day they were born to help produce unique
693 hashes for people with the same name.
694
695 Internally, QHash uses a hash table to perform lookups. Unlike Qt
696 3's \c QDict class, which needed to be initialized with a prime
697 number, QHash's hash table automatically grows and shrinks to
698 provide fast lookups without wasting too much memory. You can
699 still control the size of the hash table by calling reserve() if
700 you already know approximately how many items the QHash will
701 contain, but this isn't necessary to obtain good performance. You
702 can also call capacity() to retrieve the hash table's size.
703
704 \sa QHashIterator, QMutableHashIterator, QMap, QSet
705*/
706
707/*! \fn QHash::QHash()
708
709 Constructs an empty hash.
710
711 \sa clear()
712*/
713
714/*! \fn QHash::QHash(const QHash<Key, T> &other)
715
716 Constructs a copy of \a other.
717
718 This operation occurs in \l{constant time}, because QHash is
719 \l{implicitly shared}. This makes returning a QHash from a
720 function very fast. If a shared instance is modified, it will be
721 copied (copy-on-write), and this takes \l{linear time}.
722
723 \sa operator=()
724*/
725
726/*! \fn QHash::~QHash()
727
728 Destroys the hash. References to the values in the hash and all
729 iterators of this hash become invalid.
730*/
731
732/*! \fn QHash<Key, T> &QHash::operator=(const QHash<Key, T> &other)
733
734 Assigns \a other to this hash and returns a reference to this hash.
735*/
736
737/*! \fn bool QHash::operator==(const QHash<Key, T> &other) const
738
739 Returns true if \a other is equal to this hash; otherwise returns
740 false.
741
742 Two hashes are considered equal if they contain the same (key,
743 value) pairs.
744
745 This function requires the value type to implement \c operator==().
746
747 \sa operator!=()
748*/
749
750/*! \fn bool QHash::operator!=(const QHash<Key, T> &other) const
751
752 Returns true if \a other is not equal to this hash; otherwise
753 returns false.
754
755 Two hashes are considered equal if they contain the same (key,
756 value) pairs.
757
758 This function requires the value type to implement \c operator==().
759
760 \sa operator==()
761*/
762
763/*! \fn int QHash::size() const
764
765 Returns the number of items in the hash.
766
767 \sa isEmpty(), count()
768*/
769
770/*! \fn bool QHash::isEmpty() const
771
772 Returns true if the hash contains no items; otherwise returns
773 false.
774
775 \sa size()
776*/
777
778/*! \fn int QHash::capacity() const
779
780 Returns the number of buckets in the QHash's internal hash table.
781
782 The sole purpose of this function is to provide a means of fine
783 tuning QHash's memory usage. In general, you will rarely ever
784 need to call this function. If you want to know how many items are
785 in the hash, call size().
786
787 \sa reserve(), squeeze()
788*/
789
790/*! \fn void QHash::reserve(int size)
791
792 Ensures that the QHash's internal hash table consists of at least
793 \a size buckets.
794
795 This function is useful for code that needs to build a huge hash
796 and wants to avoid repeated reallocation. For example:
797
798 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 14
799
800 Ideally, \a size should be slightly more than the maximum number
801 of items expected in the hash. \a size doesn't have to be prime,
802 because QHash will use a prime number internally anyway. If \a size
803 is an underestimate, the worst that will happen is that the QHash
804 will be a bit slower.
805
806 In general, you will rarely ever need to call this function.
807 QHash's internal hash table automatically shrinks or grows to
808 provide good performance without wasting too much memory.
809
810 \sa squeeze(), capacity()
811*/
812
813/*! \fn void QHash::squeeze()
814
815 Reduces the size of the QHash's internal hash table to save
816 memory.
817
818 The sole purpose of this function is to provide a means of fine
819 tuning QHash's memory usage. In general, you will rarely ever
820 need to call this function.
821
822 \sa reserve(), capacity()
823*/
824
825/*! \fn void QHash::detach()
826
827 \internal
828
829 Detaches this hash from any other hashes with which it may share
830 data.
831
832 \sa isDetached()
833*/
834
835/*! \fn bool QHash::isDetached() const
836
837 \internal
838
839 Returns true if the hash's internal data isn't shared with any
840 other hash object; otherwise returns false.
841
842 \sa detach()
843*/
844
845/*! \fn void QHash::setSharable(bool sharable)
846
847 \internal
848*/
849
850/*! \fn void QHash::clear()
851
852 Removes all items from the hash.
853
854 \sa remove()
855*/
856
857/*! \fn int QHash::remove(const Key &key)
858
859 Removes all the items that have the \a key from the hash.
860 Returns the number of items removed which is usually 1 but will
861 be 0 if the key isn't in the hash, or greater than 1 if
862 insertMulti() has been used with the \a key.
863
864 \sa clear(), take(), QMultiHash::remove()
865*/
866
867/*! \fn T QHash::take(const Key &key)
868
869 Removes the item with the \a key from the hash and returns
870 the value associated with it.
871
872 If the item does not exist in the hash, the function simply
873 returns a \l{default-constructed value}. If there are multiple
874 items for \a key in the hash, only the most recently inserted one
875 is removed.
876
877 If you don't use the return value, remove() is more efficient.
878
879 \sa remove()
880*/
881
882/*! \fn bool QHash::contains(const Key &key) const
883
884 Returns true if the hash contains an item with the \a key;
885 otherwise returns false.
886
887 \sa count(), QMultiHash::contains()
888*/
889
890/*! \fn const T QHash::value(const Key &key) const
891
892 Returns the value associated with the \a key.
893
894 If the hash contains no item with the \a key, the function
895 returns a \l{default-constructed value}. If there are multiple
896 items for the \a key in the hash, the value of the most recently
897 inserted one is returned.
898
899 \sa key(), values(), contains(), operator[]()
900*/
901
902/*! \fn const T QHash::value(const Key &key, const T &defaultValue) const
903 \overload
904
905 If the hash contains no item with the given \a key, the function returns
906 \a defaultValue.
907*/
908
909/*! \fn T &QHash::operator[](const Key &key)
910
911 Returns the value associated with the \a key as a modifiable
912 reference.
913
914 If the hash contains no item with the \a key, the function inserts
915 a \l{default-constructed value} into the hash with the \a key, and
916 returns a reference to it. If the hash contains multiple items
917 with the \a key, this function returns a reference to the most
918 recently inserted value.
919
920 \sa insert(), value()
921*/
922
923/*! \fn const T QHash::operator[](const Key &key) const
924
925 \overload
926
927 Same as value().
928*/
929
930/*! \fn QList<Key> QHash::uniqueKeys() const
931 \since 4.2
932
933 Returns a list containing all the keys in the map. Keys that occur multiple
934 times in the map (because items were inserted with insertMulti(), or
935 unite() was used) occur only once in the returned list.
936
937 \sa keys(), values()
938*/
939
940/*! \fn QList<Key> QHash::keys() const
941
942 Returns a list containing all the keys in the hash, in an
943 arbitrary order. Keys that occur multiple times in the hash
944 (because items were inserted with insertMulti(), or unite() was
945 used) also occur multiple times in the list.
946
947 To obtain a list of unique keys, where each key from the map only
948 occurs once, use uniqueKeys().
949
950 The order is guaranteed to be the same as that used by values().
951
952 \sa uniqueKeys(), values(), key()
953*/
954
955/*! \fn QList<Key> QHash::keys(const T &value) const
956
957 \overload
958
959 Returns a list containing all the keys associated with value \a
960 value, in an arbitrary order.
961
962 This function can be slow (\l{linear time}), because QHash's
963 internal data structure is optimized for fast lookup by key, not
964 by value.
965*/
966
967/*! \fn QList<T> QHash::values() const
968
969 Returns a list containing all the values in the hash, in an
970 arbitrary order. If a key is associated multiple values, all of
971 its values will be in the list, and not just the most recently
972 inserted one.
973
974 The order is guaranteed to be the same as that used by keys().
975
976 \sa keys(), value()
977*/
978
979/*! \fn QList<T> QHash::values(const Key &key) const
980
981 \overload
982
983 Returns a list of all the values associated with the \a key,
984 from the most recently inserted to the least recently inserted.
985
986 \sa count(), insertMulti()
987*/
988
989/*! \fn Key QHash::key(const T &value) const
990
991 Returns the first key mapped to \a value.
992
993 If the hash contains no item with the \a value, the function
994 returns a \link {default-constructed value} default-constructed
995 key \endlink.
996
997 This function can be slow (\l{linear time}), because QHash's
998 internal data structure is optimized for fast lookup by key, not
999 by value.
1000
1001 \sa value(), keys()
1002*/
1003
1004/*!
1005 \fn Key QHash::key(const T &value, const Key &defaultKey) const
1006 \since 4.3
1007 \overload
1008
1009 Returns the first key mapped to \a value, or \a defaultKey if the
1010 hash contains no item mapped to \a value.
1011
1012 This function can be slow (\l{linear time}), because QHash's
1013 internal data structure is optimized for fast lookup by key, not
1014 by value.
1015*/
1016
1017/*! \fn int QHash::count(const Key &key) const
1018
1019 Returns the number of items associated with the \a key.
1020
1021 \sa contains(), insertMulti()
1022*/
1023
1024/*! \fn int QHash::count() const
1025
1026 \overload
1027
1028 Same as size().
1029*/
1030
1031/*! \fn QHash::iterator QHash::begin()
1032
1033 Returns an \l{STL-style iterator} pointing to the first item in
1034 the hash.
1035
1036 \sa constBegin(), end()
1037*/
1038
1039/*! \fn QHash::const_iterator QHash::begin() const
1040
1041 \overload
1042*/
1043
1044/*! \fn QHash::const_iterator QHash::constBegin() const
1045
1046 Returns a const \l{STL-style iterator} pointing to the first item
1047 in the hash.
1048
1049 \sa begin(), constEnd()
1050*/
1051
1052/*! \fn QHash::iterator QHash::end()
1053
1054 Returns an \l{STL-style iterator} pointing to the imaginary item
1055 after the last item in the hash.
1056
1057 \sa begin(), constEnd()
1058*/
1059
1060/*! \fn QHash::const_iterator QHash::end() const
1061
1062 \overload
1063*/
1064
1065/*! \fn QHash::const_iterator QHash::constEnd() const
1066
1067 Returns a const \l{STL-style iterator} pointing to the imaginary
1068 item after the last item in the hash.
1069
1070 \sa constBegin(), end()
1071*/
1072
1073/*! \fn QHash::iterator QHash::erase(iterator pos)
1074
1075 Removes the (key, value) pair associated with the iterator \a pos
1076 from the hash, and returns an iterator to the next item in the
1077 hash.
1078
1079 Unlike remove() and take(), this function never causes QHash to
1080 rehash its internal data structure. This means that it can safely
1081 be called while iterating, and won't affect the order of items in
1082 the hash. For example:
1083
1084 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 15
1085
1086 \sa remove(), take(), find()
1087*/
1088
1089/*! \fn QHash::iterator QHash::find(const Key &key)
1090
1091 Returns an iterator pointing to the item with the \a key in the
1092 hash.
1093
1094 If the hash contains no item with the \a key, the function
1095 returns end().
1096
1097 If the hash contains multiple items with the \a key, this
1098 function returns an iterator that points to the most recently
1099 inserted value. The other values are accessible by incrementing
1100 the iterator. For example, here's some code that iterates over all
1101 the items with the same key:
1102
1103 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 16
1104
1105 \sa value(), values(), QMultiHash::find()
1106*/
1107
1108/*! \fn QHash::const_iterator QHash::find(const Key &key) const
1109
1110 \overload
1111*/
1112
1113/*! \fn QHash::iterator QHash::constFind(const Key &key) const
1114 \since 4.1
1115
1116 Returns an iterator pointing to the item with the \a key in the
1117 hash.
1118
1119 If the hash contains no item with the \a key, the function
1120 returns constEnd().
1121
1122 \sa find(), QMultiHash::constFind()
1123*/
1124
1125/*! \fn QHash::iterator QHash::insert(const Key &key, const T &value)
1126
1127 Inserts a new item with the \a key and a value of \a value.
1128
1129 If there is already an item with the \a key, that item's value
1130 is replaced with \a value.
1131
1132 If there are multiple items with the \a key, the most
1133 recently inserted item's value is replaced with \a value.
1134
1135 \sa insertMulti()
1136*/
1137
1138/*! \fn QHash::iterator QHash::insertMulti(const Key &key, const T &value)
1139
1140 Inserts a new item with the \a key and a value of \a value.
1141
1142 If there is already an item with the same key in the hash, this
1143 function will simply create a new one. (This behavior is
1144 different from insert(), which overwrites the value of an
1145 existing item.)
1146
1147 \sa insert(), values()
1148*/
1149
1150/*! \fn QHash<Key, T> &QHash::unite(const QHash<Key, T> &other)
1151
1152 Inserts all the items in the \a other hash into this hash. If a
1153 key is common to both hashes, the resulting hash will contain the
1154 key multiple times.
1155
1156 \sa insertMulti()
1157*/
1158
1159/*! \fn bool QHash::empty() const
1160
1161 This function is provided for STL compatibility. It is equivalent
1162 to isEmpty(), returning true if the hash is empty; otherwise
1163 returns false.
1164*/
1165
1166/*! \typedef QHash::ConstIterator
1167
1168 Qt-style synonym for QHash::const_iterator.
1169*/
1170
1171/*! \typedef QHash::Iterator
1172
1173 Qt-style synonym for QHash::iterator.
1174*/
1175
1176/*! \typedef QHash::difference_type
1177
1178 Typedef for ptrdiff_t. Provided for STL compatibility.
1179*/
1180
1181/*! \typedef QHash::key_type
1182
1183 Typedef for Key. Provided for STL compatibility.
1184*/
1185
1186/*! \typedef QHash::mapped_type
1187
1188 Typedef for T. Provided for STL compatibility.
1189*/
1190
1191/*! \typedef QHash::size_type
1192
1193 Typedef for int. Provided for STL compatibility.
1194*/
1195
1196/*! \typedef QHash::iterator::difference_type
1197 \internal
1198*/
1199
1200/*! \typedef QHash::iterator::iterator_category
1201 \internal
1202*/
1203
1204/*! \typedef QHash::iterator::pointer
1205 \internal
1206*/
1207
1208/*! \typedef QHash::iterator::reference
1209 \internal
1210*/
1211
1212/*! \typedef QHash::iterator::value_type
1213 \internal
1214*/
1215
1216/*! \typedef QHash::const_iterator::difference_type
1217 \internal
1218*/
1219
1220/*! \typedef QHash::const_iterator::iterator_category
1221 \internal
1222*/
1223
1224/*! \typedef QHash::const_iterator::pointer
1225 \internal
1226*/
1227
1228/*! \typedef QHash::const_iterator::reference
1229 \internal
1230*/
1231
1232/*! \typedef QHash::const_iterator::value_type
1233 \internal
1234*/
1235
1236/*! \class QHash::iterator
1237 \brief The QHash::iterator class provides an STL-style non-const iterator for QHash and QMultiHash.
1238
1239 QHash features both \l{STL-style iterators} and \l{Java-style
1240 iterators}. The STL-style iterators are more low-level and more
1241 cumbersome to use; on the other hand, they are slightly faster
1242 and, for developers who already know STL, have the advantage of
1243 familiarity.
1244
1245 QHash\<Key, T\>::iterator allows you to iterate over a QHash (or
1246 QMultiHash) and to modify the value (but not the key) associated
1247 with a particular key. If you want to iterate over a const QHash,
1248 you should use QHash::const_iterator. It is generally good
1249 practice to use QHash::const_iterator on a non-const QHash as
1250 well, unless you need to change the QHash through the iterator.
1251 Const iterators are slightly faster, and can improve code
1252 readability.
1253
1254 The default QHash::iterator constructor creates an uninitialized
1255 iterator. You must initialize it using a QHash function like
1256 QHash::begin(), QHash::end(), or QHash::find() before you can
1257 start iterating. Here's a typical loop that prints all the (key,
1258 value) pairs stored in a hash:
1259
1260 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 17
1261
1262 Unlike QMap, which orders its items by key, QHash stores its
1263 items in an arbitrary order. The only guarantee is that items that
1264 share the same key (because they were inserted using
1265 QHash::insertMulti()) will appear consecutively, from the most
1266 recently to the least recently inserted value.
1267
1268 Let's see a few examples of things we can do with a
1269 QHash::iterator that we cannot do with a QHash::const_iterator.
1270 Here's an example that increments every value stored in the QHash
1271 by 2:
1272
1273 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 18
1274
1275 Here's an example that removes all the items whose key is a
1276 string that starts with an underscore character:
1277
1278 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 19
1279
1280 The call to QHash::erase() removes the item pointed to by the
1281 iterator from the hash, and returns an iterator to the next item.
1282 Here's another way of removing an item while iterating:
1283
1284 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 20
1285
1286 It might be tempting to write code like this:
1287
1288 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 21
1289
1290 However, this will potentially crash in \c{++i}, because \c i is
1291 a dangling iterator after the call to erase().
1292
1293 Multiple iterators can be used on the same hash. However, be
1294 aware that any modification performed directly on the QHash has
1295 the potential of dramatically changing the order in which the
1296 items are stored in the hash, as they might cause QHash to rehash
1297 its internal data structure. There is one notable exception:
1298 QHash::erase(). This function can safely be called while
1299 iterating, and won't affect the order of items in the hash. If you
1300 need to keep iterators over a long period of time, we recommend
1301 that you use QMap rather than QHash.
1302
1303 \sa QHash::const_iterator, QMutableHashIterator
1304*/
1305
1306/*! \fn QHash::iterator::operator Node *() const
1307
1308 \internal
1309*/
1310
1311/*! \fn QHash::iterator::iterator()
1312
1313 Constructs an uninitialized iterator.
1314
1315 Functions like key(), value(), and operator++() must not be
1316 called on an uninitialized iterator. Use operator=() to assign a
1317 value to it before using it.
1318
1319 \sa QHash::begin() QHash::end()
1320*/
1321
1322/*! \fn QHash::iterator::iterator(void *node)
1323
1324 \internal
1325*/
1326
1327/*! \fn const Key &QHash::iterator::key() const
1328
1329 Returns the current item's key as a const reference.
1330
1331 There is no direct way of changing an item's key through an
1332 iterator, although it can be done by calling QHash::erase()
1333 followed by QHash::insert() or QHash::insertMulti().
1334
1335 \sa value()
1336*/
1337
1338/*! \fn T &QHash::iterator::value() const
1339
1340 Returns a modifiable reference to the current item's value.
1341
1342 You can change the value of an item by using value() on
1343 the left side of an assignment, for example:
1344
1345 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 22
1346
1347 \sa key(), operator*()
1348*/
1349
1350/*! \fn T &QHash::iterator::operator*() const
1351
1352 Returns a modifiable reference to the current item's value.
1353
1354 Same as value().
1355
1356 \sa key()
1357*/
1358
1359/*! \fn T *QHash::iterator::operator->() const
1360
1361 Returns a pointer to the current item's value.
1362
1363 \sa value()
1364*/
1365
1366/*!
1367 \fn bool QHash::iterator::operator==(const iterator &other) const
1368 \fn bool QHash::iterator::operator==(const const_iterator &other) const
1369
1370 Returns true if \a other points to the same item as this
1371 iterator; otherwise returns false.
1372
1373 \sa operator!=()
1374*/
1375
1376/*!
1377 \fn bool QHash::iterator::operator!=(const iterator &other) const
1378 \fn bool QHash::iterator::operator!=(const const_iterator &other) const
1379
1380 Returns true if \a other points to a different item than this
1381 iterator; otherwise returns false.
1382
1383 \sa operator==()
1384*/
1385
1386/*!
1387 \fn QHash::iterator &QHash::iterator::operator++()
1388
1389 The prefix ++ operator (\c{++i}) advances the iterator to the
1390 next item in the hash and returns an iterator to the new current
1391 item.
1392
1393 Calling this function on QHash::end() leads to undefined results.
1394
1395 \sa operator--()
1396*/
1397
1398/*! \fn QHash::iterator QHash::iterator::operator++(int)
1399
1400 \overload
1401
1402 The postfix ++ operator (\c{i++}) advances the iterator to the
1403 next item in the hash and returns an iterator to the previously
1404 current item.
1405*/
1406
1407/*!
1408 \fn QHash::iterator &QHash::iterator::operator--()
1409
1410 The prefix -- operator (\c{--i}) makes the preceding item
1411 current and returns an iterator pointing to the new current item.
1412
1413 Calling this function on QHash::begin() leads to undefined
1414 results.
1415
1416 \sa operator++()
1417*/
1418
1419/*!
1420 \fn QHash::iterator QHash::iterator::operator--(int)
1421
1422 \overload
1423
1424 The postfix -- operator (\c{i--}) makes the preceding item
1425 current and returns an iterator pointing to the previously
1426 current item.
1427*/
1428
1429/*! \fn QHash::iterator QHash::iterator::operator+(int j) const
1430
1431 Returns an iterator to the item at \a j positions forward from
1432 this iterator. (If \a j is negative, the iterator goes backward.)
1433
1434 This operation can be slow for large \a j values.
1435
1436 \sa operator-()
1437
1438*/
1439
1440/*! \fn QHash::iterator QHash::iterator::operator-(int j) const
1441
1442 Returns an iterator to the item at \a j positions backward from
1443 this iterator. (If \a j is negative, the iterator goes forward.)
1444
1445 This operation can be slow for large \a j values.
1446
1447 \sa operator+()
1448*/
1449
1450/*! \fn QHash::iterator &QHash::iterator::operator+=(int j)
1451
1452 Advances the iterator by \a j items. (If \a j is negative, the
1453 iterator goes backward.)
1454
1455 \sa operator-=(), operator+()
1456*/
1457
1458/*! \fn QHash::iterator &QHash::iterator::operator-=(int j)
1459
1460 Makes the iterator go back by \a j items. (If \a j is negative,
1461 the iterator goes forward.)
1462
1463 \sa operator+=(), operator-()
1464*/
1465
1466/*! \class QHash::const_iterator
1467 \brief The QHash::const_iterator class provides an STL-style const iterator for QHash and QMultiHash.
1468
1469 QHash features both \l{STL-style iterators} and \l{Java-style
1470 iterators}. The STL-style iterators are more low-level and more
1471 cumbersome to use; on the other hand, they are slightly faster
1472 and, for developers who already know STL, have the advantage of
1473 familiarity.
1474
1475 QHash\<Key, T\>::const_iterator allows you to iterate over a
1476 QHash (or a QMultiHash). If you want to modify the QHash as you
1477 iterate over it, you must use QHash::iterator instead. It is
1478 generally good practice to use QHash::const_iterator on a
1479 non-const QHash as well, unless you need to change the QHash
1480 through the iterator. Const iterators are slightly faster, and
1481 can improve code readability.
1482
1483 The default QHash::const_iterator constructor creates an
1484 uninitialized iterator. You must initialize it using a QHash
1485 function like QHash::constBegin(), QHash::constEnd(), or
1486 QHash::find() before you can start iterating. Here's a typical
1487 loop that prints all the (key, value) pairs stored in a hash:
1488
1489 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 23
1490
1491 Unlike QMap, which orders its items by key, QHash stores its
1492 items in an arbitrary order. The only guarantee is that items that
1493 share the same key (because they were inserted using
1494 QHash::insertMulti()) will appear consecutively, from the most
1495 recently to the least recently inserted value.
1496
1497 Multiple iterators can be used on the same hash. However, be aware
1498 that any modification performed directly on the QHash has the
1499 potential of dramatically changing the order in which the items
1500 are stored in the hash, as they might cause QHash to rehash its
1501 internal data structure. If you need to keep iterators over a long
1502 period of time, we recommend that you use QMap rather than QHash.
1503
1504 \sa QHash::iterator, QHashIterator
1505*/
1506
1507/*! \fn QHash::const_iterator::operator Node *() const
1508
1509 \internal
1510*/
1511
1512/*! \fn QHash::const_iterator::const_iterator()
1513
1514 Constructs an uninitialized iterator.
1515
1516 Functions like key(), value(), and operator++() must not be
1517 called on an uninitialized iterator. Use operator=() to assign a
1518 value to it before using it.
1519
1520 \sa QHash::constBegin() QHash::constEnd()
1521*/
1522
1523/*! \fn QHash::const_iterator::const_iterator(void *node)
1524
1525 \internal
1526*/
1527
1528/*! \fn QHash::const_iterator::const_iterator(const iterator &other)
1529
1530 Constructs a copy of \a other.
1531*/
1532
1533/*! \fn const Key &QHash::const_iterator::key() const
1534
1535 Returns the current item's key.
1536
1537 \sa value()
1538*/
1539
1540/*! \fn const T &QHash::const_iterator::value() const
1541
1542 Returns the current item's value.
1543
1544 \sa key(), operator*()
1545*/
1546
1547/*! \fn const T &QHash::const_iterator::operator*() const
1548
1549 Returns the current item's value.
1550
1551 Same as value().
1552
1553 \sa key()
1554*/
1555
1556/*! \fn const T *QHash::const_iterator::operator->() const
1557
1558 Returns a pointer to the current item's value.
1559
1560 \sa value()
1561*/
1562
1563/*! \fn bool QHash::const_iterator::operator==(const const_iterator &other) const
1564
1565 Returns true if \a other points to the same item as this
1566 iterator; otherwise returns false.
1567
1568 \sa operator!=()
1569*/
1570
1571/*! \fn bool QHash::const_iterator::operator!=(const const_iterator &other) const
1572
1573 Returns true if \a other points to a different item than this
1574 iterator; otherwise returns false.
1575
1576 \sa operator==()
1577*/
1578
1579/*!
1580 \fn QHash::const_iterator &QHash::const_iterator::operator++()
1581
1582 The prefix ++ operator (\c{++i}) advances the iterator to the
1583 next item in the hash and returns an iterator to the new current
1584 item.
1585
1586 Calling this function on QHash::end() leads to undefined results.
1587
1588 \sa operator--()
1589*/
1590
1591/*! \fn QHash::const_iterator QHash::const_iterator::operator++(int)
1592
1593 \overload
1594
1595 The postfix ++ operator (\c{i++}) advances the iterator to the
1596 next item in the hash and returns an iterator to the previously
1597 current item.
1598*/
1599
1600/*! \fn QHash::const_iterator &QHash::const_iterator::operator--()
1601
1602 The prefix -- operator (\c{--i}) makes the preceding item
1603 current and returns an iterator pointing to the new current item.
1604
1605 Calling this function on QHash::begin() leads to undefined
1606 results.
1607
1608 \sa operator++()
1609*/
1610
1611/*! \fn QHash::const_iterator QHash::const_iterator::operator--(int)
1612
1613 \overload
1614
1615 The postfix -- operator (\c{i--}) makes the preceding item
1616 current and returns an iterator pointing to the previously
1617 current item.
1618*/
1619
1620/*! \fn QHash::const_iterator QHash::const_iterator::operator+(int j) const
1621
1622 Returns an iterator to the item at \a j positions forward from
1623 this iterator. (If \a j is negative, the iterator goes backward.)
1624
1625 This operation can be slow for large \a j values.
1626
1627 \sa operator-()
1628*/
1629
1630/*! \fn QHash::const_iterator QHash::const_iterator::operator-(int j) const
1631
1632 Returns an iterator to the item at \a j positions backward from
1633 this iterator. (If \a j is negative, the iterator goes forward.)
1634
1635 This operation can be slow for large \a j values.
1636
1637 \sa operator+()
1638*/
1639
1640/*! \fn QHash::const_iterator &QHash::const_iterator::operator+=(int j)
1641
1642 Advances the iterator by \a j items. (If \a j is negative, the
1643 iterator goes backward.)
1644
1645 This operation can be slow for large \a j values.
1646
1647 \sa operator-=(), operator+()
1648*/
1649
1650/*! \fn QHash::const_iterator &QHash::const_iterator::operator-=(int j)
1651
1652 Makes the iterator go back by \a j items. (If \a j is negative,
1653 the iterator goes forward.)
1654
1655 This operation can be slow for large \a j values.
1656
1657 \sa operator+=(), operator-()
1658*/
1659
1660/*! \fn QDataStream &operator<<(QDataStream &out, const QHash<Key, T>& hash)
1661 \relates QHash
1662
1663 Writes the hash \a hash to stream \a out.
1664
1665 This function requires the key and value types to implement \c
1666 operator<<().
1667
1668 \sa {Format of the QDataStream operators}
1669*/
1670
1671/*! \fn QDataStream &operator>>(QDataStream &in, QHash<Key, T> &hash)
1672 \relates QHash
1673
1674 Reads a hash from stream \a in into \a hash.
1675
1676 This function requires the key and value types to implement \c
1677 operator>>().
1678
1679 \sa {Format of the QDataStream operators}
1680*/
1681
1682/*! \class QMultiHash
1683 \brief The QMultiHash class is a convenience QHash subclass that provides multi-valued hashes.
1684
1685 \ingroup tools
1686 \ingroup shared
1687
1688 \reentrant
1689
1690 QMultiHash\<Key, T\> is one of Qt's generic \l{container classes}.
1691 It inherits QHash and extends it with a few convenience functions
1692 that make it more suitable than QHash for storing multi-valued
1693 hashes. A multi-valued hash is a hash that allows multiple values
1694 with the same key; QHash normally doesn't allow that, unless you
1695 call QHash::insertMulti().
1696
1697 Because QMultiHash inherits QHash, all of QHash's functionality also
1698 applies to QMultiHash. For example, you can use isEmpty() to test
1699 whether the hash is empty, and you can traverse a QMultiHash using
1700 QHash's iterator classes (for example, QHashIterator). But in
1701 addition, it provides an insert() function that corresponds to
1702 QHash::insertMulti(), and a replace() function that corresponds to
1703 QHash::insert(). It also provides convenient operator+() and
1704 operator+=().
1705
1706 Example:
1707 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 24
1708
1709 Unlike QHash, QMultiHash provides no operator[]. Use value() or
1710 replace() if you want to access the most recently inserted item
1711 with a certain key.
1712
1713 If you want to retrieve all the values for a single key, you can
1714 use values(const Key &key), which returns a QList<T>:
1715
1716 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 25
1717
1718 The items that share the same key are available from most
1719 recently to least recently inserted.
1720
1721 A more efficient approach is to call find() to get
1722 the STL-style iterator for the first item with a key and iterate from
1723 there:
1724
1725 \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 26
1726
1727 QMultiHash's key and value data types must be \l{assignable data
1728 types}. You cannot, for example, store a QWidget as a value;
1729 instead, store a QWidget *. In addition, QMultiHash's key type
1730 must provide operator==(), and there must also be a global
1731 qHash() function that returns a hash value for an argument of the
1732 key's type. See the QHash documentation for details.
1733
1734 \sa QHash, QHashIterator, QMutableHashIterator, QMultiMap
1735*/
1736
1737/*! \fn QMultiHash::QMultiHash()
1738
1739 Constructs an empty hash.
1740*/
1741
1742/*! \fn QMultiHash::QMultiHash(const QHash<Key, T> &other)
1743
1744 Constructs a copy of \a other (which can be a QHash or a
1745 QMultiHash).
1746
1747 \sa operator=()
1748*/
1749
1750/*! \fn QMultiHash::iterator QMultiHash::replace(const Key &key, const T &value)
1751
1752 Inserts a new item with the \a key and a value of \a value.
1753
1754 If there is already an item with the \a key, that item's value
1755 is replaced with \a value.
1756
1757 If there are multiple items with the \a key, the most
1758 recently inserted item's value is replaced with \a value.
1759
1760 \sa insert()
1761*/
1762
1763/*! \fn QMultiHash::iterator QMultiHash::insert(const Key &key, const T &value)
1764
1765 Inserts a new item with the \a key and a value of \a value.
1766
1767 If there is already an item with the same key in the hash, this
1768 function will simply create a new one. (This behavior is
1769 different from replace(), which overwrites the value of an
1770 existing item.)
1771
1772 \sa replace()
1773*/
1774
1775/*! \fn QMultiHash &QMultiHash::operator+=(const QMultiHash &other)
1776
1777 Inserts all the items in the \a other hash into this hash
1778 and returns a reference to this hash.
1779
1780 \sa insert()
1781*/
1782
1783/*! \fn QMultiHash QMultiHash::operator+(const QMultiHash &other) const
1784
1785 Returns a hash that contains all the items in this hash in
1786 addition to all the items in \a other. If a key is common to both
1787 hashes, the resulting hash will contain the key multiple times.
1788
1789 \sa operator+=()
1790*/
1791
1792/*!
1793 \fn bool QMultiHash::contains(const Key &key, const T &value) const
1794 \since 4.3
1795
1796 Returns true if the hash contains an item with the \a key and
1797 \a value; otherwise returns false.
1798
1799 \sa QHash::contains()
1800*/
1801
1802/*!
1803 \fn bool QMultiHash::contains(const Key &key) const
1804 \overload
1805 \sa QHash::contains()
1806*/
1807
1808/*!
1809 \fn int QMultiHash::remove(const Key &key, const T &value)
1810 \since 4.3
1811
1812 Removes all the items that have the \a key and the value \a
1813 value from the hash. Returns the number of items removed.
1814
1815 \sa QHash::remove()
1816*/
1817
1818/*!
1819 \fn int QMultiHash::remove(const Key &key)
1820 \overload
1821 \sa QHash::remove()
1822*/
1823
1824/*!
1825 \fn int QMultiHash::count(const Key &key, const T &value) const
1826 \since 4.3
1827
1828 Returns the number of items with the \a key and \a value.
1829
1830 \sa QHash::count()
1831*/
1832
1833/*!
1834 \fn int QMultiHash::count(const Key &key) const
1835 \overload
1836 \sa QHash::count()
1837*/
1838
1839/*!
1840 \fn int QMultiHash::count() const
1841 \overload
1842 \sa QHash::count()
1843*/
1844
1845/*!
1846 \fn typename QHash<Key, T>::iterator QMultiHash::find(const Key &key, const T &value)
1847 \since 4.3
1848
1849 Returns an iterator pointing to the item with the \a key and \a value.
1850 If the hash contains no such item, the function returns end().
1851
1852 If the hash contains multiple items with the \a key and \a value, the
1853 iterator returned points to the most recently inserted item.
1854
1855 \sa QHash::find()
1856*/
1857
1858/*!
1859 \fn typename QHash<Key, T>::iterator QMultiHash::find(const Key &key)
1860 \overload
1861 \sa QHash::find()
1862*/
1863
1864/*!
1865 \fn typename QHash<Key, T>::const_iterator QMultiHash::find(const Key &key, const T &value) const
1866 \since 4.3
1867 \overload
1868*/
1869
1870/*!
1871 \fn typename QHash<Key, T>::const_iterator QMultiHash::find(const Key &key) const
1872 \overload
1873 \sa QHash::find()
1874*/
1875
1876/*!
1877 \fn typename QHash<Key, T>::const_iterator QMultiHash::constFind(const Key &key, const T &value) const
1878 \since 4.3
1879
1880 Returns an iterator pointing to the item with the \a key and the
1881 \a value in the hash.
1882
1883 If the hash contains no such item, the function returns
1884 constEnd().
1885
1886 \sa QHash::constFind()
1887*/
1888
1889/*!
1890 \fn typename QHash<Key, T>::const_iterator QMultiHash::constFind(const Key &key) const
1891 \overload
1892 \sa QHash::constFind()
1893*/
1894
1895QT_END_NAMESPACE
Note: See TracBrowser for help on using the repository browser.