The QCborValue class encapsulates a value in CBOR. More...

#include <qcborvalue.h>

Public Types
enum	EncodingOption { SortKeysInMaps = 0x01 , UseFloat = 0x02 , UseFloat16 = UseFloat \| 0x04 , UseIntegers = 0x08 , NoTransformation = 0 }

enum	DiagnosticNotationOption { Compact = 0x00 , LineWrapped = 0x01 , ExtendedFormat = 0x02 }

enum	Type : int { Integer = 0x00 , ByteArray = 0x40 , String = 0x60 , Array = 0x80 , Map = 0xa0 , Tag = 0xc0 , SimpleType = 0x100 , False = SimpleType + int(QCborSimpleType::False) , True = SimpleType + int(QCborSimpleType::True) , Null = SimpleType + int(QCborSimpleType::Null) , Undefined = SimpleType + int(QCborSimpleType::Undefined) , Double = 0x202 , DateTime = 0x10000 , Url = 0x10020 , RegularExpression = 0x10023 , Uuid = 0x10025 , Invalid = -1 }

Public Member Functions
	QCborValue ()

	QCborValue (Type t_)

	QCborValue (std::nullptr_t)

	QCborValue (bool b_)

	QCborValue (int i)

	QCborValue (unsigned u)

	QCborValue (qint64 i)

	QCborValue (double v)

	QCborValue (QCborSimpleType st)

	QCborValue (const QByteArray &ba)

	QCborValue (const QString &s)

	QCborValue (QStringView s)

	QCborValue (QLatin1String s)

QT_ASCII_CAST_WARN	QCborValue (const char *s)

	QCborValue (const QCborArray &a)

	QCborValue (QCborArray &&a)

	QCborValue (const QCborMap &m)

	QCborValue (QCborMap &&m)

	QCborValue (QCborTag tag, const QCborValue &taggedValue=QCborValue())

	QCborValue (QCborKnownTags t_, const QCborValue &tv=QCborValue())

	QCborValue (const QDateTime &dt)

	QCborValue (const QUrl &url)

	QCborValue (const QUuid &uuid)

	~QCborValue ()

	QCborValue (const void *)=delete

	QCborValue (const QCborValue &other)

	QCborValue (QCborValue &&other) noexcept

QCborValue &	operator= (const QCborValue &other)

void	swap (QCborValue &other) noexcept

Type	type () const

bool	isInteger () const

bool	isByteArray () const

bool	isString () const

bool	isArray () const

bool	isMap () const

bool	isTag () const

bool	isFalse () const

bool	isTrue () const

bool	isBool () const

bool	isNull () const

bool	isUndefined () const

bool	isDouble () const

bool	isDateTime () const

bool	isUrl () const

bool	isRegularExpression () const

bool	isUuid () const

bool	isInvalid () const

bool	isContainer () const

bool	isSimpleType () const

bool	isSimpleType (QCborSimpleType st) const

QCborSimpleType	toSimpleType (QCborSimpleType defaultValue=QCborSimpleType::Undefined) const

qint64	toInteger (qint64 defaultValue=0) const

bool	toBool (bool defaultValue=false) const

double	toDouble (double defaultValue=0) const

QCborTag	tag (QCborTag defaultValue=QCborTag(-1)) const

QCborValue	taggedValue (const QCborValue &defaultValue=QCborValue()) const

QByteArray	toByteArray (const QByteArray &defaultValue={}) const

QString	toString (const QString &defaultValue={}) const

QDateTime	toDateTime (const QDateTime &defaultValue={}) const

QUrl	toUrl (const QUrl &defaultValue={}) const

QUuid	toUuid (const QUuid &defaultValue={}) const

QCborArray	toArray () const

QCborArray	toArray (const QCborArray &defaultValue) const

QCborMap	toMap () const

QCborMap	toMap (const QCborMap &defaultValue) const

const QCborValue	operator[] (const QString &key) const

const QCborValue	operator[] (QLatin1String key) const

const QCborValue	operator[] (qint64 key) const

QCborValueRef	operator[] (qint64 key)

QCborValueRef	operator[] (QLatin1String key)

QCborValueRef	operator[] (const QString &key)

int	compare (const QCborValue &other) const

bool	operator== (const QCborValue &other) const noexcept

bool	operator!= (const QCborValue &other) const noexcept

bool	operator< (const QCborValue &other) const

QVariant	toVariant () const

QJsonValue	toJsonValue () const

QString	toDiagnosticNotation (DiagnosticNotationOptions opts=Compact) const

Static Public Member Functions
static QCborValue	fromVariant (const QVariant &variant)

static QCborValue	fromJsonValue (const QJsonValue &v)

Friends
class	QCborValueRef

class	QCborContainerPrivate

class	QJsonPrivate::Value

Detailed Description

The QCborValue class encapsulates a value in CBOR.

\inmodule QtCore

\reentrant

Since: 5.12

This class can be used to hold one of the many types available in CBOR. CBOR is the Concise Binary Object Representation, a very compact form of binary data encoding that is a superset of JSON. It was created by the IETF Constrained RESTful Environments (CoRE) WG, which has used it in many new RFCs. It is meant to be used alongside the \l{RFC 7252}{CoAP protocol}.

CBOR has three groups of built-in types:

\list

Basic types: integers, floating point (double), boolean, null, etc.
String-like types: strings and byte arrays
Containers: arrays and maps \endlist

Additionally, CBOR supports a form of type extensibility by associating a "tag" to one of the above types to convey more information. For example, a UUID is represented by a tag and a byte array containing the 16 bytes of the UUID content. QCborValue supports creating and decoding several of those extended types directly with Qt classes (like QUuid).

For the complete list, see \l QCborValue::Type. The type of a QCborValue can be queried using type() or one of the "isXxxx" functions.

Definition at line 85 of file qcborvalue.h.

Member Enumeration Documentation

◆ DiagnosticNotationOption

enum QCborValue::DiagnosticNotationOption

This enum is used in the option argument to toDiagnosticNotation(), to modify the output format.

\value Compact Does not use any line-breaks, producing a compact representation. \value LineWrapped Uses line-breaks, one QCborValue per line. \value ExtendedFormat Uses some different options to represent values, not found in RFC 7049. Those options are subject to change.

Currently, ExtendedFormat will change how byte arrays are represented. Without it, they are always hex-encoded and without spaces. With it, QCborValue::toCbor() will either use hex with spaces, base64 or base64url encoding, depending on the context.

See also: toDiagnosticNotation()

Enumerator
Compact
LineWrapped
ExtendedFormat

Definition at line 101 of file qcborvalue.h.

◆ EncodingOption

enum QCborValue::EncodingOption

This enum is used in the options argument to toCbor(), modifying the behavior of the encoder.

\omitvalue SortKeysInMaps \value NoTransformation (Default) Performs no transformations. \value UseFloat Tells the encoder to use IEEE 754 single-precision floating point (that is, float) whenever possible. \value UseFloat16 Tells the encoder to use IEEE 754 half-precision floating point (that is, qfloat16), whenever possible. Implies UseFloat. \value UseIntegers Tells the encoder to use integers whenever a value of type \l {Type}{Double} contains an integer.

The use of UseFloat16 is required to encode the stream in Canonical Format, but is not otherwise necessary.

See also: toCbor()

Enumerator
SortKeysInMaps
UseFloat
UseFloat16
UseIntegers
NoTransformation

Definition at line 89 of file qcborvalue.h.

◆ Type

enum QCborValue::Type : int

This enum represents the QCborValue type. It is returned by the type() function.

The CBOR built-in types are:

\value Integer qint64: An integer value \value ByteArray \l QByteArray: a byte array ("byte string") \value String \l QString: a Unicode string ("text string") \value Array \l QCborArray: an array of QCborValues \value Map \l QCborMap: an associative container of QCborValues \value SimpleType \l QCborSimpleType: one of several simple types/values \value False bool: the simple type for value false \value True bool: the simple type for value true \value Null std::nullptr_t: the simple type for the null value \value Undefined (no type) the simple type for the undefined value \value Double double: a double-precision floating point \value Invalid Not a valid value, this usually indicates a CBOR decoding error

Additionally, QCborValue can represent extended types:

\value Tag An unknown or unrecognized extended type, represented by its tag (a \l QCborTag) and the tagged value (a QCborValue) \value DateTime \l QDateTime: a date and time stamp \value Url \l QUrl: a URL or URI \value RegularExpression \l QRegularExpression: the pattern of a regular expression \value Uuid \l QUuid: a UUID

See also: type()

Enumerator
Integer
ByteArray
String
Array
Map
Tag
SimpleType
False
True
Null
Undefined
Double
DateTime
Url
RegularExpression
Uuid
Invalid

Definition at line 109 of file qcborvalue.h.

Constructor & Destructor Documentation

◆ QCborValue() [1/26]

QCborValue::QCborValue ( )

inline

Creates a QCborValue of the \l {Type}{Undefined} type.

CBOR undefined values are used to indicate missing information, usually as a result of a previous operation that did not complete as expected. They are also used by the QCborArray and QCborMap API to indicate the searched item was not found.

Undefined values are represented by the \l {QCborSimpleType}{Undefined simple type}. Because of that, QCborValues with undefined values will also return true for isSimpleType() and {isSimpleType(QCborSimpleType::Undefined)}.

Undefined values are different from null values.

QCborValue objects with undefined values are also different from invalid QCborValue objects. The API will not create invalid QCborValues, but they may exist as a result of a parsing error.

See also: isUndefined(), isNull(), isSimpleType()

Definition at line 136 of file qcborvalue.h.

Here is the caller graph for this function:

◆ QCborValue() [2/26]

QCborValue::QCborValue ( Type t_ )

inline

Creates a QCborValue of type t_. The value associated with such a type (if any) will be default constructed.

See also: type()

Definition at line 137 of file qcborvalue.h.

◆ QCborValue() [3/26]

QCborValue::QCborValue ( std::nullptr_t )

inline

Creates a QCborValue of the \l {Type}{Null} type.

CBOR null values are used to indicate optional values that were not provided. They are distinct from undefined values, in that null values are usually not the result of an earlier error or problem.

See also: isNull(), isUndefined(), isSimpleType()

Definition at line 138 of file qcborvalue.h.

◆ QCborValue() [4/26]

QCborValue::QCborValue ( bool b )

inline

Creates a QCborValue with boolean value b. The value can later be retrieved using toBool().

Internally, CBOR booleans are represented by a pair of types, one for true and one for false. For that reason, boolean QCborValues will return true for isSimpleType() and one of {isSimpleType(QCborSimpleType::False)} or {isSimpleType(QCborSimpleType::True)}.

See also: toBool(), isBool(), isTrue(), isFalse(), isSimpleType()

Definition at line 139 of file qcborvalue.h.

◆ QCborValue() [5/26]

QCborValue::QCborValue ( int i )

inline

Definition at line 141 of file qcborvalue.h.

◆ QCborValue() [6/26]

QCborValue::QCborValue ( unsigned u )

inline

Definition at line 142 of file qcborvalue.h.

◆ QCborValue() [7/26]

QCborValue::QCborValue ( qint64 i )

inline

Creates a QCborValue with integer value i. The value can later be retrieved using toInteger().

CBOR integer values are distinct from floating point values. Therefore, QCborValue objects with integers will compare differently to QCborValue objects containing floating-point, even if the values contained in the objects are equivalent.

See also: toInteger(), isInteger(), isDouble()

Definition at line 144 of file qcborvalue.h.

◆ QCborValue() [8/26]

QCborValue::QCborValue ( double d )

inline

Creates a QCborValue with floating point value d. The value can later be retrieved using toDouble().

CBOR floating point values are distinct from integer values. Therefore, QCborValue objects with integers will compare differently to QCborValue objects containing floating-point, even if the values contained in the objects are equivalent.

See also: toDouble(), isDouble(), isInteger()

Definition at line 145 of file qcborvalue.h.

◆ QCborValue() [9/26]

QCborValue::QCborValue ( QCborSimpleType st )

inline

Creates a QCborValue of simple type st. The type can later later be retrieved using toSimpleType() as well as isSimpleType(st).

CBOR simple types are types that do not have any associated value, like C++'s {std::nullptr_t} type, whose only possible value is \nullptr.

If st is {QCborSimpleType::Null}, the resulting QCborValue will be of the \l{Type}{Null} type and similarly for {QCborSimpleType::Undefined}. If st is {QCborSimpleType::False} or {QCborSimpleType::True}, the created QCborValue will be a boolean containing a value of false or true, respectively.

This function can be used with simple types not defined in the API. For example, to create a QCborValue with simple type 12, one could write:

Simple types should not be used until a specification for them has been published, since other implementations may not support them properly. Simple type values 24 to 31 are reserved and must not be used.

isSimpleType(), isNull(), isUndefined(), isTrue(), isFalse()

Definition at line 146 of file qcborvalue.h.

◆ QCborValue() [10/26]

QCborValue::QCborValue ( const QByteArray & ba )

Creates a QCborValue with byte array value ba. The value can later be retrieved using toByteArray().

See also: toByteArray(), isByteArray(), isString()

Definition at line 1709 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [11/26]

QCborValue::QCborValue ( const QString & s )

Creates a QCborValue with string value s. The value can later be retrieved using toString().

See also: toString(), isString(), isByteArray()

Definition at line 1723 of file qcborvalue.cpp.

◆ QCborValue() [12/26]

QCborValue::QCborValue ( QStringView s )

Creates a QCborValue with string value s. The value can later be retrieved using toString().

See also: toString(), isString(), isByteArray()

Definition at line 1732 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [13/26]

QCborValue::QCborValue ( QLatin1String s )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a QCborValue with string value s. The value can later be retrieved using toString().

See also: toString(), isString(), isByteArray()

Definition at line 1747 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [14/26]

QT_ASCII_CAST_WARN QCborValue::QCborValue ( const char * s )

inline

Definition at line 155 of file qcborvalue.h.

◆ QCborValue() [15/26]

QCborValue::QCborValue ( const QCborArray & a )

Definition at line 1763 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [16/26]

QCborValue::QCborValue ( QCborArray && a )

inline

Creates a QCborValue with the array a. The array can later be retrieved using toArray().

See also: toArray(), isArray(), isMap()

Definition at line 286 of file qcborarray.h.

◆ QCborValue() [17/26]

QCborValue::QCborValue ( const QCborMap & m )

Definition at line 1779 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [18/26]

QCborValue::QCborValue ( QCborMap && m )

inline

Creates a QCborValue with the map m. The map can later be retrieved using toMap().

See also: toMap(), isMap(), isArray()

Definition at line 338 of file qcbormap.h.

◆ QCborValue() [19/26]

QCborValue::QCborValue	(	QCborTag	tag,
		const QCborValue &	taggedValue = `QCborValue()`
	)

Definition at line 1796 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [20/26]

QCborValue::QCborValue	(	QCborKnownTags	tag,
		const QCborValue &	tv = `QCborValue()`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a QCborValue for the extended type represented by the tag value tag, tagging value taggedValue. The tag can later be retrieved using tag() and the tagged value using taggedValue().

See also: isTag(), tag(), taggedValue(), QCborKnownTags

Creates a QCborValue for the extended type represented by the tag value tag, tagging value tv. The tag can later be retrieved using tag() and the tagged value using taggedValue().

See also: isTag(), tag(), taggedValue(), QCborKnownTags

Definition at line 162 of file qcborvalue.h.

◆ QCborValue() [21/26]

QCborValue::QCborValue ( const QDateTime & dt )

explicit

Creates a QCborValue object of the date/time extended type and containing the value represented by dt. The value can later be retrieved using toDateTime().

The CBOR date/time types are extension types using tags: either a string (in ISO date format) tagged as a \l{QCborKnownTags}{DateTime} or a number (of seconds since the start of 1970, UTC) tagged as a \l{QCborKnownTags}{UnixTime_t}. When parsing CBOR streams, QCborValue will convert \l{QCborKnownTags}{UnixTime_t} to the string-based type.

See also: toDateTime(), isDateTime(), taggedValue()

Definition at line 1828 of file qcborvalue.cpp.

◆ QCborValue() [22/26]

QCborValue::QCborValue ( const QUrl & url )

explicit

Creates a QCborValue object of the URL extended type and containing the value represented by url. The value can later be retrieved using toUrl().

The CBOR URL type is an extended type represented by a string tagged as an \l{QCborKnownTags}{Url}.

See also: toUrl(), isUrl(), taggedValue()

Definition at line 1846 of file qcborvalue.cpp.

◆ QCborValue() [23/26]

QCborValue::QCborValue ( const QUuid & uuid )

explicit

Creates a QCborValue object of the UUID extended type and containing the value represented by uuid. The value can later be retrieved using toUuid().

The CBOR UUID type is an extended type represented by a byte array tagged as an \l{QCborKnownTags}{Uuid}.

See also: toUuid(), isUuid(), taggedValue()

Definition at line 1886 of file qcborvalue.cpp.

◆ ~QCborValue()

QCborValue::~QCborValue ( )

inline

Disposes of the current QCborValue object and frees any associated resources.

Definition at line 175 of file qcborvalue.h.

◆ QCborValue() [24/26]

QCborValue::QCborValue ( const void * )

delete

◆ QCborValue() [25/26]

QCborValue::QCborValue ( const QCborValue & other )

Copies the contents of other into this object.

Definition at line 1808 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ QCborValue() [26/26]

QCborValue::QCborValue ( QCborValue && other )

inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Moves the contents of the other QCborValue object into this one and frees the resources of this one.

Definition at line 181 of file qcborvalue.h.

Member Function Documentation

◆ compare()

int QCborValue::compare ( const QCborValue & other ) const

Compares this value and other, and returns an integer that indicates whether this value should be sorted prior to (if the result is negative) or after other (if the result is positive). If this function returns 0, the two values are equal and hold the same contents.

If each QCborValue contains an array or map, the comparison is recursive to elements contained in them.

Definition at line 1320 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ fromJsonValue()

QCborValue QCborValue::fromJsonValue ( const QJsonValue & v )

static

Converts the JSON value contained in v into its corresponding CBOR value and returns it. There is no data loss in converting from JSON to CBOR, as the CBOR type set is richer than JSON's. Additionally, values converted to CBOR using this function can be converted back to JSON using toJsonValue() with no data loss.

The following table lists the mapping of JSON types to CBOR types:

\table \header

JSON Type
CBOR Type \row
Bool
Bool \row
Number
Integer (if the number has no fraction and is in the \l qint64 range) or Double \row
String
String \row
Array
Array \row
Object
Map \row
Null
Null \endtable

\l QJsonValue can also be undefined, indicating a previous operation that failed to complete (for example, searching for a key not present in an object). Undefined values are not JSON types and may not appear in JSON arrays and objects, but this function does return the QCborValue undefined value if the corresponding QJsonValue is undefined.

See also: toJsonValue(), fromVariant(), QCborArray::fromJsonArray(), QCborMap::fromJsonObject()

Definition at line 639 of file qjsoncbor.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fromVariant()

QCborValue QCborValue::fromVariant ( const QVariant & variant )

static

Converts the QVariant variant into QCborValue and returns it.

QVariants may contain a large list of different meta types, many of which have no corresponding representation in CBOR. That includes all user-defined meta types. When preparing transmission using CBOR, it is suggested to encode carefully each value to prevent loss of representation.

The following table lists the conversion this function will apply:

\table \header

Qt (C++) type
CBOR type \row
invalid (QVariant())
Undefined \row
bool
Bool \row
std::nullptr_t
Null \row
short, ushort, int, uint, \l qint64
Integer \row
\l quint64
Integer, or Double if outside the range of qint64 \row
float, double
Double \row
\l QByteArray
ByteArray \row
\l QDateTime
DateTime \row
\l QCborSimpleType
Simple type \row
\l QJsonArray
Array, converted using QCborArray::formJsonArray() \row
\l QJsonDocument
Array or Map \row
\l QJsonObject
Map, converted using QCborMap::fromJsonObject() \row
\l QJsonValue
converted using fromJsonValue() \row
\l QRegularExpression
RegularExpression \row
\l QString
String \row
\l QStringList
Array \row
\l QVariantHash
Map \row
\l QVariantList
Array \row
\l QVariantMap
Map \row
\l QUrl
Url \row
\l QUuid
Uuid \endtable

If QVariant::isNull() returns true, a null QCborValue 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.

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 an Undefined CBOR value. Note that QVariant::toString() is also lossy for the majority of types.

Please note that the conversions via QVariant::toString() are subject to change at any time. Both QVariant and QCborValue 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(), fromJsonValue(), QCborArray::toVariantList(), QCborMap::toVariantMap(), QJsonValue::fromVariant()

Definition at line 731 of file qjsoncbor.cpp.

Here is the call graph for this function:

◆ isArray()

bool QCborValue::isArray ( ) const

inline

Returns true if this QCborValue is of the array type. The array value can be retrieved using toArray().

See also: type(), toArray()

Definition at line 199 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isBool()

bool QCborValue::isBool ( ) const

inline

Returns true if this QCborValue is a boolean. The value can be retrieved using toBool().

See also: type(), toBool(), isTrue(), isFalse()

Definition at line 204 of file qcborvalue.h.

◆ isByteArray()

bool QCborValue::isByteArray ( ) const

inline

Returns true if this QCborValue is of the byte array type. The byte array value can be retrieved using toByteArray().

See also: type(), toByteArray()

Definition at line 197 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isContainer()

bool QCborValue::isContainer ( ) const

inline

This convenience function returns true if the QCborValue is either an array or a map.

See also: isArray(), isMap()

Definition at line 213 of file qcborvalue.h.

◆ isDateTime()

bool QCborValue::isDateTime ( ) const

inline

Returns true if this QCborValue is of the date/time type. The value can be retrieved using toDateTime(). Date/times are extended types that use the tag \l{QCborKnownTags}{DateTime}.

Additionally, when decoding from a CBOR stream, QCborValue will interpret tags of value \l{QCborKnownTags}{UnixTime_t} and convert them to the equivalent date/time.

See also: type(), toDateTime()

Definition at line 208 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isDouble()

bool QCborValue::isDouble ( ) const

inline

Returns true if this QCborValue is of the floating-point type. The value can be retrieved using toDouble().

See also: type(), toDouble()

Definition at line 207 of file qcborvalue.h.

◆ isFalse()

bool QCborValue::isFalse ( ) const

inline

Returns true if this QCborValue is a boolean with false value. This function exists because, internally, CBOR booleans are stored as two separate types, one for true and one for false.

See also: type(), isBool(), isTrue(), toBool()

Definition at line 202 of file qcborvalue.h.

◆ isInteger()

bool QCborValue::isInteger ( ) const

inline

Returns true if this QCborValue is of the integer type. The integer value can be retrieved using toInteger().

See also: type(), toInteger()

Definition at line 196 of file qcborvalue.h.

◆ isInvalid()

bool QCborValue::isInvalid ( ) const

inline

Returns true if this QCborValue is not of any valid type. Invalid QCborValues are distinct from those with undefined values and they usually represent a decoding error.

See also: isUndefined(), isNull()

Definition at line 212 of file qcborvalue.h.

◆ isMap()

bool QCborValue::isMap ( ) const

inline

Returns true if this QCborValue is of the map type. The map value can be retrieved using toMap().

See also: type(), toMap()

Definition at line 200 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isNull()

bool QCborValue::isNull ( ) const

inline

Returns true if this QCborValue is of the null type.

CBOR null values are used to indicate optional values that were not provided. They are distinct from undefined values, in that null values are usually not the result of an earlier error or problem.

Null values are distinct from undefined values and from invalid QCborValue objects. The API will not create invalid QCborValues, but they may exist as a result of a parsing error.

See also: type(), isUndefined(), isInvalid()

Definition at line 205 of file qcborvalue.h.

◆ isRegularExpression()

bool QCborValue::isRegularExpression ( ) const

inline

Returns true if this QCborValue contains a regular expression's pattern. The pattern can be retrieved using toRegularExpression().

See also: type(), toRegularExpression()

Definition at line 210 of file qcborvalue.h.

◆ isSimpleType() [1/2]

bool QCborValue::isSimpleType ( ) const

inline

Returns true if this QCborValue is of one of the CBOR simple types. The type itself can later be retrieved using type(), even for types that don't have an enumeration in the API. They can also be checked with the \l{isSimpleType(QCborSimpleType)} overload.

See also: QCborSimpleType, isSimpleType(QCborSimpleType), toSimpleType()

Definition at line 215 of file qcborvalue.h.

◆ isSimpleType() [2/2]

bool QCborValue::isSimpleType ( QCborSimpleType st ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns true if this QCborValue is of a simple type and toSimpleType() would return st, false otherwise. This function can be used to check for any CBOR simple type, even those for which there is no enumeration in the API. For example, for the simple type of value 12, you could write:

See also: QCborValue::QCborValue(QCborSimpleType), isSimpleType(), isFalse(), isTrue(), isNull, isUndefined(), toSimpleType()

Definition at line 219 of file qcborvalue.h.

◆ isString()

bool QCborValue::isString ( ) const

inline

Returns true if this QCborValue is of the string type. The string value can be retrieved using toString().

See also: type(), toString()

Definition at line 198 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isTag()

bool QCborValue::isTag ( ) const

inline

Returns true if this QCborValue is of the tag type. The tag value can be retrieved using tag() and the tagged value using taggedValue().

This function also returns true for extended types that the API recognizes. For code that handles extended types directly before the Qt API is updated to support them, it is possible to recreate the tag + tagged value pair by using taggedValue().

See also: type(), tag(), taggedValue(), taggedValue()

Definition at line 201 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isTrue()

bool QCborValue::isTrue ( ) const

inline

Returns true if this QCborValue is a boolean with true value. This function exists because, internally, CBOR booleans are stored as two separate types, one for false and one for true.

See also: type(), isBool(), isFalse(), toBool()

Definition at line 203 of file qcborvalue.h.

◆ isUndefined()

bool QCborValue::isUndefined ( ) const

inline

Returns true if this QCborValue is of the undefined type.

CBOR undefined values are used to indicate missing information, usually as a result of a previous operation that did not complete as expected. They are also used by the QCborArray and QCborMap API to indicate the searched item was not found.

Undefined values are distinct from null values.

QCborValue objects with undefined values are also different from invalid QCborValue objects. The API will not create invalid QCborValues, but they may exist as a result of a parsing error.

See also: type(), isNull(), isInvalid()

Definition at line 206 of file qcborvalue.h.

◆ isUrl()

bool QCborValue::isUrl ( ) const

inline

Returns true if this QCborValue is of the URL type. The URL value can be retrieved using toUrl().

See also: type(), toUrl()

Definition at line 209 of file qcborvalue.h.

Here is the caller graph for this function:

◆ isUuid()

bool QCborValue::isUuid ( ) const

inline

Returns true if this QCborValue contains a UUID. The value can be retrieved using toUuid().

See also: type(), toUuid()

Definition at line 211 of file qcborvalue.h.

Here is the caller graph for this function:

◆ operator!=()

bool QCborValue::operator!= ( const QCborValue & other ) const

inlinenoexcept

Compares this value and other, and returns true if contents differ, false otherwise. If each QCborValue contains an array or map, the comparison is recursive to elements contained in them.

For more information on CBOR equality in Qt, see, QCborValue::compare().

See also: compare(), QCborValue::operator==(), QCborMap::operator==(), operator==(), operator<()

Definition at line 272 of file qcborvalue.h.

Here is the call graph for this function:

◆ operator<()

bool QCborValue::operator< ( const QCborValue & other ) const

inline

Compares this value and other, and returns true if this value should be sorted before other, false otherwise. If each QCborValue contains an array or map, the comparison is recursive to elements contained in them.

For more information on CBOR sorting order, see QCborValue::compare().

See also: compare(), QCborValue::operator==(), QCborMap::operator==(), operator==(), operator!=()

Definition at line 274 of file qcborvalue.h.

Here is the call graph for this function:

◆ operator=()

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Moves the contents of the other QCborValue object into this one and frees the resources of this one. Returns a reference to this object.

Replaces the contents of this QCborObject with a copy of other.

Definition at line 1902 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator==()

bool QCborValue::operator== ( const QCborValue & other ) const

inlinenoexcept

Compares this value and other, and returns true if they hold the same contents, false otherwise. If each QCborValue contains an array or map, the comparison is recursive to elements contained in them.

For more information on CBOR equality in Qt, see, compare().

See also: compare(), QCborValue::operator==(), QCborMap::operator==(), operator!=(), operator<()

Definition at line 270 of file qcborvalue.h.

Here is the call graph for this function:

◆ operator[]() [1/6]

QCborValueRef QCborValue::operator[] ( const QString & key )

Returns a QCborValueRef that can be used to read or modify the entry in this, as a map, with the given key. When this QCborValue is a QCborMap, this function is equivalent to the matching operator[] on that map.

Before returning the reference: if this QCborValue was an array, it is first converted to a map (so that {map[i]} is {array[i]} for each index, i, with valid {array[i]}); otherwise, if it was not a map it will be over-written with an empty map.

See also: operator[](qint64), QCborMap::operator[], QCborMap::value(), QCborMap::find()

Definition at line 2283 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator[]() [2/6]

const QCborValue QCborValue::operator[] ( const QString & key ) const

If this QCborValue is a QCborMap, searches elements for the value whose key matches key. If there's no key matching key in the map or if this QCborValue object is not a map, returns the undefined value.

This function is equivalent to:

See also: operator[](qint64), QCborMap::operator[], QCborMap::value(), QCborMap::find()

Definition at line 2170 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator[]() [3/6]

QCborValueRef QCborValue::operator[] ( qint64 key )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns a QCborValueRef that can be used to read or modify the entry in this, as a map or array, with the given key. When this QCborValue is a QCborMap or, for 0 <= key < 0x10000, a QCborArray, this function is equivalent to the matching operator[] on that map or array.

Before returning the reference: if this QCborValue was an array but the key is out of range, the array is first converted to a map (so that {map[i]} is {array[i]} for each index, i, with valid {array[i]}); otherwise, if it was not a map it will be over-written with an empty map.

See also: operator[], QCborMap::operator[], QCborMap::value(), QCborMap::find(), QCborArray::operator[], QCborArray::at()

Definition at line 2370 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator[]() [4/6]

const QCborValue QCborValue::operator[] ( qint64 key ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

If this QCborValue is a QCborMap, searches elements for the value whose key matches key. If this is a QCborArray, returns the element whose index is key. If there's no matching value in the array or map, or if this QCborValue object is not an array or map, returns the undefined value.

See also: operator[], QCborMap::operator[], QCborMap::value(), QCborMap::find(), QCborArray::operator[], QCborArray::at()

Definition at line 2209 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator[]() [5/6]

QCborValueRef QCborValue::operator[] ( QLatin1String key )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns a QCborValueRef that can be used to read or modify the entry in this, as a map, with the given key. When this QCborValue is a QCborMap, this function is equivalent to the matching operator[] on that map.

Before returning the reference: if this QCborValue was an array, it is first converted to a map (so that {map[i]} is {array[i]} for each index, i, with valid {array[i]}); otherwise, if it was not a map it will be over-written with an empty map.

See also: operator[](qint64), QCborMap::operator[], QCborMap::value(), QCborMap::find()

Definition at line 2326 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ operator[]() [6/6]

const QCborValue QCborValue::operator[] ( QLatin1String key ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

If this QCborValue is a QCborMap, searches elements for the value whose key matches key. If there's no key matching key in the map or if this QCborValue object is not a map, returns the undefined value.

This function is equivalent to:

See also: operator[](qint64), QCborMap::operator[], QCborMap::value(), QCborMap::find()

Definition at line 2191 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ swap()

void QCborValue::swap ( QCborValue & other )

inlinenoexcept

Swaps the contents of this QCborValue object and other.

Definition at line 188 of file qcborvalue.h.

Here is the call graph for this function:

◆ tag()

QCborTag QCborValue::tag ( QCborTag defaultValue = QCborTag(-1) ) const

Returns the tag of this extended QCborValue object, if it is of the tag type, defaultValue otherwise.

CBOR represents extended types by associating a number (the tag) with a stored representation. This function returns that number. To retrieve the representation, use taggedValue().

See also: isTag(), taggedValue(), isDateTime(), isUrl(), isRegularExpression(), isUuid()

Definition at line 1925 of file qcborvalue.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ taggedValue()

QCborValue QCborValue::taggedValue ( const QCborValue & defaultValue = QCborValue() ) const

Returns the tagged value of this extended QCborValue object, if it is of the tag type, defaultValue otherwise.

CBOR represents extended types by associating a number (the tag) with a stored representation. This function returns that representation. To retrieve the tag, use tag().

See also: isTag(), tag(), isDateTime(), isUrl(), isRegularExpression(), isUuid()

Definition at line 1941 of file qcborvalue.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toArray() [1/2]

QCborArray QCborValue::toArray ( ) const

Definition at line 2098 of file qcborvalue.cpp.

Here is the caller graph for this function:

◆ toArray() [2/2]

QCborArray QCborValue::toArray ( const QCborArray & defaultValue ) const

Returns the array value stored in this QCborValue, if it is of the array type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QCborArray.

See also: isArray(), isByteArray(), isMap(), isContainer(), toMap()

Definition at line 2103 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toBool()

bool QCborValue::toBool ( bool defaultValue = false ) const

inline

Returns the boolean value stored in this QCborValue, if it is of a boolean type. Otherwise, it returns defaultValue.

See also: isBool(), isTrue(), isFalse()

Definition at line 230 of file qcborvalue.h.

◆ toByteArray()

QByteArray QCborValue::toByteArray ( const QByteArray & defaultValue = {} ) const

Returns the byte array value stored in this QCborValue, if it is of the byte array type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QByteArray.

See also: isByteArray(), isString(), toString()

Definition at line 1956 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toDateTime()

QDateTime QCborValue::toDateTime ( const QDateTime & defaultValue = {} ) const

Returns the date/time value stored in this QCborValue, if it is of the date/time extended type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QDateTime.

See also: isDateTime(), isTag(), taggedValue()

Definition at line 1992 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toDiagnosticNotation()

QString QCborValue::toDiagnosticNotation ( DiagnosticNotationOptions opts = Compact ) const

Creates the diagnostic notation equivalent of this CBOR object and returns it. The opts parameter controls the dialect of the notation. Diagnostic notation is useful in debugging, to aid the developer in understanding what value is stored in the QCborValue or in a CBOR stream. For that reason, the Qt API provides no support for parsing the diagnostic back into the in-memory format or CBOR stream, though the representation is unique and it would be possible.

CBOR diagnostic notation is specified by \l{RFC 7049, section 6}{section 6} of RFC 7049. It is a text representation of the CBOR stream and it is very similar to JSON, but it supports the CBOR types not found in JSON. The extended format enabled by the \l{DiagnosticNotationOption}{ExtendedFormat} flag is currently in some IETF drafts and its format is subject to change.

This function produces the equivalent representation of the stream that toCbor() would produce, without any transformation option provided there. This also implies this function may not produce a representation of the stream that was used to create the object, if it was created using fromCbor(), as that function may have applied transformations. For a high-fidelity notation of a stream, without transformation, see the cbordump example.

See also: toCbor(), QJsonDocument::toJson()

Definition at line 345 of file qcbordiagnostic.cpp.

Here is the call graph for this function:

◆ toDouble()

double QCborValue::toDouble ( double defaultValue = 0 ) const

inline

Returns the floating point value stored in this QCborValue, if it is of the Double type. If it is of the Integer type, this function returns the integer value converted to double. In any other case, it returns defaultValue.

See also: isDouble(), isInteger(), toInteger()

Definition at line 232 of file qcborvalue.h.

◆ toInteger()

qint64 QCborValue::toInteger ( qint64 defaultValue = 0 ) const

inline

Returns the integer value stored in this QCborValue, if it is of the integer type. If it is of the Double type, this function returns the floating point value converted to integer. In any other case, it returns defaultValue.

See also: isInteger(), isDouble(), toDouble()

Definition at line 228 of file qcborvalue.h.

◆ toJsonValue()

QJsonValue QCborValue::toJsonValue ( ) const

Converts this QCborValue object to an equivalent representation in JSON and returns it as a QJsonValue.

Please note that CBOR contains a richer and wider type set than JSON, so some information may be lost in this conversion. The following table compares CBOR types to JSON types and indicates whether information may be lost or not.

\table \header

CBOR Type
JSON Type
Comments \row
Bool
Bool
No data loss possible \row
Double
Number
Infinities and NaN will be converted to Null; no data loss for other values \row
Integer
Number
Data loss possible in the conversion if the integer is larger than 2\sup{53} or smaller than -2\sup{53}. \row
Null
Null
No data loss possible \row
Undefined
Null
Type information lost \row
String
String
No data loss possible \row
Byte Array
String
Converted to a lossless encoding like Base64url, but the distinction between strings and byte arrays is lost \row
Other simple types
String
Type information lost \row
Array
Array
Conversion applies to each contained value \row
Map
Object
Keys are converted to string; values converted according to this table \row
Tags and extended types
Special
The tag number itself is lost and the tagged value is converted to JSON \endtable

For information on the conversion of CBOR map keys to string, see QCborMap::toJsonObject().

If this QCborValue contains the undefined value, this function will return an undefined QJsonValue too. Note that JSON does not support undefined values and undefined QJsonValues are an extension to the specification. They cannot be held in a QJsonArray or QJsonObject, but can be returned from functions to indicate a failure. For all other intents and purposes, they are the same as null.

Definition at line 379 of file qjsoncbor.cpp.

Here is the call graph for this function:

◆ toMap() [1/2]

QCborMap QCborValue::toMap ( ) const

Definition at line 2141 of file qcborvalue.cpp.

Here is the caller graph for this function:

◆ toMap() [2/2]

QCborMap QCborValue::toMap ( const QCborMap & defaultValue ) const

Returns the map value stored in this QCborValue, if it is of the map type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QCborMap.

See also: isMap(), isArray(), isContainer(), toArray()

Definition at line 2146 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toSimpleType()

QCborSimpleType QCborValue::toSimpleType ( QCborSimpleType defaultValue = QCborSimpleType::Undefined ) const

inline

Returns the simple type this QCborValue is of, if it is a simple type. If it is not a simple type, it returns defaultValue.

The following types are simple types and this function will return the listed values:

\table \row

See also: type(), isSimpleType(), isBool(), isTrue(), isFalse(), isTrue(), isNull(), isUndefined()

Definition at line 223 of file qcborvalue.h.

Here is the call graph for this function:

◆ toString()

QString QCborValue::toString ( const QString & defaultValue = {} ) const

Returns the string value stored in this QCborValue, if it is of the string type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QString.

See also: isString(), isByteArray(), toByteArray()

Definition at line 1974 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toUrl()

QUrl QCborValue::toUrl ( const QUrl & defaultValue = {} ) const

Returns the URL value stored in this QCborValue, if it is of the URL extended type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QUrl.

See also: isUrl(), isTag(), taggedValue()

Definition at line 2016 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toUuid()

QUuid QCborValue::toUuid ( const QUuid & defaultValue = {} ) const

Returns the UUID value stored in this QCborValue, if it is of the UUID extended type. Otherwise, it returns defaultValue.

Note that this function performs no conversion from other types to QUuid.

See also: isUuid(), isTag(), taggedValue()

Definition at line 2059 of file qcborvalue.cpp.

Here is the call graph for this function:

◆ toVariant()

QVariant QCborValue::toVariant ( ) const

Converts this value to a native Qt type and returns the corresponding QVariant.

The following table lists the mapping performed between \l{Type}{QCborValue types} and \l{QMetaType::Type}{Qt meta types}.

\table \header

CBOR Type
Qt or C++ type
Notes \row
Integer
\l qint64
\row
Double
double
\row
Bool
bool
\row
Null
std::nullptr_t
\row
Undefined
no type (QVariant())
\row
Byte array
\l QByteArray
\row
String
\l QString
\row
Array
\l QVariantList
Recursively converts all values \row
Map
\l QVariantMap
Key types are "stringified" \row
Other simple types
\l QCborSimpleType
\row
DateTime
\l QDateTime
\row
Url
\l QUrl
\row
RegularExpression
\l QRegularExpression
\row
Uuid
\l QUuid
\row
Other tags
Special
The tag is ignored and the tagged value is converted using this function \endtable

Note that values in both CBOR Maps and Arrays are converted recursively using this function too and placed in QVariantMap and QVariantList instead. You will not find QCborMap and QCborArray stored inside the QVariants.

QVariantMaps have string keys, unlike CBOR, so the conversion of a QCborMap to QVariantMap will imply a step of "stringification" of the key values. See QCborMap::toJsonObject() for details.

See also: fromVariant(), toJsonValue(), QCborArray::toVariantList(), QCborMap::toVariantMap()

Definition at line 543 of file qjsoncbor.cpp.

Here is the call graph for this function:

◆ type()

QCborValue::Type QCborValue::type ( ) const

inline

Returns the type of this QCborValue. The type can also later be retrieved by one of the "isXxx" functions.

See also: isInteger(), isByteArray(), isString(), isArray(), isMap(), isTag(), isFalse(), isTrue(), isBool(), isNull(), isUndefined, isDouble(), isDateTime(), isUrl(), isRegularExpression(), isUuid()

Definition at line 195 of file qcborvalue.h.

Friends And Related Function Documentation

◆ QCborContainerPrivate

friend class QCborContainerPrivate

friend

Definition at line 300 of file qcborvalue.h.

◆ QCborValueRef

friend class QCborValueRef

friend

Definition at line 299 of file qcborvalue.h.

◆ QJsonPrivate::Value

friend class QJsonPrivate::Value

friend

Definition at line 301 of file qcborvalue.h.

The documentation for this class was generated from the following files:

src/corelib/serialization/qcborvalue.h
src/corelib/serialization/qcborarray.h
src/corelib/serialization/qcbordiagnostic.cpp
src/corelib/serialization/qcbormap.h
src/corelib/serialization/qcborvalue.cpp
src/corelib/serialization/qjsoncbor.cpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ DiagnosticNotationOption

◆ EncodingOption

◆ Type

Constructor & Destructor Documentation

◆ QCborValue() [1/26]

◆ QCborValue() [2/26]

◆ QCborValue() [3/26]

◆ QCborValue() [4/26]

◆ QCborValue() [5/26]

◆ QCborValue() [6/26]

◆ QCborValue() [7/26]

◆ QCborValue() [8/26]

◆ QCborValue() [9/26]

◆ QCborValue() [10/26]

◆ QCborValue() [11/26]

◆ QCborValue() [12/26]

◆ QCborValue() [13/26]

◆ QCborValue() [14/26]

◆ QCborValue() [15/26]

◆ QCborValue() [16/26]

◆ QCborValue() [17/26]

◆ QCborValue() [18/26]

◆ QCborValue() [19/26]

◆ QCborValue() [20/26]

◆ QCborValue() [21/26]

◆ QCborValue() [22/26]

◆ QCborValue() [23/26]

◆ ~QCborValue()

◆ QCborValue() [24/26]

◆ QCborValue() [25/26]

◆ QCborValue() [26/26]

Member Function Documentation

◆ compare()

◆ fromJsonValue()

◆ fromVariant()

◆ isArray()

◆ isBool()

◆ isByteArray()

◆ isContainer()

◆ isDateTime()

◆ isDouble()

◆ isFalse()

◆ isInteger()

◆ isInvalid()

◆ isMap()

◆ isNull()

◆ isRegularExpression()

◆ isSimpleType() [1/2]

◆ isSimpleType() [2/2]

◆ isString()

◆ isTag()

◆ isTrue()

◆ isUndefined()

◆ isUrl()

◆ isUuid()

◆ operator!=()

◆ operator<()

◆ operator=()

◆ operator==()

◆ operator[]() [1/6]

◆ operator[]() [2/6]

◆ operator[]() [3/6]

◆ operator[]() [4/6]

◆ operator[]() [5/6]

◆ operator[]() [6/6]

◆ swap()

◆ tag()

◆ taggedValue()

◆ toArray() [1/2]

◆ toArray() [2/2]

◆ toBool()

◆ toByteArray()

◆ toDateTime()

◆ toDiagnosticNotation()