From 8cd955416cb809ba750dd6f67ce4370c9b660ea2 Mon Sep 17 00:00:00 2001 From: Lars Knoll Date: Mon, 16 Jan 2012 10:41:07 +0100 Subject: Add documentation for QJsonObject Change-Id: Ia5a129749b3eb831e84d217cb42607003e5ef841 Sanity-Review: Qt Sanity Bot Reviewed-by: Denis Dzyubenko --- src/qjsonobject.cpp | 616 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 616 insertions(+) diff --git a/src/qjsonobject.cpp b/src/qjsonobject.cpp index d855eee..b3ddfe4 100644 --- a/src/qjsonobject.cpp +++ b/src/qjsonobject.cpp @@ -49,11 +49,38 @@ namespace QtJson { +/*! + \class QJsonObject + \ingroup json + \reentrant + \since 5.0 + + \brief The QJsonObject class encapsulates a JSON object. + + A JSON object is a list of key value pairs, where the keys are unique strings + and the values are represented by a QJsonValue. + + A QJsonObject can be converted from and to a QVariantMap, you can query the + number of key/value pairs with size(), insert() and remove() entries from it + and iterate over it's content using the standard C++ iterator pattern. + + QJsonObject 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. +*/ + +/*! + Constructs an empty JSON object + + \sa isEmpty + */ QJsonObject::QJsonObject() : d(0), o(0) { } +/*! + \internal + */ QJsonObject::QJsonObject(Private::Data *data, Private::Object *object) : d(data), o(object) { @@ -63,12 +90,21 @@ QJsonObject::QJsonObject(Private::Data *data, Private::Object *object) } +/*! + Destroys the object. + */ QJsonObject::~QJsonObject() { if (d && !d->ref.deref()) delete d; } +/*! + Creates a copy of \a other. + + Since QJsonObject is implicitly shared, the copy is shallow + as long as the object doesn't get modified. + */ QJsonObject::QJsonObject(const QJsonObject &other) { d = other.d; @@ -77,6 +113,9 @@ QJsonObject::QJsonObject(const QJsonObject &other) d->ref.ref(); } +/*! + Assigns \a other to this object. + */ QJsonObject &QJsonObject::operator =(const QJsonObject &other) { if (d != other.d) { @@ -91,6 +130,14 @@ QJsonObject &QJsonObject::operator =(const QJsonObject &other) return *this; } +/*! + Converts the variant map \a map to a QJsonObject. + + The keys in \a map will be used as the keys in the JSON object, + and the QVariant values will be converted to JSON values. + + \sa toVariantMap, QJsonValue::fromVariant + */ QJsonObject QJsonObject::fromVariantMap(const QVariantMap &map) { // ### this is implemented the trivial way, not the most efficient way @@ -101,6 +148,11 @@ QJsonObject QJsonObject::fromVariantMap(const QVariantMap &map) return object; } +/*! + Converts this object to a QVariantMap. + + \returns the created map. + */ QVariantMap QJsonObject::toVariantMap() const { QVariantMap map; @@ -111,6 +163,9 @@ QVariantMap QJsonObject::toVariantMap() const return map; } +/*! + \returns a list of all keys in this object. + */ QStringList QJsonObject::keys() const { if (!d) @@ -126,6 +181,10 @@ QStringList QJsonObject::keys() const return keys; } +/*! + \returns the size of this object, ie. the number of + key/value pairs stored in it. + */ int QJsonObject::size() const { if (!d) @@ -134,6 +193,11 @@ int QJsonObject::size() const return o->length; } +/*! + \returns true if the object is empty. This is the same as size() == 0. + + \sa size + */ bool QJsonObject::isEmpty() const { if (!d) @@ -142,6 +206,13 @@ bool QJsonObject::isEmpty() const return !o->length; } +/*! + \returns a QJsonValue representing the value for the key \a key. + + The returned QJsonValue is Undefined, if the key does not exist. + + \sa setValue, QJsonValue, QJsonValue::isUndefined + */ QJsonValue QJsonObject::value(const QString &key) const { if (!d) @@ -155,11 +226,31 @@ QJsonValue QJsonObject::value(const QString &key) const return QJsonValue(QJsonValue::Undefined); } +/*! + \returns a QJsonValue representing the value for the key \a key. + + This does the same as value(). + + The returned QJsonValue is Undefined, if the key does not exist. + + \sa value, setValue, QJsonValue, QJsonValue::isUndefined + */ QJsonValue QJsonObject::operator [](const QString &key) const { return value(key); } +/*! + \returns a reference to the value for \a key. + + 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 setValue, value + */ QJsonValueRef QJsonObject::operator [](const QString &key) { int index = o ? o->indexOf(key) : -1; @@ -170,6 +261,19 @@ QJsonValueRef QJsonObject::operator [](const QString &key) return QJsonValueRef(this, index); } +/*! + Inserts a new item with the key \a key and a value of \a value. + + If there is already an item with the key \a key, that item's value + is replaced with \a value. + + \returns an iterator pointing to the inserted item. + + If the value is QJsonValue::Undefined, it will cause the key to get removed + from the object. The returned iterator will then point to end() + + \sa remove, take, QJsonObject::iterator, end + */ QJsonObject::iterator QJsonObject::insert(const QString &key, const QJsonValue &value) { if (value.t == QJsonValue::Undefined) { @@ -212,6 +316,11 @@ QJsonObject::iterator QJsonObject::insert(const QString &key, const QJsonValue & return iterator(this, pos); } +/*! + Removes \a key from the object. + + \sa insert, take + */ void QJsonObject::remove(const QString &key) { if (!d) @@ -228,6 +337,15 @@ void QJsonObject::remove(const QString &key) compact(); } +/*! + Removes \a key from the object. + + \returns a QJsonValue containing the value referenced by \a key. + If \a key was not contained in the object, the returned QJsonValue + is Undefined. + + \sa insert, remove, QJsonValue + */ QJsonValue QJsonObject::take(const QString &key) { if (!o) @@ -246,6 +364,11 @@ QJsonValue QJsonObject::take(const QString &key) return QJsonValue(d, o, e->value); } +/*! + \returns true if the object contains key \a key. + + \sa insert, remove, take + */ bool QJsonObject::contains(const QString &key) const { if (!o) @@ -254,6 +377,9 @@ bool QJsonObject::contains(const QString &key) const return o->indexOf(key) >= 0; } +/*! + \returns true if \a other is equal to this object + */ bool QJsonObject::operator==(const QJsonObject &other) const { if (o == other.o) @@ -276,11 +402,21 @@ bool QJsonObject::operator==(const QJsonObject &other) const return true; } +/*! + \returns true if \a other is not equal to this object + */ bool QJsonObject::operator!=(const QJsonObject &other) const { return !(*this == other); } +/*! + Removes the (key, value) pair pointed to by the iterator \a it + from the map, and returns an iterator to the next item in the + map. + + \sa remove() + */ QJsonObject::iterator QJsonObject::erase(QJsonObject::iterator it) { Q_ASSERT(d && d->ref.load() == 1); @@ -298,6 +434,13 @@ QJsonObject::iterator QJsonObject::erase(QJsonObject::iterator it) return it; } +/*! + Returns an iterator pointing to the item with key \a key in the + map. + + If the map contains no item with key \a key, the function + returns end(). + */ QJsonObject::iterator QJsonObject::find(const QString &key) { int index = o ? o->indexOf(key) : 0; @@ -306,6 +449,18 @@ QJsonObject::iterator QJsonObject::find(const QString &key) return iterator(this, index); } +/*! \fn QJsonObject::const_iterator QJsonObject::find(const Key &key) const + + \overload +*/ + +/*! + Returns an const iterator pointing to the item with key \a key in the + map. + + If the map contains no item with key \a key, the function + returns constEnd(). + */ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const { int index = o ? o->indexOf(key) : 0; @@ -314,6 +469,434 @@ QJsonObject::const_iterator QJsonObject::constFind(const QString &key) const return const_iterator(this, index); } +/*! \fn int QJsonObject::count() const + + \overload + + Same as size(). +*/ + +/*! \fn QJsonObject::iterator QJsonObject::begin() + + Returns an \l{STL-style iterator} pointing to the first item in + the object. + + \sa constBegin(), end() +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::begin() const + + \overload +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::constBegin() const + + Returns a const \l{STL-style iterator} pointing to the first item + in the object. + + \sa begin(), constEnd() +*/ + +/*! \fn QJsonObject::iterator QJsonObject::end() + + Returns an \l{STL-style iterator} pointing to the imaginary item + after the last item in the object. + + \sa begin(), constEnd() +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::end() const + + \overload +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::constEnd() const + + Returns a const \l{STL-style iterator} pointing to the imaginary + item after the last item in the object. + + \sa constBegin(), end() +*/ + +/*! + \fn bool QJsonObject::empty() const + + This function is provided for STL compatibility. It is equivalent + to isEmpty(), returning true if the object is empty; otherwise + returning false. +*/ + +/*! \class QJsonObject::iterator + \brief The QJsonObject::iterator class provides an STL-style non-const iterator for QJsonObject. + + QJsonObject::iterator allows you to iterate over a QJsonObject + and to modify the value (but not the key) stored under + a particular key. If you want to iterate over a const QJsonObject, you + should use QJsonObject::const_iterator. It is generally good practice to + use QJsonObject::const_iterator on a non-const QJsonObject as well, unless you + need to change the QJsonObject through the iterator. Const iterators are + slightly faster, and can improve code readability. + + The default QJsonObject::iterator constructor creates an uninitialized + iterator. You must initialize it using a QJsonObject function like + QJsonObject::begin(), QJsonObject::end(), or QJsonObject::find() before you can + start iterating. + + Multiple iterators can be used on the same object. Existing iterators will however + become dangling once the object gets modified. + + \sa QJsonObject::const_iterator +*/ + +/*! \typedef QJsonObject::iterator::difference_type + + \internal +*/ + +/*! \typedef QJsonObject::iterator::iterator_category + + A synonym for \e {std::bidirectional_iterator_tag} indicating + this iterator is a bidirectional iterator. +*/ + +/*! \typedef QJsonObject::iterator::reference + + \internal +*/ + +/*! \typedef QJsonObject::iterator::value_type + + \internal +*/ + +/*! \fn QJsonObject::iterator::iterator() + + Constructs an uninitialized iterator. + + Functions like key(), value(), and operator++() must not be + called on an uninitialized iterator. Use operator=() to assign a + value to it before using it. + + \sa QJsonObject::begin() QJsonObject::end() +*/ + +/*! \fn QString QJsonObject::iterator::key() const + + Returns the current item's key. + + There is no direct way of changing an item's key through an + iterator, although it can be done by calling QJsonObject::erase() + followed by QJsonObject::insert(). + + \sa value() +*/ + +/*! \fn QJsonValueRef QJsonObject::iterator::value() const + + Returns a modifiable reference to the current item's value. + + You can change the value of an item by using value() 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. + + \sa key(), operator*() +*/ + +/*! \fn QJsonValueRef QJsonObject::iterator::operator*() const + + Returns a modifiable reference to the current item's value. + + Same as value(). + + 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 key() +*/ + +/*! + \fn bool QJsonObject::iterator::operator==(const iterator &other) const + \fn bool QJsonObject::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 QJsonObject::iterator::operator!=(const iterator &other) const + \fn bool QJsonObject::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 QJsonObject::iterator QJsonObject::iterator::operator++() + + The prefix ++ operator (\c{++i}) advances the iterator to the + next item in the object and returns an iterator to the new current + item. + + Calling this function on QJsonObject::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn QJsonObject::iterator QJsonObject::iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{i++}) advances the iterator to the + next item in the object and returns an iterator to the previously + current item. +*/ + +/*! \fn QJsonObject::iterator QJsonObject::iterator::operator--() + + The prefix -- operator (\c{--i}) makes the preceding item + current and returns an iterator pointing to the new current item. + + Calling this function on QJsonObject::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! \fn QJsonObject::iterator QJsonObject::iterator::operator--(int) + + \overload + + The postfix -- operator (\c{i--}) makes the preceding item + current and returns an iterator pointing to the previously + current item. +*/ + +/*! \fn QJsonObject::iterator QJsonObject::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-() + +*/ + +/*! \fn QJsonObject::iterator QJsonObject::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+() +*/ + +/*! \fn QJsonObject::iterator &QJsonObject::iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + \sa operator-=(), operator+() +*/ + +/*! \fn QJsonObject::iterator &QJsonObject::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-() +*/ + +/*! \class QJsonObject::const_iterator + \brief The QJsonObject::const_iterator class provides an STL-style const iterator for QJsonObject. + + QJsonObject::const_iterator allows you to iterate over a QJsonObject. + If you want to modify the QJsonObject as you iterate + over it, you must use QJsonObject::iterator instead. It is generally + good practice to use QJsonObject::const_iterator on a non-const QJsonObject as + well, unless you need to change the QJsonObject through the iterator. + Const iterators are slightly faster, and can improve code + readability. + + The default QJsonObject::const_iterator constructor creates an + uninitialized iterator. You must initialize it using a QJsonObject + function like QJsonObject::constBegin(), QJsonObject::constEnd(), or + QJsonObject::find() before you can start iterating. + + Multiple iterators can be used on the same object. Existing iterators + will however become dangling if the object gets modified. + + \sa QJsonObject::iterator, QJsonObjectIterator +*/ + +/*! \typedef QJsonObject::const_iterator::difference_type + + \internal +*/ + +/*! \typedef QJsonObject::const_iterator::iterator_category + + A synonym for \e {std::bidirectional_iterator_tag} indicating + this iterator is a bidirectional iterator. +*/ + +/*! \typedef QJsonObject::const_iterator::reference + + \internal +*/ + +/*! \typedef QJsonObject::const_iterator::value_type + + \internal +*/ + +/*! \fn QJsonObject::const_iterator::const_iterator() + + Constructs an uninitialized iterator. + + Functions like key(), value(), and operator++() must not be + called on an uninitialized iterator. Use operator=() to assign a + value to it before using it. + + \sa QJsonObject::constBegin() QJsonObject::constEnd() +*/ + +/*! \fn QJsonObject::const_iterator::const_iterator(const iterator &other) + + Constructs a copy of \a other. +*/ + +/*! \fn QString QJsonObject::const_iterator::key() const + + Returns the current item's key. + + \sa value() +*/ + +/*! \fn QJsonValue QJsonObject::const_iterator::value() const + + Returns the current item's value. + + \sa key(), operator*() +*/ + +/*! \fn QJsonValue QJsonObject::const_iterator::operator*() const + + Returns the current item's value. + + Same as value(). + + \sa key() +*/ + +/*! \fn bool QJsonObject::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 QJsonObject::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 QJsonObject::const_iterator QJsonObject::const_iterator::operator++() + + The prefix ++ operator (\c{++i}) advances the iterator to the + next item in the object and returns an iterator to the new current + item. + + Calling this function on QJsonObject::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{i++}) advances the iterator to the + next item in the object and returns an iterator to the previously + current item. +*/ + +/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator--() + + The prefix -- operator (\c{--i}) makes the preceding item + current and returns an iterator pointing to the new current item. + + Calling this function on QJsonObject::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::const_iterator::operator--(int) + + \overload + + The postfix -- operator (\c{i--}) makes the preceding item + current and returns an iterator pointing to the previously + current item. +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::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.) + + This operation can be slow for large \a j values. + + \sa operator-() +*/ + +/*! \fn QJsonObject::const_iterator QJsonObject::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.) + + This operation can be slow for large \a j values. + + \sa operator+() +*/ + +/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + This operation can be slow for large \a j values. + + \sa operator-=(), operator+() +*/ + +/*! \fn QJsonObject::const_iterator &QJsonObject::const_iterator::operator-=(int j) + + Makes the iterator go back by \a j items. (If \a j is negative, + the iterator goes forward.) + + This operation can be slow for large \a j values. + + \sa operator+=(), operator-() +*/ + + +/*! + \internal + */ void QJsonObject::detach(uint reserve) { if (!d) { @@ -333,6 +916,9 @@ void QJsonObject::detach(uint reserve) o = static_cast(d->header->root()); } +/*! + \internal + */ void QJsonObject::compact() const { if (!d || !d->compactionCounter) @@ -343,6 +929,9 @@ void QJsonObject::compact() const const_cast(this)->o = static_cast(d->header->root()); } +/*! + \internal + */ QString QJsonObject::keyAt(int i) const { Q_ASSERT(o && i >= 0 && i < (int)o->length); @@ -351,6 +940,9 @@ QString QJsonObject::keyAt(int i) const return e->key(); } +/*! + \internal + */ QJsonValue QJsonObject::valueAt(int i) const { if (!o || i < 0 || i >= (int)o->length) @@ -360,6 +952,9 @@ QJsonValue QJsonObject::valueAt(int i) const return QJsonValue(d, o, e->value); } +/*! + \internal + */ void QJsonObject::setValueAt(int i, const QJsonValue &val) { Q_ASSERT(o && i >= 0 && i < (int)o->length); @@ -368,6 +963,27 @@ void QJsonObject::setValueAt(int i, const QJsonValue &val) insert(e->key(), val); } +/*! \typedef QJsonObject::Iterator + + Qt-style synonym for QJsonObject::iterator. +*/ + +/*! \typedef QJsonObject::ConstIterator + + Qt-style synonym for QJsonObject::const_iterator. +*/ + + +/*! \class QJsonObject::iterator + \ingroup json + \reentrant + \since 5.0 + + \brief The QJsonDocument::iterator class provides a way to iterate over q QJsonObject + + + */ + } // namespace QtJson -- cgit v1.2.3