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