From 24d0cc2cc4623457df17bbecf4e8a6594f02eba1 Mon Sep 17 00:00:00 2001 From: Lars Knoll Date: Mon, 16 Jan 2012 12:24:54 +0100 Subject: Add docs for QJsonArray Change-Id: I72f8fb7e647e5c7bf3b045268ab104dbb2569ffe Sanity-Review: Qt Sanity Bot Reviewed-by: Denis Dzyubenko --- src/qjsonarray.cpp | 685 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 684 insertions(+), 1 deletion(-) diff --git a/src/qjsonarray.cpp b/src/qjsonarray.cpp index 70c6d3c..cfd77d1 100644 --- a/src/qjsonarray.cpp +++ b/src/qjsonarray.cpp @@ -51,23 +51,57 @@ namespace QtJson { +/*! + \class QJsonArray + \ingroup json + \reentrant + \since 5.0 + + \brief The QJsonArray class encapsulates a JSON array. + + A JSON array is a list values. The list can be manipulated by inserting and + removing QJsonValue's from the array. + + A QJsonArray can be converted from and to a QVariantList, you can query the + number of entries with size(), insert() and remove() entries from it + and iterate over it's content using the standard C++ iterator pattern. + + QJsonArray is an implicitly shared class, and shares the data with the document + it has been created from as long as it is not being modified. +*/ + +/*! + Creates an empty array. + */ QJsonArray::QJsonArray() : d(0), a(0) { } +/*! + \internal + */ QJsonArray::QJsonArray(Private::Data *data, Private::Array *array) : d(data), a(array) { d->ref.ref(); } +/*! + Deletes the array + */ QJsonArray::~QJsonArray() { if (d && !d->ref.deref()) delete d; } +/*! + Creates a copy of \a other. + + Since QJsonArray is implicitly shared, the copy is shallow + as long as the object doesn't get modified. + */ QJsonArray::QJsonArray(const QJsonArray &other) { d = other.d; @@ -76,6 +110,9 @@ QJsonArray::QJsonArray(const QJsonArray &other) d->ref.ref(); } +/*! + Assigns \a other to this array. + */ QJsonArray &QJsonArray::operator =(const QJsonArray &other) { if (d != other.d) { @@ -90,6 +127,13 @@ QJsonArray &QJsonArray::operator =(const QJsonArray &other) return *this; } +/*! + Converts the string list \a list to a QJsonArray. + + The values in \a list will be converted to JSON values. + + \sa toVariantList, QJsonValue::fromString + */ QJsonArray QJsonArray::fromStringList(const QStringList &list) { QJsonArray array; @@ -98,6 +142,13 @@ QJsonArray QJsonArray::fromStringList(const QStringList &list) return array; } +/*! + Converts the variant list \a list to a QJsonArray. + + The QVariant values in \a list will be converted to JSON values. + + \sa toVariantList, QJsonValue::fromVariant + */ QJsonArray QJsonArray::fromVariantList(const QVariantList &list) { QJsonArray array; @@ -106,6 +157,11 @@ QJsonArray QJsonArray::fromVariantList(const QVariantList &list) return array; } +/*! + Converts this object to a QVariantList. + + \returns the created map. + */ QVariantList QJsonArray::toVariantList() const { QVariantList list; @@ -118,6 +174,10 @@ QVariantList QJsonArray::toVariantList() const } +/*! + \returns the size of this object, ie. the number of + values stored in it. + */ int QJsonArray::size() const { if (!d) @@ -126,6 +186,11 @@ int QJsonArray::size() const return (int)a->length; } +/*! + \returns true if the object is empty. This is the same as size() == 0. + + \sa size + */ bool QJsonArray::isEmpty() const { if (!d) @@ -134,6 +199,12 @@ bool QJsonArray::isEmpty() const return !a->length; } +/*! + \returns a QJsonValue representing the value for index \a i. + + The returned QJsonValue is Undefined, if i is out of bounds. + + */ QJsonValue QJsonArray::at(int i) const { if (!a || i < 0 || i >= (int)a->length) @@ -142,26 +213,58 @@ QJsonValue QJsonArray::at(int i) const return QJsonValue(d, a, a->at(i)); } +/*! + Returns the first value stored in the array. + + Same as at(0). + + \sa at + */ QJsonValue QJsonArray::first() const { return at(0); } +/*! + Returns the last value stored in the array. + + Same as at(size() - 1). + + \sa at + */ QJsonValue QJsonArray::last() const { return at(a ? (a->length - 1) : 0); } +/*! + Inserts \a value at the beginning of the array. + + This is the same as array.insert(0, \a value). + + \sa append(), insert() + */ void QJsonArray::prepend(const QJsonValue &value) { insert(0, value); } +/*! + Inserts \a value at the end of the array. + + \sa prepend(), insert() + */ void QJsonArray::append(const QJsonValue &value) { insert(a ? a->length : 0, value); } +/*! + Removes the value at index position \a i. \a i must be a valid + index position in the array (i.e., 0 <= \a i < size()). + + \sa insert(), replace() + */ void QJsonArray::removeAt(int i) { if (!a || i < 0 || i >= (int)a->length) @@ -174,6 +277,34 @@ void QJsonArray::removeAt(int i) compact(); } +/*! \fn void QJsonArray::removeFirst() + + Removes the first item in the array. Calling this function is + equivalent to calling removeAt(0). The array must not be empty. If + the array can be empty, call isEmpty() before calling this + function. + + \sa removeAt(), takeFirst() +*/ + +/*! \fn void QJsonArray::removeLast() + + Removes the last item in the array. Calling this function is + equivalent to calling removeAt(size() - 1). The array must not be + empty. If the array can be empty, call isEmpty() before calling + this function. + + \sa removeAt(), takeLast() +*/ + +/*! + Removes the item at index position \a i and returns it. \a i must + be a valid index position in the array (i.e., 0 <= \a i < size()). + + If you don't use the return value, removeAt() is more efficient. + + \sa removeAt() + */ QJsonValue QJsonArray::takeAt(int i) { if (!a || i < 0 || i >= (int)a->length) @@ -189,6 +320,13 @@ QJsonValue QJsonArray::takeAt(int i) return v; } +/*! + Inserts \a value at index position \a i in the array. If \a i + is 0, the value is prepended to the array. If \a i is size(), the + value is appended to the array. + + \sa append(), prepend(), replace(), removeAt() + */ void QJsonArray::insert(int i, const QJsonValue &value) { Q_ASSERT (i >= 0 && i <= (int)(a ? a->length : 0)); @@ -211,6 +349,12 @@ void QJsonArray::insert(int i, const QJsonValue &value) value.copyData((char *)a + valueOffset, compressed); } +/*! + Replaces the item at index position \a i with \a value. \a i must + be a valid index position in the array (i.e., 0 <= \a i < size()). + + \sa operator[](), removeAt() + */ void QJsonArray::replace(int i, const QJsonValue &value) { Q_ASSERT (a && i >= 0 && i < (int)(a->length)); @@ -237,7 +381,12 @@ void QJsonArray::replace(int i, const QJsonValue &value) compact(); } -bool QJsonArray::contains(const QJsonValue &element) const +/*! + Returns true if the array contains an occurrence of \a value, otherwise false. + + \sa count() + */ +bool QJsonArray::contains(const QJsonValue &value) const { for (int i = 0; i < size(); i++) { if (at(i) == element) @@ -246,17 +395,38 @@ bool QJsonArray::contains(const QJsonValue &element) const return false; } +/*! + Returns the value at index position \a i as a modifiable reference. + \a i must be a valid index position in the array (i.e., 0 <= \a i < + size()). + + The return value is of type QJsonValueRef, a helper class for QJsonArray + and QJsonObject. When you get an object of type QJsonValueRef, you can + use it as if it were a QJsonValue &. If you assign to it, the assignment + will apply to the character in the QJsonArray of QJsonObject from which + you got the reference. + + \sa at(), value() + */ QJsonValueRef QJsonArray::operator [](int i) { Q_ASSERT(a && i >= 0 && i < (int)a->length); return QJsonValueRef(this, i); } +/*! + \overload + + Same as at(). + */ QJsonValue QJsonArray::operator[](int i) const { return at(i); } +/*! + Returns true if this array is equal to \a other. + */ bool QJsonArray::operator==(const QJsonArray &other) const { if (a == other.a) @@ -276,11 +446,521 @@ bool QJsonArray::operator==(const QJsonArray &other) const return true; } +/*! + Returns true if this array is not equal to \a other. + */ bool QJsonArray::operator!=(const QJsonArray &other) const { return !(*this == other); } +/*! \fn QJsonArray::iterator QJsonArray::begin() + + Returns an \l{STL-style iterator} pointing to the first item in + the array. + + \sa constBegin(), end() +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::begin() const + + \overload +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::constBegin() const + + Returns a const \l{STL-style iterator} pointing to the first item + in the array. + + \sa begin(), constEnd() +*/ + +/*! \fn QJsonArray::iterator QJsonArray::end() + + Returns an \l{STL-style iterator} pointing to the imaginary item + after the last item in the array. + + \sa begin(), constEnd() +*/ + +/*! \fn const_iterator QJsonArray::end() const + + \overload +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::constEnd() const + + Returns a const \l{STL-style iterator} pointing to the imaginary + item after the last item in the array. + + \sa constBegin(), end() +*/ + +/*! \fn void QJsonArray::push_back(const T &value) + + This function is provided for STL compatibility. It is equivalent + to \l{QJsonArray::append()}{append(\a value)}. +*/ + +/*! \fn void QJsonArray::push_front(const T &value) + + This function is provided for STL compatibility. It is equivalent + to \l{QJsonArray::prepend()}{prepend(\a value)}. +*/ + +/*! \fn void QJsonArray::pop_front() + + This function is provided for STL compatibility. It is equivalent + to removeFirst(). The array must not be empty. If the array can be + empty, call isEmpty() before calling this function. +*/ + +/*! \fn void QJsonArray::pop_back() + + This function is provided for STL compatibility. It is equivalent + to removeLast(). The array must not be empty. If the array can be + empty, call isEmpty() before calling this function. +*/ + +/*! \fn bool QJsonArray::empty() const + + This function is provided for STL compatibility. It is equivalent + to isEmpty() and returns true if the array is empty. +*/ + +/*! \class QJsonArray::iterator + \brief The QJsonArray::iterator class provides an STL-style non-const iterator for QJsonArray. + + QJsonArray::iterator allows you to iterate over a QJsonArray + and to modify the array item associated with the + iterator. If you want to iterate over a const QJsonArray, use + QJsonArray::const_iterator instead. It is generally good practice to + use QJsonArray::const_iterator on a non-const QJsonArray as well, unless + you need to change the QJsonArray through the iterator. Const + iterators are slightly faster, and can improve code readability. + + The default QJsonArray::iterator constructor creates an uninitialized + iterator. You must initialize it using a QJsonArray function like + QJsonArray::begin(), QJsonArray::end(), or QJsonArray::insert() before you can + start iterating. + + Most QJsonArray functions accept an integer index rather than an + iterator. For that reason, iterators are rarely useful in + connection with QJsonArray. One place where STL-style iterators do + make sense is as arguments to \l{generic algorithms}. + + Multiple iterators can be used on the same array. However, be + aware that any non-const function call performed on the QJsonArray + will render all existing iterators undefined. + + \sa QJsonArray::const_iterator +*/ + +/*! \typedef QJsonArray::iterator::iterator_category + + A synonym for \e {std::random_access_iterator_tag} indicating + this iterator is a random access iterator. +*/ + +/*! \typedef QJsonArray::iterator::difference_type + + \internal +*/ + +/*! \typedef QJsonArray::iterator::value_type + + \internal +*/ + +/*! \typedef QJsonArray::iterator::reference + + \internal +*/ + +/*! \fn QJsonArray::iterator::iterator() + + Constructs an uninitialized iterator. + + Functions like operator*() and operator++() should not be called + on an uninitialized iterator. Use operator=() to assign a value + to it before using it. + + \sa QJsonArray::begin() QJsonArray::end() +*/ + +/*! \fn QJsonArray::iterator::iterator(const iterator &other) + + Constructs a copy of \a other. +*/ + +/*! \fn QJsonValueRef QJsonArray::iterator::operator*() const + + Returns a modifiable reference to the current item. + + You can change the value of an item by using operator*() on the + left side of an assignment. + + The return value is of type QJsonValueRef, a helper class for QJsonArray + and QJsonObject. When you get an object of type QJsonValueRef, you can + use it as if it were a QJsonValue &. If you assign to it, the assignment + will apply to the character in the QJsonArray of QJsonObject from which + you got the reference. +*/ + +/*! \fn QJsonValueRef QJsonArray::iterator::operator[](int j) const + + Returns a modifiable reference to the item at position *this + + \a{j}. + + This function is provided to make QJsonArray iterators behave like C++ + pointers. + + The return value is of type QJsonValueRef, a helper class for QJsonArray + and QJsonObject. When you get an object of type QJsonValueRef, you can + use it as if it were a QJsonValue &. If you assign to it, the assignment + will apply to the character in the QJsonArray of QJsonObject from which + you got the reference. + + \sa operator+() +*/ + +/*! + \fn bool QJsonArray::iterator::operator==(const iterator &other) const + \fn bool QJsonArray::iterator::operator==(const const_iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! + \fn bool QJsonArray::iterator::operator!=(const iterator &other) const + \fn bool QJsonArray::iterator::operator!=(const const_iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn bool QJsonArray::iterator::operator<(const iterator& other) const + \fn bool QJsonArray::iterator::operator<(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is less than + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::iterator::operator<=(const iterator& other) const + \fn bool QJsonArray::iterator::operator<=(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is less than + or equal to the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::iterator::operator>(const iterator& other) const + \fn bool QJsonArray::iterator::operator>(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is greater + than the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::iterator::operator>=(const iterator& other) const + \fn bool QJsonArray::iterator::operator>=(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is greater + than or equal to the item pointed to by the \a other iterator. +*/ + +/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator++() + + The prefix ++ operator (\c{++it}) advances the iterator to the + next item in the array and returns an iterator to the new current + item. + + Calling this function on QJsonArray::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn QJsonArray::iterator QJsonArray::iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{it++}) advances the iterator to the + next item in the array and returns an iterator to the previously + current item. +*/ + +/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator--() + + The prefix -- operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QJsonArray::begin() leads to undefined results. + + \sa operator++() +*/ + +/*! \fn QJsonArray::iterator QJsonArray::iterator::operator--(int) + + \overload + + The postfix -- operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. +*/ + +/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + \sa operator-=(), operator+() +*/ + +/*! \fn QJsonArray::iterator &QJsonArray::iterator::operator-=(int j) + + Makes the iterator go back by \a j items. (If \a j is negative, + the iterator goes forward.) + + \sa operator+=(), operator-() +*/ + +/*! \fn QJsonArray::iterator QJsonArray::iterator::operator+(int j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. (If \a j is negative, the iterator goes backward.) + + \sa operator-(), operator+=() +*/ + +/*! \fn QJsonArray::iterator QJsonArray::iterator::operator-(int j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. (If \a j is negative, the iterator goes forward.) + + \sa operator+(), operator-=() +*/ + +/*! \fn int QJsonArray::iterator::operator-(iterator other) const + + Returns the number of items between the item pointed to by \a + other and the item pointed to by this iterator. +*/ + +/*! \class QJsonArray::const_iterator + \brief The QJsonArray::const_iterator class provides an STL-style const iterator for QJsonArray. + + QJsonArray::const_iterator allows you to iterate over a + QJsonArray. If you want to modify the QJsonArray as + you iterate over it, use QJsonArray::iterator instead. It is generally + good practice to use QJsonArray::const_iterator on a non-const QJsonArray + as well, unless you need to change the QJsonArray through the + iterator. Const iterators are slightly faster, and can improve + code readability. + + The default QJsonArray::const_iterator constructor creates an + uninitialized iterator. You must initialize it using a QJsonArray + function like QJsonArray::constBegin(), QJsonArray::constEnd(), or + QJsonArray::insert() before you can start iterating. + + Most QJsonArray functions accept an integer index rather than an + iterator. For that reason, iterators are rarely useful in + connection with QJsonArray. One place where STL-style iterators do + make sense is as arguments to \l{generic algorithms}. + + Multiple iterators can be used on the same array. However, be + aware that any non-const function call performed on the QJsonArray + will render all existing iterators undefined. + + \sa QJsonArray::iterator, QJsonArrayIterator +*/ + +/*! \fn QJsonArray::const_iterator::const_iterator() + + Constructs an uninitialized iterator. + + Functions like operator*() and operator++() should not be called + on an uninitialized iterator. Use operator=() to assign a value + to it before using it. + + \sa QJsonArray::constBegin() QJsonArray::constEnd() +*/ + +/*! \typedef QJsonArray::const_iterator::iterator_category + + A synonym for \e {std::random_access_iterator_tag} indicating + this iterator is a random access iterator. +*/ + +/*! \typedef QJsonArray::const_iterator::difference_type + + \internal +*/ + +/*! \typedef QJsonArray::const_iterator::value_type + + \internal +*/ + +/*! \typedef QJsonArray::const_iterator::reference + + \internal +*/ + +/*! \fn QJsonArray::const_iterator::const_iterator(const const_iterator &other) + + Constructs a copy of \a other. +*/ + +/*! \fn QJsonArray::const_iterator::const_iterator(const iterator &other) + + Constructs a copy of \a other. +*/ + +/*! \fn QJsonValue QJsonArray::const_iterator::operator*() const + + Returns the current item. +*/ + +/*! \fn QJsonValue QJsonArray::const_iterator::operator[](int j) const + + Returns the item at position *this + \a{j}. + + This function is provided to make QJsonArray iterators behave like C++ + pointers. + + \sa operator+() +*/ + +/*! \fn bool QJsonArray::const_iterator::operator==(const const_iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! \fn bool QJsonArray::const_iterator::operator!=(const const_iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn bool QJsonArray::const_iterator::operator<(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is less than + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::const_iterator::operator<=(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is less than + or equal to the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::const_iterator::operator>(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is greater + than the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool QJsonArray::const_iterator::operator>=(const const_iterator& other) const + + Returns true if the item pointed to by this iterator is greater + than or equal to the item pointed to by the \a other iterator. +*/ + +/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator++() + + The prefix ++ operator (\c{++it}) advances the iterator to the + next item in the array and returns an iterator to the new current + item. + + Calling this function on QJsonArray::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{it++}) advances the iterator to the + next item in the array and returns an iterator to the previously + current item. +*/ + +/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator--() + + The prefix -- operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QJsonArray::begin() leads to undefined results. + + \sa operator++() +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator--(int) + + \overload + + The postfix -- operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. +*/ + +/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + \sa operator-=(), operator+() +*/ + +/*! \fn QJsonArray::const_iterator &QJsonArray::const_iterator::operator-=(int j) + + Makes the iterator go back by \a j items. (If \a j is negative, + the iterator goes forward.) + + \sa operator+=(), operator-() +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator+(int j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. (If \a j is negative, the iterator goes backward.) + + \sa operator-(), operator+=() +*/ + +/*! \fn QJsonArray::const_iterator QJsonArray::const_iterator::operator-(int j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. (If \a j is negative, the iterator goes forward.) + + \sa operator+(), operator-=() +*/ + +/*! \fn int QJsonArray::const_iterator::operator-(const_iterator other) const + + Returns the number of items between the item pointed to by \a + other and the item pointed to by this iterator. +*/ + + +/*! + \internal + */ void QJsonArray::detach(uint reserve) { if (!d) { @@ -300,6 +980,9 @@ void QJsonArray::detach(uint reserve) a = static_cast(d->header->root()); } +/*! + \internal + */ void QJsonArray::compact() const { if (!d || !d->compactionCounter) -- cgit v1.2.3