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 |
|
---|
55 | QT_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 |
|
---|
64 | static 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 |
|
---|
78 | static 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 |
|
---|
92 | uint qHash(const QByteArray &key)
|
---|
93 | {
|
---|
94 | return hash(reinterpret_cast<const uchar *>(key.constData()), key.size());
|
---|
95 | }
|
---|
96 |
|
---|
97 | uint qHash(const QString &key)
|
---|
98 | {
|
---|
99 | return hash(key.unicode(), key.size());
|
---|
100 | }
|
---|
101 |
|
---|
102 | uint qHash(const QStringRef &key)
|
---|
103 | {
|
---|
104 | return hash(key.unicode(), key.size());
|
---|
105 | }
|
---|
106 |
|
---|
107 | uint 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 |
|
---|
130 | static 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 |
|
---|
135 | static 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 | */
|
---|
144 | static 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 | */
|
---|
166 | const int MinNumBits = 4;
|
---|
167 |
|
---|
168 | QHashData QHashData::shared_null = {
|
---|
169 | 0, 0, Q_BASIC_ATOMIC_INITIALIZER(1), 0, 0, MinNumBits, 0, 0, true, false, 0
|
---|
170 | };
|
---|
171 |
|
---|
172 | void *QHashData::allocateNode()
|
---|
173 | {
|
---|
174 | return allocateNode(0);
|
---|
175 | }
|
---|
176 |
|
---|
177 | void *QHashData::allocateNode(int nodeAlign)
|
---|
178 | {
|
---|
179 | void *ptr = strictAlignment ? qMallocAligned(nodeSize, nodeAlign) : qMalloc(nodeSize);
|
---|
180 | Q_CHECK_PTR(ptr);
|
---|
181 | return ptr;
|
---|
182 | }
|
---|
183 |
|
---|
184 | void QHashData::freeNode(void *node)
|
---|
185 | {
|
---|
186 | if (strictAlignment)
|
---|
187 | qFreeAligned(node);
|
---|
188 | else
|
---|
189 | qFree(node);
|
---|
190 | }
|
---|
191 |
|
---|
192 | QHashData *QHashData::detach_helper(void (*node_duplicate)(Node *, void *), int nodeSize)
|
---|
193 | {
|
---|
194 | return detach_helper2( node_duplicate, 0, nodeSize, 0 );
|
---|
195 | }
|
---|
196 |
|
---|
197 | QHashData *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 |
|
---|
264 | void 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 |
|
---|
285 | QHashData::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 |
|
---|
308 | QHashData::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 | */
|
---|
349 | void 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 |
|
---|
395 | void QHashData::destroyAndFree()
|
---|
396 | {
|
---|
397 | free_helper(0);
|
---|
398 | }
|
---|
399 |
|
---|
400 | #ifdef QT_QHASH_DEBUG
|
---|
401 |
|
---|
402 | void 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 |
|
---|
426 | void 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 |
|
---|
1895 | QT_END_NAMESPACE
|
---|