diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc new file mode 100644 index 0000000000..dfceed55f2 --- /dev/null +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtserialization.html + \title Qt Serialization + \brief Serializations provided by Qt API + + The purpose of serialization is to save the state of an object to be able to + recreate it when needed. It allows you to perform actions like: + + \list + \li Sending the object to a remote application by using a web service + \li Passing the object as a JSON or XML string + \li Saving and restoring user information or sharing it across applications + \endlist + + The Qt API provides support for serialization for several use cases: + + \list + \li \l JSON support in Qt provides an easy to use C++ API to parse, modify + and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form + of binary data encoding that is a superset of JSON. + \li \l QDataStream provides serialization of binary data to a QIODevice + \li \l {Qt XML C++ Classes} provide C++ implementations of the \l XML Streaming + and DOM standards for XML + \li \l CBOR is Qt's implementation for the CBOR serialization format. + \li \l QSettings provides a way of serializing and storing platform independent + application settings. + \endlist + + \section1 Advantages of JSON and CBOR + + When you use \l JSON information is stored in a QJsonObject and a QJsonDocument + takes care to stream values into a QByteArray. + + For example + \code + QJsonObject jobject; + jobject["SensorID"] = m_id; + jobject["AmbientTemperature"] = m_ambientTemperature; + jobject["ObjectTemperature"] = m_objectTemperature; + jobject["AccelerometerX"] = m_accelerometerX; + jobject["AccelerometerY"] = m_accelerometerY; + jobject["AccelerometerZ"] = m_accelerometerZ; + jobject["Altitude"] = m_altitude; + jobject["Light"] = m_light; + jobject["Humidity"] = m_humidity; + QJsonDocument doc( jobject ); + + return doc.toJson(); + \endcode + + JSON has several advantages: + + \list + \li Textual JSON is declarative, which makes it readable to humans + \li The information is structured + \li Exchanging generic information is easy + \li JSON allows extending messages with additional values + \li Many solutions exist to receive and parse JSON in cloud-based solutions + \endlist + + \l 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 been used in many new + RFCs. CBOR shares many of the advantages of JSON, but sacrifices human + readability for compactness. + + \section1 Advantages of QDataStream Classes + + \l QDataStream is a viable option when the whole flow of data is determined + and not about to change. In addition, both the reader and the writer of the + data must be written in Qt. + + Adding support for this to a class requires two additional operators. + For example, for a class named SensorInformation: + + \code + QDataStream &operator<<(QDataStream &, const SensorInformation &); + QDataStream &operator>>(QDataStream &, SensorInformation &); + \endcode + + The implementation for the serialization is shown below: + + \code + QDataStream &operator<<(QDataStream &out, const SensorInformation &item) + { + QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision(); + out.setFloatingPointPrecision(QDataStream::DoublePrecision); + out << item.m_id + << item.m_ambientTemperature + << item.m_objectTemperature + << item.m_accelerometerX + << item.m_accelerometerY + << item.m_accelerometerZ + << item.m_altitude + << item.m_light + << item.m_humidity; + out.setFloatingPointPrecision(prev); + return out; + } + \endcode + + Deserialization works similarly, but using the \c {>>} operator. + For example, \c {out >> item.m_id}, and so on. + + Usually, using QDataStream is faster than using textual JSON. + + \section1 Advantages of Qt XML C++ Classes + + Qt provides the QDomDocument class that represents the XML document and + two classes for reading and writing the XML through a simple streaming API: + QXmlStreamReader and QXmlStreamWriter. + + QDomDocument class represents the entire XML document. It is the root of the + document tree and provides primary access to the document's data. + + A stream reader reports an XML document as a stream of tokens. This differs + from SAX as SAX applications provide handlers to receive XML events from the + parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the + reader when they are needed. This pulling approach makes it possible to build + recursive descent parsers, allowing XML parsing code to be split into + different methods or classes. + + QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed + entities. Hence, data provided to the stream reader adheres to the + W3C's criteria for well-formed XML, or an error will be raised. Functions + such as \c atEnd(), \c error(), and \c hasError() can be used to test for + such errors and obtain a description of them. + + The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, + when the namespaceUri is specified when writing elements or attributes. + + \section1 Classes that provide serialization + + \annotatedlist qtserialization +*/ diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp index 95fd47b767..dc373533c5 100644 --- a/src/corelib/serialization/qcborarray.cpp +++ b/src/corelib/serialization/qcborarray.cpp @@ -13,6 +13,7 @@ using namespace QtCbor; \class QCborArray \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp index 844bcef4af..66d6dcd685 100644 --- a/src/corelib/serialization/qcborcommon.cpp +++ b/src/corelib/serialization/qcborcommon.cpp @@ -17,6 +17,7 @@ QT_IMPL_METATYPE_EXTERN(QCborTag) /*! \headerfile \inmodule QtCore + \ingroup qtserialization \brief The header contains definitions common to both the streaming classes (QCborStreamReader and QCborStreamWriter) and to QCborValue. diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index c8895cb42a..3b16c309b0 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -12,6 +12,7 @@ using namespace QtCbor; \class QCborMap \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp index 86fb1f0d7e..887bcdd6b0 100644 --- a/src/corelib/serialization/qcborstreamreader.cpp +++ b/src/corelib/serialization/qcborstreamreader.cpp @@ -60,6 +60,7 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType); \class QCborStreamReader \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp index a2ddc15161..e798da7e52 100644 --- a/src/corelib/serialization/qcborstreamwriter.cpp +++ b/src/corelib/serialization/qcborstreamwriter.cpp @@ -43,6 +43,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE); \class QCborStreamWriter \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index 1cb351906c..e9b351166f 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -44,6 +44,7 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount = \class QCborValue \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qdatastream.cpp b/src/corelib/serialization/qdatastream.cpp index 34f8f7b5ff..ef404250b7 100644 --- a/src/corelib/serialization/qdatastream.cpp +++ b/src/corelib/serialization/qdatastream.cpp @@ -18,6 +18,7 @@ QT_BEGIN_NAMESPACE /*! \class QDataStream \inmodule QtCore + \ingroup qtserialization \reentrant \brief The QDataStream class provides serialization of binary data to a QIODevice. diff --git a/src/corelib/serialization/qjsonarray.cpp b/src/corelib/serialization/qjsonarray.cpp index 01899aaf95..96947cf2d0 100644 --- a/src/corelib/serialization/qjsonarray.cpp +++ b/src/corelib/serialization/qjsonarray.cpp @@ -22,6 +22,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsondocument.cpp b/src/corelib/serialization/qjsondocument.cpp index 01df13d097..1ba4b5952c 100644 --- a/src/corelib/serialization/qjsondocument.cpp +++ b/src/corelib/serialization/qjsondocument.cpp @@ -24,6 +24,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonobject.cpp b/src/corelib/serialization/qjsonobject.cpp index ab482876af..d4f702e46e 100644 --- a/src/corelib/serialization/qjsonobject.cpp +++ b/src/corelib/serialization/qjsonobject.cpp @@ -25,6 +25,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonparser.cpp b/src/corelib/serialization/qjsonparser.cpp index acc2bc383f..b11ae3a9d2 100644 --- a/src/corelib/serialization/qjsonparser.cpp +++ b/src/corelib/serialization/qjsonparser.cpp @@ -50,6 +50,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonvalue.cpp b/src/corelib/serialization/qjsonvalue.cpp index 49fc0d85d1..cc15f412f4 100644 --- a/src/corelib/serialization/qjsonvalue.cpp +++ b/src/corelib/serialization/qjsonvalue.cpp @@ -53,6 +53,7 @@ static QJsonValue::Type convertFromCborType(QCborValue::Type type) noexcept \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qtextstream.cpp b/src/corelib/serialization/qtextstream.cpp index 2a2536aeee..a268002dc6 100644 --- a/src/corelib/serialization/qtextstream.cpp +++ b/src/corelib/serialization/qtextstream.cpp @@ -14,6 +14,7 @@ static const int QTEXTSTREAM_BUFFERSIZE = 16384; \ingroup io \ingroup string-processing + \ingroup qtserialization \reentrant QTextStream can operate on a QIODevice, a QByteArray or a diff --git a/src/corelib/serialization/qxmlstream.cpp b/src/corelib/serialization/qxmlstream.cpp index 80eed02b11..ed34c3e0d6 100644 --- a/src/corelib/serialization/qxmlstream.cpp +++ b/src/corelib/serialization/qxmlstream.cpp @@ -231,6 +231,8 @@ QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const \ingroup xml-tools + \ingroup qtserialization + QXmlStreamReader provides a simple streaming API to parse well-formed XML. It is an alternative to first loading the complete XML into a DOM tree (see \l QDomDocument). QXmlStreamReader reads data either @@ -2728,6 +2730,7 @@ QStringView QXmlStreamReader::documentEncoding() const simple streaming API. \ingroup xml-tools + \ingroup qtserialization QXmlStreamWriter is the counterpart to QXmlStreamReader for writing XML. Like its related class, it operates on a QIODevice specified