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