diff options
author | Øystein Heskestad <oystein.heskestad@qt.io> | 2022-08-24 17:54:37 +0200 |
---|---|---|
committer | Øystein Heskestad <oystein.heskestad@qt.io> | 2022-09-02 08:38:11 +0000 |
commit | 192df6ef4772535b110957eb684da72237f9a510 (patch) | |
tree | 164cd08d77cc3e794919127e3422179b5b7c1ce8 /src | |
parent | 255234136c678f26b348f0c9cfeaebd9e20d5411 (diff) |
Add CBOR documentation
Add documentation of usage of CBOR in convert and cbordump examples,
add a CBOR overview, and add links to them other places in the
documentation.
Task-number: QTBUG-85912
Change-Id: I518792db63647bf9ddd4507d8d4b7ef056192f82
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
(cherry picked from commit 855a9ca217ad3b9d8eb8f6544698a174323843fc)
Reviewed-by: Ievgenii Meshcheriakov <ievgenii.meshcheriakov@qt.io>
Diffstat (limited to 'src')
-rw-r--r-- | src/corelib/doc/src/cbor.qdoc | 78 | ||||
-rw-r--r-- | src/corelib/doc/src/datastreamformat.qdoc | 3 | ||||
-rw-r--r-- | src/corelib/doc/src/qtcore-index.qdoc | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcborarray.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborcommon.cpp | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcbormap.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborstreamreader.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborstreamwriter.cpp | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcborvalue.cpp | 3 |
9 files changed, 91 insertions, 5 deletions
diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc new file mode 100644 index 0000000000..22252bbd88 --- /dev/null +++ b/src/corelib/doc/src/cbor.qdoc @@ -0,0 +1,78 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group cbor + \title CBOR Support in Qt + \ingroup qt-basic-concepts + \brief An overview of CBOR support in Qt. + + \ingroup frameworks-technologies + + \keyword CBOR + + Qt provides support for dealing with CBOR data. CBOR is a binary format to + store data that has a superset of the types available in JSON, but is more + compact. + + The CBOR support in Qt provides an easy to use C++ API to parse, + modify and save CBOR data. + + More details about the CBOR data format can be found in \l {RFC 7049}. + + \tableofcontents + + \section1 Overview + + CBOR is a format to store structured data. It has three groups of built-in types: + + \list + \li Basic types: integers, floating point, boolean, null, etc. + \li String-like types: strings and byte arrays + \li Containers: arrays and maps + \endlist + + In addition, CBOR can add a "tag" to extend the meaning of the type. The + container types can contain basic types, string-like types and containers. + + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} + + \section1 The CBOR Classes + + \section2 The QCborValue Class + + The QCborValue class represents any CBOR type. It also has a simple API for + reading and writing to QCborStreamReader and QCborStreamWriter objects, as + well as manipulating such objects in memory, with the help of QCborArray + and QCborMap. The CborValue API is simplified from the full CBOR data type + and always represents all integers as \l qint64 and all floating-point as + \c double. This means QCborValue is unable to represent CBOR integer values + outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR + stream, QCborValue::toCbor() can be configured to attempt to write the + shorter single- and half-precision floating-point representations. + + \section2 The QCborArray Class + + The QCborArray class is used to hold an array of QCborValue objects. A + QCborValue object can contain a QCborArray object. It has functions for + converting to and from QVariantList, QStringList, QJsonArray. + + \section2 The QCborMap Class + + The QCborMap class is used to hold an map of QCborValue objects. A + QCborValue object can contain a QCborMap object. It has functions for + converting to and from QVariantMap, QVariantMap, and QJsonObject, but it + can have keys of any type, not just QString. + + \section2 The QCborStreamReader Class + + The QCborStreamReader class is a low level API for reading CBOR data from a + QIODevice, a QByteArray, or a pointer to memory. It has an API similar to + the QXmlStreamReader class. + + \section2 The QCborStreamWriter Class + + The QCborStreamWriter class is a low level API for writing CBOR data to a + QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter + class. +*/ diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index c3e57a9adf..60ea1aa495 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -67,5 +67,6 @@ \li QVector4D \endlist - \sa {JSON Support in Qt} + \sa {JSON Support in Qt}, {CBOR Support in Qt} + */ diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc index 377e199784..99cc114d64 100644 --- a/src/corelib/doc/src/qtcore-index.qdoc +++ b/src/corelib/doc/src/qtcore-index.qdoc @@ -75,6 +75,7 @@ \list \li \l{The Animation Framework} \li \l{JSON Support in Qt} + \li \l{CBOR Support in Qt} \li \l{How to Create Qt Plugins} \li \l{The Event System} \endlist diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp index e9d31b4cc3..91644fe2ea 100644 --- a/src/corelib/serialization/qcborarray.cpp +++ b/src/corelib/serialization/qcborarray.cpp @@ -30,7 +30,8 @@ using namespace QtCbor; from those two, though there may be loss of information in some conversions. - \sa QCborValue, QCborMap, QJsonArray, QList + \sa QCborValue, QCborMap, QJsonArray, QList, {Cbordump Example}, + {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp index 648ca59d8b..9168b8c520 100644 --- a/src/corelib/serialization/qcborcommon.cpp +++ b/src/corelib/serialization/qcborcommon.cpp @@ -179,6 +179,7 @@ QDataStream &operator>>(QDataStream &ds, QCborSimpleType &st) validating a CBOR stream. \sa QCborStreamReader, QCborValue, QCborParserError + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index 050565d5ae..dcb4299027 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -46,7 +46,8 @@ 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, {Cbordump Example} + \sa {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp index 10b3eb2d45..65edd3a941 100644 --- a/src/corelib/serialization/qcborstreamreader.cpp +++ b/src/corelib/serialization/qcborstreamreader.cpp @@ -151,7 +151,8 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType); parsing from a QByteArray, or reparse(), if it is instead reading directly a the QIDOevice that now has more data available (see setDevice()). - \sa QCborStreamWriter, QCborValue, QXmlStreamReader + \sa QCborStreamWriter, QCborValue, QXmlStreamReader, {Cbordump Example} + \sa {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp index 9f7e30e8cb..0e445451bc 100644 --- a/src/corelib/serialization/qcborstreamwriter.cpp +++ b/src/corelib/serialization/qcborstreamwriter.cpp @@ -175,6 +175,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE); \endlist \sa QCborStreamReader, QCborValue, QXmlStreamWriter + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} */ class QCborStreamWriterPrivate diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index 056e8c07b6..59a8007b81 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -189,7 +189,8 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount = aspects, its API is identical to QCborValue. \sa QCborArray, QCborMap, QCborStreamReader, QCborStreamWriter - QJsonValue, QJsonDocument + \sa QJsonValue, QJsonDocument, {Cbordump Example}, {Convert Example} + \sa {JSON Save Game Example} */ /*! |