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-01 19:03:00 +0200 |
commit | 855a9ca217ad3b9d8eb8f6544698a174323843fc (patch) | |
tree | 7694c33d990df202896f0b8bbaa766da1daef11a /examples/corelib/serialization/convert | |
parent | 2e8c84cda25de38d64669a9d078d87c7d2bf451c (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>
Diffstat (limited to 'examples/corelib/serialization/convert')
-rw-r--r-- | examples/corelib/serialization/convert/cborconverter.cpp | 14 | ||||
-rw-r--r-- | examples/corelib/serialization/convert/doc/images/convert.png | bin | 0 -> 49201 bytes | |||
-rw-r--r-- | examples/corelib/serialization/convert/doc/src/convert.qdoc | 80 |
3 files changed, 90 insertions, 4 deletions
diff --git a/examples/corelib/serialization/convert/cborconverter.cpp b/examples/corelib/serialization/convert/cborconverter.cpp index 0f49de2551..8c88d42af3 100644 --- a/examples/corelib/serialization/convert/cborconverter.cpp +++ b/examples/corelib/serialization/convert/cborconverter.cpp @@ -57,6 +57,7 @@ QT_END_NAMESPACE static QVariant convertCborValue(const QCborValue &value); +//! [0] static QVariant convertCborMap(const QCborMap &map) { VariantOrderedMap result; @@ -83,8 +84,9 @@ static QVariant convertCborValue(const QCborValue &value) return convertCborMap(value.toMap()); return value.toVariant(); } - +//! [0] enum TrimFloatingPoint { Double, Float, Float16 }; +//! [1] static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrimming) { if (v.userType() == QMetaType::QVariantList) { @@ -114,6 +116,7 @@ static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrim return QCborValue::fromVariant(v); } +//! [1] QString CborDiagnosticDumper::name() { @@ -216,6 +219,7 @@ bool CborConverter::probeFile(QIODevice *f) return f->isReadable() && f->peek(3) == QByteArray("\xd9\xd9\xf7", 3); } +//! [2] QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter) { const char *ptr = nullptr; @@ -250,9 +254,11 @@ QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter) return contents.toVariant(); return convertCborValue(contents); } - +//! [2] +//! [3] void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStringList &options) { + //! [3] bool useSignature = true; bool useIntegers = true; enum { Yes, No, Always } useFloat16 = Yes, useFloat = Yes; @@ -311,7 +317,7 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri qPrintable(s), optionHelp); exit(EXIT_FAILURE); } - + //! [4] QCborValue v = convertFromVariant(contents, useFloat16 == Always ? Float16 : useFloat == Always ? Float : Double); QCborStreamWriter writer(f); @@ -327,4 +333,4 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri opts |= QCborValue::UseFloat16; v.toCbor(writer, opts); } - +//! [4] diff --git a/examples/corelib/serialization/convert/doc/images/convert.png b/examples/corelib/serialization/convert/doc/images/convert.png Binary files differnew file mode 100644 index 0000000000..8d6816a626 --- /dev/null +++ b/examples/corelib/serialization/convert/doc/images/convert.png diff --git a/examples/corelib/serialization/convert/doc/src/convert.qdoc b/examples/corelib/serialization/convert/doc/src/convert.qdoc new file mode 100644 index 0000000000..dc3264a469 --- /dev/null +++ b/examples/corelib/serialization/convert/doc/src/convert.qdoc @@ -0,0 +1,80 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example serialization/convert + \title Convert Example + + \brief The Convert example demonstrates how to convert between different + serialization formats. + + The Convert example converts between the serialization formats JSON, CBOR, + XML, QDataStream and text. It can also auto detect the format being used. + Not all formats support both input and output, and they have different + sets of which types they support. QDataStream and XML are the richest, + followed by CBOR, then JSON, and then the plain text one. + + \image convert.png + + \section1 The Converter Class + + The Converter class is the abstract superclass for all the converters to + and from all the formats. They all convert to and from the QVariant class, + which is used to represent all the datastructures internally. + The name() function returns the name of the converter. The directions() + function is used to determine if a converter can be used for input, output, + or both. The outputOptions() and optionsHelp() functions are used to get + and query which options are used by the different converters. The + probeFile() function is used to determine if a file has the same file + format as the converter. The loadFile() function deserializes the given + file, while the saveFile() serializes to the given file. + + \section1 The CborConverter Class + + The CborConverter class shows how to serialize to and from the CBOR-format. + There is also a CborDiagnosticDumper class to output in CBOR diagnostic + notation. That is similar to JSON, but not exactly, because it allows + displaying the contents of a CBOR stream losslessly, while a conversion + to JSON is lossy. + + The convertCborValue() function is used to convert a QCborValue to a + QVariant. It uses the helper functions convertCborMap() and + convertCborArray(). + \snippet serialization/convert/cborconverter.cpp 0 + + A CBOR-file is read using loadFile() function. + \snippet serialization/convert/cborconverter.cpp 2 + + The convertFromVariant() function is used to convert a QVariant to a + QCborValue. + \snippet serialization/convert/cborconverter.cpp 1 + + A CBOR-file is written using the saveFile() function. + \snippet serialization/convert/cborconverter.cpp 3 + \snippet serialization/convert/cborconverter.cpp 4 + + \sa {CBOR Support in Qt} + + \section1 The DataStreamConverter Class + + The DataStreamConverter class is used to serialize to and from the + QDataStream format. There is also the DataStreamDumper class for outputting + the data lossless in a non-standardized human readable format. + + \section1 The JsonConverter Class + + The JsonConverter class is used to serialize to and from the JSON-format. + \sa {JSON Support in Qt} + + \section1 The XmlConverter Class + + The XmlConverter class is used to serialize to and from the XML-format. + + \section1 The TextConverter Class + + The TextConverter class is used to serialize to and from a text format. + + \section1 The NullConverter Class + + The NullConverter class is an output serializer that does nothing. +*/ |