- Qt 6.9
- Qt Core
- C++ Classes
- QJsonValue
- Qt 6.9.2 Reference Documentation

# QJsonValue Class

The QJsonValue class encapsulates a value in JSON. More...

Header: | `#include <QJsonValue>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`

- List of all members, including inherited members
- QJsonValue is part of JSON Support in Qt and Implicitly Shared Classes.

This class is equality-comparable.

This class is equality-comparable with QJsonValueConstRef and QJsonValueRef.

Note: All functions in this class are reentrant.

## Public Types

`(since 6.9)` | JsonFormat
enum | Type { Null, Bool, Double, String, Array, …, Undefined }

## Public Functions

| QJsonValue(QJsonValue::Type type = Null)
| QJsonValue(QLatin1StringView s)
| QJsonValue(bool b)
| QJsonValue(const QJsonArray &a)
| QJsonValue(const QJsonObject &o)
| QJsonValue(const QString &s)
| QJsonValue(const char *s)
| QJsonValue(double v)
`(since 6.3)` | QJsonValue(QJsonArray &&a)
`(since 6.3)` | QJsonValue(QJsonObject &&o)
| QJsonValue(int v)
| QJsonValue(qint64 v)
| QJsonValue(const QJsonValue &other)
| QJsonValue(QJsonValue &&other)
| ~QJsonValue()
bool | isArray() const
bool | isBool() const
bool | isDouble() const
bool | isNull() const
bool | isObject() const
bool | isString() const
bool | isUndefined() const
void | swap(QJsonValue &other)
QJsonArray | toArray(const QJsonArray &defaultValue) const
QJsonArray | toArray() const
bool | toBool(bool defaultValue = false) const
double | toDouble(double defaultValue = 0) const
int | toInt(int defaultValue = 0) const
`(since 6.0)` qint64 | toInteger(qint64 defaultValue = 0) const
`(since 6.9)` QByteArray | toJson(QJsonValue::JsonFormat format = JsonFormat::Indented) const
QJsonObject | toObject(const QJsonObject &defaultValue) const
QJsonObject | toObject() const
QString | toString() const
QString | toString(const QString &defaultValue) const
QVariant | toVariant() const
QJsonValue::Type | type() const
QJsonValue & | operator=(QJsonValue &&other)
QJsonValue & | operator=(const QJsonValue &other)
const QJsonValue | operator[](const QString &key) const
const QJsonValue | operator[](qsizetype i) const
const QJsonValue | operator[](QLatin1StringView key) const
const QJsonValue | operator[](QStringView key) const

## Static Public Members

`(since 6.9)` QJsonValue | fromJson(QByteArrayView json, QJsonParseError *error = nullptr)
QJsonValue | fromVariant(const QVariant &variant)

## Related Non-Members

bool | operator!=(const QJsonValue &lhs, const QJsonValue &rhs)
bool | operator==(const QJsonValue &lhs, const QJsonValue &rhs)

## Detailed Description

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:

- bool QJsonValue::Bool
- double QJsonValue::Double
- string QJsonValue::String
- array QJsonValue::Array
- object QJsonValue::Object
- null QJsonValue::Null

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(), and so on. Likewise, the value can be converted to the type stored in it using the toBool(), toString() and so on.

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.

### QJsonValueRef

QJsonValueRef is a helper class for QJsonArray and QJsonObject. When you get an object of type QJsonValueRef, you can use it as if it were a reference to a QJsonValue. If you assign to it, the assignment will apply to the element in the QJsonArray or QJsonObject from which you got the reference.

The following methods return QJsonValueRef:

- QJsonArray::operator[](qsizetype i)
- QJsonObject::operator[](const QString & key) const

See also JSON Support in Qt and Saving and Loading a Game.

## Member Type Documentation

### `[alias, since 6.9]` QJsonValue::JsonFormat

Same as QJsonDocument::JsonFormat.

This typedef was introduced in Qt 6.9.

### enum QJsonValue::Type

This enum describes the type of the JSON value.

Constant | Value | Description
--- | --- | ---
`QJsonValue::Null` | `0x0` | A Null value
`QJsonValue::Bool` | `0x1` | A boolean value. Use toBool() to convert to a bool.
`QJsonValue::Double` | `0x2` | A number value. Use toDouble() to convert to a double, or toInteger() to convert to a qint64.
`QJsonValue::String` | `0x3` | A string. Use toString() to convert to a QString.
`QJsonValue::Array` | `0x4` | An array. Use toArray() to convert to a QJsonArray.
`QJsonValue::Object` | `0x5` | An object. Use toObject() to convert to a QJsonObject.
`QJsonValue::Undefined` | `0x80` | 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 existent key in an object.

## Member Function Documentation

### QJsonValue::QJsonValue(QJsonValue::Type type = Null)

Creates a QJsonValue of type type.

The default is to create a Null value.

### QJsonValue::QJsonValue(QLatin1StringView s)

Creates a value of type String, with the Latin-1 string viewed by s.

### QJsonValue::QJsonValue(bool b)

Creates a value of type Bool, with value b.

### QJsonValue::QJsonValue(const QJsonArray &a)

Creates a value of type Array, with value a.

### QJsonValue::QJsonValue(const QJsonObject &o)

Creates a value of type Object, with value o.

### QJsonValue::QJsonValue(const QString &s)

Creates a value of type String, with value s.

### QJsonValue::QJsonValue(const char *s)

Creates a value of type String with value s, assuming UTF-8 encoding of the input.

You can disable this constructor by defining `QT_NO_CAST_FROM_ASCII` when you compile your applications.

### QJsonValue::QJsonValue(double v)

Creates a value of type Double, with value v.

### `[noexcept, since 6.3]` QJsonValue::QJsonValue(QJsonArray &&a)

This is an overloaded function.

This function was introduced in Qt 6.3.

### `[noexcept, since 6.3]` QJsonValue::QJsonValue(QJsonObject &&o)

This is an overloaded function.

This function was introduced in Qt 6.3.

### QJsonValue::QJsonValue(int v)

Creates a value of type Double, with value v.

This is an overloaded function.

### QJsonValue::QJsonValue(qint64 v)

Creates a value of type Double, with value v.

This is stored internally as a 64-bit integer, so retains its full precision, as long as it is retrieved with toInteger(). However, retrieving its value with toDouble() will lose precision unless the value lies between ±2^53.

This is an overloaded function.

See also toInteger() and toDouble().

### `[noexcept]` QJsonValue::QJsonValue(const QJsonValue &other)

Creates a copy of other.

### `[noexcept]` QJsonValue::QJsonValue(QJsonValue &&other)

Move-constructs a QJsonValue from other.

### `[noexcept]` QJsonValue::~QJsonValue()

Destroys the value.

### `[static, since 6.9]` QJsonValue QJsonValue::fromJson(QByteArrayView json, QJsonParseError *error = nullptr)

Parses json as a UTF-8 encoded JSON value, and creates a QJsonValue from it.

Returns a valid QJsonValue if the parsing succeeds. If it fails, the returned value will be undefined, and the optional error variable will contain further details about the error.

This function was introduced in Qt 6.9.

See also QJsonParseError, isUndefined(), and toJson().

### `[static]` QJsonValue QJsonValue::fromVariant(const QVariant &variant)

Converts variant to a QJsonValue and returns it.

The conversion will convert QVariant types as follows:

Source type | Destination type
--- | ---

- QMetaType::Nullptr

QJsonValue::Null

- QMetaType::Bool

QJsonValue::Bool

- QMetaType::Int
- QMetaType::UInt
- QMetaType::LongLong
- QMetaType::ULongLong
- QMetaType::Float
- QMetaType::Double

QJsonValue::Double

- QMetaType::QString

QJsonValue::String

- QMetaType::QStringList
- QMetaType::QVariantList

QJsonValue::Array

- QMetaType::QVariantMap
- QMetaType::QVariantHash

QJsonValue::Object

- QMetaType::QUrl

QJsonValue::String. The conversion will use QUrl::toString() with flag QUrl::FullyEncoded, so as to ensure maximum compatibility in parsing the URL

- QMetaType::QUuid

QJsonValue::String. Since Qt 5.11, the resulting string will not include braces

- QMetaType::QCborValue

Whichever type QCborValue::toJsonValue() returns.

- QMetaType::QCborArray

QJsonValue::Array. See QCborValue::toJsonValue() for conversion restrictions.

- QMetaType::QCborMap

QJsonValue::Map. See QCborValue::toJsonValue() for conversion restrictions and the "stringification" of map keys.

##### Loss of information and other types

QVariant can carry more information than is representable in JSON. If the QVariant is not one of the types above, the conversion is not guaranteed and is subject to change in future versions of Qt, as the UUID one did. Code should strive not to use any other types than those listed above.

If QVariant::isNull() returns true, a null QJsonValue is returned or inserted into the list or object, regardless of the type carried by QVariant. Note the behavior change in Qt 6.0 affecting QVariant::isNull() also affects this function.

A floating point value that is either an infinity or NaN will be converted to a null JSON value. Since Qt 6.0, QJsonValue can store the full precision of any 64-bit signed integer without loss, but in previous versions values outside the range of ±2^53 may lose precision. Unsigned 64-bit values greater than or equal to 2^63 will either lose precision or alias to negative values, so QMetaType::ULongLong should be avoided.

For other types not listed above, a conversion to string will be attempted, usually but not always by calling QVariant::toString(). If the conversion fails the value is replaced by a null JSON value. Note that QVariant::toString() is also lossy for the majority of types. For example, if the passed QVariant is representing raw byte array data, it is recommended to pre-encode it to Base64 (or another lossless encoding), otherwise a lossy conversion using QString::fromUtf8() will be used.

Please note that the conversions via QVariant::toString() are subject to change at any time. Both QVariant and QJsonValue may be extended in the future to support more types, which will result in a change in how this function performs conversions.

See also toVariant() and QCborValue::fromVariant().

### bool QJsonValue::isArray() const

Returns `true` if the value contains an array.

See also toArray().

### bool QJsonValue::isBool() const

Returns `true` if the value contains a boolean.

See also toBool().

### bool QJsonValue::isDouble() const

Returns `true` if the value contains a double.

See also toDouble().

### bool QJsonValue::isNull() const

Returns `true` if the value is null.

### bool QJsonValue::isObject() const

Returns `true` if the value contains an object.

See also toObject().

### bool QJsonValue::isString() const

Returns `true` if the value contains a string.

See also toString().

### bool QJsonValue::isUndefined() const

Returns `true` if the value is undefined. This can happen in certain error cases as e.g. accessing a non existing key in a QJsonObject.

### `[noexcept]` void QJsonValue::swap(QJsonValue &other)

Swaps this value with other. This operation is very fast and never fails.

### QJsonArray QJsonValue::toArray(const QJsonArray &defaultValue) const

Converts the value to an array and returns it.

If type() is not Array, the defaultValue will be returned.

### QJsonArray QJsonValue::toArray() const

Converts the value to an array and returns it.

If type() is not Array, a QJsonArray() will be returned.

This is an overloaded function.

### bool QJsonValue::toBool(bool defaultValue = false) const

Converts the value to a bool and returns it.

If type() is not bool, the defaultValue will be returned.

### double QJsonValue::toDouble(double defaultValue = 0) const

Converts the value to a double and returns it.

If type() is not Double, the defaultValue will be returned.

### int QJsonValue::toInt(int defaultValue = 0) const

Converts the value to an int and returns it.

If type() is not Double or the value is not a whole number, the defaultValue will be returned.

### `[since 6.0]` qint64 QJsonValue::toInteger(qint64 defaultValue = 0) const

Converts the value to an integer and returns it.

If type() is not Double or the value is not a whole number representable as qint64, the defaultValue will be returned.

This function was introduced in Qt 6.0.

### `[since 6.9]` QByteArray QJsonValue::toJson(QJsonValue::JsonFormat format = JsonFormat::Indented) const

Converts the QJsonValue to a UTF-8 encoded JSON value in the provided format.

This function was introduced in Qt 6.9.

See also fromJson() and JsonFormat.

### QJsonObject QJsonValue::toObject(const QJsonObject &defaultValue) const

Converts the value to an object and returns it.

If type() is not Object, the defaultValue will be returned.

### QJsonObject QJsonValue::toObject() const

Converts the value to an object and returns it.

If type() is not Object, the QJsonObject() will be returned.

This is an overloaded function.

### QString QJsonValue::toString() const

Converts the value to a QString and returns it.

If type() is not String, a null QString will be returned.

See also QString::isNull().

### QString QJsonValue::toString(const QString &defaultValue) const

Converts the value to a QString and returns it.

If type() is not String, the defaultValue will be returned.

### QVariant QJsonValue::toVariant() const

Converts the value to a QVariant().

The QJsonValue types will be converted as follows:

Constant | Description
--- | ---
`Null` | QMetaType::Nullptr
`Bool` | QMetaType::Bool
`Double` | QMetaType::Double or QMetaType::LongLong
`String` | QString
`Array` | QVariantList
`Object` | QVariantMap
`Undefined` | QVariant()

See also fromVariant().

### QJsonValue::Type QJsonValue::type() const

Returns the type of the value.

See also QJsonValue::Type.

### `[noexcept]` QJsonValue &QJsonValue::operator=(QJsonValue &&other)

Move-assigns other to this value.

### `[noexcept]` QJsonValue &QJsonValue::operator=(const QJsonValue &other)

Assigns the value stored in other to this object.

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

Returns a QJsonValue representing the value for the key key.

Equivalent to calling toObject().value(key).

The returned QJsonValue is QJsonValue::Undefined if the key does not exist, or if isObject() is false.

See also QJsonValue, QJsonValue::isUndefined(), and QJsonObject.

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

Returns a QJsonValue representing the value for index i.

Equivalent to calling toArray().at(i).

The returned QJsonValue is QJsonValue::Undefined, if i is out of bounds, or if isArray() is false.

See also QJsonValue, QJsonValue::isUndefined(), and QJsonArray.

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

This is an overloaded function.

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

This is an overloaded function.

## Related Non-Members

### `[noexcept]` bool operator!=(const QJsonValue &lhs, const QJsonValue &rhs)

Returns `true` if the lhs value is not equal to rhs value, `false` otherwise.

### `[noexcept]` bool operator==(const QJsonValue &lhs, const QJsonValue &rhs)

Returns `true` if the lhs value is equal to rhs value, `false` otherwise.