diff options
Diffstat (limited to 'src/corelib/serialization/qcbormap.cpp')
| -rw-r--r-- | src/corelib/serialization/qcbormap.cpp | 196 |
1 files changed, 132 insertions, 64 deletions
diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index 050565d5ae..038e0d61ce 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -12,11 +12,16 @@ using namespace QtCbor; \class QCborMap \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 \brief The QCborMap class is used to hold an associative container representable in CBOR. + \compares strong + \compareswith strong QCborValue QCborValueConstRef + \endcompareswith + 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 @@ -46,7 +51,9 @@ using namespace QtCbor; stringified using a one-way method that the conversion back to QCborMap will not undo. - \sa QCborArray, QCborValue, QJsonDocument, QVariantMap + \sa QCborArray, QCborValue, QJsonDocument, QVariantMap, + {Parsing and displaying CBOR data}, {Serialization Converter}, + {Saving and Loading a Game} */ /*! @@ -1102,10 +1109,10 @@ QCborValue QCborMap::extract(iterator it) */ /*! - \fn bool QCborMap::operator==(const QCborMap &other) const + \fn bool QCborMap::operator==(const QCborMap &lhs, const QCborMap &rhs) - Compares this map and \a other, comparing each element in sequence, and - returns true if the two maps contains the same elements in the same order, + Compares \a lhs and \a 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 @@ -1121,10 +1128,10 @@ QCborValue QCborMap::extract(iterator it) */ /*! - \fn bool QCborMap::operator!=(const QCborMap &other) const + \fn bool QCborMap::operator!=(const QCborMap &lhs, const QCborMap &rhs) - Compares this map and \a other, comparing each element in sequence, and - returns true if the two maps contains any different elements or elements in + Compares \a lhs and \a 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 @@ -1140,10 +1147,10 @@ QCborValue QCborMap::extract(iterator it) */ /*! - \fn bool QCborMap::operator<(const QCborMap &other) const + \fn bool QCborMap::operator<(const QCborMap &lhs, const QCborMap &rhs) - Compares this map and \a other, comparing each element in sequence, and - returns true if this map should be sorted before \a other, false + Compares \a lhs and \a rhs maps, comparing each element in sequence, and + returns true if \a lhs map should be sorted before \a rhs, false otherwise. Note that CBOR maps are unordered, which means that two maps containing the @@ -1158,6 +1165,65 @@ QCborValue QCborMap::extract(iterator it) operator==(), operator!=() */ +/*! + \fn bool QCborMap::operator<=(const QCborMap &lhs, const QCborMap &rhs) + + Compares \a lhs and \a rhs maps, comparing each element in sequence, and + returns true if \a lhs map should be sorted before \a 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 QCborValue::compare(). + + \sa compare(), QCborValue::operator==(), QCborMap::operator==(), + operator==(), operator!=() +*/ + +/*! + \fn bool QCborMap::operator>=(const QCborMap &lhs, const QCborMap &rhs) + + Compares \a lhs and \a rhs maps, comparing each element in sequence, and + returns true if \a lhs map should be sorted after \a 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 QCborValue::compare(). + + \sa compare(), QCborValue::operator==(), QCborMap::operator==(), + operator==(), operator!=() +*/ + +/*! + \fn bool QCborMap::operator>(const QCborMap &lhs, const QCborMap &rhs) + + Compares \a lhs and \a rhs maps, comparing each element in sequence, and + returns true if \a lhs map should be sorted after \a 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 QCborValue::compare(). + + \sa compare(), QCborValue::operator==(), QCborMap::operator==(), + operator==(), operator!=() +*/ + void QCborMap::detach(qsizetype reserved) { d = QCborContainerPrivate::detach(d.data(), reserved ? reserved : size() * 2); @@ -1172,6 +1238,10 @@ void QCborMap::detach(qsizetype reserved) \brief The QCborMap::Iterator class provides an STL-style non-const iterator for QCborMap. + \compares strong + \compareswith strong ConstIterator + \endcompareswith + QCborMap::Iterator allows you to iterate over a QCborMap and to modify the value (but not the key) stored under a particular key. If you want to iterate over a const QCborMap, you should use QCborMap::ConstIterator. It @@ -1293,63 +1363,63 @@ void QCborMap::detach(qsizetype reserved) */ /*! - \fn bool QCborMap::Iterator::operator==(const Iterator &other) const - \fn bool QCborMap::Iterator::operator==(const ConstIterator &other) const + \fn bool QCborMap::Iterator::operator==(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator==(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if \a other points to the same entry in the map as this + Returns \c true if \a lhs points to the same entry in the map as \a rhs iterator; otherwise returns \c false. \sa operator!=() */ /*! - \fn bool QCborMap::Iterator::operator!=(const Iterator &other) const - \fn bool QCborMap::Iterator::operator!=(const ConstIterator &other) const + \fn bool QCborMap::Iterator::operator!=(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator!=(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if \a other points to a different entry in the map than - this iterator; otherwise returns \c false. + Returns \c true if \a lhs points to a different entry in the map than + \a rhs iterator; otherwise returns \c false. \sa operator==() */ /*! - \fn bool QCborMap::Iterator::operator<(const Iterator& other) const - \fn bool QCborMap::Iterator::operator<(const ConstIterator& other) const + \fn bool QCborMap::Iterator::operator<(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator<(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs before the entry pointed to by the \a other iterator. + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs before the entry pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::Iterator::operator<=(const Iterator& other) const - \fn bool QCborMap::Iterator::operator<=(const ConstIterator& other) const + \fn bool QCborMap::Iterator::operator<=(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator<=(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs before or is the same entry as is pointed to by the \a other + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs before or is the same entry as is pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::Iterator::operator>(const Iterator& other) const - \fn bool QCborMap::Iterator::operator>(const ConstIterator& other) const + \fn bool QCborMap::Iterator::operator>(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator>(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs after the entry pointed to by the \a other iterator. + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs after the entry pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::Iterator::operator>=(const Iterator& other) const - \fn bool QCborMap::Iterator::operator>=(const ConstIterator& other) const + \fn bool QCborMap::Iterator::operator>=(const Iterator &lhs, const Iterator &rhs) + \fn bool QCborMap::Iterator::operator>=(const Iterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs after or is the same entry as is pointed to by the \a other + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs after or is the same entry as is pointed to by the \a rhs iterator. */ /*! \fn QCborMap::Iterator &QCborMap::Iterator::operator++() - The prefix ++ operator, \c{++i}, advances the iterator to the next item in + The prefix \c{++} operator, \c{++i}, advances the iterator to the next item in the map and returns this iterator. Calling this function on QCborMap::end() leads to undefined results. @@ -1361,14 +1431,14 @@ void QCborMap::detach(qsizetype reserved) \fn QCborMap::Iterator QCborMap::Iterator::operator++(int) \overload - The postfix ++ operator, \c{i++}, advances the iterator to the next item in + The postfix \c{++} operator, \c{i++}, advances the iterator to the next item in the map and returns an iterator to the previously current item. */ /*! \fn QCborMap::Iterator QCborMap::Iterator::operator--() - The prefix -- operator, \c{--i}, makes the preceding item current and + The prefix \c{--} operator, \c{--i}, makes the preceding item current and returns this iterator. Calling this function on QCborMap::begin() leads to undefined results. @@ -1380,7 +1450,7 @@ void QCborMap::detach(qsizetype reserved) \fn QCborMap::Iterator QCborMap::Iterator::operator--(int) \overload - The postfix -- operator, \c{i--}, makes the preceding item current and + The postfix \c{--} operator, \c{i--}, makes the preceding item current and returns an iterator pointing to the previously current item. */ @@ -1438,6 +1508,10 @@ void QCborMap::detach(qsizetype reserved) \brief The QCborMap::ConstIterator class provides an STL-style const iterator for QCborMap. + \compares strong + \compareswith strong Iterator + \endcompareswith + QCborMap::ConstIterator allows you to iterate over a QCborMap. If you want to modify the QCborMap as you iterate over it, you must use QCborMap::Iterator instead. It is generally good practice to use @@ -1538,63 +1612,57 @@ void QCborMap::detach(qsizetype reserved) */ /*! - \fn bool QCborMap::ConstIterator::operator==(const ConstIterator &other) const - \fn bool QCborMap::ConstIterator::operator==(const Iterator &other) const + \fn bool QCborMap::ConstIterator::operator==(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if \a other points to the same entry in the map as this + Returns \c true if \a lhs points to the same entry in the map as \a rhs iterator; otherwise returns \c false. \sa operator!=() */ /*! - \fn bool QCborMap::ConstIterator::operator!=(const ConstIterator &other) const - \fn bool QCborMap::ConstIterator::operator!=(const Iterator &other) const + \fn bool QCborMap::ConstIterator::operator!=(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if \a other points to a different entry in the map than - this iterator; otherwise returns \c false. + Returns \c true if \a lhs points to a different entry in the map than + \a rhs iterator; otherwise returns \c false. \sa operator==() */ /*! - \fn bool QCborMap::ConstIterator::operator<(const Iterator &other) const - \fn bool QCborMap::ConstIterator::operator<(const ConstIterator &other) const + \fn bool QCborMap::ConstIterator::operator<(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs before the entry pointed to by the \a other iterator. + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs before the entry pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::ConstIterator::operator<=(const Iterator &other) const - \fn bool QCborMap::ConstIterator::operator<=(const ConstIterator &other) const + \fn bool QCborMap::ConstIterator::operator<=(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs before or is the same entry as is pointed to by the \a other + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs before or is the same entry as is pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::ConstIterator::operator>(const Iterator &other) const - \fn bool QCborMap::ConstIterator::operator>(const ConstIterator &other) const + \fn bool QCborMap::ConstIterator::operator>(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs after the entry pointed to by the \a other iterator. + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs after the entry pointed to by the \a rhs iterator. */ /*! - \fn bool QCborMap::ConstIterator::operator>=(const Iterator &other) const - \fn bool QCborMap::ConstIterator::operator>=(const ConstIterator &other) const + \fn bool QCborMap::ConstIterator::operator>=(const ConstIterator &lhs, const ConstIterator &rhs) - Returns \c true if the entry in the map pointed to by this iterator - occurs after or is the same entry as is pointed to by the \a other + Returns \c true if the entry in the map pointed to by \a lhs iterator + occurs after or is the same entry as is pointed to by the \a rhs iterator. */ /*! \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator++() - The prefix ++ operator, \c{++i}, advances the iterator to the next item in + The prefix \c{++} operator, \c{++i}, advances the iterator to the next item in the map and returns this iterator. Calling this function on QCborMap::end() leads to undefined results. @@ -1606,14 +1674,14 @@ void QCborMap::detach(qsizetype reserved) \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator++(int) \overload - The postfix ++ operator, \c{i++}, advances the iterator to the next item in + The postfix \c{++} operator, \c{i++}, advances the iterator to the next item in the map and returns an iterator to the previously current item. */ /*! \fn QCborMap::ConstIterator &QCborMap::ConstIterator::operator--() - The prefix -- operator, \c{--i}, makes the preceding item current and + The prefix \c{--} operator, \c{--i}, makes the preceding item current and returns this iterator. Calling this function on QCborMap::begin() leads to undefined results. @@ -1625,7 +1693,7 @@ void QCborMap::detach(qsizetype reserved) \fn QCborMap::ConstIterator QCborMap::ConstIterator::operator--(int) \overload - The postfix -- operator, \c{i--}, makes the preceding item current and + The postfix \c{--} operator, \c{i--}, makes the preceding item current and returns an iterator pointing to the previously current item. */ |