src/corelib/json/qjsonarray.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include <qjsonobject.h>
  43 #include <qjsonvalue.h>
  44 #include <qjsonarray.h>
  45 #include <qjsonvalue.h>
  46 #include <qstringlist.h>
  47 #include <qvariant.h>
  48 #include <qdebug.h>
  49
  50 #include "qjsonwriter_p.h"
  51 #include "qjson_p.h"
  52
  53 QT_BEGIN_NAMESPACE
  54
  55 /*!
  56     \class QJsonArray
  57     \ingroup json
  58     \reentrant
  59     \since 5.0
  60
  61     \brief The QJsonArray class encapsulates a JSON array.
  62
  63     A JSON array is a list of values. The list can be manipulated by inserting and
  64     removing QJsonValue's from the array.
  65
  66     A QJsonArray can be converted to and from a QVariantList. You can query the
  67     number of entries with size(), insert(), and remove() entries from it
  68     and iterate over its content using the standard C++ iterator pattern.
  69
  70     QJsonArray is an implicitly shared class and shares the data with the document
  71     it has been created from as long as it is not being modified.
  72
  73     You can convert the array to and from text based JSON through QJsonDocument.
  74 */
  75
  76 /*!
  77     \typedef QJsonArray::Iterator
  78
  79     Qt-style synonym for QJsonArray::iterator.
  80 */
  81
  82 /*!
  83     \typedef QJsonArray::ConstIterator
  84
  85     Qt-style synonym for QJsonArray::const_iterator.
  86 */
  87
  88 /*!
  89     \typedef QJsonArray::size_type
  90
  91     Typedef for int. Provided for STL compatibility.
  92 */
  93
  94 /*!
  95     \typedef QJsonArray::value_type
  96
  97     Typedef for QJsonValue. Provided for STL compatibility.
  98 */
  99
 100 /*!
 101     \typedef QJsonArray::difference_type
 102
 103     Typedef for int. Provided for STL compatibility.
 104 */
 105
 106 /*!
 107     \typedef QJsonArray::pointer
 108
 109     Typedef for QJsonValue *. Provided for STL compatibility.
 110 */
 111
 112 /*!
 113     \typedef QJsonArray::const_pointer
 114
 115     Typedef for const QJsonValue *. Provided for STL compatibility.
 116 */
 117
 118 /*!
 119     \typedef QJsonArray::reference
 120
 121     Typedef for QJsonValue &. Provided for STL compatibility.
 122 */
 123
 124 /*!
 125     \typedef QJsonArray::const_reference
 126
 127     Typedef for const QJsonValue &. Provided for STL compatibility.
 128 */
 129
 130 /*!
 131     Creates an empty array.
 132  */
 133 QJsonArray::QJsonArray()
 134     : d(0), a(0)
 135 {
 136 }
 137
 138 /*!
 139     \internal
 140  */
 141 QJsonArray::QJsonArray(QJsonPrivate::Data *data, QJsonPrivate::Array *array)
 142     : d(data), a(array)
 143 {
 144     Q_ASSERT(data);
 145     Q_ASSERT(array);
 146     d->ref.ref();
 147 }
 148
 149 /*!
 150     Deletes the array.
 151  */
 152 QJsonArray::~QJsonArray()
 153 {
 154     if (d && !d->ref.deref())
 155         delete d;
 156 }
 157
 158 /*!
 159     Creates a copy of \a other.
 160
 161     Since QJsonArray is implicitly shared, the copy is shallow
 162     as long as the object doesn't get modified.
 163  */
 164 QJsonArray::QJsonArray(const QJsonArray &other)
 165 {
 166     d = other.d;
 167     a = other.a;
 168     if (d)
 169         d->ref.ref();
 170 }
 171
 172 /*!
 173     Assigns \a other to this array.
 174  */
 175 QJsonArray &QJsonArray::operator =(const QJsonArray &other)
 176 {
 177     if (d != other.d) {
 178         if (d && !d->ref.deref())
 179             delete d;
 180         d = other.d;
 181         if (d)
 182             d->ref.ref();
 183     }
 184     a = other.a;
 185
 186     return *this;
 187 }
 188
 189 /*!
 190     Converts the string list \a list to a QJsonArray.
 191
 192     The values in \a list will be converted to JSON values.
 193
 194     \sa toVariantList(), QJsonValue::fromVariant()
 195  */
 196 QJsonArray QJsonArray::fromStringList(const QStringList &list)
 197 {
 198     QJsonArray array;
 199     for (QStringList::const_iterator it = list.constBegin(); it != list.constEnd(); ++it)
 200         array.append(QJsonValue(*it));
 201     return array;
 202 }
 203
 204 /*!
 205     Converts the variant list \a list to a QJsonArray.
 206
 207     The QVariant values in \a list will be converted to JSON values.
 208
 209     \sa toVariantList(), QJsonValue::fromVariant()
 210  */
 211 QJsonArray QJsonArray::fromVariantList(const QVariantList &list)
 212 {
 213     QJsonArray array;
 214     for (QVariantList::const_iterator it = list.constBegin(); it != list.constEnd(); ++it)
 215         array.append(QJsonValue::fromVariant(*it));
 216     return array;
 217 }
 218
 219 /*!
 220     Converts this object to a QVariantList.
 221
 222     Returns the created map.
 223  */
 224 QVariantList QJsonArray::toVariantList() const
 225 {
 226     QVariantList list;
 227
 228     if (a) {
 229         for (int i = 0; i < (int)a->length; ++i)
 230             list.append(QJsonValue(d, a, a->at(i)).toVariant());
 231     }
 232     return list;
 233 }
 234
 235
 236 /*!
 237     Returns the number of values stored in the array.
 238  */
 239 int QJsonArray::size() const
 240 {
 241     if (!d)
 242         return 0;
 243
 244     return (int)a->length;
 245 }
 246
 247 /*!
 248     \fn QJsonArray::count() const
 249
 250     Same as size().
 251
 252     \sa size()
 253 */
 254
 255 /*!
 256     Returns \c true if the object is empty. This is the same as size() == 0.
 257
 258     \sa size()
 259  */
 260 bool QJsonArray::isEmpty() const
 261 {
 262     if (!d)
 263         return true;
 264
 265     return !a->length;
 266 }
 267
 268 /*!
 269     Returns a QJsonValue representing the value for index \a i.
 270
 271     The returned QJsonValue is \c Undefined, if \a i is out of bounds.
 272
 273  */
 274 QJsonValue QJsonArray::at(int i) const
 275 {
 276     if (!a || i < 0 || i >= (int)a->length)
 277         return QJsonValue(QJsonValue::Undefined);
 278
 279     return QJsonValue(d, a, a->at(i));
 280 }
 281
 282 /*!
 283     Returns the first value stored in the array.
 284
 285     Same as \c at(0).
 286
 287     \sa at()
 288  */
 289 QJsonValue QJsonArray::first() const
 290 {
 291     return at(0);
 292 }
 293
 294 /*!
 295     Returns the last value stored in the array.
 296
 297     Same as \c{at(size() - 1)}.
 298
 299     \sa at()
 300  */
 301 QJsonValue QJsonArray::last() const
 302 {
 303     return at(a ? (a->length - 1) : 0);
 304 }
 305
 306 /*!
 307     Inserts \a value at the beginning of the array.
 308
 309     This is the same as \c{insert(0, \a value)}.
 310
 311     \sa append(), insert()
 312  */
 313 void QJsonArray::prepend(const QJsonValue &value)
 314 {
 315     insert(0, value);
 316 }
 317
 318 /*!
 319     Inserts \a value at the end of the array.
 320
 321     \sa prepend(), insert()
 322  */
 323 void QJsonArray::append(const QJsonValue &value)
 324 {
 325     insert(a ? (int)a->length : 0, value);
 326 }
 327
 328 /*!
 329     Removes the value at index position \a i. \a i must be a valid
 330     index position in the array (i.e., \c{0 <= \a i < size()}).
 331
 332     \sa insert(), replace()
 333  */
 334 void QJsonArray::removeAt(int i)
 335 {
 336     if (!a || i < 0 || i >= (int)a->length)
 337         return;
 338
 339     detach();
 340     a->removeItems(i, 1);
 341     ++d->compactionCounter;
 342     if (d->compactionCounter > 32u && d->compactionCounter >= unsigned(a->length) / 2u)
 343         compact();
 344 }
 345
 346 /*! \fn void QJsonArray::removeFirst()
 347
 348     Removes the first item in the array. Calling this function is
 349     equivalent to calling \c{removeAt(0)}. The array must not be empty. If
 350     the array can be empty, call isEmpty() before calling this
 351     function.
 352
 353     \sa removeAt(), removeLast()
 354 */
 355
 356 /*! \fn void QJsonArray::removeLast()
 357
 358     Removes the last item in the array. Calling this function is
 359     equivalent to calling \c{removeAt(size() - 1)}. The array must not be
 360     empty. If the array can be empty, call isEmpty() before calling
 361     this function.
 362
 363     \sa removeAt(), removeFirst()
 364 */
 365
 366 /*!
 367     Removes the item at index position \a i and returns it. \a i must
 368     be a valid index position in the array (i.e., \c{0 <= \a i < size()}).
 369
 370     If you don't use the return value, removeAt() is more efficient.
 371
 372     \sa removeAt()
 373  */
 374 QJsonValue QJsonArray::takeAt(int i)
 375 {
 376     if (!a || i < 0 || i >= (int)a->length)
 377         return QJsonValue(QJsonValue::Undefined);
 378
 379     detach();
 380
 381     QJsonValue v(d, a, a->at(i));
 382     v.detach();
 383
 384     removeAt(i);
 385
 386     return v;
 387 }
 388
 389 /*!
 390     Inserts \a value at index position \a i in the array. If \a i
 391     is \c 0, the value is prepended to the array. If \a i is size(), the
 392     value is appended to the array.
 393
 394     \sa append(), prepend(), replace(), removeAt()
 395  */
 396 void QJsonArray::insert(int i, const QJsonValue &value)
 397 {
 398     Q_ASSERT (i >= 0 && i <= (a ? (int)a->length : 0));
 399
 400     bool compressed;
 401     int valueSize = QJsonPrivate::Value::requiredStorage(value, &compressed);
 402
 403     detach(valueSize + sizeof(QJsonPrivate::Value));
 404
 405     if (!a->length)
 406         a->tableOffset = sizeof(QJsonPrivate::Array);
 407
 408     int valueOffset = a->reserveSpace(valueSize, i, 1, false);
 409     QJsonPrivate::Value &v = (*a)[i];
 410     v.type = (value.t == QJsonValue::Undefined ? QJsonValue::Null : value.t);
 411     v.latinOrIntValue = compressed;
 412     v.latinKey = false;
 413     v.value = QJsonPrivate::Value::valueToStore(value, valueOffset);
 414     if (valueSize)
 415         QJsonPrivate::Value::copyData(value, (char *)a + valueOffset, compressed);
 416 }
 417
 418 /*!
 419     \fn QJsonArray::iterator QJsonArray::insert(iterator before, const QJsonValue &value)
 420
 421     Inserts \a value before the position pointed to by \a before, and returns an iterator
 422     pointing to the newly inserted item.
 423
 424     \sa erase(), insert()
 425 */
 426
 427 /*!
 428     \fn QJsonArray::iterator QJsonArray::erase(iterator it)
 429
 430     Removes the item pointed to by \a it, and returns an iterator pointing to the
 431     next item.
 432
 433     \sa removeAt()
 434 */
 435
 436 /*!
 437     Replaces the item at index position \a i with \a value. \a i must
 438     be a valid index position in the array (i.e., \c{0 <= \a i < size()}).
 439
 440     \sa operator[](), removeAt()
 441  */
 442 void QJsonArray::replace(int i, const QJsonValue &value)
 443 {
 444     Q_ASSERT (a && i >= 0 && i < (int)(a->length));
 445
 446     bool compressed;
 447     int valueSize = QJsonPrivate::Value::requiredStorage(value, &compressed);
 448
 449     detach(valueSize);
 450
 451     if (!a->length)
 452         a->tableOffset = sizeof(QJsonPrivate::Array);
 453
 454     int valueOffset = a->reserveSpace(valueSize, i, 1, true);
 455     QJsonPrivate::Value &v = (*a)[i];
 456     v.type = (value.t == QJsonValue::Undefined ? QJsonValue::Null : value.t);
 457     v.latinOrIntValue = compressed;
 458     v.latinKey = false;
 459     v.value = QJsonPrivate::Value::valueToStore(value, valueOffset);
 460     if (valueSize)
 461         QJsonPrivate::Value::copyData(value, (char *)a + valueOffset, compressed);
 462
 463     ++d->compactionCounter;
 464     if (d->compactionCounter > 32u && d->compactionCounter >= unsigned(a->length) / 2u)
 465         compact();
 466 }
 467
 468 /*!
 469     Returns \c true if the array contains an occurrence of \a value, otherwise \c false.
 470
 471     \sa count()
 472  */
 473 bool QJsonArray::contains(const QJsonValue &value) const
 474 {
 475     for (int i = 0; i < size(); i++) {
 476         if (at(i) == value)
 477             return true;
 478     }
 479     return false;
 480 }
 481
 482 /*!
 483     Returns the value at index position \a i as a modifiable reference.
 484     \a i must be a valid index position in the array (i.e., \c{0 <= \a i <
 485     size()}).
 486
 487     The return value is of type QJsonValueRef, a helper class for QJsonArray
 488     and QJsonObject. When you get an object of type QJsonValueRef, you can
 489     use it as if it were a reference to a QJsonValue. If you assign to it,
 490     the assignment will apply to the character in the QJsonArray of QJsonObject
 491     from which you got the reference.
 492
 493     \sa at()
 494  */
 495 QJsonValueRef QJsonArray::operator [](int i)
 496 {
 497     Q_ASSERT(a && i >= 0 && i < (int)a->length);
 498     return QJsonValueRef(this, i);
 499 }
 500
 501 /*!
 502     \overload
 503
 504     Same as at().
 505  */
 506 QJsonValue QJsonArray::operator[](int i) const
 507 {
 508     return at(i);
 509 }
 510
 511 /*!
 512     Returns \c true if this array is equal to \a other.
 513  */
 514 bool QJsonArray::operator==(const QJsonArray &other) const
 515 {
 516     if (a == other.a)
 517         return true;
 518
 519     if (!a)
 520         return !other.a->length;
 521     if (!other.a)
 522         return !a->length;
 523     if (a->length != other.a->length)
 524         return false;
 525
 526     for (int i = 0; i < (int)a->length; ++i) {
 527         if (QJsonValue(d, a, a->at(i)) != QJsonValue(other.d, other.a, other.a->at(i)))
 528             return false;
 529     }
 530     return true;
 531 }
 532
 533 /*!
 534     Returns \c true if this array is not equal to \a other.
 535  */
 536 bool QJsonArray::operator!=(const QJsonArray &other) const
 537 {
 538     return !(*this == other);
 539 }
 540
 541 /*! \fn QJsonArray::iterator QJsonArray::begin()
 542
 543     Returns an \l{STL-style iterator} pointing to the first item in
 544     the array.
 545
 546     \sa constBegin(), end()
 547 */
 548
 549 /*! \fn QJsonArray::const_iterator QJsonArray::begin() const
 550
 551     \overload
 552 */
 553
 554 /*! \fn QJsonArray::const_iterator QJsonArray::constBegin() const
 555
 556     Returns a const \l{STL-style iterator} pointing to the first item
 557     in the array.
 558
 559     \sa begin(), constEnd()
 560 */
 561
 562 /*! \fn QJsonArray::iterator QJsonArray::end()
 563
 564     Returns an \l{STL-style iterator} pointing to the imaginary item
 565     after the last item in the array.
 566
 567     \sa begin(), constEnd()
 568 */
 569
 570 /*! \fn const_iterator QJsonArray::end() const
 571
 572     \overload
 573 */
 574
 575 /*! \fn QJsonArray::const_iterator QJsonArray::constEnd() const
 576
 577     Returns a const \l{STL-style iterator} pointing to the imaginary
 578     item after the last item in the array.
 579
 580     \sa constBegin(), end()
 581 */
 582
 583 /*! \fn void QJsonArray::push_back(const QJsonValue &value)
 584
 585     This function is provided for STL compatibility. It is equivalent
 586     to \l{QJsonArray::append()}{append(\a value)}.
 587 */
 588
 589 /*! \fn void QJsonArray::push_front(const QJsonValue &value)
 590
 591     This function is provided for STL compatibility. It is equivalent
 592     to \l{QJsonArray::prepend()}{prepend(\a value)}.
 593 */
 594
 595 /*! \fn void QJsonArray::pop_front()
 596
 597     This function is provided for STL compatibility. It is equivalent
 598     to removeFirst(). The array must not be empty. If the array can be
 599     empty, call isEmpty() before calling this function.
 600 */
 601
 602 /*! \fn void QJsonArray::pop_back()
 603
 604     This function is provided for STL compatibility. It is equivalent
 605     to removeLast(). The array must not be empty. If the array can be
 606     empty, call isEmpty() before calling this function.
 607 */
 608
 609 /*! \fn bool QJsonArray::empty() const
 610
 611     This function is provided for STL compatibility. It is equivalent
 612     to isEmpty() and returns \c true if the array is empty.
 613 */
 614
 615 /*! \class QJsonArray::iterator
 616     \brief The QJsonArray::iterator class provides an STL-style non-const iterator for QJsonArray.
 617
 618     QJsonArray::iterator allows you to iterate over a QJsonArray
 619     and to modify the array item associated with the
 620     iterator. If you want to iterate over a const QJsonArray, use
 621     QJsonArray::const_iterator instead. It is generally a good practice to
 622     use QJsonArray::const_iterator on a non-const QJsonArray as well, unless
 623     you need to change the QJsonArray through the iterator. Const
 624     iterators are slightly faster and improves code readability.
 625
 626     The default QJsonArray::iterator constructor creates an uninitialized
 627     iterator. You must initialize it using a QJsonArray function like
 628     QJsonArray::begin(), QJsonArray::end(), or QJsonArray::insert() before you can
 629     start iterating.
 630
 631     Most QJsonArray functions accept an integer index rather than an
 632     iterator. For that reason, iterators are rarely useful in
 633     connection with QJsonArray. One place where STL-style iterators do
 634     make sense is as arguments to \l{generic algorithms}.
 635
 636     Multiple iterators can be used on the same array. However, be
 637     aware that any non-const function call performed on the QJsonArray
 638     will render all existing iterators undefined.
 639
 640     \sa QJsonArray::const_iterator
 641 */
 642
 643 /*! \typedef QJsonArray::iterator::iterator_category
 644
 645   A synonym for \e {std::random_access_iterator_tag} indicating
 646   this iterator is a random access iterator.
 647 */
 648
 649 /*! \typedef QJsonArray::iterator::difference_type
 650
 651     \internal
 652 */
 653
 654 /*! \typedef QJsonArray::iterator::value_type
 655
 656     \internal
 657 */
 658
 659 /*! \typedef QJsonArray::iterator::reference
 660
 661     \internal
 662 */
 663
 664 /*! \fn QJsonArray::iterator::iterator()
 665
 666     Constructs an uninitialized iterator.
 667
 668     Functions like operator*() and operator++() should not be called
 669     on an uninitialized iterator. Use operator=() to assign a value
 670     to it before using it.
 671
 672     \sa QJsonArray::begin(), QJsonArray::end()
 673 */
 674
 675 /*! \fn QJsonValueRef QJsonArray::iterator::operator*() const
 676
 677     Returns a modifiable reference to the current item.
 678
 679     You can change the value of an item by using operator*() on the
 680     left side of an assignment.
 681
 682     The return value is of type QJsonValueRef, a helper class for QJsonArray
 683     and QJsonObject. When you get an object of type QJsonValueRef, you can
 684     use it as if it were a reference to a QJsonValue. If you assign to it,
 685     the assignment will apply to the character in the QJsonArray of QJsonObject
 686     from which you got the reference.
 687 */
 688
 689 /*! \fn QJsonValueRef QJsonArray::iterator::operator[](int j) const
 690
 691     Returns a modifiable reference to the item at position \c{*this + j}.
 692
 693     This function is provided to make QJsonArray iterators behave like C++
 694     pointers.
 695
 696     The return value is of type QJsonValueRef, a helper class for QJsonArray
 697     and QJsonObject. When you get an object of type QJsonValueRef, you can
 698     use it as if it were a reference to a QJsonValue. If you assign to it,
 699     the assignment will apply to the character in the QJsonArray of QJsonObject
 700     from which you got the reference.
 701
 702     \sa operator+()
 703 */
 704
 705 /*!
 706     \fn bool QJsonArray::iterator::operator==(const iterator &other) const
 707     \fn bool QJsonArray::iterator::operator==(const const_iterator &other) const
 708
 709     Returns \c true if \a other points to the same item as this
 710     iterator; otherwise returns \c false.
 711
 712     \sa operator!=()
 713 */
 714
 715 /*!
 716     \fn bool QJsonArray::iterator::operator!=(const iterator &other) const
 717     \fn bool QJsonArray::iterator::operator!=(const const_iterator &other) const
 718
 719     Returns \c true if \a other points to a different item than this
 720     iterator; otherwise returns \c false.
 721
 722     \sa operator==()
 723 */
 724
 725 /*!
 726     \fn bool QJsonArray::iterator::operator<(const iterator& other) const
 727     \fn bool QJsonArray::iterator::operator<(const const_iterator& other) const
 728
 729     Returns \c true if the item pointed to by this iterator is less than
 730     the item pointed to by the \a other iterator.
 731 */
 732
 733 /*!
 734     \fn bool QJsonArray::iterator::operator<=(const iterator& other) const
 735     \fn bool QJsonArray::iterator::operator<=(const const_iterator& other) const
 736
 737     Returns \c true if the item pointed to by this iterator is less than
 738     or equal to the item pointed to by the \a other iterator.
 739 */
 740
 741 /*!
 742     \fn bool QJsonArray::iterator::operator>(const iterator& other) const
 743     \fn bool QJsonArray::iterator::operator>(const const_iterator& other) const
 744
 745     Returns \c true if the item pointed to by this iterator is greater
 746     than the item pointed to by the \a other iterator.
 747 */
 748
 749 /*!
 750     \fn bool QJsonArray::iterator::operator>=(const iterator& other) const
 751     \fn bool QJsonArray::iterator::operator>=(const const_iterator& other) const
 752
 753     Returns \c true if the item pointed to by this iterator is greater
 754     than or equal to the item pointed to by the \a other iterator.
 755 */
 756
 757 /*! \fn QJsonArray::iterator &QJsonArray::iterator::operator++()
 758
 759     The prefix ++ operator, \c{++it}, advances the iterator to the
 760     next item in the array and returns an iterator to the new current
 761     item.
 762
 763     Calling this function on QJsonArray::end() leads to undefined results.
 764
 765     \sa operator--()
 766 */
 767
 768 /*! \fn QJsonArray::iterator QJsonArray::iterator::operator++(int)
 769
 770     \overload
 771
 772     The postfix ++ operator, \c{it++}, advances the iterator to the
 773     next item in the array and returns an iterator to the previously
 774     current item.
 775 */
 776
 777 /*! \fn QJsonArray::iterator &QJsonArray::iterator::operator--()
 778
 779     The prefix -- operator, \c{--it}, makes the preceding item
 780     current and returns an iterator to the new current item.
 781
 782     Calling this function on QJsonArray::begin() leads to undefined results.
 783
 784     \sa operator++()
 785 */
 786
 787 /*! \fn QJsonArray::iterator QJsonArray::iterator::operator--(int)
 788
 789     \overload
 790
 791     The postfix -- operator, \c{it--}, makes the preceding item
 792     current and returns an iterator to the previously current item.
 793 */
 794
 795 /*! \fn QJsonArray::iterator &QJsonArray::iterator::operator+=(int j)
 796
 797     Advances the iterator by \a j items. If \a j is negative, the
 798     iterator goes backward.
 799
 800     \sa operator-=(), operator+()
 801 */
 802
 803 /*! \fn QJsonArray::iterator &QJsonArray::iterator::operator-=(int j)
 804
 805     Makes the iterator go back by \a j items. If \a j is negative,
 806     the iterator goes forward.
 807
 808     \sa operator+=(), operator-()
 809 */
 810
 811 /*! \fn QJsonArray::iterator QJsonArray::iterator::operator+(int j) const
 812
 813     Returns an iterator to the item at \a j positions forward from
 814     this iterator. If \a j is negative, the iterator goes backward.
 815
 816     \sa operator-(), operator+=()
 817 */
 818
 819 /*! \fn QJsonArray::iterator QJsonArray::iterator::operator-(int j) const
 820
 821     Returns an iterator to the item at \a j positions backward from
 822     this iterator. If \a j is negative, the iterator goes forward.
 823
 824     \sa operator+(), operator-=()
 825 */
 826
 827 /*! \fn int QJsonArray::iterator::operator-(iterator other) const
 828
 829     Returns the number of items between the item pointed to by \a
 830     other and the item pointed to by this iterator.
 831 */
 832
 833 /*! \class QJsonArray::const_iterator
 834     \brief The QJsonArray::const_iterator class provides an STL-style const iterator for QJsonArray.
 835
 836     QJsonArray::const_iterator allows you to iterate over a
 837     QJsonArray. If you want to modify the QJsonArray as
 838     you iterate over it, use QJsonArray::iterator instead. It is generally a
 839     good practice to use QJsonArray::const_iterator on a non-const QJsonArray
 840     as well, unless you need to change the QJsonArray through the
 841     iterator. Const iterators are slightly faster and improves
 842     code readability.
 843
 844     The default QJsonArray::const_iterator constructor creates an
 845     uninitialized iterator. You must initialize it using a QJsonArray
 846     function like QJsonArray::constBegin(), QJsonArray::constEnd(), or
 847     QJsonArray::insert() before you can start iterating.
 848
 849     Most QJsonArray functions accept an integer index rather than an
 850     iterator. For that reason, iterators are rarely useful in
 851     connection with QJsonArray. One place where STL-style iterators do
 852     make sense is as arguments to \l{generic algorithms}.
 853
 854     Multiple iterators can be used on the same array. However, be
 855     aware that any non-const function call performed on the QJsonArray
 856     will render all existing iterators undefined.
 857
 858     \sa QJsonArray::iterator
 859 */
 860
 861 /*! \fn QJsonArray::const_iterator::const_iterator()
 862
 863     Constructs an uninitialized iterator.
 864
 865     Functions like operator*() and operator++() should not be called
 866     on an uninitialized iterator. Use operator=() to assign a value
 867     to it before using it.
 868
 869     \sa QJsonArray::constBegin(), QJsonArray::constEnd()
 870 */
 871
 872 /*! \typedef QJsonArray::const_iterator::iterator_category
 873
 874   A synonym for \e {std::random_access_iterator_tag} indicating
 875   this iterator is a random access iterator.
 876 */
 877
 878 /*! \typedef QJsonArray::const_iterator::difference_type
 879
 880     \internal
 881 */
 882
 883 /*! \typedef QJsonArray::const_iterator::value_type
 884
 885     \internal
 886 */
 887
 888 /*! \typedef QJsonArray::const_iterator::reference
 889
 890     \internal
 891 */
 892
 893 /*! \fn QJsonArray::const_iterator::const_iterator(const const_iterator &other)
 894
 895     Constructs a copy of \a other.
 896 */
 897
 898 /*! \fn QJsonArray::const_iterator::const_iterator(const iterator &other)
 899
 900     Constructs a copy of \a other.
 901 */
 902
 903 /*! \fn QJsonValue QJsonArray::const_iterator::operator*() const
 904
 905     Returns the current item.
 906 */
 907
 908 /*! \fn QJsonValue QJsonArray::const_iterator::operator[](int j) const
 909
 910     Returns the item at position \c{*this + j}.
 911
 912     This function is provided to make QJsonArray iterators behave like C++
 913     pointers.
 914
 915     \sa operator+()
 916 */
 917
 918 /*! \fn bool QJsonArray::const_iterator::operator==(const const_iterator &other) const
 919
 920     Returns \c true if \a other points to the same item as this
 921     iterator; otherwise returns \c false.
 922
 923     \sa operator!=()
 924 */
 925
 926 /*! \fn bool QJsonArray::const_iterator::operator!=(const const_iterator &other) const
 927
 928     Returns \c true if \a other points to a different item than this
 929     iterator; otherwise returns \c false.
 930
 931     \sa operator==()
 932 */
 933
 934 /*!
 935     \fn bool QJsonArray::const_iterator::operator<(const const_iterator& other) const
 936
 937     Returns \c true if the item pointed to by this iterator is less than
 938     the item pointed to by the \a other iterator.
 939 */
 940
 941 /*!
 942     \fn bool QJsonArray::const_iterator::operator<=(const const_iterator& other) const
 943
 944     Returns \c true if the item pointed to by this iterator is less than
 945     or equal to the item pointed to by the \a other iterator.
 946 */
 947
 948 /*!
 949     \fn bool QJsonArray::const_iterator::operator>(const const_iterator& other) const
 950
 951     Returns \c true if the item pointed to by this iterator is greater
 952     than the item pointed to by the \a other iterator.
 953 */
 954
 955 /*!
 956     \fn bool QJsonArray::const_iterator::operator>=(const const_iterator& other) const
 957
 958     Returns \c true if the item pointed to by this iterator is greater
 959     than or equal to the item pointed to by the \a other iterator.
 960 */
 961
 962 /*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator++()
 963
 964     The prefix ++ operator, \c{++it}, advances the iterator to the
 965     next item in the array and returns an iterator to the new current
 966     item.
 967
 968     Calling this function on QJsonArray::end() leads to undefined results.
 969
 970     \sa operator--()
 971 */
 972
 973 /*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator++(int)
 974
 975     \overload
 976
 977     The postfix ++ operator, \c{it++}, advances the iterator to the
 978     next item in the array and returns an iterator to the previously
 979     current item.
 980 */
 981
 982 /*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator--()
 983
 984     The prefix -- operator, \c{--it}, makes the preceding item
 985     current and returns an iterator to the new current item.
 986
 987     Calling this function on QJsonArray::begin() leads to undefined results.
 988
 989     \sa operator++()
 990 */
 991
 992 /*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator--(int)
 993
 994     \overload
 995
 996     The postfix -- operator, \c{it--}, makes the preceding item
 997     current and returns an iterator to the previously current item.
 998 */
 999
1000 /*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator+=(int j)
1001
1002     Advances the iterator by \a j items. If \a j is negative, the
1003     iterator goes backward.
1004
1005     \sa operator-=(), operator+()
1006 */
1007
1008 /*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator-=(int j)
1009
1010     Makes the iterator go back by \a j items. If \a j is negative,
1011     the iterator goes forward.
1012
1013     \sa operator+=(), operator-()
1014 */
1015
1016 /*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator+(int j) const
1017
1018     Returns an iterator to the item at \a j positions forward from
1019     this iterator. If \a j is negative, the iterator goes backward.
1020
1021     \sa operator-(), operator+=()
1022 */
1023
1024 /*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator-(int j) const
1025
1026     Returns an iterator to the item at \a j positions backward from
1027     this iterator. If \a j is negative, the iterator goes forward.
1028
1029     \sa operator+(), operator-=()
1030 */
1031
1032 /*! \fn int QJsonArray::const_iterator::operator-(const_iterator other) const
1033
1034     Returns the number of items between the item pointed to by \a
1035     other and the item pointed to by this iterator.
1036 */
1037
1038
1039 /*!
1040     \internal
1041  */
1042 void QJsonArray::detach(uint reserve)
1043 {
1044     if (!d) {
1045         d = new QJsonPrivate::Data(reserve, QJsonValue::Array);
1046         a = static_cast<QJsonPrivate::Array *>(d->header->root());
1047         d->ref.ref();
1048         return;
1049     }
1050     if (reserve == 0 && d->ref.load() == 1)
1051         return;
1052
1053     QJsonPrivate::Data *x = d->clone(a, reserve);
1054     x->ref.ref();
1055     if (!d->ref.deref())
1056         delete d;
1057     d = x;
1058     a = static_cast<QJsonPrivate::Array *>(d->header->root());
1059 }
1060
1061 /*!
1062     \internal
1063  */
1064 void QJsonArray::compact()
1065 {
1066     if (!d || !d->compactionCounter)
1067         return;
1068
1069     detach();
1070     d->compact();
1071     a = static_cast<QJsonPrivate::Array *>(d->header->root());
1072 }
1073
1074
1075 #ifndef QT_NO_DEBUG_STREAM
1076 QDebug operator<<(QDebug dbg, const QJsonArray &a)
1077 {
1078     if (!a.a) {
1079         dbg << "QJsonArray()";
1080         return dbg;
1081     }
1082     QByteArray json;
1083     QJsonPrivate::Writer::arrayToJson(a.a, json, 0, true);
1084     dbg.nospace() << "QJsonArray("
1085                   << json.constData() // print as utf-8 string without extra quotation marks
1086                   << ")";
1087     return dbg.space();
1088 }
1089 #endif
1090
1091 QT_END_NAMESPACE
1092