QCborMap Class

The QCborMap class is used to hold an associative container representable in CBOR. More...

Header: #include <QCborMap>
qmake: QT += core
Since: Qt 5.12

This class was introduced in Qt 5.12.

Note: All functions in this class are reentrant.

Public Types

class ConstIterator
class Iterator
typedef const_iterator
typedef iterator
typedef key_type
typedef mapped_type
typedef size_type
typedef value_type

Public Functions

QCborMap(const QCborMap &other)
QCborMap()
QCborMap &operator=(const QCborMap &other)
~QCborMap()
void clear()
QCborMap::const_iterator constFind(qint64 key) const
QCborMap::const_iterator constFind(QLatin1String key) const
QCborMap::const_iterator constFind(const QString &key) const
QCborMap::const_iterator constFind(const QCborValue &key) const
QCborMap::iterator erase(QCborMap::iterator it)
QVector<QCborValue> keys() const
qsizetype size() const
QJsonObject toJsonObject() const
QVariantHash toVariantHash() const
QVariantMap toVariantMap() const
QCborValueRef operator[](qint64 key)
QCborValueRef operator[](QLatin1String key)
QCborValueRef operator[](const QString &key)
QCborValueRef operator[](const QCborValue &key)

Static Public Members

QCborMap fromJsonObject(const QJsonObject &obj)
QCborMap fromVariantHash(const QVariantHash &hash)
QCborMap fromVariantMap(const QVariantMap &map)

Detailed Description

This class can be used to hold an associative container in CBOR, a map between a key and a value type. 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.

Unlike JSON and QVariantMap, CBOR map keys can be of any type, not just strings. For that reason, QCborMap is effectively a map between QCborValue keys to QCborValue value elements.

However, for all member functions that take a key parameter, QCborMap provides overloads that will work efficiently with integers and strings. In fact, the use of integer keys is encouraged, since they occupy fewer bytes to transmit and are simpler to encode and decode. Newer protocols designed by the IETF CoRE WG to work specifically with CBOR are known to use them.

QCborMap is not sorted, because of that, searching for keys has linear complexity (O(n)). QCborMap actually keeps the elements in the order that they were inserted, which means that it is possible to make sorted QCborMaps by carefully inserting elements in sorted order. CBOR does not require sorting, but recommends it.

QCborMap can also be converted to and from QVariantMap and QJsonObject. However, when performing the conversion, any non-string keys will be stringified using a one-way method that the conversion back to QCborMap will not undo.

See also QCborArray, QCborValue, QJsonDocument, and QVariantMap.

Member Type Documentation

typedef QCborMap::const_iterator

A synonym for QCborMap::ConstIterator

typedef QCborMap::iterator

A synonym for QCborMap::Iterator.

typedef QCborMap::key_type

The key type for this map. Since QCborMap keys can be any CBOR type, this is a QCborValue.

typedef QCborMap::mapped_type

The type that is mapped to (the value), that is, a QCborValue.

typedef QCborMap::size_type

The type that QCborMap uses for sizes.

typedef QCborMap::value_type

The value that is stored in this container: a pair of QCborValues

Member Function Documentation

QCborMap::QCborMap(const QCborMap &other)

Creates a QCborMap object that is a copy of other.

QCborMap::QCborMap()

Constructs an empty CBOR Map object.

See also isEmpty().

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

Replaces the contents of this object with a copy of other, then returns a reference to this object.

QCborMap::~QCborMap()

Destroys this QCborMap object and frees any associated resources it owns.

void QCborMap::clear()

Empties this map.

See also isEmpty().

QCborMap::const_iterator QCborMap::constFind(qint64 key) const

Returns a map iterator to the key-value pair whose key is key, if the map contains such a pair. If it doesn't, this function returns constEnd().

CBOR recommends using integer keys, since they occupy less space and are simpler to encode and decode.

If the map contains more than one key equal to key, it is undefined which one this function will find. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

value(QLatin1String), value(const QString &), value(const QCborValue &)

See also value(qint64), operator[](qint64), find(qint64), remove(qint64), and contains(qint64).

QCborMap::const_iterator QCborMap::constFind(QLatin1String key) const

This is an overloaded function.

Returns a map iterator to the key-value pair whose key is key, if the map contains such a pair. If it doesn't, this function returns constEnd().

If the map contains more than one key equal to key, it is undefined which one this function will find. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

value(qint64), value(const QString &), value(const QCborValue &)

See also value(QLatin1String), operator[](QLatin1String), find(QLatin1String), remove(QLatin1String), and contains(QLatin1String).

QCborMap::const_iterator QCborMap::constFind(const QString &key) const

This is an overloaded function.

Returns a map iterator to the key-value pair whose key is key, if the map contains such a pair. If it doesn't, this function returns constEnd().

If the map contains more than one key equal to key, it is undefined which one this function will find. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

value(qint64), value(QLatin1String), value(const QCborValue &)

See also value(const QString &), operator[](const QString &), find(const QString &), remove(const QString &), and contains(const QString &).

QCborMap::const_iterator QCborMap::constFind(const QCborValue &key) const

This is an overloaded function.

Returns a map iterator to the key-value pair whose key is key, if the map contains such a pair. If it doesn't, this function returns constEnd().

If the map contains more than one key equal to key, it is undefined which one this function will find. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

See also value(const QCborValue &), operator[](const QCborValue &), find(const QCborValue &), remove(const QCborValue &), contains(const QCborValue &), value(qint64), value(QLatin1String), and value(const QString &).

QCborMap::iterator QCborMap::erase(QCborMap::iterator it)

This is an overloaded function.

Removes the key-value pair pointed to by the map iterator it and returns a pointer to the next element, after removal.

See also remove(), begin(), end(), and insert().

[static] QCborMap QCborMap::fromJsonObject(const QJsonObject &obj)

Converts all JSON items found in the obj object to CBOR using QCborValue::fromJson(), and returns the map composed of those elements.

This conversion is lossless, as the CBOR type system is a superset of JSON's. Moreover, the map returned by this function can be converted back to the original obj by using toJsonObject().

See also toJsonObject(), toVariantMap(), QCborValue::fromJsonValue(), and QCborArray::fromJsonArray().

[static] QCborMap QCborMap::fromVariantHash(const QVariantHash &hash)

Converts all the items in hash to CBOR using QCborValue::fromVariant() and returns the map composed of those elements.

Conversion from QVariant is not completely lossless. Please see the documentation in QCborValue::fromVariant() for more information.

See also toVariantHash(), fromVariantMap(), fromJsonObject(), and QCborValue::fromVariant().

[static] QCborMap QCborMap::fromVariantMap(const QVariantMap &map)

Converts all the items in map to CBOR using QCborValue::fromVariant() and returns the map composed of those elements.

Conversion from QVariant is not completely lossless. Please see the documentation in QCborValue::fromVariant() for more information.

See also toVariantMap(), fromVariantHash(), fromJsonObject(), and QCborValue::fromVariant().

QVector<QCborValue> QCborMap::keys() const

Returns a list of all keys in this map.

See also QMap::keys() and QHash::keys().

qsizetype QCborMap::size() const

Returns the number of elements in this map.

See also isEmpty().

QJsonObject QCborMap::toJsonObject() const

Recursively converts every QCborValue value in this array to JSON using QCborValue::toJsonValue() and creates a string key for all keys that aren't strings, then returns the corresponding QJsonObject composed of those associations.

Please note that CBOR contains a richer and wider type set than JSON, so some information may be lost in this conversion. For more details on what conversions are applied, see QCborValue::toJsonValue().

Map key conversion to string

JSON objects are defined as having string keys, unlike CBOR, so the conversion of a QCborMap to QJsonObject will imply a step of "stringification" of the key values. The conversion will use the special handling of tags and extended types from above and will also convert the rest of the types as follows:

TypeTransformation
Bool"true" and "false"
Null"null"
Undefined"undefined"
IntegerThe decimal string form of the number
DoubleThe decimal string form of the number
Byte arrayUnless tagged differently (see above), encoded as Base64url
ArrayReplaced by the compact form of its Diagnostic notation
MapReplaced by the compact form of its Diagnostic notation
Tags and extended typesTag number is dropped and the tagged value is converted to string

See also fromJsonObject(), QCborValue::toJsonValue(), QCborArray::toJsonArray(), and toVariantMap().

QVariantHash QCborMap::toVariantHash() const

Converts the CBOR values to QVariant using QCborValue::toVariant() and "stringifies" all the CBOR keys in this map, returning the QVariantHash that results from that association list.

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.

In addition, the conversion to QVariant is not completely lossless. Please see the documentation in QCborValue::toVariant() for more information.

See also fromVariantHash(), toVariantMap(), toJsonObject(), QCborValue::toVariant(), and QCborArray::toVariantList().

QVariantMap QCborMap::toVariantMap() const

Converts the CBOR values to QVariant using QCborValue::toVariant() and "stringifies" all the CBOR keys in this map, returning the QVariantMap that results from that association list.

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.

In addition, the conversion to QVariant is not completely lossless. Please see the documentation in QCborValue::toVariant() for more information.

See also fromVariantMap(), toVariantHash(), toJsonObject(), QCborValue::toVariant(), and QCborArray::toVariantList().

QCborValueRef QCborMap::operator[](qint64 key)

Returns a QCborValueRef to the value in this map that corresponds to key key. CBOR recommends using integer keys, since they occupy less space and are simpler to encode and decode.

QCborValueRef has the exact same API as QCborValue, with one important difference: if you assign new values to it, this map will be updated with that new value.

If the map did not have a key equal to key, one is inserted and this function returns a reference to the new value, which will be a QCborValue with an undefined value. For that reason, it is not possible with this function to tell apart the situation where the key was not present from the situation where the key was mapped to an undefined value.

If the map contains more than one key equal to key, it is undefined which one the return will reference. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

See also value(qint64), find(qint64), contains(qint64), remove(qint64), operator[](QLatin1String), operator[](const QString &), and operator[](const QCborValue &).

QCborValueRef QCborMap::operator[](QLatin1String key)

This is an overloaded function.

Returns a QCborValueRef to the value in this map that corresponds to key key.

QCborValueRef has the exact same API as QCborValue, with one important difference: if you assign new values to it, this map will be updated with that new value.

If the map did not have a key equal to key, one is inserted and this function returns a reference to the new value, which will be a QCborValue with an undefined value. For that reason, it is not possible with this function to tell apart the situation where the key was not present from the situation where the key was mapped to an undefined value.

If the map contains more than one key equal to key, it is undefined which one the return will reference. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

See also value(QLatin1String), find(QLatin1String), contains(QLatin1String), remove(QLatin1String), operator[](qint64), operator[](const QString &), and operator[](const QCborValue &).

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

This is an overloaded function.

Returns a QCborValueRef to the value in this map that corresponds to key key.

QCborValueRef has the exact same API as QCborValue, with one important difference: if you assign new values to it, this map will be updated with that new value.

If the map did not have a key equal to key, one is inserted and this function returns a reference to the new value, which will be a QCborValue with an undefined value. For that reason, it is not possible with this function to tell apart the situation where the key was not present from the situation where the key was mapped to an undefined value.

If the map contains more than one key equal to key, it is undefined which one the return will reference. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

See also value(const QString &), find(const QString &), contains(const QString &), remove(const QString &), operator[](qint64), operator[](QLatin1String), and operator[](const QCborValue &).

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

This is an overloaded function.

Returns a QCborValueRef to the value in this map that corresponds to key key.

QCborValueRef has the exact same API as QCborValue, with one important difference: if you assign new values to it, this map will be updated with that new value.

If the map did not have a key equal to key, one is inserted and this function returns a reference to the new value, which will be a QCborValue with an undefined value. For that reason, it is not possible with this function to tell apart the situation where the key was not present from the situation where the key was mapped to an undefined value.

If the map contains more than one key equal to key, it is undefined which one the return will reference. QCborMap does not allow inserting duplicate keys, but it is possible to create such a map by decoding a CBOR stream with them. They are usually not permitted and having duplicate keys is usually an indication of a problem in the sender.

See also value(const QCborValue &), find(const QCborValue &), contains(const QCborValue &), remove(const QCborValue &), operator[](qint64), operator[](QLatin1String), and operator[](const QString &).