1// Copyright (C) 2018 Intel Corporation.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qcbormap.h"
5#include "qcborvalue_p.h"
6
7QT_BEGIN_NAMESPACE
8
9using namespace QtCbor;
10
11/*!
12 \class QCborMap
13 \inmodule QtCore
14 \ingroup cbor
15 \ingroup qtserialization
16 \reentrant
17 \since 5.12
18
19 \brief The QCborMap class is used to hold an associative container representable in CBOR.
20
21 \compares strong
22 \compareswith strong QCborValue QCborValueConstRef
23 \endcompareswith
24
25 This class can be used to hold an associative container in CBOR, a map
26 between a key and a value type. CBOR is the Concise Binary Object
27 Representation, a very compact form of binary data encoding that is a
28 superset of JSON. It was created by the IETF Constrained RESTful
29 Environments (CoRE) WG, which has used it in many new RFCs. It is meant to
30 be used alongside the \l{RFC 7252}{CoAP
31 protocol}.
32
33 Unlike JSON and \l QVariantMap, CBOR map keys can be of any type, not just
34 strings. For that reason, QCborMap is effectively a map between QCborValue
35 keys to QCborValue value elements.
36
37 However, for all member functions that take a key parameter, QCborMap
38 provides overloads that will work efficiently with integers and strings. In
39 fact, the use of integer keys is encouraged, since they occupy fewer bytes
40 to transmit and are simpler to encode and decode. Newer protocols designed
41 by the IETF CoRE WG to work specifically with CBOR are known to use them.
42
43 QCborMap is not sorted, because of that, searching for keys has linear
44 complexity (O(n)). QCborMap actually keeps the elements in the order that
45 they were inserted, which means that it is possible to make sorted
46 QCborMaps by carefully inserting elements in sorted order. CBOR does not
47 require sorting, but recommends it.
48
49 QCborMap can also be converted to and from QVariantMap and QJsonObject.
50 However, when performing the conversion, any non-string keys will be
51 stringified using a one-way method that the conversion back to QCborMap
52 will not undo.
53
54 \sa QCborArray, QCborValue, QJsonDocument, QVariantMap,
55 {Parsing and displaying CBOR data}, {Serialization Converter},
56 {Saving and Loading a Game}
57 */
58
59/*!
60 \typedef QCborMap::value_type
61
62 The value that is stored in this container: a pair of QCborValues
63 */
64
65/*!
66 \typedef QCborMap::key_type
67
68 The key type for this map. Since QCborMap keys can be any CBOR type, this
69 is a QCborValue.
70 */
71
72/*!
73 \typedef QCborMap::mapped_type
74
75 The type that is mapped to (the value), that is, a QCborValue.
76 */
77
78/*!
79 \typedef QCborMap::size_type
80
81 The type that QCborMap uses for sizes.
82 */
83
84/*!
85 \typedef QCborMap::iterator
86
87 A synonym for QCborMap::Iterator.
88 */
89
90/*!
91 \typedef QCborMap::const_iterator
92
93 A synonym for QCborMap::ConstIterator
94 */
95
96/*!
97 \fn QCborMap::iterator QCborMap::begin()
98
99 Returns a map iterator pointing to the first key-value pair of this map. If
100 this map is empty, the returned iterator will be the same as end().
101
102 \sa constBegin(), end()
103 */
104
105/*!
106 \fn QCborMap::const_iterator QCborMap::constBegin() const
107
108 Returns a map iterator pointing to the first key-value pair of this map. If
109 this map is empty, the returned iterator will be the same as constEnd().
110
111 \sa begin(), constEnd()
112 */
113
114/*!
115 \fn QCborMap::const_iterator QCborMap::begin() const
116
117 Returns a map iterator pointing to the first key-value pair of this map. If
118 this map is empty, the returned iterator will be the same as constEnd().
119
120 \sa begin(), constEnd()
121 */
122
123/*!
124 \fn QCborMap::const_iterator QCborMap::cbegin() const
125
126 Returns a map iterator pointing to the first key-value pair of this map. If
127 this map is empty, the returned iterator will be the same as constEnd().
128
129 \sa begin(), constEnd()
130 */
131
132/*!
133 \fn QCborMap::iterator QCborMap::end()
134
135 Returns a map iterator representing an element just past the last element
136 in the map.
137
138 \sa begin(), constBegin(), find(), constFind()
139 */
140
141/*!
142 \fn QCborMap::iterator QCborMap::constEnd() const
143
144 Returns a map iterator representing an element just past the last element
145 in the map.
146
147 \sa begin(), constBegin(), find(), constFind()
148 */
149
150/*!
151 \fn QCborMap::iterator QCborMap::end() const
152
153 Returns a map iterator representing an element just past the last element
154 in the map.
155
156 \sa begin(), constBegin(), find(), constFind()
157 */
158
159/*!
160 \fn QCborMap::iterator QCborMap::cend() const
161
162 Returns a map iterator representing an element just past the last element
163 in the map.
164
165 \sa begin(), constBegin(), find(), constFind()
166 */
167
168/*! \typedef QCborMap::const_key_value_iterator
169 \inmodule QtCore
170 \since 6.10
171 \brief The QCborMap::const_key_value_iterator typedef provides an STL-style iterator for
172 QCborMap.
173
174 QCborMap::const_key_value_iterator is essentially the same as QCborMap::const_iterator
175 but provided for symmetry with other containers like QJsonObject.
176
177 \sa QKeyValueIterator
178 */
179
180/*! \typedef QCborMap::key_value_iterator
181 \inmodule QtCore
182 \since 6.10
183 \brief The QCborMap::key_value_iterator typedef provides an STL-style iterator for QCborMap.
184
185 QCborMap::key_value_iterator is essentially the same as QCborMap::iterator
186 but provided for symmetry with other containers like QJsonObject.
187
188 \sa QKeyValueIterator
189 */
190
191/*! \fn QCborMap::key_value_iterator QCborMap::keyValueBegin()
192 \since 6.10
193
194 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
195 in the map.
196
197 \sa keyValueEnd()
198 */
199
200/*! \fn QCborMap::key_value_iterator QCborMap::keyValueEnd()
201 \since 6.10
202
203 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
204 entry after the last entry in the map.
205
206 \sa keyValueBegin()
207*/
208
209/*! \fn QCborMap::const_key_value_iterator QCborMap::keyValueBegin() const
210 \since 6.10
211
212 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
213 in the map.
214
215 \sa keyValueEnd()
216 */
217
218/*! \fn QCborMap::const_key_value_iterator QCborMap::constKeyValueBegin() const
219 \since 6.10
220
221 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
222 in the map.
223
224 \sa keyValueBegin()
225 */
226
227/*! \fn QCborMap::const_key_value_iterator QCborMap::keyValueEnd() const
228 \since 6.10
229
230 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
231 entry after the last entry in the map.
232
233 \sa keyValueBegin()
234 */
235
236/*! \fn QCborMap::const_key_value_iterator QCborMap::constKeyValueEnd() const
237 \since 6.10
238
239 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
240 entry after the last entry in the map.
241
242 \sa constKeyValueBegin()
243 */
244
245/*! \fn auto QCborMap::asKeyValueRange() &
246 \fn auto QCborMap::asKeyValueRange() const &
247 \fn auto QCborMap::asKeyValueRange() &&
248 \fn auto QCborMap::asKeyValueRange() const &&
249 \since 6.10
250
251 Returns a range object that allows iteration over this map as
252 key/value pairs.
253
254 Note that the values obtained this way are references into the one in the
255 map. Specifically, mutating the value will modify the map itself.
256
257 \sa QKeyValueIterator
258 */
259
260/*!
261 Constructs an empty CBOR Map object.
262
263 \sa isEmpty()
264 */
265QCborMap::QCborMap() noexcept
266 : d(nullptr)
267{
268}
269
270/*!
271 Creates a QCborMap object that is a copy of \a other.
272 */
273QCborMap::QCborMap(const QCborMap &other) noexcept
274 : d(other.d)
275{
276}
277
278/*!
279 \fn QCborMap::QCborMap(QCborMap &&other)
280 \since 6.10
281
282 Move-constructor.
283
284 The moved-from object \a other is placed in the default-constructed state.
285
286 \sa QCborMap::QCborMap()
287*/
288
289/*!
290 \fn QCborMap::QCborMap(std::initializer_list<value_type> args)
291
292 Constructs a QCborMap with items from a brace-initialization list found in
293 \a args, as in the following example:
294
295 \code
296 QCborMap map = {
297 {0, "Hello"},
298 {1, "World"},
299 {"foo", nullptr},
300 {"bar", QCborArray{0, 1, 2, 3, 4}}
301 };
302 \endcode
303 */
304
305/*!
306 Destroys this QCborMap object and frees any associated resources it owns.
307 */
308QCborMap::~QCborMap()
309{
310}
311
312/*!
313 Replaces the contents of this object with a copy of \a other, then returns
314 a reference to this object.
315 */
316QCborMap &QCborMap::operator=(const QCborMap &other) noexcept
317{
318 d = other.d;
319 return *this;
320}
321
322/*!
323 \fn QCborMap &QCborMap::operator=(QCborMap &&other)
324 \since 6.10
325
326 Move-assignment operator.
327
328 The moved-from object \a other is placed in a valid, but unspecified state.
329*/
330
331/*!
332 \fn void QCborMap::swap(QCborMap &other)
333 \memberswap{map}
334 */
335
336/*!
337 \fn QCborValue QCborMap::toCborValue() const
338
339 Explicitly constructs a \l QCborValue object that represents this map.
340 This function is usually not necessary since QCborValue has a constructor
341 for QCborMap, so the conversion is implicit.
342
343 Converting QCborMap to QCborValue allows it to be used in any context where
344 QCborValues can be used, including as keys and mapped types in QCborMap, as
345 well as QCborValue::toCbor().
346
347 \sa QCborValue::QCborValue(const QCborMap &)
348 */
349
350/*!
351 \fn bool QCborMap::isEmpty() const
352
353 Returns true if this map is empty (that is, size() is 0).
354
355 \sa size(), clear()
356 */
357
358/*!
359 Returns the number of elements in this map.
360
361 \sa isEmpty()
362 */
363qsizetype QCborMap::size() const noexcept
364{
365 return d ? d->elements.size() / 2 : 0;
366}
367
368/*!
369 Empties this map.
370
371 \sa isEmpty()
372 */
373void QCborMap::clear()
374{
375 d.reset();
376}
377
378/*!
379 Returns a list of all keys in this map.
380
381 \sa QMap::keys(), QHash::keys()
382 */
383QList<QCborValue> QCborMap::keys() const
384{
385 QList<QCborValue> result;
386 if (d) {
387 result.reserve(asize: size());
388 for (qsizetype i = 0; i < d->elements.size(); i += 2)
389 result << d->valueAt(idx: i);
390 }
391 return result;
392}
393
394/*!
395 \fn QCborValue QCborMap::value(qint64 key) const
396
397 Returns the QCborValue element in this map that corresponds to key \a key,
398 if there is one. CBOR recommends using integer keys, since they occupy less
399 space and are simpler to encode and decode.
400
401 If the map does not contain key \a key, this function returns a QCborValue
402 containing an undefined value. For that reason, it is not possible with
403 this function to tell apart the situation where the key was not present
404 from the situation where the key was mapped to an undefined value.
405
406 If the map contains more than one key equal to \a key, it is undefined
407 which one the return from function will reference. QCborMap does not allow
408 inserting duplicate keys, but it is possible to create such a map by
409 decoding a CBOR stream with them. They are usually not permitted and having
410 duplicate keys is usually an indication of a problem in the sender.
411
412 \sa operator[](qint64), find(qint64), constFind(qint64), remove(qint64), contains(qint64)
413 value(QLatin1StringView), value(const QString &), value(const QCborValue &)
414 */
415
416/*!
417 \fn QCborValue QCborMap::operator[](qint64 key) const
418
419 Returns the QCborValue element in this map that corresponds to key \a key,
420 if there is one. CBOR recommends using integer keys, since they occupy less
421 space and are simpler to encode and decode.
422
423 If the map does not contain key \a key, this function returns a QCborValue
424 containing an undefined value. For that reason, it is not possible with
425 this function to tell apart the situation where the key was not present
426 from the situation where the key was mapped to an undefined value.
427
428 If the map contains more than one key equal to \a key, it is undefined
429 which one this function will return. QCborMap does not allow inserting
430 duplicate keys, but it is possible to create such a map by decoding a CBOR
431 stream with them. They are usually not permitted and having duplicate keys
432 is usually an indication of a problem in the sender.
433
434 \sa value(qint64), find(qint64), constFind(qint64), remove(qint64), contains(qint64)
435 operator[](QLatin1StringView), operator[](const QString &),
436 operator[](const QCborOperator[] &)
437 */
438
439/*!
440 \fn QCborValue QCborMap::take(qint64 key)
441
442 Removes the key \a key and the corresponding value from the map and returns
443 the value, if it is found. If the map contains no such key, this function does nothing.
444
445 If the map contains more than one key equal to \a key, it is undefined
446 which one this function will remove. QCborMap does not allow inserting
447 duplicate keys, but it is possible to create such a map by decoding a CBOR
448 stream with them. They are usually not permitted and having duplicate keys
449 is usually an indication of a problem in the sender.
450
451 \sa value(qint64), operator[](qint64), find(qint64), contains(qint64),
452 take(QLatin1StringView), take(const QString &), take(const QCborValue &), insert()
453 */
454
455/*!
456 \fn void QCborMap::remove(qint64 key)
457
458 Removes the key \a key and the corresponding value from the map, if it is
459 found. If the map contains no such key, this function does nothing.
460
461 If the map contains more than one key equal to \a key, it is undefined
462 which one this function will remove. QCborMap does not allow inserting
463 duplicate keys, but it is possible to create such a map by decoding a CBOR
464 stream with them. They are usually not permitted and having duplicate keys
465 is usually an indication of a problem in the sender.
466
467 \sa value(qint64), operator[](qint64), find(qint64), contains(qint64)
468 remove(QLatin1StringView), remove(const QString &), remove(const QCborValue &)
469 */
470
471/*!
472 \fn bool QCborMap::contains(qint64 key) const
473
474 Returns true if this map contains a key-value pair identified by key \a
475 key. CBOR recommends using integer keys, since they occupy less space and
476 are simpler to encode and decode.
477
478 \sa value(qint64), operator[](qint64), find(qint64), remove(qint64),
479 contains(QLatin1StringView), remove(const QString &), remove(const QCborValue &)
480 */
481
482/*!
483 Returns a QCborValueRef to the value in this map that corresponds to key \a
484 key. CBOR recommends using integer keys, since they occupy less space and
485 are simpler to encode and decode.
486
487 QCborValueRef has the exact same API as \l QCborValue, with one important
488 difference: if you assign new values to it, this map will be updated with
489 that new value.
490
491 If the map did not have a key equal to \a key, one is inserted and this
492 function returns a reference to the new value, which will be a QCborValue
493 with an undefined value. For that reason, it is not possible with this
494 function to tell apart the situation where the key was not present from the
495 situation where the key was mapped to an undefined value.
496
497 If the map contains more than one key equal to \a key, it is undefined
498 which one the return will reference. QCborMap does not allow inserting
499 duplicate keys, but it is possible to create such a map by decoding a CBOR
500 stream with them. They are usually not permitted and having duplicate keys
501 is usually an indication of a problem in the sender.
502
503 \sa value(qint64), find(qint64), contains(qint64), remove(qint64),
504 operator[](QLatin1StringView), operator[](const QString &), operator[](const QCborValue &)
505 */
506QCborValueRef QCborMap::operator[](qint64 key)
507{
508 return QCborContainerPrivate::findOrAddMapKey(map&: *this, key);
509}
510
511/*!
512 \fn QCborValue QCborMap::value(QLatin1StringView key) const
513 \overload
514
515 Returns the QCborValue element in this map that corresponds to key \a key,
516 if there is one.
517
518 If the map does not contain key \a key, this function returns a QCborValue
519 containing an undefined value. For that reason, it is not possible with
520 this function to tell apart the situation where the key was not present
521 from the situation where the key was mapped to an undefined value.
522
523 If the map contains more than one key equal to \a key, it is undefined
524 which one this function will return. QCborMap does not allow inserting
525 duplicate keys, but it is possible to create such a map by decoding a CBOR
526 stream with them. They are usually not permitted and having duplicate keys
527 is usually an indication of a problem in the sender.
528
529 \sa operator[](QLatin1StringView), find(QLatin1StringView), constFind(QLatin1StringView),
530 remove(QLatin1StringView), contains(QLatin1StringView)
531 value(qint64), value(const QString &), value(const QCborValue &)
532 */
533
534/*!
535 \fn QCborValue QCborMap::operator[](QLatin1StringView key) const
536 \overload
537
538 Returns the QCborValue element in this map that corresponds to key \a key,
539 if there is one.
540
541 If the map does not contain key \a key, this function returns a QCborValue
542 containing an undefined value. For that reason, it is not possible with
543 this function to tell apart the situation where the key was not present
544 from the situation where the key was mapped to an undefined value.
545
546 If the map contains more than one key equal to \a key, it is undefined
547 which one this function will return. QCborMap does not allow inserting
548 duplicate keys, but it is possible to create such a map by decoding a CBOR
549 stream with them. They are usually not permitted and having duplicate keys
550 is usually an indication of a problem in the sender.
551
552 \sa value(QLatin1StringView), find(QLatin1StringView), constFind(QLatin1StringView),
553 remove(QLatin1StringView), contains(QLatin1StringView)
554 operator[](qint64), operator[](const QString &), operator[](const QCborOperator[] &)
555 */
556
557/*!
558 \fn QCborValue QCborMap::take(QLatin1StringView key)
559
560 Removes the key \a key and the corresponding value from the map and returns
561 the value, if it is found. If the map contains no such key, this function does nothing.
562
563 If the map contains more than one key equal to \a key, it is undefined
564 which one this function will remove. QCborMap does not allow inserting
565 duplicate keys, but it is possible to create such a map by decoding a CBOR
566 stream with them. They are usually not permitted and having duplicate keys
567 is usually an indication of a problem in the sender.
568
569 \sa value(QLatin1StringView), operator[](QLatin1StringView), find(QLatin1StringView),
570 contains(QLatin1StringView), take(qint64), take(const QString &),
571 take(const QCborValue &), insert()
572 */
573
574/*!
575 \fn void QCborMap::remove(QLatin1StringView key)
576 \overload
577
578 Removes the key \a key and the corresponding value from the map, if it is
579 found. If the map contains no such key, this function does nothing.
580
581 If the map contains more than one key equal to \a key, it is undefined
582 which one this function will remove. QCborMap does not allow inserting
583 duplicate keys, but it is possible to create such a map by decoding a CBOR
584 stream with them. They are usually not permitted and having duplicate keys
585 is usually an indication of a problem in the sender.
586
587 \sa value(QLatin1StringView), operator[](QLatin1StringView), find(QLatin1StringView),
588 contains(QLatin1StringView), remove(qint64), remove(const QString &),
589 remove(const QCborValue &)
590 */
591
592/*!
593 \fn bool QCborMap::contains(QLatin1StringView key) const
594 \overload
595
596 Returns true if this map contains a key-value pair identified by key \a
597 key.
598
599 \sa value(QLatin1StringView), operator[](QLatin1StringView), find(QLatin1StringView),
600 remove(QLatin1StringView), contains(qint64), remove(const QString &),
601 remove(const QCborValue &)
602 */
603
604/*!
605 \overload
606
607 Returns a QCborValueRef to the value in this map that corresponds to key \a
608 key.
609
610 QCborValueRef has the exact same API as \l QCborValue, with one important
611 difference: if you assign new values to it, this map will be updated with
612 that new value.
613
614 If the map did not have a key equal to \a key, one is inserted and this
615 function returns a reference to the new value, which will be a QCborValue
616 with an undefined value. For that reason, it is not possible with this
617 function to tell apart the situation where the key was not present from the
618 situation where the key was mapped to an undefined value.
619
620 If the map contains more than one key equal to \a key, it is undefined
621 which one the return will reference. QCborMap does not allow inserting
622 duplicate keys, but it is possible to create such a map by decoding a CBOR
623 stream with them. They are usually not permitted and having duplicate keys
624 is usually an indication of a problem in the sender.
625
626 \sa value(QLatin1StringView), find(QLatin1StringView), contains(QLatin1StringView),
627 remove(QLatin1StringView), operator[](qint64), operator[](const QString &),
628 operator[](const QCborValue &)
629 */
630QCborValueRef QCborMap::operator[](QLatin1StringView key)
631{
632 return QCborContainerPrivate::findOrAddMapKey(map&: *this, key);
633}
634
635/*!
636 \fn QCborValue QCborMap::value(const QString &key) const
637 \overload
638
639 Returns the QCborValue element in this map that corresponds to key \a key,
640 if there is one.
641
642 If the map does not contain key \a key, this function returns a QCborValue
643 containing an undefined value. For that reason, it is not possible with
644 this function to tell apart the situation where the key was not present
645 from the situation where the key was mapped to an undefined value.
646
647 If the map contains more than one key equal to \a key, it is undefined
648 which one this function will return. QCborMap does not allow inserting
649 duplicate keys, but it is possible to create such a map by decoding a CBOR
650 stream with them. They are usually not permitted and having duplicate keys
651 is usually an indication of a problem in the sender.
652
653 \sa operator[](const QString &), find(const QString &), constFind(const QString &),
654 remove(const QString &), contains(const QString &)
655 value(qint64), value(QLatin1StringView), value(const QCborValue &)
656 */
657
658/*!
659 \fn QCborValue QCborMap::operator[](const QString &key) const
660 \overload
661
662 Returns the QCborValue element in this map that corresponds to key \a key,
663 if there is one.
664
665 If the map does not contain key \a key, this function returns a QCborValue
666 containing an undefined value. For that reason, it is not possible with
667 this function to tell apart the situation where the key was not present
668 from the situation where the key was mapped to an undefined value.
669
670 If the map contains more than one key equal to \a key, it is undefined
671 which one this function will return. QCborMap does not allow inserting
672 duplicate keys, but it is possible to create such a map by decoding a CBOR
673 stream with them. They are usually not permitted and having duplicate keys
674 is usually an indication of a problem in the sender.
675
676 \sa value(const QString &), find(const QString &), constFind(const QString &),
677 remove(const QString &), contains(const QString &)
678 operator[](qint64), operator[](QLatin1StringView), operator[](const QCborOperator[] &)
679 */
680
681/*!
682 \fn QCborValue QCborMap::take(const QString &key)
683
684 Removes the key \a key and the corresponding value from the map and returns
685 the value, if it is found. If the map contains no such key, this function does nothing.
686
687 If the map contains more than one key equal to \a key, it is undefined
688 which one this function will remove. QCborMap does not allow inserting
689 duplicate keys, but it is possible to create such a map by decoding a CBOR
690 stream with them. They are usually not permitted and having duplicate keys
691 is usually an indication of a problem in the sender.
692
693 \sa value(const QString &), operator[](const QString &), find(const QString &),
694 contains(const QString &), take(QLatin1StringView), take(qint64),
695 take(const QCborValue &), insert()
696 */
697
698/*!
699 \fn void QCborMap::remove(const QString &key)
700 \overload
701
702 Removes the key \a key and the corresponding value from the map, if it is
703 found. If the map contains no such key, this function does nothing.
704
705 If the map contains more than one key equal to \a key, it is undefined
706 which one this function will remove. QCborMap does not allow inserting
707 duplicate keys, but it is possible to create such a map by decoding a CBOR
708 stream with them. They are usually not permitted and having duplicate keys
709 is usually an indication of a problem in the sender.
710
711 \sa value(const QString &), operator[](const QString &), find(const QString &),
712 contains(const QString &)
713 remove(qint64), remove(QLatin1StringView), remove(const QCborValue &)
714 */
715
716/*!
717 \fn bool QCborMap::contains(const QString &key) const
718 \overload
719
720 Returns true if this map contains a key-value pair identified by key \a
721 key.
722
723 \sa value(const QString &), operator[](const QString &), find(const QString &),
724 remove(const QString &),
725 contains(qint64), remove(QLatin1StringView), remove(const QCborValue &)
726 */
727
728/*!
729 \overload
730
731 Returns a QCborValueRef to the value in this map that corresponds to key \a
732 key.
733
734 QCborValueRef has the exact same API as \l QCborValue, with one important
735 difference: if you assign new values to it, this map will be updated with
736 that new value.
737
738 If the map did not have a key equal to \a key, one is inserted and this
739 function returns a reference to the new value, which will be a QCborValue
740 with an undefined value. For that reason, it is not possible with this
741 function to tell apart the situation where the key was not present from the
742 situation where the key was mapped to an undefined value.
743
744 If the map contains more than one key equal to \a key, it is undefined
745 which one the return will reference. QCborMap does not allow inserting
746 duplicate keys, but it is possible to create such a map by decoding a CBOR
747 stream with them. They are usually not permitted and having duplicate keys
748 is usually an indication of a problem in the sender.
749
750 \sa value(const QString &), find(const QString &), contains(const QString &),
751 remove(const QString &), operator[](qint64), operator[](QLatin1StringView),
752 operator[](const QCborValue &)
753 */
754QCborValueRef QCborMap::operator[](const QString & key)
755{
756 return QCborContainerPrivate::findOrAddMapKey(map&: *this, key: qToStringViewIgnoringNull(s: key));
757}
758
759/*!
760 \fn QCborValue QCborMap::value(const QCborValue &key) const
761
762 Returns the QCborValue element in this map that corresponds to key \a key,
763 if there is one.
764
765 If the map does not contain key \a key, this function returns a QCborValue
766 containing an undefined value. For that reason, it is not possible with
767 this function to tell apart the situation where the key was not present
768 from the situation where the key was mapped to an undefined value.
769
770 If the map contains more than one key equal to \a key, it is undefined
771 which one this function will return. QCborMap does not allow inserting
772 duplicate keys, but it is possible to create such a map by decoding a CBOR
773 stream with them. They are usually not permitted and having duplicate keys
774 is usually an indication of a problem in the sender.
775
776 \sa operator[](const QCborValue &), find(const QCborValue &), constFind(const QCborValue &),
777 remove(const QCborValue &), contains(const QCborValue &)
778 value(qint64), value(QLatin1StringView), value(const QString &)
779 */
780
781/*!
782 \fn QCborValue QCborMap::operator[](const QCborValue &key) const
783
784 Returns the QCborValue element in this map that corresponds to key \a key,
785 if there is one.
786
787 If the map does not contain key \a key, this function returns a QCborValue
788 containing an undefined value. For that reason, it is not possible with
789 this function to tell apart the situation where the key was not present
790 from the situation where the key was mapped to an undefined value.
791
792 If the map contains more than one key equal to \a key, it is undefined
793 which one this function will return. QCborMap does not allow inserting
794 duplicate keys, but it is possible to create such a map by decoding a CBOR
795 stream with them. They are usually not permitted and having duplicate keys
796 is usually an indication of a problem in the sender.
797
798 \sa value(const QCborValue &), find(const QCborValue &), constFind(const QCborValue &),
799 remove(const QCborValue &), contains(const QCborValue &)
800 operator[](qint64), operator[](QLatin1StringView), operator[](const QCborOperator[] &)
801 */
802
803/*!
804 \fn QCborValue QCborMap::take(const QCborValue &key)
805
806 Removes the key \a key and the corresponding value from the map and returns
807 the value, if it is found. If the map contains no such key, this function does nothing.
808
809 If the map contains more than one key equal to \a key, it is undefined
810 which one this function will remove. QCborMap does not allow inserting
811 duplicate keys, but it is possible to create such a map by decoding a CBOR
812 stream with them. They are usually not permitted and having duplicate keys
813 is usually an indication of a problem in the sender.
814
815 \sa value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &),
816 contains(const QCborValue &), take(QLatin1StringView), take(const QString &),
817 take(qint64), insert()
818 */
819
820/*!
821 \fn void QCborMap::remove(const QCborValue &key)
822
823 Removes the key \a key and the corresponding value from the map, if it is
824 found. If the map contains no such key, this function does nothing.
825
826 If the map contains more than one key equal to \a key, it is undefined
827 which one this function will remove. QCborMap does not allow inserting
828 duplicate keys, but it is possible to create such a map by decoding a CBOR
829 stream with them. They are usually not permitted and having duplicate keys
830 is usually an indication of a problem in the sender.
831
832 \sa value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &),
833 contains(const QCborValue &)
834 remove(qint64), remove(QLatin1StringView), remove(const QString &)
835 */
836
837/*!
838 \fn bool QCborMap::contains(const QCborValue &key) const
839
840 Returns true if this map contains a key-value pair identified by key \a
841 key.
842
843 \sa value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &),
844 remove(const QCborValue &),
845 contains(qint64), remove(QLatin1StringView), remove(const QString &)
846 */
847
848/*!
849 \overload
850
851 Returns a QCborValueRef to the value in this map that corresponds to key \a
852 key.
853
854 QCborValueRef has the exact same API as \l QCborValue, with one important
855 difference: if you assign new values to it, this map will be updated with
856 that new value.
857
858 If the map did not have a key equal to \a key, one is inserted and this
859 function returns a reference to the new value, which will be a QCborValue
860 with an undefined value. For that reason, it is not possible with this
861 function to tell apart the situation where the key was not present from the
862 situation where the key was mapped to an undefined value.
863
864 If the map contains more than one key equal to \a key, it is undefined
865 which one the return will reference. QCborMap does not allow inserting
866 duplicate keys, but it is possible to create such a map by decoding a CBOR
867 stream with them. They are usually not permitted and having duplicate keys
868 is usually an indication of a problem in the sender.
869
870 \sa value(const QCborValue &), find(const QCborValue &), contains(const QCborValue &),
871 remove(const QCborValue &), operator[](qint64), operator[](QLatin1StringView),
872 operator[](const QString &)
873 */
874QCborValueRef QCborMap::operator[](const QCborValue &key)
875{
876 return QCborContainerPrivate::findOrAddMapKey<const QCborValue &>(map&: *this, key);
877}
878
879template <typename KeyType> inline QCborValueRef
880QCborContainerPrivate::findOrAddMapKey(QCborMap &map, KeyType key)
881{
882 QCborValueRef result = findOrAddMapKey<KeyType>(map.d.data(), key);
883 map.d = result.d;
884 return result;
885}
886
887/*!
888 \fn QCborMap::iterator QCborMap::find(qint64 key)
889 \fn QCborMap::const_iterator QCborMap::find(qint64 key) const
890
891 Returns a map iterator to the key-value pair whose key is \a key, if the
892 map contains such a pair. If it doesn't, this function returns end().
893
894 CBOR recommends using integer keys, since they occupy less
895 space and are simpler to encode and decode.
896
897 If the map contains more than one key equal to \a key, it is undefined
898 which one this function will find. QCborMap does not allow inserting
899 duplicate keys, but it is possible to create such a map by decoding a CBOR
900 stream with them. They are usually not permitted and having duplicate keys
901 is usually an indication of a problem in the sender.
902
903 \sa value(qint64), operator[](qint64), constFind(qint64), remove(qint64), contains(qint64),
904 value(QLatin1StringView), value(const QString &), value(const QCborValue &)
905 */
906QCborMap::iterator QCborMap::find(qint64 key)
907{
908 detach();
909 auto it = constFind(key);
910 return { d.data(), it.item.i };
911}
912
913/*!
914 \fn QCborMap::iterator QCborMap::find(QLatin1StringView key)
915 \fn QCborMap::const_iterator QCborMap::find(QLatin1StringView key) const
916 \overload
917
918 Returns a map iterator to the key-value pair whose key is \a key, if the
919 map contains such a pair. If it doesn't, this function returns end().
920
921 If the map contains more than one key equal to \a key, it is undefined
922 which one this function will find. QCborMap does not allow inserting
923 duplicate keys, but it is possible to create such a map by decoding a CBOR
924 stream with them. They are usually not permitted and having duplicate keys
925 is usually an indication of a problem in the sender.
926
927 \sa value(QLatin1StringView), operator[](QLatin1StringView), constFind(QLatin1StringView),
928 remove(QLatin1StringView), contains(QLatin1StringView),
929 value(qint64), value(const QString &), value(const QCborValue &)
930 */
931QCborMap::iterator QCborMap::find(QLatin1StringView key)
932{
933 detach();
934 auto it = constFind(key);
935 return { d.data(), it.item.i };
936}
937
938/*!
939 \fn QCborMap::iterator QCborMap::find(const QString & key)
940 \fn QCborMap::const_iterator QCborMap::find(const QString & key) const
941 \overload
942
943 Returns a map iterator to the key-value pair whose key is \a key, if the
944 map contains such a pair. If it doesn't, this function returns end().
945
946 If the map contains more than one key equal to \a key, it is undefined
947 which one this function will find. QCborMap does not allow inserting
948 duplicate keys, but it is possible to create such a map by decoding a CBOR
949 stream with them. They are usually not permitted and having duplicate keys
950 is usually an indication of a problem in the sender.
951
952 \sa value(const QString &), operator[](const QString &), constFind(const QString &),
953 remove(const QString &), contains(const QString &),
954 value(qint64), value(QLatin1StringView), value(const QCborValue &)
955 */
956QCborMap::iterator QCborMap::find(const QString & key)
957{
958 detach();
959 auto it = constFind(key);
960 return { d.data(), it.item.i };
961}
962
963/*!
964 \fn QCborMap::iterator QCborMap::find(const QCborValue &key)
965 \fn QCborMap::const_iterator QCborMap::find(const QCborValue &key) const
966 \overload
967
968 Returns a map iterator to the key-value pair whose key is \a key, if the
969 map contains such a pair. If it doesn't, this function returns end().
970
971 If the map contains more than one key equal to \a key, it is undefined
972 which one this function will find. QCborMap does not allow inserting
973 duplicate keys, but it is possible to create such a map by decoding a CBOR
974 stream with them. They are usually not permitted and having duplicate keys
975 is usually an indication of a problem in the sender.
976
977 \sa value(const QCborValue &), operator[](const QCborValue &), constFind(const QCborValue &),
978 remove(const QCborValue &), contains(const QCborValue &),
979 value(qint64), value(QLatin1StringView), value(const QString &)
980 */
981QCborMap::iterator QCborMap::find(const QCborValue &key)
982{
983 detach();
984 auto it = constFind(key);
985 return { d.data(), it.item.i };
986}
987
988/*!
989 Returns a map iterator to the key-value pair whose key is \a key, if the
990 map contains such a pair. If it doesn't, this function returns constEnd().
991
992 CBOR recommends using integer keys, since they occupy less
993 space and are simpler to encode and decode.
994
995 If the map contains more than one key equal to \a key, it is undefined
996 which one this function will find. QCborMap does not allow inserting
997 duplicate keys, but it is possible to create such a map by decoding a CBOR
998 stream with them. They are usually not permitted and having duplicate keys
999 is usually an indication of a problem in the sender.
1000
1001 \sa value(qint64), operator[](qint64), find(qint64), remove(qint64), contains(qint64),
1002 value(QLatin1StringView), value(const QString &), value(const QCborValue &)
1003 */
1004QCborMap::const_iterator QCborMap::constFind(qint64 key) const
1005{
1006 return d ? d->findCborMapKey(key) : constEnd();
1007}
1008
1009/*!
1010 \overload
1011
1012 Returns a map iterator to the key-value pair whose key is \a key, if the
1013 map contains such a pair. If it doesn't, this function returns constEnd().
1014
1015 If the map contains more than one key equal to \a key, it is undefined
1016 which one this function will find. QCborMap does not allow inserting
1017 duplicate keys, but it is possible to create such a map by decoding a CBOR
1018 stream with them. They are usually not permitted and having duplicate keys
1019 is usually an indication of a problem in the sender.
1020
1021 \sa value(QLatin1StringView), operator[](QLatin1StringView), find(QLatin1StringView),
1022 remove(QLatin1StringView), contains(QLatin1StringView),
1023 value(qint64), value(const QString &), value(const QCborValue &)
1024 */
1025QCborMap::const_iterator QCborMap::constFind(QLatin1StringView key) const
1026{
1027 return d ? d->findCborMapKey(key) : constEnd();
1028}
1029
1030/*!
1031 \overload
1032
1033 Returns a map iterator to the key-value pair whose key is \a key, if the
1034 map contains such a pair. If it doesn't, this function returns constEnd().
1035
1036 If the map contains more than one key equal to \a key, it is undefined
1037 which one this function will find. QCborMap does not allow inserting
1038 duplicate keys, but it is possible to create such a map by decoding a CBOR
1039 stream with them. They are usually not permitted and having duplicate keys
1040 is usually an indication of a problem in the sender.
1041
1042 \sa value(const QString &), operator[](const QString &), find(const QString &),
1043 remove(const QString &), contains(const QString &),
1044 value(qint64), value(QLatin1StringView), value(const QCborValue &)
1045 */
1046QCborMap::const_iterator QCborMap::constFind(const QString &key) const
1047{
1048 return d ? d->findCborMapKey(key: qToStringViewIgnoringNull(s: key)) : constEnd();
1049}
1050
1051/*!
1052 \overload
1053
1054 Returns a map iterator to the key-value pair whose key is \a key, if the
1055 map contains such a pair. If it doesn't, this function returns constEnd().
1056
1057 If the map contains more than one key equal to \a key, it is undefined
1058 which one this function will find. QCborMap does not allow inserting
1059 duplicate keys, but it is possible to create such a map by decoding a CBOR
1060 stream with them. They are usually not permitted and having duplicate keys
1061 is usually an indication of a problem in the sender.
1062
1063 \sa value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &),
1064 remove(const QCborValue &), contains(const QCborValue &),
1065 value(qint64), value(QLatin1StringView), value(const QString &)
1066 */
1067QCborMap::const_iterator QCborMap::constFind(const QCborValue &key) const
1068{
1069 return d ? d->findCborMapKey<const QCborValue &>(key) : constEnd();
1070}
1071
1072/*!
1073 \fn QCborMap::iterator QCborMap::insert(qint64 key, const QCborValue &value)
1074 \overload
1075
1076 Inserts the key \a key and value \a value into this map and returns a map
1077 iterator pointing to the newly inserted pair.
1078
1079 If the map already had a key equal to \a key, its value will be overwritten
1080 by \a value.
1081
1082 \sa erase(), remove(qint64), value(qint64), operator[](qint64), find(qint64),
1083 contains(qint64), take(qint64), extract()
1084 */
1085
1086/*!
1087 \fn QCborMap::iterator QCborMap::insert(QLatin1StringView key, const QCborValue &value)
1088 \overload
1089
1090 Inserts the key \a key and value \a value into this map and returns a map
1091 iterator pointing to the newly inserted pair.
1092
1093 If the map already had a key equal to \a key, its value will be overwritten
1094 by \a value.
1095
1096 \sa erase(), remove(QLatin1StringView), value(QLatin1StringView), operator[](QLatin1StringView),
1097 find(QLatin1StringView), contains(QLatin1StringView), take(QLatin1StringView), extract()
1098 */
1099
1100/*!
1101 \fn QCborMap::iterator QCborMap::insert(const QString &key, const QCborValue &value)
1102 \overload
1103
1104 Inserts the key \a key and value \a value into this map and returns a map
1105 iterator pointing to the newly inserted pair.
1106
1107 If the map already had a key equal to \a key, its value will be overwritten
1108 by \a value.
1109
1110 \sa erase(), remove(const QString &), value(const QString &), operator[](const QString &),
1111 find(const QString &), contains(const QString &), take(const QString &), extract()
1112 */
1113
1114/*!
1115 \fn QCborMap::iterator QCborMap::insert(const QCborValue &key, const QCborValue &value)
1116 \overload
1117
1118 Inserts the key \a key and value \a value into this map and returns a map
1119 iterator pointing to the newly inserted pair.
1120
1121 If the map already had a key equal to \a key, its value will be overwritten
1122 by \a value.
1123
1124 \sa erase(), remove(const QCborValue &), value(const QCborValue &), operator[](const QCborValue &),
1125 find(const QCborValue &), contains(const QCborValue &), take(const QCborValue &), extract()
1126 */
1127
1128/*!
1129 \fn QCborMap::iterator QCborMap::insert(value_type v)
1130 \overload
1131
1132 Inserts the key-value pair in \a v into this map and returns a map iterator
1133 pointing to the newly inserted pair.
1134
1135 If the map already had a key equal to \c{v.first}, its value will be
1136 overwritten by \c{v.second}.
1137
1138 \sa operator[], erase(), extract()
1139 */
1140
1141
1142/*!
1143 \fn QCborMap::iterator QCborMap::erase(const_iterator it)
1144
1145 Removes the key-value pair pointed to by the map iterator \a it and returns a
1146 pointer to the next element, after removal.
1147
1148 \sa remove(), begin(), end(), insert(), extract()
1149 */
1150
1151/*!
1152 \overload
1153
1154 Removes the key-value pair pointed to by the map iterator \a it and returns a
1155 pointer to the next element, after removal.
1156
1157 \sa remove(), begin(), end(), insert()
1158 */
1159QCborMap::iterator QCborMap::erase(QCborMap::iterator it)
1160{
1161 detach();
1162
1163 // remove both key and value
1164 // ### optimize?
1165 d->removeAt(idx: it.item.i - 1);
1166 d->removeAt(idx: it.item.i - 1);
1167 return it;
1168}
1169
1170/*!
1171 \fn QCborValue QCborMap::extract(iterator it)
1172 \fn QCborValue QCborMap::extract(const_iterator it)
1173
1174 Extracts a value from the map at the position indicated by iterator \a it
1175 and returns the value so extracted.
1176
1177 \sa insert(), erase(), take(), remove()
1178 */
1179QCborValue QCborMap::extract(iterator it)
1180{
1181 detach();
1182 QCborValue v = d->extractAt(idx: it.item.i);
1183 // remove both key and value
1184 // ### optimize?
1185 d->removeAt(idx: it.item.i - 1);
1186 d->removeAt(idx: it.item.i - 1);
1187
1188 return v;
1189}
1190
1191/*!
1192 \fn bool QCborMap::empty() const
1193
1194 Synonym for isEmpty(). This function is provided for compatibility with
1195 generic code that uses the Standard Library API.
1196
1197 Returns true if this map is empty (size() == 0).
1198
1199 \sa isEmpty(), size()
1200 */
1201
1202/*!
1203 \fn int QCborMap::compare(const QCborMap &other) const
1204
1205 Compares this map and \a other, comparing each element in sequence, and
1206 returns an integer that indicates whether this map should be sorted prior
1207 to (if the result is negative) or after \a other (if the result is
1208 positive). If this function returns 0, the two maps are equal and contain
1209 the same elements.
1210
1211 Note that CBOR maps are unordered, which means that two maps containing the
1212 very same pairs but in different order will still compare differently. To
1213 avoid this, it is recommended to insert elements into the map in a
1214 predictable order, such as by ascending key value. In fact, maps with keys
1215 in sorted order are required for Canonical CBOR representation.
1216
1217 For more information on CBOR sorting order, see QCborValue::compare().
1218
1219 \sa QCborValue::compare(), QCborArray::compare(), operator==()
1220 */
1221
1222/*!
1223 \fn bool QCborMap::operator==(const QCborMap &lhs, const QCborMap &rhs)
1224
1225 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1226 returns true if the two maps contain the same elements in the same order,
1227 false otherwise.
1228
1229 Note that CBOR maps are unordered, which means that two maps containing the
1230 very same pairs but in different order will still compare differently. To
1231 avoid this, it is recommended to insert elements into the map in a
1232 predictable order, such as by ascending key value. In fact, maps with keys
1233 in sorted order are required for Canonical CBOR representation.
1234
1235 For more information on CBOR equality in Qt, see, QCborValue::compare().
1236
1237 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1238 operator!=(), operator<()
1239 */
1240
1241/*!
1242 \fn bool QCborMap::operator!=(const QCborMap &lhs, const QCborMap &rhs)
1243
1244 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1245 returns true if the two maps contain any different elements or elements in
1246 different orders, false otherwise.
1247
1248 Note that CBOR maps are unordered, which means that two maps containing the
1249 very same pairs but in different order will still compare differently. To
1250 avoid this, it is recommended to insert elements into the map in a
1251 predictable order, such as by ascending key value. In fact, maps with keys
1252 in sorted order are required for Canonical CBOR representation.
1253
1254 For more information on CBOR equality in Qt, see, QCborValue::compare().
1255
1256 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1257 operator==(), operator<()
1258 */
1259
1260/*!
1261 \fn bool QCborMap::operator<(const QCborMap &lhs, const QCborMap &rhs)
1262
1263 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1264 returns true if \a lhs map should be sorted before \a rhs, false
1265 otherwise.
1266
1267 Note that CBOR maps are unordered, which means that two maps containing the
1268 very same pairs but in different order will still compare differently. To
1269 avoid this, it is recommended to insert elements into the map in a
1270 predictable order, such as by ascending key value. In fact, maps with keys
1271 in sorted order are required for Canonical CBOR representation.
1272
1273 For more information on CBOR sorting order, see QCborValue::compare().
1274
1275 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1276 operator==(), operator!=()
1277 */
1278
1279/*!
1280 \fn bool QCborMap::operator<=(const QCborMap &lhs, const QCborMap &rhs)
1281
1282 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1283 returns true if \a lhs map should be sorted before \a rhs or
1284 if the two maps contain the same elements in the same order, false
1285 otherwise.
1286
1287 Note that CBOR maps are unordered, which means that two maps containing the
1288 very same pairs but in different order will still compare differently. To
1289 avoid this, it is recommended to insert elements into the map in a
1290 predictable order, such as by ascending key value. In fact, maps with keys
1291 in sorted order are required for Canonical CBOR representation.
1292
1293 For more information on CBOR sorting order, see QCborValue::compare().
1294
1295 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1296 operator==(), operator!=()
1297*/
1298
1299/*!
1300 \fn bool QCborMap::operator>=(const QCborMap &lhs, const QCborMap &rhs)
1301
1302 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1303 returns true if \a lhs map should be sorted after \a rhs or
1304 if the two maps contain the same elements in the same order, false
1305 otherwise.
1306
1307 Note that CBOR maps are unordered, which means that two maps containing the
1308 very same pairs but in different order will still compare differently. To
1309 avoid this, it is recommended to insert elements into the map in a
1310 predictable order, such as by ascending key value. In fact, maps with keys
1311 in sorted order are required for Canonical CBOR representation.
1312
1313 For more information on CBOR sorting order, see QCborValue::compare().
1314
1315 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1316 operator==(), operator!=()
1317*/
1318
1319/*!
1320 \fn bool QCborMap::operator>(const QCborMap &lhs, const QCborMap &rhs)
1321
1322 Compares \a lhs and \a rhs maps, comparing each element in sequence, and
1323 returns true if \a lhs map should be sorted after \a rhs, false
1324 otherwise.
1325
1326 Note that CBOR maps are unordered, which means that two maps containing the
1327 very same pairs but in different order will still compare differently. To
1328 avoid this, it is recommended to insert elements into the map in a
1329 predictable order, such as by ascending key value. In fact, maps with keys
1330 in sorted order are required for Canonical CBOR representation.
1331
1332 For more information on CBOR sorting order, see QCborValue::compare().
1333
1334 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1335 operator==(), operator!=()
1336*/
1337
1338void QCborMap::detach(qsizetype reserved)
1339{
1340 d = QCborContainerPrivate::detach(d: d.data(), reserved: reserved ? reserved : size() * 2);
1341}
1342
1343/*!
1344 \class QCborMap::Iterator
1345 \inmodule QtCore
1346 \ingroup cbor
1347 \reentrant
1348 \since 5.12
1349
1350 \brief The QCborMap::Iterator class provides an STL-style non-const iterator for QCborMap.
1351
1352 \compares strong
1353 \compareswith strong ConstIterator
1354 \endcompareswith
1355
1356 QCborMap::Iterator allows you to iterate over a QCborMap and to modify the
1357 value (but not the key) stored under a particular key. If you want to
1358 iterate over a const QCborMap, you should use QCborMap::ConstIterator. It
1359 is generally good practice to use QCborMap::ConstIterator on a non-const
1360 QCborMap as well, unless you need to change the QCborMap through the
1361 iterator. Const iterators are slightly faster, and improve code
1362 readability.
1363
1364 You must initialize the iterator using a QCborMap function like
1365 QCborMap::begin(), QCborMap::end(), or QCborMap::find() before you can
1366 start iterating..
1367
1368 Multiple iterators can be used on the same object. Existing iterators will however
1369 become dangling once the object gets modified.
1370
1371 \sa QCborMap::ConstIterator
1372*/
1373
1374/*!
1375 \typedef QCborMap::Iterator::difference_type
1376 \internal
1377*/
1378
1379/*!
1380 \typedef QCborMap::Iterator::iterator_category
1381
1382 A synonym for \e {std::random_access_iterator_tag} indicating
1383 this iterator is a random-access iterator.
1384*/
1385
1386/*!
1387 \typedef QCborMap::Iterator::reference
1388 \internal
1389*/
1390
1391/*!
1392 \typedef QCborMap::Iterator::value_type
1393 \internal
1394*/
1395
1396/*!
1397 \typedef QCborMap::Iterator::pointer
1398 \internal
1399*/
1400
1401/*!
1402 \fn QCborMap::Iterator::Iterator()
1403
1404 Constructs an uninitialized iterator.
1405
1406 Functions like key(), value(), and operator++() must not be
1407 called on an uninitialized iterator. Use operator=() to assign a
1408 value to it before using it.
1409
1410 \sa QCborMap::begin(), QCborMap::end()
1411*/
1412
1413/*!
1414 \fn QCborMap::Iterator::Iterator(const Iterator &other)
1415
1416 Constructs an iterator as a copy of \a other.
1417 */
1418
1419/*!
1420 \fn QCborMap::Iterator &QCborMap::Iterator::operator=(const Iterator &other)
1421
1422 Makes this iterator a copy of \a other and returns a reference to this
1423 iterator.
1424 */
1425
1426/*!
1427 \fn QCborValue QCborMap::Iterator::key() const
1428
1429 Returns the current item's key.
1430
1431 There is no direct way of changing an item's key through an iterator,
1432 although it can be done by calling QCborMap::erase() followed by
1433 QCborMap::insert().
1434
1435 \sa value()
1436*/
1437
1438/*!
1439 \fn QCborValueRef QCborMap::Iterator::value() const
1440
1441 Returns a modifiable reference to the current item's value.
1442
1443 You can change the value for a key by using value() on the left side of an
1444 assignment.
1445
1446 The return value is of type QCborValueRef, a helper class for QCborArray
1447 and QCborMap. When you get an object of type QCborValueRef, you can use it
1448 as if it were a reference to a QCborValue. If you assign to it, the
1449 assignment will apply to the element in the QCborArray or QCborMap from
1450 which you got the reference.
1451
1452 \sa key(), operator*()
1453*/
1454
1455/*!
1456 \fn QCborMap::Iterator::value_type QCborMap::Iterator::operator*() const
1457
1458 Returns a pair containing the current item's key and a modifiable reference
1459 to the current item's value.
1460
1461 The second element of the pair is of type QCborValueRef, a helper class for
1462 QCborArray and QCborMap. When you get an object of type QCborValueRef, you
1463 can use it as if it were a reference to a QCborValue. If you assign to it,
1464 the assignment will apply to the element in the QCborArray or QCborMap from
1465 which you got the reference.
1466
1467 \sa key(), value()
1468*/
1469
1470/*!
1471 \fn QCborValueRef *QCborMap::Iterator::operator->() const
1472
1473 Returns a pointer to a modifiable reference to the current pair's value.
1474*/
1475
1476/*!
1477 \fn bool QCborMap::Iterator::operator==(const Iterator &lhs, const Iterator &rhs)
1478 \fn bool QCborMap::Iterator::operator==(const Iterator &lhs, const ConstIterator &rhs)
1479
1480 Returns \c true if \a lhs points to the same entry in the map as \a rhs
1481 iterator; otherwise returns \c false.
1482
1483 \sa operator!=()
1484*/
1485
1486/*!
1487 \fn bool QCborMap::Iterator::operator!=(const Iterator &lhs, const Iterator &rhs)
1488 \fn bool QCborMap::Iterator::operator!=(const Iterator &lhs, const ConstIterator &rhs)
1489
1490 Returns \c true if \a lhs points to a different entry in the map than
1491 \a rhs iterator; otherwise returns \c false.
1492
1493 \sa operator==()
1494*/
1495
1496/*!
1497 \fn bool QCborMap::Iterator::operator<(const Iterator &lhs, const Iterator &rhs)
1498 \fn bool QCborMap::Iterator::operator<(const Iterator &lhs, const ConstIterator &rhs)
1499
1500 Returns \c true if the entry in the map pointed to by \a lhs iterator
1501 occurs before the entry pointed to by the \a rhs iterator.
1502*/
1503
1504/*!
1505 \fn bool QCborMap::Iterator::operator<=(const Iterator &lhs, const Iterator &rhs)
1506 \fn bool QCborMap::Iterator::operator<=(const Iterator &lhs, const ConstIterator &rhs)
1507
1508 Returns \c true if the entry in the map pointed to by \a lhs iterator
1509 occurs before or is the same entry as is pointed to by the \a rhs
1510 iterator.
1511*/
1512
1513/*!
1514 \fn bool QCborMap::Iterator::operator>(const Iterator &lhs, const Iterator &rhs)
1515 \fn bool QCborMap::Iterator::operator>(const Iterator &lhs, const ConstIterator &rhs)
1516
1517 Returns \c true if the entry in the map pointed to by \a lhs iterator
1518 occurs after the entry pointed to by the \a rhs iterator.
1519 */
1520
1521/*!
1522 \fn bool QCborMap::Iterator::operator>=(const Iterator &lhs, const Iterator &rhs)
1523 \fn bool QCborMap::Iterator::operator>=(const Iterator &lhs, const ConstIterator &rhs)
1524
1525 Returns \c true if the entry in the map pointed to by \a lhs iterator
1526 occurs after or is the same entry as is pointed to by the \a rhs
1527 iterator.
1528*/
1529
1530/*!
1531 \fn QCborMap::Iterator &QCborMap::Iterator::operator++()
1532
1533 The prefix \c{++} operator, \c{++i}, advances the iterator to the next item in
1534 the map and returns this iterator.
1535
1536 Calling this function on QCborMap::end() leads to undefined results.
1537
1538 \sa operator--()
1539*/
1540
1541/*!
1542 \fn QCborMap::Iterator QCborMap::Iterator::operator++(int)
1543 \overload
1544
1545 The postfix \c{++} operator, \c{i++}, advances the iterator to the next item in
1546 the map and returns an iterator to the previously current item.
1547*/
1548
1549/*!
1550 \fn QCborMap::Iterator QCborMap::Iterator::operator--()
1551
1552 The prefix \c{--} operator, \c{--i}, makes the preceding item current and
1553 returns this iterator.
1554
1555 Calling this function on QCborMap::begin() leads to undefined results.
1556
1557 \sa operator++()
1558*/
1559
1560/*!
1561 \fn QCborMap::Iterator QCborMap::Iterator::operator--(int)
1562 \overload
1563
1564 The postfix \c{--} operator, \c{i--}, makes the preceding item current and
1565 returns an iterator pointing to the previously current item.
1566*/
1567
1568/*!
1569 \fn QCborMap::Iterator QCborMap::Iterator::operator+(qsizetype j) const
1570
1571 Returns an iterator to the item at \a j positions forward from this
1572 iterator. If \a j is negative, the iterator goes backward.
1573
1574 \sa operator-()
1575*/
1576
1577/*!
1578 \fn QCborMap::Iterator QCborMap::Iterator::operator-(qsizetype j) const
1579
1580 Returns an iterator to the item at \a j positions backward from this
1581 iterator. If \a j is negative, the iterator goes forward.
1582
1583 \sa operator+()
1584*/
1585
1586/*!
1587 \fn qsizetype QCborMap::Iterator::operator-(QCborMap::Iterator j) const
1588
1589 Returns the position of the item at iterator \a j relative to the item
1590 at this iterator. If the item at \a j is forward of this time, the returned
1591 value is negative.
1592
1593 \sa operator+()
1594*/
1595
1596/*!
1597 \fn QCborMap::Iterator &QCborMap::Iterator::operator+=(qsizetype j)
1598
1599 Advances the iterator by \a j items. If \a j is negative, the iterator goes
1600 backward. Returns a reference to this iterator.
1601
1602 \sa operator-=(), operator+()
1603*/
1604
1605/*!
1606 \fn QCborMap::Iterator &QCborMap::Iterator::operator-=(qsizetype j)
1607
1608 Makes the iterator go back by \a j items. If \a j is negative, the iterator
1609 goes forward. Returns a reference to this iterator.
1610
1611 \sa operator+=(), operator-()
1612*/
1613
1614/*!
1615 \class QCborMap::ConstIterator
1616 \inmodule QtCore
1617 \ingroup cbor
1618 \since 5.12
1619
1620 \brief The QCborMap::ConstIterator class provides an STL-style const iterator for QCborMap.
1621
1622 \compares strong
1623 \compareswith strong Iterator
1624 \endcompareswith
1625
1626 QCborMap::ConstIterator allows you to iterate over a QCborMap. If you want
1627 to modify the QCborMap as you iterate over it, you must use
1628 QCborMap::Iterator instead. It is generally good practice to use
1629 QCborMap::ConstIterator, even on a non-const QCborMap, when you don't need
1630 to change the QCborMap through the iterator. Const iterators are slightly
1631 faster and improve code readability.
1632
1633 You must initialize the iterator using a QCborMap function like
1634 QCborMap::begin(), QCborMap::end(), or QCborMap::find() before you can
1635 start iterating..
1636
1637 Multiple iterators can be used on the same object. Existing iterators
1638 will however become dangling if the object gets modified.
1639
1640 \sa QCborMap::Iterator
1641*/
1642
1643/*!
1644 \typedef QCborMap::ConstIterator::difference_type
1645 \internal
1646*/
1647
1648/*!
1649 \typedef QCborMap::ConstIterator::iterator_category
1650
1651 A synonym for \e {std::random_access_iterator_tag} indicating
1652 this iterator is a random-access iterator.
1653*/
1654
1655/*!
1656 \typedef QCborMap::ConstIterator::reference
1657 \internal
1658*/
1659
1660/*!
1661 \typedef QCborMap::ConstIterator::value_type
1662 \internal
1663*/
1664
1665/*!
1666 \typedef QCborMap::ConstIterator::pointer
1667 \internal
1668*/
1669
1670/*!
1671 \fn QCborMap::ConstIterator::ConstIterator()
1672
1673 Constructs an uninitialized iterator.
1674
1675 Functions like key(), value(), and operator++() must not be
1676 called on an uninitialized iterator. Use operator=() to assign a
1677 value to it before using it.
1678
1679 \sa QCborMap::constBegin(), QCborMap::constEnd()
1680*/
1681
1682/*!
1683 \fn QCborMap::ConstIterator::ConstIterator(const ConstIterator &other)
1684
1685 Constructs an iterator as a copy of \a other.
1686 */
1687
1688/*!
1689 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator=(const ConstIterator &other)
1690
1691 Makes this iterator a copy of \a other and returns a reference to this
1692 iterator.
1693 */
1694
1695/*!
1696 \fn QString QCborMap::ConstIterator::key() const
1697
1698 Returns the current item's key.
1699
1700 \sa value()
1701*/
1702
1703/*!
1704 \fn QCborValue QCborMap::ConstIterator::value() const
1705
1706 Returns the current item's value.
1707
1708 \sa key(), operator*()
1709*/
1710
1711/*!
1712 \fn QCborMap::ConstIterator::value_type QCborMap::ConstIterator::operator*() const
1713
1714 Returns a pair containing the current item's key and value.
1715
1716 \sa key(), value()
1717 */
1718
1719/*!
1720 \fn const QCborValueRef *QCborMap::ConstIterator::operator->() const
1721
1722 Returns a pointer to the current pair's value.
1723 */
1724
1725/*!
1726 \fn bool QCborMap::ConstIterator::operator==(const ConstIterator &lhs, const ConstIterator &rhs)
1727
1728 Returns \c true if \a lhs points to the same entry in the map as \a rhs
1729 iterator; otherwise returns \c false.
1730
1731 \sa operator!=()
1732*/
1733
1734/*!
1735 \fn bool QCborMap::ConstIterator::operator!=(const ConstIterator &lhs, const ConstIterator &rhs)
1736
1737 Returns \c true if \a lhs points to a different entry in the map than
1738 \a rhs iterator; otherwise returns \c false.
1739
1740 \sa operator==()
1741 */
1742
1743/*!
1744 \fn bool QCborMap::ConstIterator::operator<(const ConstIterator &lhs, const ConstIterator &rhs)
1745
1746 Returns \c true if the entry in the map pointed to by \a lhs iterator
1747 occurs before the entry pointed to by the \a rhs iterator.
1748*/
1749
1750/*!
1751 \fn bool QCborMap::ConstIterator::operator<=(const ConstIterator &lhs, const ConstIterator &rhs)
1752
1753 Returns \c true if the entry in the map pointed to by \a lhs iterator
1754 occurs before or is the same entry as is pointed to by the \a rhs
1755 iterator.
1756*/
1757
1758/*!
1759 \fn bool QCborMap::ConstIterator::operator>(const ConstIterator &lhs, const ConstIterator &rhs)
1760
1761 Returns \c true if the entry in the map pointed to by \a lhs iterator
1762 occurs after the entry pointed to by the \a rhs iterator.
1763*/
1764
1765/*!
1766 \fn bool QCborMap::ConstIterator::operator>=(const ConstIterator &lhs, const ConstIterator &rhs)
1767
1768 Returns \c true if the entry in the map pointed to by \a lhs iterator
1769 occurs after or is the same entry as is pointed to by the \a rhs
1770 iterator.
1771*/
1772
1773/*!
1774 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator++()
1775
1776 The prefix \c{++} operator, \c{++i}, advances the iterator to the next item in
1777 the map and returns this iterator.
1778
1779 Calling this function on QCborMap::end() leads to undefined results.
1780
1781 \sa operator--()
1782*/
1783
1784/*!
1785 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator++(int)
1786 \overload
1787
1788 The postfix \c{++} operator, \c{i++}, advances the iterator to the next item in
1789 the map and returns an iterator to the previously current item.
1790 */
1791
1792/*!
1793 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator--()
1794
1795 The prefix \c{--} operator, \c{--i}, makes the preceding item current and
1796 returns this iterator.
1797
1798 Calling this function on QCborMap::begin() leads to undefined results.
1799
1800 \sa operator++()
1801*/
1802
1803/*!
1804 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator--(int)
1805 \overload
1806
1807 The postfix \c{--} operator, \c{i--}, makes the preceding item current and
1808 returns an iterator pointing to the previously current item.
1809 */
1810
1811/*!
1812 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator+(qsizetype j) const
1813
1814 Returns an iterator to the item at \a j positions forward from this
1815 iterator. If \a j is negative, the iterator goes backward.
1816
1817 \sa operator-()
1818*/
1819
1820/*!
1821 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator-(qsizetype j) const
1822
1823 Returns an iterator to the item at \a j positions backward from this
1824 iterator. If \a j is negative, the iterator goes forward.
1825
1826 \sa operator+()
1827*/
1828
1829/*!
1830 \fn qsizetype QCborMap::ConstIterator::operator-(QCborMap::ConstIterator j) const
1831
1832 Returns the position of the item at iterator \a j relative to the item
1833 at this iterator. If the item at \a j is forward of this time, the returned
1834 value is negative.
1835
1836 \sa operator+()
1837*/
1838
1839/*!
1840 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator+=(qsizetype j)
1841
1842 Advances the iterator by \a j items. If \a j is negative, the iterator goes
1843 backward. Returns a reference to this iterator.
1844
1845 \sa operator-=(), operator+()
1846*/
1847
1848/*!
1849 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator-=(qsizetype j)
1850
1851 Makes the iterator go back by \a j items. If \a j is negative, the iterator
1852 goes forward. Returns a reference to this iterator.
1853
1854 \sa operator+=(), operator-()
1855*/
1856
1857size_t qHash(const QCborMap &map, size_t seed)
1858{
1859 return qHashRange(first: map.begin(), last: map.end(), seed);
1860}
1861
1862#if !defined(QT_NO_DEBUG_STREAM)
1863QDebug operator<<(QDebug dbg, const QCborMap &m)
1864{
1865 QDebugStateSaver saver(dbg);
1866 dbg.nospace() << "QCborMap{";
1867 const char *open = "{";
1868 for (auto pair : m) {
1869 dbg << open << pair.first << ", " << pair.second << '}';
1870 open = ", {";
1871 }
1872 return dbg << '}';
1873}
1874#endif
1875
1876#ifndef QT_NO_DATASTREAM
1877#if QT_CONFIG(cborstreamwriter)
1878QDataStream &operator<<(QDataStream &stream, const QCborMap &value)
1879{
1880 stream << value.toCborValue().toCbor();
1881 return stream;
1882}
1883#endif
1884
1885QDataStream &operator>>(QDataStream &stream, QCborMap &value)
1886{
1887 QByteArray buffer;
1888 stream >> buffer;
1889 QCborParserError parseError{};
1890 value = QCborValue::fromCbor(ba: buffer, error: &parseError).toMap();
1891 if (parseError.error)
1892 stream.setStatus(QDataStream::ReadCorruptData);
1893 return stream;
1894}
1895#endif
1896
1897QT_END_NAMESPACE
1898

source code of qtbase/src/corelib/serialization/qcbormap.cpp