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 */
301QVector<QCborValue> QCborMap::keys() const
302{
303 QVector<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 auto it = constFind(key);
838 if (it != constEnd())
839 detach();
840 return { d.data(), it.item.i };
841}
842
843/*!
844 \fn QCborMap::iterator QCborMap::find(QLatin1String key)
845 \fn QCborMap::const_iterator QCborMap::find(QLatin1String key) const
846 \overload
847
848 Returns a map iterator to the key-value pair whose key is \a key, if the
849 map contains such a pair. If it doesn't, this function returns end().
850
851 If the map contains more than one key equal to \a key, it is undefined
852 which one this function will find. QCborMap does not allow inserting
853 duplicate keys, but it is possible to create such a map by decoding a CBOR
854 stream with them. They are usually not permitted and having duplicate keys
855 is usually an indication of a problem in the sender.
856
857 \sa value(QLatin1String), operator[](QLatin1String), constFind(QLatin1String),
858 remove(QLatin1String), contains(QLatin1String)
859 value(qint64), value(const QString &), value(const QCborValue &)
860 */
861QCborMap::iterator QCborMap::find(QLatin1String key)
862{
863 auto it = constFind(key);
864 if (it != constEnd())
865 detach();
866 return { d.data(), it.item.i };
867}
868
869/*!
870 \fn QCborMap::iterator QCborMap::find(const QString & key)
871 \fn QCborMap::const_iterator QCborMap::find(const QString & key) const
872 \overload
873
874 Returns a map iterator to the key-value pair whose key is \a key, if the
875 map contains such a pair. If it doesn't, this function returns end().
876
877 If the map contains more than one key equal to \a key, it is undefined
878 which one this function will find. QCborMap does not allow inserting
879 duplicate keys, but it is possible to create such a map by decoding a CBOR
880 stream with them. They are usually not permitted and having duplicate keys
881 is usually an indication of a problem in the sender.
882
883 \sa value(const QString &), operator[](const QString &), constFind(const QString &),
884 remove(const QString &), contains(const QString &)
885 value(qint64), value(QLatin1String), value(const QCborValue &)
886 */
887QCborMap::iterator QCborMap::find(const QString & key)
888{
889 auto it = constFind(key);
890 if (it != constEnd())
891 detach();
892 return { d.data(), it.item.i };
893}
894
895/*!
896 \fn QCborMap::iterator QCborMap::find(const QCborValue &key)
897 \fn QCborMap::const_iterator QCborMap::find(const QCborValue &key) const
898 \overload
899
900 Returns a map iterator to the key-value pair whose key is \a key, if the
901 map contains such a pair. If it doesn't, this function returns end().
902
903 If the map contains more than one key equal to \a key, it is undefined
904 which one this function will find. QCborMap does not allow inserting
905 duplicate keys, but it is possible to create such a map by decoding a CBOR
906 stream with them. They are usually not permitted and having duplicate keys
907 is usually an indication of a problem in the sender.
908
909 \sa value(const QCborValue &), operator[](const QCborValue &), constFind(const QCborValue &),
910 remove(const QCborValue &), contains(const QCborValue &)
911 value(qint64), value(QLatin1String), value(const QString &)
912 */
913QCborMap::iterator QCborMap::find(const QCborValue &key)
914{
915 auto it = constFind(key);
916 if (it != constEnd())
917 detach();
918 return { d.data(), it.item.i };
919}
920
921/*!
922 Returns a map iterator to the key-value pair whose key is \a key, if the
923 map contains such a pair. If it doesn't, this function returns constEnd().
924
925 CBOR recommends using integer keys, since they occupy less
926 space and are simpler to encode and decode.
927
928 If the map contains more than one key equal to \a key, it is undefined
929 which one this function will find. QCborMap does not allow inserting
930 duplicate keys, but it is possible to create such a map by decoding a CBOR
931 stream with them. They are usually not permitted and having duplicate keys
932 is usually an indication of a problem in the sender.
933
934 \sa value(qint64), operator[](qint64), find(qint64), remove(qint64), contains(qint64)
935 value(QLatin1String), value(const QString &), value(const QCborValue &)
936 */
937QCborMap::const_iterator QCborMap::constFind(qint64 key) const
938{
939 for (qsizetype i = 0; i < 2 * size(); i += 2) {
940 const auto &e = d->elements.at(i);
941 if (e.type == QCborValue::Integer && e.value == key)
942 return { d.data(), i + 1 };
943 }
944 return constEnd();
945}
946
947/*!
948 \overload
949
950 Returns a map iterator to the key-value pair whose key is \a key, if the
951 map contains such a pair. If it doesn't, this function returns constEnd().
952
953 If the map contains more than one key equal to \a key, it is undefined
954 which one this function will find. QCborMap does not allow inserting
955 duplicate keys, but it is possible to create such a map by decoding a CBOR
956 stream with them. They are usually not permitted and having duplicate keys
957 is usually an indication of a problem in the sender.
958
959 \sa value(QLatin1String), operator[](QLatin1String), find(QLatin1String),
960 remove(QLatin1String), contains(QLatin1String)
961 value(qint64), value(const QString &), value(const QCborValue &)
962 */
963QCborMap::const_iterator QCborMap::constFind(QLatin1String key) const
964{
965 for (qsizetype i = 0; i < 2 * size(); i += 2) {
966 if (d->stringEqualsElement(i, key))
967 return { d.data(), i + 1 };
968 }
969 return constEnd();
970}
971
972/*!
973 \overload
974
975 Returns a map iterator to the key-value pair whose key is \a key, if the
976 map contains such a pair. If it doesn't, this function returns constEnd().
977
978 If the map contains more than one key equal to \a key, it is undefined
979 which one this function will find. QCborMap does not allow inserting
980 duplicate keys, but it is possible to create such a map by decoding a CBOR
981 stream with them. They are usually not permitted and having duplicate keys
982 is usually an indication of a problem in the sender.
983
984 \sa value(const QString &), operator[](const QString &), find(const QString &),
985 remove(const QString &), contains(const QString &)
986 value(qint64), value(QLatin1String), value(const QCborValue &)
987 */
988QCborMap::const_iterator QCborMap::constFind(const QString & key) const
989{
990 for (qsizetype i = 0; i < 2 * size(); i += 2) {
991 if (d->stringEqualsElement(i, key))
992 return { d.data(), i + 1 };
993 }
994 return constEnd();
995}
996
997/*!
998 \overload
999
1000 Returns a map iterator to the key-value pair whose key is \a key, if the
1001 map contains such a pair. If it doesn't, this function returns constEnd().
1002
1003 If the map contains more than one key equal to \a key, it is undefined
1004 which one this function will find. QCborMap does not allow inserting
1005 duplicate keys, but it is possible to create such a map by decoding a CBOR
1006 stream with them. They are usually not permitted and having duplicate keys
1007 is usually an indication of a problem in the sender.
1008
1009 \sa value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &),
1010 remove(const QCborValue &), contains(const QCborValue &),
1011 value(qint64), value(QLatin1String), value(const QString &)
1012 */
1013QCborMap::const_iterator QCborMap::constFind(const QCborValue &key) const
1014{
1015 for (qsizetype i = 0; i < 2 * size(); i += 2) {
1016 int cmp = d->compareElement(i, key);
1017 if (cmp == 0)
1018 return { d.data(), i + 1 };
1019 }
1020 return constEnd();
1021}
1022
1023/*!
1024 \fn QCborMap::iterator QCborMap::insert(qint64 key, const QCborValue &value)
1025 \overload
1026
1027 Inserts the key \a key and value \a value into this map and returns a map
1028 iterator pointing to the newly inserted pair.
1029
1030 If the map already had a key equal to \a key, its value will be overwritten
1031 by \a value.
1032
1033 \sa erase(), remove(qint64), value(qint64), operator[](qint64), find(qint64),
1034 contains(qint64), take(qint64), extract()
1035 */
1036
1037/*!
1038 \fn QCborMap::iterator QCborMap::insert(QLatin1String key, const QCborValue &value)
1039 \overload
1040
1041 Inserts the key \a key and value \a value into this map and returns a map
1042 iterator pointing to the newly inserted pair.
1043
1044 If the map already had a key equal to \a key, its value will be overwritten
1045 by \a value.
1046
1047 \sa erase(), remove(QLatin1String), value(QLatin1String), operator[](QLatin1String),
1048 find(QLatin1String), contains(QLatin1String), take(QLatin1String), extract()
1049 */
1050
1051/*!
1052 \fn QCborMap::iterator QCborMap::insert(const QString &key, const QCborValue &value)
1053 \overload
1054
1055 Inserts the key \a key and value \a value into this map and returns a map
1056 iterator pointing to the newly inserted pair.
1057
1058 If the map already had a key equal to \a key, its value will be overwritten
1059 by \a value.
1060
1061 \sa erase(), remove(const QString &), value(const QString &), operator[](const QString &),
1062 find(const QString &), contains(const QString &), take(const QString &), extract()
1063 */
1064
1065/*!
1066 \fn QCborMap::iterator QCborMap::insert(const QCborValue &key, const QCborValue &value)
1067 \overload
1068
1069 Inserts the key \a key and value \a value into this map and returns a map
1070 iterator pointing to the newly inserted pair.
1071
1072 If the map already had a key equal to \a key, its value will be overwritten
1073 by \a value.
1074
1075 \sa erase(), remove(const QCborValue &), value(const QCborValue &), operator[](const QCborValue &),
1076 find(const QCborValue &), contains(const QCborValue &), take(const QCborValue &), extract()
1077 */
1078
1079/*!
1080 \fn QCborMap::iterator QCborMap::insert(value_type v)
1081 \overload
1082
1083 Inserts the key-value pair in \a v into this map and returns a map iterator
1084 pointing to the newly inserted pair.
1085
1086 If the map already had a key equal to \c{v.first}, its value will be
1087 overwritten by \c{v.second}.
1088
1089 \sa operator[], erase(), extract()
1090 */
1091
1092
1093/*!
1094 \fn QCborMap::iterator QCborMap::erase(const_iterator it)
1095
1096 Removes the key-value pair pointed to by the map iterator \a it and returns a
1097 pointer to the next element, after removal.
1098
1099 \sa remove(), begin(), end(), insert(), extract()
1100 */
1101
1102/*!
1103 \overload
1104
1105 Removes the key-value pair pointed to by the map iterator \a it and returns a
1106 pointer to the next element, after removal.
1107
1108 \sa remove(), begin(), end(), insert()
1109 */
1110QCborMap::iterator QCborMap::erase(QCborMap::iterator it)
1111{
1112 detach();
1113
1114 // remove both key and value
1115 // ### optimize?
1116 d->removeAt(it.item.i - 1);
1117 d->removeAt(it.item.i - 1);
1118 return it;
1119}
1120
1121/*!
1122 \fn QCborValue QCborMap::extract(iterator it)
1123 \fn QCborValue QCborMap::extract(const_iterator it)
1124
1125 Extracts a value from the map at the position indicated by iterator \a it
1126 and returns the value so extracted.
1127
1128 \sa insert(), erase(), take(), remove()
1129 */
1130QCborValue QCborMap::extract(iterator it)
1131{
1132 detach();
1133 QCborValue v = d->extractAt(it.item.i);
1134 // remove both key and value
1135 // ### optimize?
1136 d->removeAt(it.item.i - 1);
1137 d->removeAt(it.item.i - 1);
1138
1139 return v;
1140}
1141
1142/*!
1143 \fn bool QCborMap::empty() const
1144
1145 Synonym for isEmpty(). This function is provided for compatibility with
1146 generic code that uses the Standard Library API.
1147
1148 Returns true if this map is empty (size() == 0).
1149
1150 \sa isEmpty(), size()
1151 */
1152
1153/*!
1154 \fn int QCborMap::compare(const QCborMap &other) const
1155
1156 Compares this map and \a other, comparing each element in sequence, and
1157 returns an integer that indicates whether this map should be sorted prior
1158 to (if the result is negative) or after \a other (if the result is
1159 positive). If this function returns 0, the two maps are equal and contain
1160 the same elements.
1161
1162 Note that CBOR maps are unordered, which means that two maps containing the
1163 very same pairs but in different order will still compare differently. To
1164 avoid this, it is recommended to insert elements into the map in a
1165 predictable order, such as by ascending key value. In fact, maps with keys
1166 in sorted order are required for Canonical CBOR representation.
1167
1168 For more information on CBOR sorting order, see QCborValue::compare().
1169
1170 \sa QCborValue::compare(), QCborArray::compare(), operator==()
1171 */
1172
1173/*!
1174 \fn bool QCborMap::operator==(const QCborMap &other) const
1175
1176 Compares this map and \a other, comparing each element in sequence, and
1177 returns true if the two maps contains the same elements in the same order,
1178 false otherwise.
1179
1180 Note that CBOR maps are unordered, which means that two maps containing the
1181 very same pairs but in different order will still compare differently. To
1182 avoid this, it is recommended to insert elements into the map in a
1183 predictable order, such as by ascending key value. In fact, maps with keys
1184 in sorted order are required for Canonical CBOR representation.
1185
1186 For more information on CBOR equality in Qt, see, QCborValue::compare().
1187
1188 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1189 operator!=(), operator<()
1190 */
1191
1192/*!
1193 \fn bool QCborMap::operator!=(const QCborMap &other) const
1194
1195 Compares this map and \a other, comparing each element in sequence, and
1196 returns true if the two maps contains any different elements or elements in
1197 different orders, false otherwise.
1198
1199 Note that CBOR maps are unordered, which means that two maps containing the
1200 very same pairs but in different order will still compare differently. To
1201 avoid this, it is recommended to insert elements into the map in a
1202 predictable order, such as by ascending key value. In fact, maps with keys
1203 in sorted order are required for Canonical CBOR representation.
1204
1205 For more information on CBOR equality in Qt, see, QCborValue::compare().
1206
1207 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1208 operator==(), operator<()
1209 */
1210
1211/*!
1212 \fn bool QCborMap::operator<(const QCborMap &other) const
1213
1214 Compares this map and \a other, comparing each element in sequence, and
1215 returns true if this map should be sorted before \a other, false
1216 otherwise.
1217
1218 Note that CBOR maps are unordered, which means that two maps containing the
1219 very same pairs but in different order will still compare differently. To
1220 avoid this, it is recommended to insert elements into the map in a
1221 predictable order, such as by ascending key value. In fact, maps with keys
1222 in sorted order are required for Canonical CBOR representation.
1223
1224 For more information on CBOR sorting order, see QCborValue::compare().
1225
1226 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
1227 operator==(), operator!=()
1228 */
1229
1230void QCborMap::detach(qsizetype reserved)
1231{
1232 d = QCborContainerPrivate::detach(d.data(), reserved ? reserved : size() * 2);
1233}
1234
1235/*!
1236 \class QCborMap::Iterator
1237 \inmodule QtCore
1238 \ingroup cbor
1239 \reentrant
1240 \since 5.12
1241
1242 \brief The QCborMap::Iterator class provides an STL-style non-const iterator for QCborMap.
1243
1244 QCborMap::Iterator allows you to iterate over a QCborMap and to modify the
1245 value (but not the key) stored under a particular key. If you want to
1246 iterate over a const QCborMap, you should use QCborMap::ConstIterator. It
1247 is generally good practice to use QCborMap::ConstIterator on a non-const
1248 QCborMap as well, unless you need to change the QCborMap through the
1249 iterator. Const iterators are slightly faster, and improve code
1250 readability.
1251
1252 You must initialize the iterator using a QCborMap function like
1253 QCborMap::begin(), QCborMap::end(), or QCborMap::find() before you can
1254 start iterating..
1255
1256 Multiple iterators can be used on the same object. Existing iterators will however
1257 become dangling once the object gets modified.
1258
1259 \sa QCborMap::ConstIterator
1260*/
1261
1262/*!
1263 \typedef QCborMap::Iterator::difference_type
1264 \internal
1265*/
1266
1267/*!
1268 \typedef QCborMap::Iterator::iterator_category
1269
1270 A synonym for \e {std::random_access_iterator_tag} indicating
1271 this iterator is a random-access iterator.
1272*/
1273
1274/*!
1275 \typedef QCborMap::Iterator::reference
1276 \internal
1277*/
1278
1279/*!
1280 \typedef QCborMap::Iterator::value_type
1281 \internal
1282*/
1283
1284/*!
1285 \typedef QCborMap::Iterator::pointer
1286 \internal
1287*/
1288
1289/*!
1290 \fn QCborMap::Iterator::Iterator()
1291
1292 Constructs an uninitialized iterator.
1293
1294 Functions like key(), value(), and operator++() must not be
1295 called on an uninitialized iterator. Use operator=() to assign a
1296 value to it before using it.
1297
1298 \sa QCborMap::begin(), QCborMap::end()
1299*/
1300
1301/*!
1302 \fn QCborMap::Iterator::Iterator(const Iterator &other)
1303
1304 Constructs an iterator as a copy of \a other.
1305 */
1306
1307/*!
1308 \fn QCborMap::Iterator &QCborMap::Iterator::operator=(const Iterator &other)
1309
1310 Makes this iterator a copy of \a other and returns a reference to this
1311 iterator.
1312 */
1313
1314/*!
1315 \fn QCborValue QCborMap::Iterator::key() const
1316
1317 Returns the current item's key.
1318
1319 There is no direct way of changing an item's key through an iterator,
1320 although it can be done by calling QCborMap::erase() followed by
1321 QCborMap::insert().
1322
1323 \sa value()
1324*/
1325
1326/*!
1327 \fn QCborValueRef QCborMap::Iterator::value() const
1328
1329 Returns a modifiable reference to the current item's value.
1330
1331 You can change the value for a key by using value() on the left side of an
1332 assignment.
1333
1334 The return value is of type QCborValueRef, a helper class for QCborArray
1335 and QCborMap. When you get an object of type QCborValueRef, you can use it
1336 as if it were a reference to a QCborValue. If you assign to it, the
1337 assignment will apply to the element in the QCborArray or QCborMap from
1338 which you got the reference.
1339
1340 \sa key(), operator*()
1341*/
1342
1343/*!
1344 \fn QCborMap::Iterator::value_type QCborMap::Iterator::operator*() const
1345
1346 Returns a pair containing the current item's key and a modifiable reference
1347 to the current item's value.
1348
1349 The second element of the pair is of type QCborValueRef, a helper class for
1350 QCborArray and QCborMap. When you get an object of type QCborValueRef, you
1351 can use it as if it were a reference to a QCborValue. If you assign to it,
1352 the assignment will apply to the element in the QCborArray or QCborMap from
1353 which you got the reference.
1354
1355 \sa key(), value()
1356*/
1357
1358/*!
1359 \fn QCborValueRef *QCborMap::Iterator::operator->() const
1360
1361 Returns a pointer to a modifiable reference to the current pair's value.
1362*/
1363
1364/*!
1365 \fn bool QCborMap::Iterator::operator==(const Iterator &other) const
1366 \fn bool QCborMap::Iterator::operator==(const ConstIterator &other) const
1367
1368 Returns \c true if \a other points to the same entry in the map as this
1369 iterator; otherwise returns \c false.
1370
1371 \sa operator!=()
1372*/
1373
1374/*!
1375 \fn bool QCborMap::Iterator::operator!=(const Iterator &other) const
1376 \fn bool QCborMap::Iterator::operator!=(const ConstIterator &other) const
1377
1378 Returns \c true if \a other points to a different entry in the map than
1379 this iterator; otherwise returns \c false.
1380
1381 \sa operator==()
1382*/
1383
1384/*!
1385 \fn bool QCborMap::Iterator::operator<(const Iterator& other) const
1386 \fn bool QCborMap::Iterator::operator<(const ConstIterator& other) const
1387
1388 Returns \c true if the entry in the map pointed to by this iterator
1389 occurs before the entry pointed to by the \a other iterator.
1390*/
1391
1392/*!
1393 \fn bool QCborMap::Iterator::operator<=(const Iterator& other) const
1394 \fn bool QCborMap::Iterator::operator<=(const ConstIterator& other) const
1395
1396 Returns \c true if the entry in the map pointed to by this iterator
1397 occurs before or is the same entry as is pointed to by the \a other
1398 iterator.
1399*/
1400
1401/*!
1402 \fn bool QCborMap::Iterator::operator>(const Iterator& other) const
1403 \fn bool QCborMap::Iterator::operator>(const ConstIterator& other) const
1404
1405 Returns \c true if the entry in the map pointed to by this iterator
1406 occurs after the entry pointed to by the \a other iterator.
1407 */
1408
1409/*!
1410 \fn bool QCborMap::Iterator::operator>=(const Iterator& other) const
1411 \fn bool QCborMap::Iterator::operator>=(const ConstIterator& other) const
1412
1413 Returns \c true if the entry in the map pointed to by this iterator
1414 occurs after or is the same entry as is pointed to by the \a other
1415 iterator.
1416*/
1417
1418/*!
1419 \fn QCborMap::Iterator &QCborMap::Iterator::operator++()
1420
1421 The prefix ++ operator, \c{++i}, advances the iterator to the next item in
1422 the map and returns this iterator.
1423
1424 Calling this function on QCborMap::end() leads to undefined results.
1425
1426 \sa operator--()
1427*/
1428
1429/*!
1430 \fn QCborMap::Iterator QCborMap::Iterator::operator++(int)
1431 \overload
1432
1433 The postfix ++ operator, \c{i++}, advances the iterator to the next item in
1434 the map and returns an iterator to the previously current item.
1435*/
1436
1437/*!
1438 \fn QCborMap::Iterator QCborMap::Iterator::operator--()
1439
1440 The prefix -- operator, \c{--i}, makes the preceding item current and
1441 returns this iterator.
1442
1443 Calling this function on QCborMap::begin() leads to undefined results.
1444
1445 \sa operator++()
1446*/
1447
1448/*!
1449 \fn QCborMap::Iterator QCborMap::Iterator::operator--(int)
1450 \overload
1451
1452 The postfix -- operator, \c{i--}, makes the preceding item current and
1453 returns an iterator pointing to the previously current item.
1454*/
1455
1456/*!
1457 \fn QCborMap::Iterator QCborMap::Iterator::operator+(qsizetype j) const
1458
1459 Returns an iterator to the item at \a j positions forward from this
1460 iterator. If \a j is negative, the iterator goes backward.
1461
1462 \sa operator-()
1463*/
1464
1465/*!
1466 \fn QCborMap::Iterator QCborMap::Iterator::operator-(qsizetype j) const
1467
1468 Returns an iterator to the item at \a j positions backward from this
1469 iterator. If \a j is negative, the iterator goes forward.
1470
1471 \sa operator+()
1472*/
1473
1474/*!
1475 \fn qsizetype QCborMap::Iterator::operator-(QCborMap::Iterator j) const
1476
1477 Returns the position of the item at iterator \a j relative to the item
1478 at this iterator. If the item at \a j is forward of this time, the returned
1479 value is negative.
1480
1481 \sa operator+()
1482*/
1483
1484/*!
1485 \fn QCborMap::Iterator &QCborMap::Iterator::operator+=(qsizetype j)
1486
1487 Advances the iterator by \a j items. If \a j is negative, the iterator goes
1488 backward. Returns a reference to this iterator.
1489
1490 \sa operator-=(), operator+()
1491*/
1492
1493/*!
1494 \fn QCborMap::Iterator &QCborMap::Iterator::operator-=(qsizetype j)
1495
1496 Makes the iterator go back by \a j items. If \a j is negative, the iterator
1497 goes forward. Returns a reference to this iterator.
1498
1499 \sa operator+=(), operator-()
1500*/
1501
1502/*!
1503 \class QCborMap::ConstIterator
1504 \inmodule QtCore
1505 \ingroup cbor
1506 \since 5.12
1507
1508 \brief The QCborMap::ConstIterator class provides an STL-style const iterator for QCborMap.
1509
1510 QCborMap::ConstIterator allows you to iterate over a QCborMap. If you want
1511 to modify the QCborMap as you iterate over it, you must use
1512 QCborMap::Iterator instead. It is generally good practice to use
1513 QCborMap::ConstIterator, even on a non-const QCborMap, when you don't need
1514 to change the QCborMap through the iterator. Const iterators are slightly
1515 faster and improve code readability.
1516
1517 You must initialize the iterator using a QCborMap function like
1518 QCborMap::begin(), QCborMap::end(), or QCborMap::find() before you can
1519 start iterating..
1520
1521 Multiple iterators can be used on the same object. Existing iterators
1522 will however become dangling if the object gets modified.
1523
1524 \sa QCborMap::Iterator
1525*/
1526
1527/*!
1528 \typedef QCborMap::ConstIterator::difference_type
1529 \internal
1530*/
1531
1532/*!
1533 \typedef QCborMap::ConstIterator::iterator_category
1534
1535 A synonym for \e {std::random_access_iterator_tag} indicating
1536 this iterator is a random-access iterator.
1537*/
1538
1539/*!
1540 \typedef QCborMap::ConstIterator::reference
1541 \internal
1542*/
1543
1544/*!
1545 \typedef QCborMap::ConstIterator::value_type
1546 \internal
1547*/
1548
1549/*!
1550 \typedef QCborMap::ConstIterator::pointer
1551 \internal
1552*/
1553
1554/*!
1555 \fn QCborMap::ConstIterator::ConstIterator()
1556
1557 Constructs an uninitialized iterator.
1558
1559 Functions like key(), value(), and operator++() must not be
1560 called on an uninitialized iterator. Use operator=() to assign a
1561 value to it before using it.
1562
1563 \sa QCborMap::constBegin(), QCborMap::constEnd()
1564*/
1565
1566/*!
1567 \fn QCborMap::ConstIterator::ConstIterator(const ConstIterator &other)
1568
1569 Constructs an iterator as a copy of \a other.
1570 */
1571
1572/*!
1573 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator=(const ConstIterator &other)
1574
1575 Makes this iterator a copy of \a other and returns a reference to this
1576 iterator.
1577 */
1578
1579/*!
1580 \fn QString QCborMap::ConstIterator::key() const
1581
1582 Returns the current item's key.
1583
1584 \sa value()
1585*/
1586
1587/*!
1588 \fn QCborValue QCborMap::ConstIterator::value() const
1589
1590 Returns the current item's value.
1591
1592 \sa key(), operator*()
1593*/
1594
1595/*!
1596 \fn QCborMap::ConstIterator::value_type QCborMap::ConstIterator::operator*() const
1597
1598 Returns a pair containing the curent item's key and value.
1599
1600 \sa key(), value()
1601 */
1602
1603/*!
1604 \fn const QCborValueRef *QCborMap::ConstIterator::operator->() const
1605
1606 Returns a pointer to the current pair's value.
1607 */
1608
1609/*!
1610 \fn bool QCborMap::ConstIterator::operator==(const ConstIterator &other) const
1611 \fn bool QCborMap::ConstIterator::operator==(const Iterator &other) const
1612
1613 Returns \c true if \a other points to the same entry in the map as this
1614 iterator; otherwise returns \c false.
1615
1616 \sa operator!=()
1617*/
1618
1619/*!
1620 \fn bool QCborMap::ConstIterator::operator!=(const ConstIterator &other) const
1621 \fn bool QCborMap::ConstIterator::operator!=(const Iterator &other) const
1622
1623 Returns \c true if \a other points to a different entry in the map than
1624 this iterator; otherwise returns \c false.
1625
1626 \sa operator==()
1627 */
1628
1629/*!
1630 \fn bool QCborMap::ConstIterator::operator<(const Iterator &other) const
1631 \fn bool QCborMap::ConstIterator::operator<(const ConstIterator &other) const
1632
1633 Returns \c true if the entry in the map pointed to by this iterator
1634 occurs before the entry pointed to by the \a other iterator.
1635*/
1636
1637/*!
1638 \fn bool QCborMap::ConstIterator::operator<=(const Iterator &other) const
1639 \fn bool QCborMap::ConstIterator::operator<=(const ConstIterator &other) const
1640
1641 Returns \c true if the entry in the map pointed to by this iterator
1642 occurs before or is the same entry as is pointed to by the \a other
1643 iterator.
1644*/
1645
1646/*!
1647 \fn bool QCborMap::ConstIterator::operator>(const Iterator &other) const
1648 \fn bool QCborMap::ConstIterator::operator>(const ConstIterator &other) const
1649
1650 Returns \c true if the entry in the map pointed to by this iterator
1651 occurs after the entry pointed to by the \a other iterator.
1652*/
1653
1654/*!
1655 \fn bool QCborMap::ConstIterator::operator>=(const Iterator &other) const
1656 \fn bool QCborMap::ConstIterator::operator>=(const ConstIterator &other) const
1657
1658 Returns \c true if the entry in the map pointed to by this iterator
1659 occurs after or is the same entry as is pointed to by the \a other
1660 iterator.
1661*/
1662
1663/*!
1664 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator++()
1665
1666 The prefix ++ operator, \c{++i}, advances the iterator to the next item in
1667 the map and returns this iterator.
1668
1669 Calling this function on QCborMap::end() leads to undefined results.
1670
1671 \sa operator--()
1672*/
1673
1674/*!
1675 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator++(int)
1676 \overload
1677
1678 The postfix ++ operator, \c{i++}, advances the iterator to the next item in
1679 the map and returns an iterator to the previously current item.
1680 */
1681
1682/*!
1683 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator--()
1684
1685 The prefix -- operator, \c{--i}, makes the preceding item current and
1686 returns this iterator.
1687
1688 Calling this function on QCborMap::begin() leads to undefined results.
1689
1690 \sa operator++()
1691*/
1692
1693/*!
1694 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator--(int)
1695 \overload
1696
1697 The postfix -- operator, \c{i--}, makes the preceding item current and
1698 returns an iterator pointing to the previously current item.
1699 */
1700
1701/*!
1702 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator+(qsizetype j) const
1703
1704 Returns an iterator to the item at \a j positions forward from this
1705 iterator. If \a j is negative, the iterator goes backward.
1706
1707 \sa operator-()
1708*/
1709
1710/*!
1711 \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator-(qsizetype j) const
1712
1713 Returns an iterator to the item at \a j positions backward from this
1714 iterator. If \a j is negative, the iterator goes forward.
1715
1716 \sa operator+()
1717*/
1718
1719/*!
1720 \fn qsizetype QCborMap::ConstIterator::operator-(QCborMap::ConstIterator j) const
1721
1722 Returns the position of the item at iterator \a j relative to the item
1723 at this iterator. If the item at \a j is forward of this time, the returned
1724 value is negative.
1725
1726 \sa operator+()
1727*/
1728
1729/*!
1730 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator+=(qsizetype j)
1731
1732 Advances the iterator by \a j items. If \a j is negative, the iterator goes
1733 backward. Returns a reference to this iterator.
1734
1735 \sa operator-=(), operator+()
1736*/
1737
1738/*!
1739 \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator-=(qsizetype j)
1740
1741 Makes the iterator go back by \a j items. If \a j is negative, the iterator
1742 goes forward. Returns a reference to this iterator.
1743
1744 \sa operator+=(), operator-()
1745*/
1746
1747uint qHash(const QCborMap &map, uint seed)
1748{
1749 return qHashRange(map.begin(), map.end(), seed);
1750}
1751
1752#if !defined(QT_NO_DEBUG_STREAM)
1753QDebug operator<<(QDebug dbg, const QCborMap &m)
1754{
1755 QDebugStateSaver saver(dbg);
1756 dbg.nospace() << "QCborMap{";
1757 const char *open = "{";
1758 for (auto pair : m) {
1759 dbg << open << pair.first << ", " << pair.second << '}';
1760 open = ", {";
1761 }
1762 return dbg << '}';
1763}
1764#endif
1765
1766#ifndef QT_NO_DATASTREAM
1767QDataStream &operator<<(QDataStream &stream, const QCborMap &value)
1768{
1769 stream << value.toCborValue().toCbor();
1770 return stream;
1771}
1772
1773QDataStream &operator>>(QDataStream &stream, QCborMap &value)
1774{
1775 QByteArray buffer;
1776 stream >> buffer;
1777 QCborParserError parseError{};
1778 value = QCborValue::fromCbor(buffer, &parseError).toMap();
1779 if (parseError.error)
1780 stream.setStatus(QDataStream::ReadCorruptData);
1781 return stream;
1782}
1783#endif
1784
1785QT_END_NAMESPACE
1786