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