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 "qcborarray.h"
5#include "qcborvalue_p.h"
6#include "qdatastream.h"
7
8QT_BEGIN_NAMESPACE
9
10using namespace QtCbor;
11
12/*!
13 \class QCborArray
14 \inmodule QtCore
15 \ingroup cbor
16 \ingroup qtserialization
17 \reentrant
18 \since 5.12
19
20 \brief The QCborArray class is used to hold an array of CBOR elements.
21
22 \compares strong
23 \compareswith strong QCborValueConstRef
24 \endcompareswith
25
26 This class can be used to hold one sequential container in CBOR (an array).
27 CBOR is the Concise Binary Object Representation, a very compact form of
28 binary data encoding that is a superset of JSON. It was created by the IETF
29 Constrained RESTful Environments (CoRE) WG, which has used it in many new
30 RFCs. It is meant to be used alongside the
31 \l{RFC 7252}{CoAP protocol}.
32
33 QCborArray is very similar to \l QVariantList and \l QJsonArray and its API
34 is almost identical to those two classes. It can also be converted to and
35 from those two, though there may be loss of information in some
36 conversions.
37
38 \sa QCborValue, QCborMap, QJsonArray, QList, {Parsing and displaying CBOR data},
39 {Serialization Converter}, {Saving and Loading a Game}
40 */
41
42/*!
43 \typedef QCborArray::size_type
44
45 A typedef to qsizetype.
46 */
47
48/*!
49 \typedef QCborArray::difference_type
50
51 A typedef to qsizetype.
52 */
53
54/*!
55 \typedef QCborArray::value_type
56
57 The type of values that can be held in a QCborArray: that is, QCborValue.
58 */
59
60/*!
61 \typedef QCborArray::pointer
62
63 A typedef to \c{QCborValue *}, for compatibility with generic algorithms.
64 */
65
66/*!
67 \typedef QCborArray::const_pointer
68
69 A typedef to \c{const QCborValue *}, for compatibility with generic algorithms.
70 */
71
72/*!
73 \typedef QCborArray::reference
74
75 A typedef to \c{QCborValue &}, for compatibility with generic algorithms.
76 */
77
78/*!
79 \typedef QCborArray::const_reference
80
81 A typedef to \c{const QCborValue &}, for compatibility with generic algorithms.
82 */
83
84/*!
85 Constructs an empty QCborArray.
86 */
87QCborArray::QCborArray() noexcept
88 : d(nullptr)
89{
90}
91
92/*!
93 Copies the contents of \a other into this object.
94 */
95QCborArray::QCborArray(const QCborArray &other) noexcept
96 : d(other.d)
97{
98}
99
100/*!
101 \fn QCborArray::QCborArray(std::initializer_list<QCborValue> args)
102
103 Initializes this QCborArray from the C++ brace-enclosed list found in \a
104 args, as in the following example:
105
106 \code
107 QCborArray a = { null, 0, 1, 1.5, 2, "Hello", QByteArray("World") };
108 \endcode
109 */
110
111/*!
112 Destroys this QCborArray and frees any associated resources.
113 */
114QCborArray::~QCborArray()
115{
116}
117
118/*!
119 Replaces the contents of this array with that found in \a other, then
120 returns a reference to this object.
121 */
122QCborArray &QCborArray::operator=(const QCborArray &other) noexcept
123{
124 d = other.d;
125 return *this;
126}
127
128/*!
129 \fn void QCborArray::swap(QCborArray &other)
130
131 Swaps the contents of this object and \a other.
132 */
133
134/*!
135 \fn QCborValue QCborArray::toCborValue() const
136
137 Explicitly construcuts a \l QCborValue object that represents this array.
138 This function is usually not necessary since QCborValue has a constructor
139 for QCborArray, so the conversion is implicit.
140
141 Converting QCborArray to QCborValue allows it to be used in any context
142 where QCborValues can be used, including as items in QCborArrays and as keys
143 and mapped types in QCborMap. Converting an array to QCborValue allows
144 access to QCborValue::toCbor().
145
146 \sa QCborValue::QCborValue(const QCborArray &)
147 */
148
149/*!
150 Returns the size of this array.
151
152 \sa isEmpty()
153 */
154qsizetype QCborArray::size() const noexcept
155{
156 return d ? d->elements.size() : 0;
157}
158
159/*!
160 Empties this array.
161
162 \sa isEmpty()
163 */
164void QCborArray::clear()
165{
166 d.reset();
167}
168
169/*!
170 \fn bool QCborArray::isEmpty() const
171
172 Returns true if this QCborArray is empty (that is if size() is 0).
173
174 \sa size(), clear()
175 */
176
177/*!
178 Returns the QCborValue element at position \a i in the array.
179
180 If the array is smaller than \a i elements, this function returns a
181 QCborValue containing an undefined value. For that reason, it is not
182 possible with this function to tell apart the situation where the array is
183 not large enough from the case where the array starts with an undefined
184 value.
185
186 \sa operator[](), first(), last(), insert(), prepend(), append(),
187 removeAt(), takeAt()
188 */
189QCborValue QCborArray::at(qsizetype i) const
190{
191 if (!d || size_t(i) >= size_t(size()))
192 return QCborValue();
193 return d->valueAt(idx: i);
194}
195
196/*!
197 \fn QCborValue QCborArray::first() const
198
199 Returns the first QCborValue of this array.
200
201 If the array is empty, this function returns a QCborValue containing an
202 undefined value. For that reason, it is not possible with this function to
203 tell apart the situation where the array is not large enough from the case
204 where the array ends with an undefined value.
205
206 \sa operator[](), at(), last(), insert(), prepend(), append(),
207 removeAt(), takeAt()
208 */
209
210/*!
211 \fn QCborValue QCborArray::last() const
212
213 Returns the last QCborValue of this array.
214
215 If the array is empty, this function returns a QCborValue containing an
216 undefined value. For that reason, it is not possible with this function to
217 tell apart the situation where the array is not large enough from the case
218 where the array ends with an undefined value.
219
220 \sa operator[](), at(), first(), insert(), prepend(), append(),
221 removeAt(), takeAt()
222 */
223
224/*!
225 \fn QCborValue QCborArray::operator[](qsizetype i) const
226
227 Returns the QCborValue element at position \a i in the array.
228
229 If the array is smaller than \a i elements, this function returns a
230 QCborValue containing an undefined value. For that reason, it is not
231 possible with this function to tell apart the situation where the array is
232 not large enough from the case where the array contains an undefined value
233 at position \a i.
234
235 \sa at(), first(), last(), insert(), prepend(), append(),
236 removeAt(), takeAt()
237 */
238
239/*!
240 \fn QCborValueRef QCborArray::first()
241
242 Returns a reference to the first QCborValue of this array. The array must
243 not be empty.
244
245 QCborValueRef has the exact same API as \l QCborValue, with one important
246 difference: if you assign new values to it, this array will be updated with
247 that new value.
248
249 \sa operator[](), at(), last(), insert(), prepend(), append(),
250 removeAt(), takeAt()
251 */
252
253/*!
254 \fn QCborValueRef QCborArray::last()
255
256 Returns a reference to the last QCborValue of this array. The array must
257 not be empty.
258
259 QCborValueRef has the exact same API as \l QCborValue, with one important
260 difference: if you assign new values to it, this array will be updated with
261 that new value.
262
263 \sa operator[](), at(), first(), insert(), prepend(), append(),
264 removeAt(), takeAt()
265 */
266
267/*!
268 \fn QCborValueRef QCborArray::operator[](qsizetype i)
269
270 Returns a reference to the QCborValue element at position \a i in the
271 array. Indices beyond the end of the array will grow the array, filling
272 with undefined entries, until it has an entry at the specified index.
273
274 QCborValueRef has the exact same API as \l QCborValue, with one important
275 difference: if you assign new values to it, this array will be updated with
276 that new value.
277
278 \sa at(), first(), last(), insert(), prepend(), append(),
279 removeAt(), takeAt()
280 */
281
282/*!
283 \fn void QCborArray::insert(qsizetype i, const QCborValue &value)
284 \fn void QCborArray::insert(qsizetype i, QCborValue &&value)
285
286 Inserts \a value into the array at position \a i in this array. If \a i is
287 -1, the entry is appended to the array. Pads the array with invalid entries
288 if \a i is greater than the prior size of the array.
289
290 \sa at(), operator[](), first(), last(), prepend(), append(),
291 removeAt(), takeAt(), extract()
292 */
293void QCborArray::insert(qsizetype i, const QCborValue &value)
294{
295 if (i < 0) {
296 Q_ASSERT(i == -1);
297 i = size();
298 detach(reserve: i + 1);
299 } else {
300 d = QCborContainerPrivate::grow(d: d.data(), index: i); // detaches
301 }
302 d->insertAt(idx: i, value);
303}
304
305void QCborArray::insert(qsizetype i, QCborValue &&value)
306{
307 if (i < 0) {
308 Q_ASSERT(i == -1);
309 i = size();
310 detach(reserve: i + 1);
311 } else {
312 d = QCborContainerPrivate::grow(d: d.data(), index: i); // detaches
313 }
314 d->insertAt(idx: i, value, disp: QCborContainerPrivate::MoveContainer);
315 QCborContainerPrivate::resetValue(v&: value);
316}
317
318/*!
319 \fn QCborValue QCborArray::extract(Iterator it)
320 \fn QCborValue QCborArray::extract(ConstIterator it)
321
322 Extracts a value from the array at the position indicated by iterator \a it
323 and returns the value so extracted.
324
325 \sa insert(), erase(), takeAt(), removeAt()
326 */
327QCborValue QCborArray::extract(iterator it)
328{
329 detach();
330
331 QCborValue v = d->extractAt(idx: it.item.i);
332 d->removeAt(idx: it.item.i);
333 return v;
334}
335
336/*!
337 \fn void QCborArray::prepend(const QCborValue &value)
338 \fn void QCborArray::prepend(QCborValue &&value)
339
340 Prepends \a value into the array before any other elements it may already
341 contain.
342
343 \sa at(), operator[](), first(), last(), insert(), append(),
344 removeAt(), takeAt()
345 */
346
347/*!
348 \fn void QCborArray::append(const QCborValue &value)
349 \fn void QCborArray::append(QCborValue &&value)
350
351 Appends \a value into the array after all other elements it may already
352 contain.
353
354 \sa at(), operator[](), first(), last(), insert(), prepend(),
355 removeAt(), takeAt()
356 */
357
358/*!
359 Removes the item at position \a i from the array. The array must have more
360 than \a i elements before the removal.
361
362 \sa takeAt(), removeFirst(), removeLast(), at(), operator[](), insert(),
363 prepend(), append()
364 */
365void QCborArray::removeAt(qsizetype i)
366{
367 detach(reserve: size());
368 d->removeAt(idx: i);
369}
370
371/*!
372 \fn QCborValue QCborArray::takeAt(qsizetype i)
373
374 Removes the item at position \a i from the array and returns it. The array
375 must have more than \a i elements before the removal.
376
377 \sa removeAt(), removeFirst(), removeLast(), at(), operator[](), insert(),
378 prepend(), append()
379 */
380
381/*!
382 \fn void QCborArray::removeFirst()
383
384 Removes the first item in the array, making the second element become the
385 first. The array must not be empty before this call.
386
387 \sa removeAt(), takeFirst(), removeLast(), at(), operator[](), insert(),
388 prepend(), append()
389 */
390
391/*!
392 \fn void QCborArray::removeLast()
393
394 Removes the last item in the array. The array must not be empty before this
395 call.
396
397 \sa removeAt(), takeLast(), removeFirst(), at(), operator[](), insert(),
398 prepend(), append()
399 */
400
401/*!
402 \fn void QCborArray::takeFirst()
403
404 Removes the first item in the array and returns it, making the second
405 element become the first. The array must not be empty before this call.
406
407 \sa takeAt(), removeFirst(), removeLast(), at(), operator[](), insert(),
408 prepend(), append()
409 */
410
411/*!
412 \fn void QCborArray::takeLast()
413
414 Removes the last item in the array and returns it. The array must not be
415 empty before this call.
416
417 \sa takeAt(), removeLast(), removeFirst(), at(), operator[](), insert(),
418 prepend(), append()
419 */
420
421/*!
422 Returns true if this array contains an element that is equal to \a value.
423 */
424bool QCborArray::contains(const QCborValue &value) const
425{
426 for (qsizetype i = 0; i < size(); ++i) {
427 int cmp = d->compareElement(idx: i, value, mode: Comparison::ForEquality);
428 if (cmp == 0)
429 return true;
430 }
431 return false;
432}
433
434/*!
435 \fn int QCborArray::compare(const QCborArray &other) const
436
437 Compares this array and \a other, comparing each element in sequence, and
438 returns an integer that indicates whether this array should be sorted
439 before (if the result is negative) or after \a other (if the result is
440 positive). If this function returns 0, the two arrays are equal and contain
441 the same elements.
442
443 For more information on CBOR sorting order, see QCborValue::compare().
444
445 \sa QCborValue::compare(), QCborMap::compare(), operator==()
446 */
447
448/*!
449 \fn bool QCborArray::operator==(const QCborArray &lhs, const QCborArray &rhs)
450
451 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
452 returns true if both arrays contains the same elements, false otherwise.
453
454 For more information on CBOR equality in Qt, see, QCborValue::compare().
455
456 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
457 operator!=(), operator<()
458 */
459
460/*!
461 \fn bool QCborArray::operator!=(const QCborArray &lhs, const QCborArray &rhs)
462
463 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
464 returns true if the two arrays' contents are different, false otherwise.
465
466 For more information on CBOR equality in Qt, see, QCborValue::compare().
467
468 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
469 operator==(), operator<()
470 */
471
472/*!
473 \fn bool QCborArray::operator<(const QCborArray &lhs, const QCborArray &rhs)
474
475 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
476 returns true if \a lhs array should be sorted before \a rhs, false
477 otherwise.
478
479 For more information on CBOR sorting order, see QCborValue::compare().
480
481 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
482 operator==(), operator!=(), operator<=()
483 */
484
485/*!
486 \fn bool QCborArray::operator<=(const QCborArray &lhs, const QCborArray &rhs)
487
488 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
489 returns true if \a lhs array should be sorted before \a rhs, or if both
490 arrays contains the same elements, false otherwise.
491
492 For more information on CBOR sorting order, see QCborValue::compare().
493
494 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
495 operator==(), operator!=(), operator<()
496*/
497
498/*!
499 \fn bool QCborArray::operator>(const QCborArray &lhs, const QCborArray &rhs)
500
501 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
502 returns true if \a lhs array should be sorted after \a rhs, false
503 otherwise.
504
505 For more information on CBOR sorting order, see QCborValue::compare().
506
507 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
508 operator==(), operator!=(), operator>=()
509*/
510
511/*!
512 \fn bool QCborArray::operator>=(const QCborArray &lhs, const QCborArray &rhs)
513
514 Compares \a lhs and \a rhs arrays, comparing each element in sequence, and
515 returns true if \a lhs array should be sorted after \a rhs, or if both
516 arrays contains the same elements, false otherwise.
517
518 For more information on CBOR sorting order, see QCborValue::compare().
519
520 \sa compare(), QCborValue::operator==(), QCborMap::operator==(),
521 operator==(), operator!=(), operator>()
522*/
523
524/*!
525 \typedef QCborArray::iterator
526
527 A synonym to QCborArray::Iterator.
528 */
529
530/*!
531 \typedef QCborArray::const_iterator
532
533 A synonym to QCborArray::ConstIterator.
534 */
535
536/*!
537 \fn QCborArray::iterator QCborArray::begin()
538
539 Returns an array iterator pointing to the first item in this array. If the
540 array is empty, then this function returns the same as end().
541
542 \sa constBegin(), end()
543 */
544
545/*!
546 \fn QCborArray::const_iterator QCborArray::begin() const
547
548 Returns an array iterator pointing to the first item in this array. If the
549 array is empty, then this function returns the same as end().
550
551 \sa constBegin(), constEnd()
552 */
553
554/*!
555 \fn QCborArray::const_iterator QCborArray::cbegin() const
556
557 Returns an array iterator pointing to the first item in this array. If the
558 array is empty, then this function returns the same as end().
559
560 \sa constBegin(), constEnd()
561 */
562
563/*!
564 \fn QCborArray::const_iterator QCborArray::constBegin() const
565
566 Returns an array iterator pointing to the first item in this array. If the
567 array is empty, then this function returns the same as end().
568
569 \sa begin(), constEnd()
570 */
571
572/*!
573 \fn QCborArray::iterator QCborArray::end()
574
575 Returns an array iterator pointing to just after the last element in this
576 array.
577
578 \sa begin(), constEnd()
579 */
580
581/*!
582 \fn QCborArray::const_iterator QCborArray::end() const
583
584 Returns an array iterator pointing to just after the last element in this
585 array.
586
587 \sa constBegin(), constEnd()
588 */
589
590/*!
591 \fn QCborArray::const_iterator QCborArray::cend() const
592
593 Returns an array iterator pointing to just after the last element in this
594 array.
595
596 \sa constBegin(), constEnd()
597 */
598
599/*!
600 \fn QCborArray::const_iterator QCborArray::constEnd() const
601
602 Returns an array iterator pointing to just after the last element in this
603 array.
604
605 \sa constBegin(), end()
606 */
607
608/*!
609 \fn QCborArray::iterator QCborArray::insert(iterator before, const QCborValue &value)
610 \fn QCborArray::iterator QCborArray::insert(const_iterator before, const QCborValue &value)
611 \overload
612
613 Inserts \a value into this array before element \a before and returns an
614 array iterator pointing to the just-inserted element.
615
616 \sa erase(), removeAt(), prepend(), append()
617 */
618
619/*!
620 \fn QCborArray::iterator QCborArray::erase(iterator it)
621 \fn QCborArray::iterator QCborArray::erase(const_iterator it)
622
623 Removes the element pointed to by the array iterator \a it from this array,
624 then returns an iterator to the next element (the one that took the same
625 position in the array that \a it used to occupy).
626
627 \sa insert(), removeAt(), takeAt(), takeFirst(), takeLast()
628 */
629
630/*!
631 \fn void QCborArray::push_back(const QCborValue &t)
632
633 Synonym for append(). This function is provided for compatibility with
634 generic code that uses the Standard Library API.
635
636 Appends the element \a t to this array.
637
638 \sa append(), push_front(), pop_back(), prepend(), insert()
639 */
640
641/*!
642 \fn void QCborArray::push_front(const QCborValue &t)
643
644 Synonym for prepend(). This function is provided for compatibility with
645 generic code that uses the Standard Library API.
646
647 Prepends the element \a t to this array.
648
649 \sa prepend(), push_back(), pop_front(), append(), insert()
650 */
651
652/*!
653 \fn void QCborArray::pop_front()
654
655 Synonym for removeFirst(). This function is provided for compatibility with
656 generic code that uses the Standard Library API.
657
658 Removes the first element of this array. The array must not be empty before
659 the removal
660
661 \sa removeFirst(), takeFirst(), pop_back(), push_front(), prepend(), insert()
662 */
663
664/*!
665 \fn void QCborArray::pop_back()
666
667 Synonym for removeLast(). This function is provided for compatibility with
668 generic code that uses the Standard Library API.
669
670 Removes the last element of this array. The array must not be empty before
671 the removal
672
673 \sa removeLast(), takeLast(), pop_front(), push_back(), append(), insert()
674 */
675
676/*!
677 \fn bool QCborArray::empty() const
678
679 Synonym for isEmpty(). This function is provided for compatibility with
680 generic code that uses the Standard Library API.
681
682 Returns true if this array is empty (size() == 0).
683
684 \sa isEmpty(), size()
685 */
686
687/*!
688 \fn QCborArray QCborArray::operator+(const QCborValue &v) const
689
690 Returns a new QCborArray containing the same elements as this array, plus
691 \a v appended as the last element.
692
693 \sa operator+=(), operator<<(), append()
694 */
695
696/*!
697 \fn QCborArray &QCborArray::operator+=(const QCborValue &v)
698
699 Appends \a v to this array and returns a reference to this array.
700
701 \sa append(), insert(), operator+(), operator<<()
702 */
703
704/*!
705 \fn QCborArray &QCborArray::operator<<(const QCborValue &v)
706
707 Appends \a v to this array and returns a reference to this array.
708
709 \sa append(), insert(), operator+(), operator+=()
710 */
711
712void QCborArray::detach(qsizetype reserved)
713{
714 d = QCborContainerPrivate::detach(d: d.data(), reserved: reserved ? reserved : size());
715}
716
717/*!
718 \class QCborArray::Iterator
719 \inmodule QtCore
720 \ingroup cbor
721 \since 5.12
722
723 \brief The QCborArray::Iterator class provides an STL-style non-const iterator for QCborArray.
724
725 \compares strong
726 \compareswith strong QCborArray::ConstIterator
727 \endcompareswith
728
729 QCborArray::Iterator allows you to iterate over a QCborArray and to modify
730 the array item associated with the iterator. If you want to iterate over a
731 const QCborArray, use QCborArray::ConstIterator instead. It is generally a
732 good practice to use QCborArray::ConstIterator on a non-const QCborArray as
733 well, unless you need to change the QCborArray through the iterator. Const
734 iterators are slightly faster and improve code readability.
735
736 Iterators are initialized by using a QCborArray function like
737 QCborArray::begin(), QCborArray::end(), or QCborArray::insert(). Iteration
738 is only possible after that.
739
740 Most QCborArray functions accept an integer index rather than an iterator.
741 For that reason, iterators are rarely useful in connection with QCborArray.
742 One place where STL-style iterators do make sense is as arguments to
743 \l{generic algorithms}.
744
745 Multiple iterators can be used on the same array. However, be aware that
746 any non-const function call performed on the QCborArray will render all
747 existing iterators undefined.
748
749 \sa QCborArray::ConstIterator
750*/
751
752/*!
753 \typedef QCborArray::Iterator::iterator_category
754
755 A synonym for \e {std::random_access_iterator_tag} indicating this iterator
756 is a random access iterator.
757 */
758
759/*!
760 \typedef QCborArray::Iterator::difference_type
761 \internal
762*/
763
764/*!
765 \typedef QCborArray::Iterator::value_type
766 \internal
767*/
768
769/*!
770 \typedef QCborArray::Iterator::reference
771 \internal
772*/
773
774/*!
775 \typedef QCborArray::Iterator::pointer
776 \internal
777*/
778
779/*!
780 \fn QCborArray::Iterator::Iterator()
781
782 Constructs an uninitialized iterator.
783
784 Functions like operator*() and operator++() should not be called on an
785 uninitialized iterator. Use operator=() to assign a value to it before
786 using it.
787
788 \sa QCborArray::begin(), QCborArray::end()
789*/
790
791/*!
792 \fn QCborArray::Iterator::Iterator(const Iterator &other)
793
794 Makes a copy of \a other.
795 */
796
797/*!
798 \fn QCborArray::Iterator &QCborArray::Iterator::operator=(const Iterator &other)
799
800 Makes this iterator a copy of \a other and returns a reference to this iterator.
801 */
802
803/*!
804 \fn QCborValueRef QCborArray::Iterator::operator*() const
805
806 Returns a modifiable reference to the current item.
807
808 You can change the value of an item by using operator*() on the left side
809 of an assignment.
810
811 The return value is of type QCborValueRef, a helper class for QCborArray
812 and QCborMap. When you get an object of type QCborValueRef, you can use it
813 as if it were a reference to a QCborValue. If you assign to it, the
814 assignment will apply to the element in the QCborArray or QCborMap from
815 which you got the reference.
816*/
817
818/*!
819 \fn QCborValueRef *QCborArray::Iterator::operator->() const
820
821 Returns a pointer to a modifiable reference to the current item.
822*/
823
824/*!
825 \fn QCborValueRef QCborArray::Iterator::operator[](qsizetype j) const
826
827 Returns a modifiable reference to the item at a position \a j steps forward
828 from the item pointed to by this iterator.
829
830 This function is provided to make QCborArray iterators behave like C++
831 pointers.
832
833 The return value is of type QCborValueRef, a helper class for QCborArray
834 and QCborMap. When you get an object of type QCborValueRef, you can use it
835 as if it were a reference to a QCborValue. If you assign to it, the
836 assignment will apply to the element in the QCborArray or QCborMap from
837 which you got the reference.
838
839 \sa operator+()
840*/
841
842/*!
843 \fn bool QCborArray::Iterator::operator==(const Iterator &lhs, const Iterator &rhs)
844 \fn bool QCborArray::Iterator::operator==(const Iterator &lhs, const ConstIterator &rhs)
845
846 Returns \c true if \a lhs points to the same entry in the array as \a rhs
847 iterator; otherwise returns \c false.
848
849 \sa operator!=()
850*/
851
852/*!
853 \fn bool QCborArray::Iterator::operator!=(const Iterator &lhs, const Iterator &rhs)
854 \fn bool QCborArray::Iterator::operator!=(const Iterator &lhs, const ConstIterator &rhs)
855
856 Returns \c true if \a lhs points to a different entry in the array than
857 \a rhs iterator; otherwise returns \c false.
858
859 \sa operator==()
860*/
861
862/*!
863 \fn bool QCborArray::Iterator::operator<(const Iterator &lhs, const Iterator &rhs)
864 \fn bool QCborArray::Iterator::operator<(const Iterator &lhs, const ConstIterator &rhs)
865
866 Returns \c true if the entry in the array pointed to by \a lhs iterator
867 occurs before the entry pointed to by the \a rhs iterator.
868*/
869
870/*!
871 \fn bool QCborArray::Iterator::operator<=(const Iterator &lhs, const Iterator &rhs)
872 \fn bool QCborArray::Iterator::operator<=(const Iterator &lhs, const ConstIterator &rhs)
873
874 Returns \c true if the entry in the array pointed to by \a lhs iterator
875 occurs before or is the same entry as is pointed to by the \a rhs
876 iterator.
877*/
878
879/*!
880 \fn bool QCborArray::Iterator::operator>(const Iterator &lhs, const Iterator &rhs)
881 \fn bool QCborArray::Iterator::operator>(const Iterator &lhs, const ConstIterator &rhs)
882
883 Returns \c true if the entry in the array pointed to by \a lhs iterator
884 occurs after the entry pointed to by the \a rhs iterator.
885 */
886
887/*!
888 \fn bool QCborArray::Iterator::operator>=(const Iterator &lhs, const Iterator &rhs)
889 \fn bool QCborArray::Iterator::operator>=(const Iterator &lhs, const ConstIterator &rhs)
890
891 Returns \c true if the entry in the array pointed to by \a lhs iterator
892 occurs after or is the same entry as is pointed to by the \a rhs
893 iterator.
894*/
895
896/*!
897 \fn QCborArray::Iterator &QCborArray::Iterator::operator++()
898
899 The prefix \c{++} operator, \c{++it}, advances the iterator to the next item in
900 the array and returns this iterator.
901
902 Calling this function on QCborArray::end() leads to undefined results.
903
904 \sa operator--()
905*/
906
907/*!
908 \fn QCborArray::Iterator QCborArray::Iterator::operator++(int)
909 \overload
910
911 The postfix \c{++} operator, \c{it++}, advances the iterator to the next item
912 in the array and returns an iterator to the previously current item.
913*/
914
915/*!
916 \fn QCborArray::Iterator &QCborArray::Iterator::operator--()
917
918 The prefix \c{--} operator, \c{--it}, makes the preceding item current and
919 returns this iterator.
920
921 Calling this function on QCborArray::begin() leads to undefined results.
922
923 \sa operator++()
924*/
925
926/*!
927 \fn QCborArray::Iterator QCborArray::Iterator::operator--(int)
928 \overload
929
930 The postfix \c{--} operator, \c{it--}, makes the preceding item current and
931 returns an iterator to the previously current item.
932*/
933
934/*!
935 \fn QCborArray::Iterator &QCborArray::Iterator::operator+=(qsizetype j)
936
937 Advances the iterator by \a j positions. If \a j is negative, the iterator
938 goes backward. Returns a reference to this iterator.
939
940 \sa operator-=(), operator+()
941*/
942
943/*!
944 \fn QCborArray::Iterator &QCborArray::Iterator::operator-=(qsizetype j)
945
946 Makes the iterator go back by \a j positions. If \a j is negative, the
947 iterator goes forward. Returns a reference to this iterator.
948
949 \sa operator+=(), operator-()
950*/
951
952/*!
953 \fn QCborArray::Iterator QCborArray::Iterator::operator+(qsizetype j) const
954
955 Returns an iterator to the item at position \a j steps forward from this
956 iterator. If \a j is negative, the iterator goes backward.
957
958 \sa operator-(), operator+=()
959*/
960
961/*!
962 \fn QCborArray::Iterator QCborArray::Iterator::operator-(qsizetype j) const
963
964 Returns an iterator to the item at position \a j steps backward from this
965 iterator. If \a j is negative, the iterator goes forward.
966
967 \sa operator+(), operator-=()
968*/
969
970/*!
971 \fn qsizetype QCborArray::Iterator::operator-(Iterator other) const
972
973 Returns the offset of this iterator relative to \a other.
974*/
975
976/*!
977 \class QCborArray::ConstIterator
978 \inmodule QtCore
979 \ingroup cbor
980 \since 5.12
981
982 \brief The QCborArray::ConstIterator class provides an STL-style const iterator for QCborArray.
983
984 \compares strong
985 \compareswith strong QCborArray::Iterator
986 \endcompareswith
987
988 QCborArray::ConstIterator allows you to iterate over a QCborArray. If you
989 want to modify the QCborArray as you iterate over it, use
990 QCborArray::Iterator instead. It is generally good practice to use
991 QCborArray::ConstIterator, even on a non-const QCborArray, when you don't
992 need to change the QCborArray through the iterator. Const iterators are
993 slightly faster and improves code readability.
994
995 Iterators are initialized by using a QCborArray function like
996 QCborArray::begin() or QCborArray::end(). Iteration is only possible after
997 that.
998
999 Most QCborArray functions accept an integer index rather than an iterator.
1000 For that reason, iterators are rarely useful in connection with QCborArray.
1001 One place where STL-style iterators do make sense is as arguments to
1002 \l{generic algorithms}.
1003
1004 Multiple iterators can be used on the same array. However, be aware that
1005 any non-const function call performed on the QCborArray will render all
1006 existing iterators undefined.
1007
1008 \sa QCborArray::Iterator
1009*/
1010
1011/*!
1012 \fn QCborArray::ConstIterator::ConstIterator()
1013
1014 Constructs an uninitialized iterator.
1015
1016 Functions like operator*() and operator++() should not be called on an
1017 uninitialized iterator. Use operator=() to assign a value to it before
1018 using it.
1019
1020 \sa QCborArray::constBegin(), QCborArray::constEnd()
1021*/
1022
1023/*!
1024 \fn QCborArray::ConstIterator &QCborArray::ConstIterator::operator=(const ConstIterator &other)
1025
1026 Makes this iterator a copy of \a other and returns a reference to this iterator.
1027*/
1028
1029/*!
1030 \typedef QCborArray::ConstIterator::iterator_category
1031
1032 A synonym for \e {std::random_access_iterator_tag} indicating this iterator
1033 is a random access iterator.
1034*/
1035
1036/*!
1037 \typedef QCborArray::ConstIterator::difference_type
1038 \internal
1039*/
1040
1041/*!
1042 \typedef QCborArray::ConstIterator::value_type
1043 \internal
1044*/
1045
1046/*!
1047 \typedef QCborArray::ConstIterator::reference
1048 \internal
1049*/
1050
1051/*!
1052 \typedef QCborArray::ConstIterator::pointer
1053 \internal
1054*/
1055
1056/*!
1057 \fn QCborArray::ConstIterator::ConstIterator(const ConstIterator &other)
1058
1059 Constructs a copy of \a other.
1060*/
1061
1062/*!
1063 \fn QCborValue QCborArray::ConstIterator::operator*() const
1064
1065 Returns the current item.
1066*/
1067
1068/*!
1069 \fn const QCborValue *QCborArray::ConstIterator::operator->() const
1070
1071 Returns a pointer to the current item.
1072*/
1073
1074/*!
1075 \fn QCborValueRef QCborArray::ConstIterator::operator[](qsizetype j) const
1076
1077 Returns the item at a position \a j steps forward from the item pointed to
1078 by this iterator.
1079
1080 This function is provided to make QCborArray iterators behave like C++
1081 pointers.
1082
1083 \sa operator+()
1084*/
1085
1086/*!
1087 \fn bool QCborArray::ConstIterator::operator==(const ConstIterator &lhs, const ConstIterator &rhs)
1088
1089 Returns \c true if \a lhs points to the same entry in the array as \a rhs
1090 iterator; otherwise returns \c false.
1091
1092 \sa operator!=()
1093*/
1094
1095/*!
1096 \fn bool QCborArray::ConstIterator::operator!=(const ConstIterator &lhs, const ConstIterator &rhs)
1097
1098 Returns \c true if \a lhs points to a different entry in the array than
1099 \a rhs iterator; otherwise returns \c false.
1100
1101 \sa operator==()
1102*/
1103
1104/*!
1105 \fn bool QCborArray::ConstIterator::operator<(const ConstIterator &lhs, const ConstIterator &rhs)
1106
1107 Returns \c true if the entry in the array pointed to by \a lhs iterator
1108 occurs before the entry pointed to by the \a rhs iterator.
1109*/
1110
1111/*!
1112 \fn bool QCborArray::ConstIterator::operator<=(const ConstIterator &lhs, const ConstIterator &rhs)
1113
1114 Returns \c true if the entry in the array pointed to by \a lhs iterator
1115 occurs before or is the same entry as is pointed to by the \a rhs
1116 iterator.
1117*/
1118
1119/*!
1120 \fn bool QCborArray::ConstIterator::operator>(const ConstIterator &lhs, const ConstIterator &rhs)
1121
1122 Returns \c true if the entry in the array pointed to by \a lhs iterator
1123 occurs after the entry pointed to by the \a rhs iterator.
1124*/
1125
1126/*!
1127 \fn bool QCborArray::ConstIterator::operator>=(const ConstIterator &lhs, const ConstIterator &rhs)
1128
1129 Returns \c true if the entry in the array pointed to by \a lhs iterator
1130 occurs after or is the same entry as is pointed to by the \a rhs
1131 iterator.
1132*/
1133
1134/*!
1135 \fn QCborArray::ConstIterator &QCborArray::ConstIterator::operator++()
1136
1137 The prefix \c{++} operator, \c{++it}, advances the iterator to the next item in
1138 the array and returns this iterator.
1139
1140 Calling this function on QCborArray::end() leads to undefined results.
1141
1142 \sa operator--()
1143*/
1144
1145/*!
1146 \fn QCborArray::ConstIterator QCborArray::ConstIterator::operator++(int)
1147 \overload
1148
1149 The postfix \c{++} operator, \c{it++}, advances the iterator to the next item
1150 in the array and returns an iterator to the previously current item.
1151*/
1152
1153/*!
1154 \fn QCborArray::ConstIterator &QCborArray::ConstIterator::operator--()
1155
1156 The prefix \c{--} operator, \c{--it}, makes the preceding item current and
1157 returns this iterator.
1158
1159 Calling this function on QCborArray::begin() leads to undefined results.
1160
1161 \sa operator++()
1162*/
1163
1164/*!
1165 \fn QCborArray::ConstIterator QCborArray::ConstIterator::operator--(int)
1166 \overload
1167
1168 The postfix \c{--} operator, \c{it--}, makes the preceding item current and
1169 returns an iterator to the previously current item.
1170*/
1171
1172/*!
1173 \fn QCborArray::ConstIterator &QCborArray::ConstIterator::operator+=(qsizetype j)
1174
1175 Advances the iterator by \a j positions. If \a j is negative, the iterator
1176 goes backward. Returns a reference to this iterator.
1177
1178 \sa operator-=(), operator+()
1179*/
1180
1181/*!
1182 \fn QCborArray::ConstIterator &QCborArray::ConstIterator::operator-=(qsizetype j)
1183
1184 Makes the iterator go back by \a j positions. If \a j is negative, the
1185 iterator goes forward. Returns a reference to this iterator.
1186
1187 \sa operator+=(), operator-()
1188*/
1189
1190/*!
1191 \fn QCborArray::ConstIterator QCborArray::ConstIterator::operator+(qsizetype j) const
1192
1193 Returns an iterator to the item at a position \a j steps forward from this
1194 iterator. If \a j is negative, the iterator goes backward.
1195
1196 \sa operator-(), operator+=()
1197*/
1198
1199/*!
1200 \fn QCborArray::ConstIterator QCborArray::ConstIterator::operator-(qsizetype j) const
1201
1202 Returns an iterator to the item at a position \a j steps backward from this
1203 iterator. If \a j is negative, the iterator goes forward.
1204
1205 \sa operator+(), operator-=()
1206*/
1207
1208/*!
1209 \fn qsizetype QCborArray::ConstIterator::operator-(ConstIterator other) const
1210
1211 Returns the offset of this iterator relative to \a other.
1212*/
1213
1214size_t qHash(const QCborArray &array, size_t seed)
1215{
1216 return qHashRange(first: array.begin(), last: array.end(), seed);
1217}
1218
1219#if !defined(QT_NO_DEBUG_STREAM)
1220QDebug operator<<(QDebug dbg, const QCborArray &a)
1221{
1222 QDebugStateSaver saver(dbg);
1223 dbg.nospace() << "QCborArray{";
1224 const char *comma = "";
1225 for (auto v : a) {
1226 dbg << comma << v;
1227 comma = ", ";
1228 }
1229 return dbg << '}';
1230}
1231#endif
1232
1233#ifndef QT_NO_DATASTREAM
1234#if QT_CONFIG(cborstreamwriter)
1235QDataStream &operator<<(QDataStream &stream, const QCborArray &value)
1236{
1237 stream << value.toCborValue().toCbor();
1238 return stream;
1239}
1240#endif
1241
1242QDataStream &operator>>(QDataStream &stream, QCborArray &value)
1243{
1244 QByteArray buffer;
1245 stream >> buffer;
1246 QCborParserError parseError{};
1247 value = QCborValue::fromCbor(ba: buffer, error: &parseError).toArray();
1248 if (parseError.error)
1249 stream.setStatus(QDataStream::ReadCorruptData);
1250 return stream;
1251}
1252#endif
1253
1254QT_END_NAMESPACE
1255

Provided by KDAB

Privacy Policy
Learn Advanced QML with KDAB
Find out more

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