From 805f64600b9f8ce8e969e8bf8ed45d66a27599fa Mon Sep 17 00:00:00 2001 From: Lars Knoll Date: Mon, 16 Jan 2012 12:58:42 +0100 Subject: Documentation for QJsonValue Change-Id: Ifc4fce1fe5ffb850962b03a7143a4c7b474aa086 Sanity-Review: Qt Sanity Bot Reviewed-by: Denis Dzyubenko --- src/qjsonvalue.cpp | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) diff --git a/src/qjsonvalue.cpp b/src/qjsonvalue.cpp index 0756e35..803f4fa 100644 --- a/src/qjsonvalue.cpp +++ b/src/qjsonvalue.cpp @@ -54,11 +54,51 @@ namespace QtJson { static const Private::Base emptyArray = { { qToLittleEndian(sizeof(Private::Base)) }, { 0 }, { 0 } }; static const Private::Base emptyObject = { { qToLittleEndian(sizeof(Private::Base)) }, { 0 }, { 0 } }; +/*! + \class QJsonValue + \ingroup json + \reentrant + \since 5.0 + + \brief The QJsonValue class encapsulates a value in JSON. + + A value in JSON can be one of 6 basic types: + + JSON is a format to store structured data. It has 6 basic data types: + + \list + \o bool QJsonValue::Bool + \o double QJsonValue::Number + \o string QJsonValue::String + \o array QJsonValue::Array + \o object QJsonValue::Object + \o null QJsonValue::Null + \endlist + + A value can represent any of the above data types. In addition, QJsonValue has one special + flag to represent undefined values. This can be queried with isUndefined(). + + The type of the value can be queried with type() or accessors like isBool(), isString(), etc. + The value can be converted to the type stored in it using the toBool(), toString(), etc. methods. + + Values are strictly typed internally and contrary to QVariant will not attempt to do any implicit type + conversions. This implies that converting to a type that is not stored in the value will return a default + constructed return value. +*/ + +/*! + Creates a QJsonValue of type \a type. + + The default is to create a Null value. + */ QJsonValue::QJsonValue(Type type) : t(type), d(0), dbl(0.) { } +/*! + \internal + */ QJsonValue::QJsonValue(Private::Data *data, Private::Base *base, const Private::Value &v) : d(0) { @@ -90,24 +130,37 @@ QJsonValue::QJsonValue(Private::Data *data, Private::Base *base, const Private:: d->ref.ref(); } +/*! + Creates a value of type Bool, with value \a b. + */ QJsonValue::QJsonValue(bool b) : t(Bool), d(0) { this->b = b; } +/*! + Creates a value of type Number, with value \a n. + */ QJsonValue::QJsonValue(double n) : t(Number), d(0) { this->dbl = n; } +/*! + \overload + Creates a value of type Number, with value \a n. + */ QJsonValue::QJsonValue(int n) : t(Number), d(0) { this->dbl = n; } +/*! + Creates a value of type String, with value \a s. + */ QJsonValue::QJsonValue(const QString &s) : t(String), d(0) { @@ -115,6 +168,9 @@ QJsonValue::QJsonValue(const QString &s) stringData->ref.ref(); } +/*! + Creates a value of type String, with value \a s. + */ QJsonValue::QJsonValue(const QLatin1String &s) : t(String), d(0) { @@ -124,6 +180,9 @@ QJsonValue::QJsonValue(const QLatin1String &s) stringData->ref.ref(); } +/*! + Creates a value of type Array, with value \a a. + */ QJsonValue::QJsonValue(const QJsonArray &a) : t(Array), d(a.d) { @@ -133,6 +192,9 @@ QJsonValue::QJsonValue(const QJsonArray &a) d->ref.ref(); } +/*! + Creates a value of type Object, with value \a o. + */ QJsonValue::QJsonValue(const QJsonObject &o) : t(Object), d(o.d) { @@ -143,6 +205,9 @@ QJsonValue::QJsonValue(const QJsonObject &o) } +/*! + Destroys the value. + */ QJsonValue::~QJsonValue() { if (t == String && stringData && !stringData->ref.deref()) @@ -152,6 +217,9 @@ QJsonValue::~QJsonValue() delete d; } +/*! + Creates a copy of \a other. + */ QJsonValue::QJsonValue(const QJsonValue &other) { t = other.t; @@ -164,6 +232,9 @@ QJsonValue::QJsonValue(const QJsonValue &other) stringData->ref.ref(); } +/*! + Assigns the value stored in \a other to this object. + */ QJsonValue &QJsonValue::operator =(const QJsonValue &other) { if (t == String && stringData && !stringData->ref.deref()) @@ -188,6 +259,29 @@ QJsonValue &QJsonValue::operator =(const QJsonValue &other) return *this; } +/*! + Converts \a variant to a QJsonValue and returns it. + + The conversion will convert QVariant types as follows: + + \list + \o QVariant::Bool to Bool + \o QVariant::Int + \o QVariant::Double + \o QVariant::LongLong + \o QVariant::ULongLong + \o QVariant::UInt to Number + \o QVariant::String to String + \o QVariant::StringList + \o QVariant::VariantList to Array + \o QVariant::VariantMap to Object + \endlist + + For all other QVariant types a conversion to a QString will be attempted. If the returned string + is empty, a Null QJsonValue will be stored, otherwise a String value using the returned QString. + + \sa toVariant() + */ QJsonValue QJsonValue::fromVariant(const QVariant &variant) { switch (variant.type()) { @@ -217,6 +311,21 @@ QJsonValue QJsonValue::fromVariant(const QVariant &variant) return QJsonValue(string); } +/*! + Converts the value to a QVariant. + + The QJsonValue types will be converted as follows: + + \value Null QVariant() + \value Bool QVariant::Bool + \value Number QVariant::Double + \value String QVariant::String + \value Array QVariantList + \value Object QVariantMap + \value Undefined QVariant() + + \sa fromVariant() + */ QVariant QJsonValue::toVariant() const { switch (t) { @@ -237,12 +346,37 @@ QVariant QJsonValue::toVariant() const return QVariant(); } +/*! + \enum QJsonValue::Type + This enum describes the type of the JSON value. + + \value Null A Null value + \value Bool A boolean value. Use toBool() to convert to a bool. + \value Number A number. Use toNumber() to convert to a double. + \value String A string. Use toString() to convert to a QString. + \value Array An array. Use toArray() to convert to a QJsonArray. + \value Object An object. Use toObject() to convert to a QJsonObject. + \value Undefined The value is undefined. This is usually returned as an + error condition, when trying to read an out of bounds value + in an array or a non existant key in an object. +*/ + +/*! + Returns the type of the value. + + \sa QJsonValue::Type + */ QJsonValue::Type QJsonValue::type() const { return t; } +/*! + Converts the value to a bool and returns it. + + If type() is not bool, false will be returned. + */ bool QJsonValue::toBool() const { if (t != Bool) @@ -250,6 +384,11 @@ bool QJsonValue::toBool() const return b; } +/*! + Converts the value to a double and returns it. + + If type() is not Number, 0. will be returned. + */ double QJsonValue::toNumber() const { if (t != Number) @@ -257,6 +396,11 @@ double QJsonValue::toNumber() const return dbl; } +/*! + Converts the value to an int and returns it. + + If type() is not Number, 0. will be returned. + */ int QJsonValue::toInt() const { if (t != Number) @@ -264,6 +408,11 @@ int QJsonValue::toInt() const return (int)dbl; } +/*! + Converts the value to a QString and returns it. + + If type() is not String, a QString() will be returned. + */ QString QJsonValue::toString() const { if (t != String) @@ -272,6 +421,11 @@ QString QJsonValue::toString() const return QString(*(const QConstStringData<1> *)stringData); } +/*! + Converts the value to an array and returns it. + + If type() is not Array, a QJsonArray() will be returned. + */ QJsonArray QJsonValue::toArray() const { if (!d || t != Array) @@ -280,6 +434,11 @@ QJsonArray QJsonValue::toArray() const return QJsonArray(d, array); } +/*! + Converts the value to an object and returns it. + + If type() is not Object, a QJsonObject() will be returned. + */ QJsonObject QJsonValue::toObject() const { if (!d || t != Object) @@ -288,6 +447,9 @@ QJsonObject QJsonValue::toObject() const return QJsonObject(d, object); } +/*! + Returns true if the value is equal to \a other. + */ bool QJsonValue::operator==(const QJsonValue &other) const { if (t != other.t) @@ -311,11 +473,17 @@ bool QJsonValue::operator==(const QJsonValue &other) const return true; } +/*! + Returns true if the value is not equal to \a other. + */ bool QJsonValue::operator!=(const QJsonValue &other) const { return !(*this == other); } +/*! + \internal + */ void QJsonValue::detach() { if (!d) @@ -329,6 +497,9 @@ void QJsonValue::detach() object = static_cast(d->header->root()); } +/*! + \internal + */ int QJsonValue::requiredStorage(bool *compressed) const { *compressed = false; @@ -355,6 +526,9 @@ int QJsonValue::requiredStorage(bool *compressed) const return 0; } +/*! + \internal + */ uint QJsonValue::valueToStore(uint offset) const { switch (t) { @@ -376,6 +550,9 @@ uint QJsonValue::valueToStore(uint offset) const return 0; } +/*! + \internal + */ void QJsonValue::copyData(char *dest, bool compressed) const { switch (t) { @@ -402,6 +579,28 @@ void QJsonValue::copyData(char *dest, bool compressed) const } } +/*! + \class QJsonValueRef + \reentrant + \brief The QJsonValueRef class is a helper class for QJsonValue. + + \internal + + \ingroup json + + When you get an object of type QJsonValueRef, if you can assign to it, + the assignment will apply to the character in the string from + which you got the reference. That is its whole purpose in life. + + You can use it exactly in the same way as a reference to a QJsonValue. + + The QJsonValueRef becomes invalid once modifications are made to the + string: if you want to keep the character, copy it into a QJsonValue. + + Most of the QJsonValue member functions also exist in QJsonValueRef. + However, they are not explicitly documented here. +*/ + QJsonValueRef &QJsonValueRef::operator =(const QJsonValue &val) { -- cgit v1.2.3