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

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