From f549916d18540f3fcf72cc51a09197738bda5c03 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Tue, 21 Jul 2015 09:40:07 -0700 Subject: Doc: update QDebug documentation to talk about the escaping Task-number: QTBUG-47316 Change-Id: Ib306f8f647014b399b87ffff13f303badb2a7a63 Reviewed-by: Martin Smith Reviewed-by: Lars Knoll --- src/corelib/io/qdebug.cpp | 103 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 95 insertions(+), 8 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp index 8eeac26d3b..30086b2dac 100644 --- a/src/corelib/io/qdebug.cpp +++ b/src/corelib/io/qdebug.cpp @@ -425,6 +425,9 @@ QDebug &QDebug::resetFormat() Disables automatic insertion of quotation characters around QChar, QString and QByteArray contents and returns a reference to the stream. + When quoting is disabled, these types are printed without quotation + characters and without escaping of non-printable characters. + \sa quote(), maybeQuote() */ @@ -444,7 +447,11 @@ QDebug &QDebug::resetFormat() \fn QDebug &QDebug::operator<<(QChar t) Writes the character, \a t, to the stream and returns a reference to the - stream. + stream. Normally, QDebug prints control characters and non-US-ASCII + characters as their C escape sequences or their Unicode value (\\u1234). To + print non-printable characters without transformation, enable the noquote() + functionality, but note that some QDebug backends may not be 8-bit clean + and may not be able to represent \c t. */ /*! @@ -535,34 +542,114 @@ QDebug &QDebug::resetFormat() \fn QDebug &QDebug::operator<<(const char *s) Writes the '\\0'-terminated string, \a s, to the stream and returns a - reference to the stream. + reference to the stream. The string is never quoted nor transformed to the + output, but note that some QDebug backends might not be 8-bit clean. */ /*! \fn QDebug &QDebug::operator<<(const QString &s) - Writes the string, \a s, to the stream and returns a reference to the stream. + Writes the string, \a s, to the stream and returns a reference to the + stream. Normally, QDebug prints the string inside quotes and transforms + non-printable characters to their Unicode values (\\u1234). + + To print non-printable characters without transformation, enable the + noquote() functionality. Note that some QDebug backends might not be 8-bit + clean. + + Output examples: + \code + QString s; + + s = "a"; + qDebug().noquote() << s; // prints: a + qDebug() << s; // prints: "a" + + s = "\"a\r\n\""; + qDebug() << s; // prints: "\"a\r\n\"" + + s = "\033"; // escape character + qDebug() << s; // prints: "\u001B" + + s = "\u00AD"; // SOFT HYPHEN + qDebug() << s; // prints: "\u00AD" + + s = "\u00E1"; // LATIN SMALL LETTER A WITH ACUTE + qDebug() << s; // prints: "á" + + s = "a\u0301"; // "a" followed by COMBINING ACUTE ACCENT + qDebug() << s; // prints: "á"; + + s = "\u0430\u0301"; // CYRILLIC SMALL LETTER A followed by COMBINING ACUTE ACCENT + qDebug() << s; // prints: "а́" + \endcode */ /*! \fn QDebug &QDebug::operator<<(const QStringRef &s) - Writes the string reference, \a s, to the stream and returns a reference to - the stream. + Writes the string, \a s, to the stream and returns a reference to the + stream. Normally, QDebug prints the string inside quotes and transforms + non-printable characters to their Unicode values (\\u1234). + + To print non-printable characters without transformation, enable the + noquote() functionality. Note that some QDebug backends might not be 8-bit + clean. + + See the QString overload for examples. */ /*! \fn QDebug &QDebug::operator<<(QLatin1String s) - Writes the Latin1-encoded string, \a s, to the stream and returns a reference - to the stream. + Writes the string, \a s, to the stream and returns a reference to the + stream. Normally, QDebug prints the string inside quotes and transforms + non-printable characters to their Unicode values (\\u1234). + + To print non-printable characters without transformation, enable the + noquote() functionality. Note that some QDebug backends might not be 8-bit + clean. + + See the QString overload for examples. */ /*! \fn QDebug &QDebug::operator<<(const QByteArray &b) Writes the byte array, \a b, to the stream and returns a reference to the - stream. + stream. Normally, QDebug prints the array inside quotes and transforms + control or non-US-ASCII characters to their C escape sequences (\\xAB). This + way, the output is always 7-bit clean and the string can be copied from the + output and pasted back into C++ sources, if necessary. + + To print non-printable characters without transformation, enable the + noquote() functionality. Note that some QDebug backends might not be 8-bit + clean. + + Output examples: + \code + QByteArray ba; + + ba = "a"; + qDebug().noquote() << ba; // prints: a + qDebug() << ba; // prints: "a" + + ba = "\"a\r\n\""; + qDebug() << ba; // prints: "\"a\r\n\"" + + ba = "\033"; // escape character + qDebug() << ba; // prints: "\x1B" + + ba = "\xC3\xA1"; + qDebug() << ba; // prints: "\xC3\xA1" + + ba = QByteArray("a\0b", 3); + qDebug() << ba // prints: "\a\x00""b" + \endcode + + Note how QDebug needed to close and reopen the string in the way C and C++ + languages concatenate string literals so that the letter 'b' is not + interpreted as part of the previous hexadecimal escape sequence. */ /*! -- cgit v1.2.3