class QCborMap

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

Synopsis

Methods

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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 QVariantMap Parsing and displaying CBOR data Serialization Converter Saving and Loading a Game

__init__()

Constructs an empty CBOR Map object.

See also

isEmpty()

__init__(other)
Parameters:

other – QCborMap

Creates a QCborMap object that is a copy of other.

clear()

Empties this map.

See also

isEmpty()

compare(other)
Parameters:

other – QCborMap

Return type:

int

Compares this map and other, comparing each element in sequence, and returns an integer that indicates whether this map 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 maps are equal and contain the same elements.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() compare() operator==()

contains(key)
Parameters:

key – QLatin1String

Return type:

bool

contains(key)
Parameters:

key – QCborValue

Return type:

bool

Returns true if this map contains a key-value pair identified by key key.

See also

value(const QCborValue &) operator[](const QCborValue &) find(const QCborValue &) remove(const QCborValue &) contains(qint64) remove(QLatin1StringView) remove(const QString &)

contains(key)
Parameters:

key – str

Return type:

bool

This is an overloaded function.

Returns true if this map contains a key-value pair identified by key key.

See also

value(const QString &) operator[](const QString &) find(const QString &) remove(const QString &) contains(qint64) remove(QLatin1StringView) remove(const QCborValue &)

contains(key)
Parameters:

key – int

Return type:

bool

Returns true if this map contains a key-value pair identified by key key. CBOR recommends using integer keys, since they occupy less space and are simpler to encode and decode.

See also

value(qint64) operator[](qint64) find(qint64) remove(qint64) contains(QLatin1StringView) remove(const QString &) remove(const QCborValue &)

empty()
Return type:

bool

Synonym for isEmpty() . This function is provided for compatibility with generic code that uses the Standard Library API.

Returns true if this map is empty ( size() == 0).

See also

isEmpty() size()

static fromJsonObject(o)
Parameters:

o – QJsonObject

Return type:

QCborMap

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() .

static fromVariantHash(hash)
Parameters:

hash – Dictionary with keys of type .QString and values of type QVariant.

Return type:

QCborMap

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

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

static fromVariantMap(map)
Parameters:

map – Dictionary with keys of type .QString and values of type QVariant.

Return type:

QCborMap

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

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

isEmpty()
Return type:

bool

Returns true if this map is empty (that is, size() is 0).

See also

size() clear()

keys()
Return type:

.list of QCborValue

Returns a list of all keys in this map.

See also

keys() keys()

__ne__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if the two maps contain any different elements or elements in different orders, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator==() operator==() operator

__ne__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

__lt__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if lhs map should be sorted before rhs, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator==() operator==() operator!=()

__lt__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

__le__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if lhs map should be sorted before rhs or if the two maps contain the same elements in the same order, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator==() operator==() operator!=()

__le__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

__eq__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if the two maps contain the same elements in the same order, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator!=() operator

__eq__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

__gt__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if lhs map should be sorted after rhs, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator==() operator==() operator!=()

__gt__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

__ge__(rhs)
Parameters:

rhs – QCborMap

Return type:

bool

Compares lhs and rhs maps, comparing each element in sequence, and returns true if lhs map should be sorted after rhs or if the two maps contain the same elements in the same order, false otherwise.

Note that CBOR maps are unordered, which means that two maps containing the very same pairs but in different order will still compare differently. To avoid this, it is recommended to insert elements into the map in a predictable order, such as by ascending key value. In fact, maps with keys in sorted order are required for Canonical CBOR representation.

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

See also

compare() operator==() operator==() operator==() operator!=()

__ge__(rhs)
Parameters:

rhs – QCborValue

Return type:

bool

operator(key)
Parameters:

key – QLatin1String

Return type:

QCborValue

operator(key)
Parameters:

key – QCborValue

Return type:

QCborValue

Returns the QCborValue element in this map that corresponds to key key, if there is one.

If the map does not contain key key, this function returns a QCborValue containing 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 this function will return. 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.

operator[](qint64), operator[]( QLatin1StringView ), operator[](const QCborOperator[] &)

See also

value(const QCborValue &) find(const QCborValue &) constFind(const QCborValue &) remove(const QCborValue &) contains(const QCborValue &)

operator(key)
Parameters:

key – str

Return type:

QCborValue

This is an overloaded function.

Returns the QCborValue element in this map that corresponds to key key, if there is one.

If the map does not contain key key, this function returns a QCborValue containing 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 this function will return. 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.

operator[](qint64), operator[]( QLatin1StringView ), operator[](const QCborOperator[] &)

See also

value(const QString &) find(const QString &) constFind(const QString &) remove(const QString &) contains(const QString &)

operator(key)
Parameters:

key – int

Return type:

QCborValue

Returns the QCborValue element in this map that corresponds to key key, if there is one. CBOR recommends using integer keys, since they occupy less space and are simpler to encode and decode.

If the map does not contain key key, this function returns a QCborValue containing 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 this function will return. 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.

operator[]( QLatin1StringView ), operator[](const QString &), operator[](const QCborOperator[] &)

See also

value(qint64) find(qint64) constFind(qint64) remove(qint64) contains(qint64)

remove(key)
Parameters:

key – QLatin1String

remove(key)
Parameters:

key – QCborValue

Removes the key key and the corresponding value from the map, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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.

remove(qint64), remove( QLatin1StringView ), remove(const QString &)

See also

value(const QCborValue &) operator[](const QCborValue &) find(const QCborValue &) contains(const QCborValue &)

remove(key)
Parameters:

key – str

This is an overloaded function.

Removes the key key and the corresponding value from the map, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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.

remove(qint64), remove( QLatin1StringView ), remove(const QCborValue &)

See also

value(const QString &) operator[](const QString &) find(const QString &) contains(const QString &)

remove(key)
Parameters:

key – int

Removes the key key and the corresponding value from the map, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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.

remove( QLatin1StringView ), remove(const QString &), remove(const QCborValue &)

See also

value(qint64) operator[](qint64) find(qint64) contains(qint64)

size()
Return type:

int

Returns the number of elements in this map.

See also

isEmpty()

swap(other)
Parameters:

other – QCborMap

Swaps the contents of this map and other.

take(key)
Parameters:

key – QLatin1String

Return type:

QCborValue

take(key)
Parameters:

key – QCborValue

Return type:

QCborValue

Removes the key key and the corresponding value from the map and returns the value, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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 &) contains(const QCborValue &) take(QLatin1StringView) take(const QString &) take(qint64) insert()

take(key)
Parameters:

key – str

Return type:

QCborValue

Removes the key key and the corresponding value from the map and returns the value, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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 &) operator[](const QString &) find(const QString &) contains(const QString &) take(QLatin1StringView) take(qint64) take(const QCborValue &) insert()

take(key)
Parameters:

key – int

Return type:

QCborValue

Removes the key key and the corresponding value from the map and returns the value, if it is found. If the map contains no such key, this function does nothing.

If the map contains more than one key equal to key, it is undefined which one this function will remove. 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) operator[](qint64) find(qint64) contains(qint64) take(QLatin1StringView) take(const QString &) take(const QCborValue &) insert()

toCborValue()
Return type:

QCborValue

Explicitly constructs a QCborValue object that represents this map. This function is usually not necessary since QCborValue has a constructor for QCborMap , so the conversion is implicit.

Converting QCborMap to QCborValue allows it to be used in any context where QCborValues can be used, including as keys and mapped types in QCborMap , as well as toCbor() .

See also

QCborValue(const QCborMap &)

toJsonObject()
Return type:

QJsonObject

Recursively converts every QCborValue value in this map to JSON using 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 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:

Type

Transformation

Bool

“true” and “false”

Null

“null”

Undefined

“undefined”

Integer

The decimal string form of the number

Double

The decimal string form of the number

Byte array

Unless tagged differently (see above), encoded as Base64url

Array

Replaced by the compact form of its Diagnostic notation

Map

Replaced by the compact form of its Diagnostic notation

Tags and extended types

Tag number is dropped and the tagged value is converted to string

See also

fromJsonObject() toJsonValue() toJsonArray() toVariantMap()

toVariantHash()
Return type:

Dictionary with keys of type .QString and values of type QVariant.

Converts the CBOR values to QVariant using 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 toJsonObject() for details.

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

toVariantMap()
Return type:

Dictionary with keys of type .QString and values of type QVariant.

Converts the CBOR values to QVariant using 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 toJsonObject() for details.

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

value(key)
Parameters:

key – QLatin1String

Return type:

QCborValue

value(key)
Parameters:

key – QCborValue

Return type:

QCborValue

Returns the QCborValue element in this map that corresponds to key key, if there is one.

If the map does not contain key key, this function returns a QCborValue containing 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 this function will return. 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( QLatin1StringView ), value(const QString &)

See also

operator[](const QCborValue &) find(const QCborValue &) constFind(const QCborValue &) remove(const QCborValue &) contains(const QCborValue &)

value(key)
Parameters:

key – str

Return type:

QCborValue

This is an overloaded function.

Returns the QCborValue element in this map that corresponds to key key, if there is one.

If the map does not contain key key, this function returns a QCborValue containing 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 this function will return. 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( QLatin1StringView ), value(const QCborValue &)

See also

operator[](const QString &) find(const QString &) constFind(const QString &) remove(const QString &) contains(const QString &)

value(key)
Parameters:

key – int

Return type:

QCborValue

Returns the QCborValue element in this map that corresponds to key key, if there is one. CBOR recommends using integer keys, since they occupy less space and are simpler to encode and decode.

If the map does not contain key key, this function returns a QCborValue containing 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 from function 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.

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

See also

operator[](qint64) find(qint64) constFind(qint64) remove(qint64) contains(qint64)