QCborValue Class

Detailed Description

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 CoAP protocol.

CBOR has three groups of built-in types:

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

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 QCborValue::Type. The type of a QCborValue can be queried using type() or one of the "isXxxx" functions.

Extended types and tagged values

A tagged value is a normal QCborValue that is paired with a number that is its tag. See QCborKnownTags for more information on what tags are in the API as well as the full, official list. Such combinations form extended types.

QCborValue has support for certain extended types in the API, like URL (with QUrl) and UUID (with QUuid). Other extended types not supported in the API are represented by a QCborValue of Tag type. The tag can later be retrieved by tag() and the tagged value using taggedValue().

In order to support future compatibility, QCborValues containing extended Qt types compare equal to the tag type of the same contents. In other words, the following expression is true:

     QCborValue(uuid) == QCborValue(QCborKnownTags::Uuid, uuid.toRfc4122());

Undefined and null values

QCborValue can contain a value of "null", which is not of any specific type. It resembles the C++ std::nullptr_t type, whose only possible value is nullptr. QCborValue has a constructor taking such a type and creates a null QCborValue.

Null values are used to indicate that an optional value is not present. In that aspect, it is similar to the C++ Standard Library type std::optional when that is disengaged. Unlike the C++ type, CBOR nulls are simply of type "Null" and it is not possible to determine what concrete type it is replacing.

QCborValue can also be of the undefined type, which represents a value of "undefined". In fact, that is what the QCborValue default constructor creates.

Undefined values are different from null values. While nulls are used to indicate an optional value that is not provided, Undefined is usually used to indicate that an expected value could not be provided, usually due to an error or a precondition that could not be satisfied.

Such values are completely valid and may appear in CBOR streams, unlike JSON content and QJsonValue's undefined bit. But like QJsonValue's Undefined, it is returned by a CBOR container's value() or read-only operator[] for invalid look-ups (index out of range for QCborArray, or key not found for QCborMap). It is not possible to tell such a case apart from the value of Undefined, so if that is required, check the QCborArray size and use the QCborMap iterator API.

Simple types

CBOR supports additional simple types that, like Null and Undefined, carry no other value. They are called interchangeably "Simple Types" and "Simple Values". CBOR encodes booleans as two distinct types (one for true and one for false), but QCborValue has a convenience API for them.

There are currently no other defined CBOR simple types. QCborValue supports them simply by their number with API like isSimpleType() and toSimpleType(), available for compatibility with future specifications before the Qt API can be updated. Their use before such a specification is discouraged, as other CBOR implementations may not support them fully.

CBOR support

QCborValue supports all CBOR features required to create canonical and strict streams. It implements almost all of the features specified in RFC 7049.

The following table lists the CBOR features that QCborValue supports.

Integers in QCborValue are limited to the range of the qint64 type. That is, from -9,223,372,036,854,775,808 (-2⁶³) to 9,223,372,036,854,775,807 (2⁶³ - 1). CBOR itself can represent integer values outside of this range, which QCborValue does not support. When decoding a stream using fromCbor() containing one of those values, QCborValue will convert automatically to Double, but that may lose up to 11 bits of precision.

fromCbor() is able to decode chunked strings, but will always merge the chunks together into a single QCborValue. For that reason, it always writes non-chunked strings when using toCbor() (which is required by the Canonical format anyway).

QCborValue will always convert half- and single-precision floating point values in the CBOR stream to double-precision. The toCbor() function can take a parameter indicating to recreate them.

QCborValueRef

QCborValueRef is a helper class for QCborArray and QCborMap. It is the type you get when using one of the mutating APIs in those classes. Unlike QCborValue, new values can be assigned to that class. When that is done, the array or map it refers to will be modified with the new value. In all other aspects, its API is identical to QCborValue.

QJsonValue, QJsonDocument