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

Provided by KDAB

Privacy Policy
Learn Advanced QML with KDAB
Find out more

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