From 67030038f3f07b3edb61eb56aa0c62bac67a7bf5 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Tue, 26 Dec 2017 10:18:49 -0200 Subject: Doc: explain how QXmlStream{Reader,Writer} deal with encoding in QString QXmlStreamWriter does not: it just writes the QString inputs to the output. QXmlStreamReader does: it first converts the QString to UTF-8 and stores locally. Then it tries to decode using the XML encoding header. Change-Id: I39332e0a867442d58082fffd1503d7652cb9fbff Reviewed-by: Martin Smith --- src/corelib/serialization/qxmlstream.cpp | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'src/corelib/serialization/qxmlstream.cpp') diff --git a/src/corelib/serialization/qxmlstream.cpp b/src/corelib/serialization/qxmlstream.cpp index 9b5295a17e..a92dd71df5 100644 --- a/src/corelib/serialization/qxmlstream.cpp +++ b/src/corelib/serialization/qxmlstream.cpp @@ -409,6 +409,11 @@ QXmlStreamReader::QXmlStreamReader(const QByteArray &data) /*! Creates a new stream reader that reads from \a data. + This function should only be used if the XML header either says the encoding + is "UTF-8" or lacks any encoding information (the latter is the case of + QXmlStreamWriter writing to a QString). Any other encoding is likely going to + cause data corruption ("mojibake"). + \sa addData(), clear(), setDevice() */ QXmlStreamReader::QXmlStreamReader(const QString &data) @@ -3268,6 +3273,9 @@ QXmlStreamWriter::QXmlStreamWriter(QByteArray *array) /*! Constructs a stream writer that writes into \a string. + * + * Note that when writing to QString, QXmlStreamWriter ignores the codec set + * with setCodec(). See that function for more information. */ QXmlStreamWriter::QXmlStreamWriter(QString *string) : d_ptr(new QXmlStreamWriterPrivate(this)) @@ -3326,6 +3334,12 @@ QIODevice *QXmlStreamWriter::device() const gets written when you call writeStartDocument(). Call this function before calling writeStartDocument(). + \note When writing the XML to a QString, the codec information is ignored + and the XML header will not include any encoding information, since all + QStrings are UTF-16. If you later convert the QString to an 8-bit format, + you must arrange for the encoding information to be transmitted + out-of-band. + \sa codec() */ void QXmlStreamWriter::setCodec(QTextCodec *codec) @@ -3345,6 +3359,12 @@ void QXmlStreamWriter::setCodec(QTextCodec *codec) "ISO 8859-1", "UTF-8", and "UTF-16". If the encoding isn't recognized, nothing happens. + \note When writing the XML to a QString, the codec information is ignored + and the XML header will not include any encoding information, since all + QStrings are UTF-16. If you later convert the QString to an 8-bit format, + you must arrange for the encoding information to be transmitted + out-of-band. + \sa QTextCodec::codecForName() */ void QXmlStreamWriter::setCodec(const char *codecName) -- cgit v1.2.3