QJsonDocument Class

The QJsonDocument class provides a way to read and write JSON documents. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A QJsonDocument holds a complete JSON document, which is either an array or an object. It can be read from UTF-8 text with fromJson() and written back with toJson().

QJsonParseError err;
QJsonDocument doc = QJsonDocument::fromJson("{\"a\": [1, 2, 3]}", &err);
if (doc.isObject())
    qDebug() << doc["a"][1].toInt();   // 2
QByteArray text = doc.toJson(QJsonDocument::Compact);

The parser follows RFC 8259: the text must be valid UTF-8, strings may use backslash-u escapes with four hex digits, including surrogate pairs, and there must be no trailing commas, comments or unquoted keys. A leading UTF-8 byte order mark is skipped. Documents nest at most 1024 levels deep. Integers that fit in 2^53 are kept exact, other numbers become doubles, and a number that does not fit in a double is an error.

A document written with Indented uses four spaces per level, puts each value on a line of its own and ends with a line feed; Compact writes no white space at all. Object keys appear in sorted order.

See also QJsonValue, QJsonObject, QJsonArray and QJsonParseError.

Differences from Qt

Member Type Documentation

enum QJsonDocument::JsonFormat

The formats toJson() can write.

{
    "Array": [
        true,
        999
    ],
    "Key": "Value"
}

{"Array":[true,999],"Key":"Value"}

Member Function Documentation

QJsonDocument::QJsonDocument()

Creates a null document.

See also isNull().

[explicit] QJsonDocument::QJsonDocument(const QJsonObject &object)

Creates a document that holds object.

[explicit] QJsonDocument::QJsonDocument(const QJsonArray &array)

Creates a document that holds array.

QJsonDocument::QJsonDocument(const QJsonDocument &other)

Creates a copy of other.

QJsonDocument::QJsonDocument(QJsonDocument &&other)

Moves other into the new document, which leaves other null.

QJsonDocument::~QJsonDocument()

Destroys the document.

QJsonArray QJsonDocument::array() const

Returns the array the document holds, or an empty array if the document does not hold one.

See also isArray() and setArray().

[static] QJsonDocument QJsonDocument::fromJson(const QByteArray &json, QJsonParseError *error = nullptr)

Parses json as UTF-8 encoded JSON and returns the document. If the text is not a valid document the result is null, and if error is not null it receives the reason and the offset at which it was found.

See also toJson() and QJsonParseError.

[static] QJsonDocument QJsonDocument::fromVariant(const QVariant &variant)

Converts variant to a document. A QVariantMap or QVariantHash gives a document that holds an object, and a QVariantList or QStringList one that holds an array; the contents are converted with QJsonValue::fromVariant(). Any other variant gives a null document.

See also toVariant(), QJsonObject::fromVariantMap() and QJsonArray::fromVariantList().

bool QJsonDocument::isArray() const

Returns true if the document holds an array.

See also array() and isObject().

bool QJsonDocument::isEmpty() const

Returns true if the document has no content. A document made from an empty array or object is not empty; only a null document is.

See also isNull().

bool QJsonDocument::isNull() const

Returns true if the document is null: it was default constructed, or it came from text that could not be parsed.

See also isEmpty().

bool QJsonDocument::isObject() const

Returns true if the document holds an object.

See also object() and isArray().

QJsonObject QJsonDocument::object() const

Returns the object the document holds, or an empty object if the document does not hold one.

See also isObject() and setObject().

QJsonDocument & QJsonDocument::operator=(const QJsonDocument &other)

Assigns other to this document and returns a reference to it.

QJsonDocument & QJsonDocument::operator=(QJsonDocument &&other)

Moves other into this document and returns a reference to it.

QJsonValue QJsonDocument::operator[](const QString &key) const

Returns the value that key maps to if the document holds an object, and an undefined value otherwise.

QJsonValue QJsonDocument::operator[](QStringView key) const

This is an overloaded function.

QJsonValue QJsonDocument::operator[](QLatin1StringView key) const

This is an overloaded function.

template <typename K, typename = std::enable_if_t<QtPrivate::IsJsonCString<K>>>QJsonValue QJsonDocument::operator[](K &&key) const

This is an overloaded function.

Looks key up when it is a C string, such as a string literal.

QJsonValue QJsonDocument::operator[](qsizetype i) const

This is an overloaded function.

Returns the element at index i if the document holds an array, and an undefined value otherwise.

void QJsonDocument::setArray(const QJsonArray &array)

Makes the document hold array.

See also array() and setObject().

void QJsonDocument::setObject(const QJsonObject &object)

Makes the document hold object.

See also object() and setArray().

void QJsonDocument::swap(QJsonDocument &other)

Swaps this document with other.

QByteArray QJsonDocument::toJson(JsonFormat format = Indented) const

Converts the document to UTF-8 JSON text in the given format. A null document gives an empty byte array.

See also fromJson() and JsonFormat.

QVariant QJsonDocument::toVariant() const

Converts the document to a QVariantMap if it holds an object, or to a QVariantList if it holds an array. A null document gives an invalid QVariant.

See also fromVariant().