QVariant Class

The QVariant class acts like a union for the most common Nt data types. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A QVariant holds a single value of one type at a time: a number, a string, a date, a list or map of other variants, or any type registered with QMetaType. It is what makes properties, QObject::property() and QMetaProperty work with values of any type.

QVariant v = 42;
v.toInt();               // 42
v.toString();            // "42"
v = QString("hello");
v.typeId();              // QMetaType::QString

struct Point3D { int x, y, z; };
Q_DECLARE_METATYPE(Point3D)
QVariant p = QVariant::fromValue(Point3D{1, 2, 3});
Point3D q = p.value<Point3D>();

A default-constructed QVariant is invalid. A QVariant is null if it holds no value, a null pointer, or a value of a built-in type that is itself null, such as an empty QString, an invalid QDate or a null QUuid.

Conversions between types follow the table in QMetaType::convert(). The toXxx() functions convert and return a default value if the conversion is not possible; convert() changes the variant in place. A value that can be converted in either direction between two types compares equal with operator==().

A QVariant can be streamed to a QDataStream in Qt's wire format and printed with QDebug.

A value can also be built in place and reached without a copy:

QVariant v(std::in_place_type<QString>, 3, QChar('x'));   // "xxx"
if (QString *s = get_if<QString>(&v))
    s->append("!");
v.emplace<QStringList>({"a", "b"});
QVariant w = QVariant::fromStdVariant(std::variant<int, QString>(7));

See also QMetaType, QSequentialIterable and QAssociativeIterable.

Differences from Qt

Member Type Documentation

enum QVariant::Type

The type a variant holds, using the ids of QMetaType::Type.

Member Function Documentation

QVariant::QVariant()

Constructs an invalid variant.

See also isValid().

[explicit] QVariant::QVariant(QMetaType type, const void *copy = nullptr)

Constructs a variant of the type type. If copy is not nullptr, the variant holds a copy of the value at that address; otherwise it holds a default-constructed value and is null. The variant is invalid if type is invalid or its values cannot be constructed that way. For QMetaType::QVariant the result is a copy of the QVariant at copy, or an invalid variant.

See also fromMetaType().

QVariant::QVariant(const QVariant &other)

Constructs a copy of other.

QVariant::QVariant(QVariant &&other)

Constructs a variant by moving other into it; other is left invalid.

QVariant::QVariant(int i)

Constructs a variant that holds the int i.

QVariant::QVariant(uint ui)

Constructs a variant that holds the unsigned integer ui.

QVariant::QVariant(qlonglong ll)

Constructs a variant that holds the qlonglong ll.

QVariant::QVariant(qulonglong ull)

Constructs a variant that holds the qulonglong ull.

QVariant::QVariant(long l)

Constructs a variant that holds l as a qlonglong.

QVariant::QVariant(unsigned long ul)

Constructs a variant that holds ul as a qulonglong.

QVariant::QVariant(bool b)

Constructs a variant that holds the bool b.

QVariant::QVariant(double d)

Constructs a variant that holds the double d.

QVariant::QVariant(float f)

Constructs a variant that holds the float f.

QVariant::QVariant(const char *str)

Constructs a variant that holds a QString made from the UTF-8 text str. A nullptr gives a null QString.

QVariant::QVariant(QLatin1StringView str)

Constructs a variant that holds a QString made from str.

QVariant::QVariant(const QByteArray &bytearray)

Constructs a variant that holds a copy of bytearray.

QVariant::QVariant(const QString &string)

Constructs a variant that holds a copy of string.

QVariant::QVariant(QChar qchar)

Constructs a variant that holds the character qchar.

QVariant::QVariant(const QStringList &stringlist)

Constructs a variant that holds a copy of stringlist.

QVariant::QVariant(std::nullptr_t)

Constructs a variant that holds a null pointer of type std::nullptr_t.

QVariant::QVariant(QDate date)

Constructs a variant that holds date.

QVariant::QVariant(QTime time)

Constructs a variant that holds time.

QVariant::QVariant(const QDateTime &datetime)

Constructs a variant that holds datetime.

QVariant::QVariant(const QVariantList &list)

Constructs a variant that holds a copy of list.

QVariant::QVariant(const QVariantMap &map)

Constructs a variant that holds a copy of map.

QVariant::QVariant(const QVariantHash &hash)

Constructs a variant that holds a copy of hash.

QVariant::QVariant(const QSize &size)

Constructs a variant that holds size.

QVariant::QVariant(const QSizeF &size)

Constructs a variant that holds size.

QVariant::QVariant(const QPoint &pt)

Constructs a variant that holds pt.

QVariant::QVariant(const QPointF &pt)

Constructs a variant that holds pt.

QVariant::QVariant(const QLine &line)

Constructs a variant that holds line.

QVariant::QVariant(const QLineF &line)

Constructs a variant that holds line.

QVariant::QVariant(const QRect &rect)

Constructs a variant that holds rect.

QVariant::QVariant(const QRectF &rect)

Constructs a variant that holds rect.

QVariant::QVariant(const QUrl &url)

Constructs a variant that holds url.

QVariant::QVariant(const QBitArray &bitarray)

Constructs a variant that holds bitarray.

QVariant::QVariant(const QLocale &locale)

Constructs a variant that holds locale.

This function was introduced in 6.0.

QVariant::QVariant(const QRegularExpression &re)

Constructs a variant that holds re.

This function was introduced in 6.0.

QVariant::QVariant(const QEasingCurve &easing)

Constructs a variant that holds easing.

This function was introduced in 6.0.

QVariant::QVariant(const QUuid &uuid)

Constructs a variant that holds uuid.

This function was introduced in 6.0.

QVariant::QVariant(const QModelIndex &modelIndex)

Constructs a variant that holds modelIndex.

This function was introduced in 6.0.

QVariant::QVariant(const QPersistentModelIndex &modelIndex)

Constructs a variant that holds modelIndex.

This function was introduced in 6.0.

QVariant::QVariant(const QJsonValue &jsonValue)

Constructs a variant that holds jsonValue.

This function was introduced in 6.0.

QVariant::QVariant(const QJsonObject &jsonObject)

Constructs a variant that holds jsonObject.

This function was introduced in 6.0.

QVariant::QVariant(const QJsonArray &jsonArray)

Constructs a variant that holds jsonArray.

This function was introduced in 6.0.

QVariant::QVariant(const QJsonDocument &jsonDocument)

Constructs a variant that holds jsonDocument.

This function was introduced in 6.0.

template <typename T, typename... Args, if_in_place<T, Args...> = true>[explicit] QVariant::QVariant(std::in_place_type_t<T>, Args &&...args)

Constructs a variant that holds a T, which is constructed in place from args. The first argument is std::in_place_type<T> and only selects the type.

QVariant v(std::in_place_type<QString>, 3, QChar('x'));   // holds "xxx"

This function was introduced in 6.6.

See also emplace() and fromValue().

template <typename T, typename U, typename... Args, if_in_place<T, std::initializer_list<U> &, Args...> = true>[explicit] QVariant::QVariant(std::in_place_type_t<T>, std::initializer_list<U> il, Args &&...args)

This is an overloaded function.

Constructs a variant that holds a T, which is constructed in place from the initializer list il and args.

This function was introduced in 6.6.

QVariant::~QVariant()

Destroys the variant and the value it holds, unless another variant shares it.

bool QVariant::canConvert(QMetaType targetType) const

Returns true if the variant can be converted to targetType; otherwise returns false. A true result does not promise that every value converts: a QString that does not hold a number is convertible to int, but not to a number.

See also convert() and QMetaType::convert().

template <typename T>bool QVariant::canConvert() const

Returns true if the variant can be converted to T; otherwise returns false.

See also convert() and value().

bool QVariant::canConvert(int targetTypeId) const

This is an overloaded function.

Returns true if the variant can be converted to the type with the id targetTypeId.

void QVariant::clear()

Releases the value and makes the variant invalid.

See also isValid().

[static] QPartialOrdering QVariant::compare(const QVariant &lhs, const QVariant &rhs)

Compares lhs and rhs and returns the result as an ordering.

Two variants of the same type are compared with the operator< and operator== of that type; the result is QPartialOrdering::Unordered if the type has no operator<. Two numbers of different types are compared by value. Any other pair of types is unordered: unlike operator==(), this function does not convert one value to the type of the other. Two invalid variants are unordered too, and so are two numbers if one of them is not a number (NaN).

QVariant::compare(QVariant(1), QVariant(2.5));        // QPartialOrdering::Less
QVariant::compare(QVariant("b"), QVariant("a"));      // QPartialOrdering::Greater
QVariant::compare(QVariant(1), QVariant("1"));        // QPartialOrdering::Unordered

This function was introduced in 6.0.

See also QMetaType::compare().

const void * QVariant::constData() const

Returns a pointer to the stored value, or nullptr if the variant is invalid.

See also data().

bool QVariant::convert(QMetaType targetType)

Converts the variant to targetType and returns true on success. If the conversion is not possible, the variant becomes a null value of targetType and the function returns false. Converting an invalid variant does the same.

See also canConvert() and clear().

bool QVariant::convert(int targetTypeId)

This is an overloaded function.

Converts the variant to the type with the id targetTypeId and returns true on success. On failure the variant becomes invalid.

void * QVariant::data()

Returns a pointer to the stored value, or nullptr if the variant is invalid. If the value is shared with other variants, it is copied first.

const void * QVariant::data() const

Returns a pointer to the stored value, or nullptr if the variant is invalid.

template <typename T, typename... Args, if_in_place<T, Args...> = true>T & QVariant::emplace(Args &&...args)

Replaces what the variant holds with a T that is constructed in place from args, and returns a reference to the new value.

This function was introduced in 6.6.

See also setValue().

template <typename T, typename U, typename... Args, if_in_place<T, std::initializer_list<U> &, Args...> = true>T & QVariant::emplace(std::initializer_list<U> il, Args &&...args)

This is an overloaded function.

Replaces what the variant holds with a T that is constructed in place from the initializer list il and args, and returns a reference to the new value.

This function was introduced in 6.6.

[static] QVariant QVariant::fromMetaType(QMetaType type, const void *copy = nullptr)

Returns a variant of the type described by type that holds a copy of the value at copy, or a default-constructed value if copy is nullptr.

See also fromValue().

template <typename... Types>[static] QVariant QVariant::fromStdVariant(const std::variant<Types...> &value)

Returns a variant that holds the active alternative of value. The result is invalid if the alternative is std::monostate or if value is valueless by exception.

This function was introduced in 6.6.

See also fromValue().

template <typename... Types>[static] QVariant QVariant::fromStdVariant(std::variant<Types...> &&value)

This is an overloaded function.

Returns a variant that holds the active alternative of value, which is moved from.

This function was introduced in 6.6.

template <typename T>[static] QVariant QVariant::fromValue(T &&value)

Returns a variant that holds a copy of value. A QVariant argument is returned unchanged.

See also setValue() and value().

bool QVariant::isNull() const

Returns true if the variant is invalid, holds a null pointer, or holds a value that is itself null: an empty-and-null QString, QByteArray or QBitArray, a null QChar, an invalid QDate, QTime or QDateTime, a null QUuid, QRect, QSize, QPoint or QLine, or a variant created with QVariant(QMetaType) and no value. Other types are never null.

See also isValid() and clear().

bool QVariant::isValid() const

Returns true if the variant holds a value, even a null one; otherwise returns false.

See also isNull().

void QVariant::load(QDataStream &ds)

Reads the variant from the stream ds in the format of QVariant::save(). If the type has no stream operators, the stream's status is set to QDataStream::ReadCorruptData and the variant becomes invalid. Streams older than Qt_4_2 have no flag for a null value, and those older than Qt_5_0 write the first user type as 127.

See also save().

QMetaType QVariant::metaType() const

Returns the QMetaType of the stored value, or an invalid QMetaType if the variant is invalid.

See also typeId().

[static] Type QVariant::nameToType(const char *name)

Returns the type that has the name name, or Invalid if there is none. A type that is registered at run time gives UserType.

See also typeToName().

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

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

QVariant & QVariant::operator=(QVariant &&other)

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

void QVariant::save(QDataStream &ds) const

Writes the variant to the stream ds: the type id (or QMetaType::User followed by the type name for a registered type), a flag that tells if the value is null, and the value itself. If the type has no stream operators, the stream's status is set to QDataStream::WriteFailed. A stream older than Qt_4_2 has no null flag, and one older than Qt_5_0 writes 127 in place of QMetaType::User, as QSettings does.

See also load().

template <typename T>void QVariant::setValue(T &&value)

Stores a copy of value in the variant, replacing what it held.

See also fromValue() and value().

void QVariant::swap(QVariant &other)

Swaps this variant with other.

QBitArray QVariant::toBitArray() const

Returns the variant as a QBitArray if it holds one; otherwise returns a null QBitArray.

bool QVariant::toBool() const

Returns the variant as a bool, converting it if needed. Zero, an empty string, "0" and "false" (in any case) are false; other numbers and strings are true. A variant that cannot be converted gives false.

QByteArray QVariant::toByteArray() const

Returns the variant as a QByteArray, converting it if needed. A QString converts to UTF-8. A variant that cannot be converted gives a null QByteArray.

QChar QVariant::toChar() const

Returns the variant as a QChar if it holds a character, a number that is a valid UTF-16 code unit, or a string of one character; otherwise returns a null QChar.

QDate QVariant::toDate() const

Returns the variant as a QDate, converting it if needed: a QDateTime gives its date and a QString is read as ISO 8601. A variant that cannot be converted gives an invalid QDate.

QDateTime QVariant::toDateTime() const

Returns the variant as a QDateTime, converting it if needed; see toDate(). A QDate gives the start of the day in local time.

double QVariant::toDouble(bool *ok = nullptr) const

Returns the variant as a double, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded.

QEasingCurve QVariant::toEasingCurve() const

Returns the variant as a QEasingCurve if it holds one; otherwise returns a linear curve.

This function was introduced in 6.0.

float QVariant::toFloat(bool *ok = nullptr) const

Returns the variant as a float, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded.

QVariantHash QVariant::toHash() const

Returns the variant as a QVariantHash, converting it if needed; see toMap().

int QVariant::toInt(bool *ok = nullptr) const

Returns the variant as an int, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded. A variant that cannot be converted gives 0.

See also canConvert() and convert().

QJsonArray QVariant::toJsonArray() const

Returns the variant as a QJsonArray, converting it from a QVariantList, a QStringList, or a QJsonValue or QJsonDocument that holds an array. Otherwise returns an empty QJsonArray.

This function was introduced in 6.0.

See also toJsonValue() and toJsonObject().

QJsonDocument QVariant::toJsonDocument() const

Returns the variant as a QJsonDocument, converting it from a list, a map, or a QJsonValue, QJsonObject or QJsonArray. Otherwise returns a null QJsonDocument.

This function was introduced in 6.0.

See also toJsonObject() and toJsonArray().

QJsonObject QVariant::toJsonObject() const

Returns the variant as a QJsonObject, converting it from a QVariantMap, a QVariantHash, or a QJsonValue or QJsonDocument that holds an object. Otherwise returns an empty QJsonObject.

This function was introduced in 6.0.

See also toJsonValue() and toJsonArray().

QJsonValue QVariant::toJsonValue() const

Returns the variant as a QJsonValue. A number, bool, QString, list, map, nullptr and the other JSON classes are converted; anything else gives a null QJsonValue.

This function was introduced in 6.0.

See also QJsonValue::fromVariant(), toJsonObject() and toJsonArray().

QLine QVariant::toLine() const

Returns the variant as a QLine, converting it from a QLineF if needed. Otherwise returns a null QLine.

QLineF QVariant::toLineF() const

Returns the variant as a QLineF, converting it from a QLine if needed. Otherwise returns a null QLineF.

QVariantList QVariant::toList() const

Returns the variant as a QVariantList, converting it if needed. A QStringList, a QByteArrayList and any registered sequential container whose elements are registered types convert element by element. A variant that cannot be converted gives an empty list.

QLocale QVariant::toLocale() const

Returns the variant as a QLocale if it holds one; otherwise returns the default locale.

This function was introduced in 6.0.

qlonglong QVariant::toLongLong(bool *ok = nullptr) const

Returns the variant as a qlonglong, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded.

QVariantMap QVariant::toMap() const

Returns the variant as a QVariantMap, converting it if needed. A QVariantHash and any registered associative container whose keys convert to QString convert entry by entry. A variant that cannot be converted gives an empty map.

QModelIndex QVariant::toModelIndex() const

Returns the variant as a QModelIndex, converting it from a QPersistentModelIndex if needed. Otherwise returns an invalid QModelIndex.

This function was introduced in 6.0.

See also toPersistentModelIndex().

QPersistentModelIndex QVariant::toPersistentModelIndex() const

Returns the variant as a QPersistentModelIndex, converting it from a QModelIndex if needed. Otherwise returns an invalid QPersistentModelIndex.

This function was introduced in 6.0.

See also toModelIndex().

QPoint QVariant::toPoint() const

Returns the variant as a QPoint, converting it from a QPointF if needed. Otherwise returns a null QPoint.

QPointF QVariant::toPointF() const

Returns the variant as a QPointF, converting it from a QPoint if needed. Otherwise returns a null QPointF.

qreal QVariant::toReal(bool *ok = nullptr) const

Returns the variant as a qreal, which is a double. If ok is not nullptr, it is set to true if the conversion succeeded.

See also toDouble().

QRect QVariant::toRect() const

Returns the variant as a QRect, converting it from a QRectF if needed. Otherwise returns a null QRect.

QRectF QVariant::toRectF() const

Returns the variant as a QRectF, converting it from a QRect if needed. Otherwise returns a null QRectF.

QRegularExpression QVariant::toRegularExpression() const

Returns the variant as a QRegularExpression if it holds one; otherwise returns an empty QRegularExpression.

This function was introduced in 6.0.

QSize QVariant::toSize() const

Returns the variant as a QSize, converting it from a QSizeF if needed. Otherwise returns an invalid QSize.

QSizeF QVariant::toSizeF() const

Returns the variant as a QSizeF, converting it from a QSize if needed. Otherwise returns an invalid QSizeF.

QString QVariant::toString() const

Returns the variant as a QString, converting it if needed: numbers and bool give their text, dates and times give ISO 8601 text, a QByteArray is read as UTF-8, and an enumeration declared with Q_ENUM() gives its key. A variant that cannot be converted gives a null QString.

See also canConvert() and QMetaType::convert().

QStringList QVariant::toStringList() const

Returns the variant as a QStringList, converting it if needed. A QString gives a list of one string, and a list of variants gives the text of each element. A variant that cannot be converted gives an empty list.

QTime QVariant::toTime() const

Returns the variant as a QTime, converting it if needed; see toDate().

uint QVariant::toUInt(bool *ok = nullptr) const

Returns the variant as an unsigned integer, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded.

qulonglong QVariant::toULongLong(bool *ok = nullptr) const

Returns the variant as a qulonglong, converting it if needed. If ok is not nullptr, it is set to true if the conversion succeeded.

QUrl QVariant::toUrl() const

Returns the variant as a QUrl, converting it from a QString if needed. Otherwise returns an empty QUrl.

QUuid QVariant::toUuid() const

Returns the variant as a QUuid, converting it from a QString if needed. Otherwise returns a null QUuid.

This function was introduced in 6.0.

Type QVariant::type() const

Returns the type of the stored value as a QVariant::Type. For a type that is not a member of the enumeration it returns the QMetaType id, or UserType for a type registered at run time. Prefer typeId().

See also typeId() and metaType().

int QVariant::typeId() const

Returns the QMetaType id of the stored value, or QMetaType::UnknownType (0) if the variant is invalid.

See also metaType() and typeName().

const char * QVariant::typeName() const

Returns the name of the type of the stored value, or nullptr if the variant is invalid.

See also typeId() and typeToName().

[static] const char * QVariant::typeToName(int typeId)

Returns the name of the type with the id typeId, or nullptr if there is none.

See also nameToType().

int QVariant::userType() const

Returns the QMetaType id of the stored value; the same as typeId().

template <typename T>T QVariant::value() const

Returns the stored value converted to T, or a default-constructed T if the variant cannot be converted. If T is a pointer to a QObject-derived class and the variant holds a pointer to a QObject, the pointer is cast with dynamic_cast.

See also setValue(), fromValue(), canConvert() and convert().