1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Copyright (C) 2016 Intel Corporation.
5** Contact: https://www.qt.io/licensing/
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see https://www.qt.io/terms-conditions. For further
16** information use the contact form at https://www.qt.io/contact-us.
17**
18** GNU Lesser General Public License Usage
19** Alternatively, this file may be used under the terms of the GNU Lesser
20** General Public License version 3 as published by the Free Software
21** Foundation and appearing in the file LICENSE.LGPL3 included in the
22** packaging of this file. Please review the following information to
23** ensure the GNU Lesser General Public License version 3 requirements
24** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
25**
26** GNU General Public License Usage
27** Alternatively, this file may be used under the terms of the GNU
28** General Public License version 2.0 or (at your option) the GNU General
29** Public license version 3 or any later version approved by the KDE Free
30** Qt Foundation. The licenses are as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
32** included in the packaging of this file. Please review the following
33** information to ensure the GNU General Public License requirements will
34** be met: https://www.gnu.org/licenses/gpl-2.0.html and
35** https://www.gnu.org/licenses/gpl-3.0.html.
36**
37** $QT_END_LICENSE$
38**
39****************************************************************************/
40
41#ifdef QT_NO_DEBUG
42#undef QT_NO_DEBUG
43#endif
44#ifdef qDebug
45#undef qDebug
46#endif
47
48#include "qdebug.h"
49#include "qmetaobject.h"
50#include <private/qtextstream_p.h>
51#include <private/qtools_p.h>
52
53QT_BEGIN_NAMESPACE
54
55using QtMiscUtils::toHexUpper;
56using QtMiscUtils::fromHex;
57
58// This file is needed to force compilation of QDebug into the kernel library.
59
60/*!
61 \class QDebug
62 \inmodule QtCore
63 \ingroup shared
64
65 \brief The QDebug class provides an output stream for debugging information.
66
67 QDebug is used whenever the developer needs to write out debugging or tracing
68 information to a device, file, string or console.
69
70 \section1 Basic Use
71
72 In the common case, it is useful to call the qDebug() function to obtain a
73 default QDebug object to use for writing debugging information.
74
75 \snippet qdebug/qdebugsnippet.cpp 1
76
77 This constructs a QDebug object using the constructor that accepts a QtMsgType
78 value of QtDebugMsg. Similarly, the qWarning(), qCritical() and qFatal()
79 functions also return QDebug objects for the corresponding message types.
80
81 The class also provides several constructors for other situations, including
82 a constructor that accepts a QFile or any other QIODevice subclass that is
83 used to write debugging information to files and other devices. The constructor
84 that accepts a QString is used to write to a string for display or serialization.
85
86 \section1 Formatting Options
87
88 QDebug formats output so that it's easily readable. It automatically adds spaces
89 between arguments, and adds quotes around QString, QByteArray, QChar arguments.
90
91 You can tweak these options through the space(), nospace() and quote(), noquote()
92 methods. Furthermore, \l{QTextStream manipulators} can be piped into a QDebug
93 stream.
94
95 QDebugStateSaver limits changes to the formatting to the current scope.
96 resetFormat() resets the options to the default ones.
97
98 \section1 Writing Custom Types to a Stream
99
100 Many standard types can be written to QDebug objects, and Qt provides support for
101 most Qt value types. To add support for custom types, you need to implement a
102 streaming operator, as in the following example:
103
104 \snippet qdebug/qdebugsnippet.cpp 0
105
106 This is described in the \l{Debugging Techniques} and
107 \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types}
108 documents.
109*/
110
111/*!
112 \fn QDebug::QDebug(QIODevice *device)
113
114 Constructs a debug stream that writes to the given \a device.
115*/
116
117/*!
118 \fn QDebug::QDebug(QString *string)
119
120 Constructs a debug stream that writes to the given \a string.
121*/
122
123/*!
124 \fn QDebug::QDebug(QtMsgType t)
125
126 Constructs a debug stream that writes to the handler for the message type \a t.
127*/
128
129/*!
130 \fn QDebug::QDebug(const QDebug &o)
131
132 Constructs a copy of the other debug stream \a o.
133*/
134
135/*!
136 \fn QDebug &QDebug::operator=(const QDebug &other)
137
138 Assigns the \a other debug stream to this stream and returns a reference to
139 this stream.
140*/
141
142/*!
143 \fn QDebug::~QDebug()
144
145 Flushes any pending data to be written and destroys the debug stream.
146*/
147// Has been defined in the header / inlined before Qt 5.4
148QDebug::~QDebug()
149{
150 if (stream && !--stream->ref) {
151 if (stream->space && stream->buffer.endsWith(QLatin1Char(' ')))
152 stream->buffer.chop(1);
153 if (stream->message_output) {
154 qt_message_output(stream->type,
155 stream->context,
156 stream->buffer);
157 }
158 delete stream;
159 }
160}
161
162/*!
163 \internal
164*/
165void QDebug::putUcs4(uint ucs4)
166{
167 maybeQuote('\'');
168 if (ucs4 < 0x20) {
169 stream->ts << "\\x" << Qt::hex << ucs4 << Qt::reset;
170 } else if (ucs4 < 0x80) {
171 stream->ts << char(ucs4);
172 } else {
173 if (ucs4 < 0x10000)
174 stream->ts << "\\u" << qSetFieldWidth(4);
175 else
176 stream->ts << "\\U" << qSetFieldWidth(8);
177 stream->ts << Qt::hex << qSetPadChar(QLatin1Char('0')) << ucs4 << Qt::reset;
178 }
179 maybeQuote('\'');
180}
181
182// These two functions return true if the character should be printed by QDebug.
183// For QByteArray, this is technically identical to US-ASCII isprint();
184// for QString, we use QChar::isPrint, which requires a full UCS-4 decode.
185static inline bool isPrintable(uint ucs4)
186{ return QChar::isPrint(ucs4); }
187static inline bool isPrintable(ushort uc)
188{ return QChar::isPrint(uc); }
189static inline bool isPrintable(uchar c)
190{ return c >= ' ' && c < 0x7f; }
191
192template <typename Char>
193static inline void putEscapedString(QTextStreamPrivate *d, const Char *begin, int length, bool isUnicode = true)
194{
195 QChar quote(QLatin1Char('"'));
196 d->write(&quote, 1);
197
198 bool lastWasHexEscape = false;
199 const Char *end = begin + length;
200 for (const Char *p = begin; p != end; ++p) {
201 // check if we need to insert "" to break an hex escape sequence
202 if (Q_UNLIKELY(lastWasHexEscape)) {
203 if (fromHex(*p) != -1) {
204 // yes, insert it
205 QChar quotes[] = { QLatin1Char('"'), QLatin1Char('"') };
206 d->write(quotes, 2);
207 }
208 lastWasHexEscape = false;
209 }
210
211 if (sizeof(Char) == sizeof(QChar)) {
212 // Surrogate characters are category Cs (Other_Surrogate), so isPrintable = false for them
213 int runLength = 0;
214 while (p + runLength != end &&
215 isPrintable(p[runLength]) && p[runLength] != '\\' && p[runLength] != '"')
216 ++runLength;
217 if (runLength) {
218 d->write(reinterpret_cast<const QChar *>(p), runLength);
219 p += runLength - 1;
220 continue;
221 }
222 } else if (isPrintable(*p) && *p != '\\' && *p != '"') {
223 QChar c = QLatin1Char(*p);
224 d->write(&c, 1);
225 continue;
226 }
227
228 // print as an escape sequence (maybe, see below for surrogate pairs)
229 int buflen = 2;
230 ushort buf[sizeof "\\U12345678" - 1];
231 buf[0] = '\\';
232
233 switch (*p) {
234 case '"':
235 case '\\':
236 buf[1] = *p;
237 break;
238 case '\b':
239 buf[1] = 'b';
240 break;
241 case '\f':
242 buf[1] = 'f';
243 break;
244 case '\n':
245 buf[1] = 'n';
246 break;
247 case '\r':
248 buf[1] = 'r';
249 break;
250 case '\t':
251 buf[1] = 't';
252 break;
253 default:
254 if (!isUnicode) {
255 // print as hex escape
256 buf[1] = 'x';
257 buf[2] = toHexUpper(uchar(*p) >> 4);
258 buf[3] = toHexUpper(uchar(*p));
259 buflen = 4;
260 lastWasHexEscape = true;
261 break;
262 }
263 if (QChar::isHighSurrogate(*p)) {
264 if ((p + 1) != end && QChar::isLowSurrogate(p[1])) {
265 // properly-paired surrogates
266 uint ucs4 = QChar::surrogateToUcs4(*p, p[1]);
267 if (isPrintable(ucs4)) {
268 buf[0] = *p;
269 buf[1] = p[1];
270 buflen = 2;
271 } else {
272 buf[1] = 'U';
273 buf[2] = '0'; // toHexUpper(ucs4 >> 32);
274 buf[3] = '0'; // toHexUpper(ucs4 >> 28);
275 buf[4] = toHexUpper(ucs4 >> 20);
276 buf[5] = toHexUpper(ucs4 >> 16);
277 buf[6] = toHexUpper(ucs4 >> 12);
278 buf[7] = toHexUpper(ucs4 >> 8);
279 buf[8] = toHexUpper(ucs4 >> 4);
280 buf[9] = toHexUpper(ucs4);
281 buflen = 10;
282 }
283 ++p;
284 break;
285 }
286 // improperly-paired surrogates, fall through
287 }
288 buf[1] = 'u';
289 buf[2] = toHexUpper(ushort(*p) >> 12);
290 buf[3] = toHexUpper(ushort(*p) >> 8);
291 buf[4] = toHexUpper(*p >> 4);
292 buf[5] = toHexUpper(*p);
293 buflen = 6;
294 }
295 d->write(reinterpret_cast<QChar *>(buf), buflen);
296 }
297
298 d->write(&quote, 1);
299}
300
301/*!
302 \internal
303 Duplicated from QtTest::toPrettyUnicode().
304*/
305void QDebug::putString(const QChar *begin, size_t length)
306{
307 if (stream->noQuotes) {
308 // no quotes, write the string directly too (no pretty-printing)
309 // this respects the QTextStream state, though
310 stream->ts.d_ptr->putString(begin, int(length));
311 } else {
312 // we'll reset the QTextStream formatting mechanisms, so save the state
313 QDebugStateSaver saver(*this);
314 stream->ts.d_ptr->params.reset();
315 putEscapedString(stream->ts.d_ptr.data(), reinterpret_cast<const ushort *>(begin), int(length));
316 }
317}
318
319/*!
320 \internal
321 Duplicated from QtTest::toPrettyCString().
322*/
323void QDebug::putByteArray(const char *begin, size_t length, Latin1Content content)
324{
325 if (stream->noQuotes) {
326 // no quotes, write the string directly too (no pretty-printing)
327 // this respects the QTextStream state, though
328 QString string = content == ContainsLatin1 ? QString::fromLatin1(begin, int(length)) : QString::fromUtf8(begin, int(length));
329 stream->ts.d_ptr->putString(string);
330 } else {
331 // we'll reset the QTextStream formatting mechanisms, so save the state
332 QDebugStateSaver saver(*this);
333 stream->ts.d_ptr->params.reset();
334 putEscapedString(stream->ts.d_ptr.data(), reinterpret_cast<const uchar *>(begin),
335 int(length), content == ContainsLatin1);
336 }
337}
338
339/*!
340 \fn QDebug::swap(QDebug &other)
341 \since 5.0
342
343 Swaps this debug stream instance with \a other. This function is
344 very fast and never fails.
345*/
346
347/*!
348 Resets the stream formatting options, bringing it back to its original constructed state.
349
350 \sa space(), quote()
351 \since 5.4
352*/
353QDebug &QDebug::resetFormat()
354{
355 stream->ts.reset();
356 stream->space = true;
357 stream->noQuotes = false;
358 stream->verbosity = DefaultVerbosity;
359 return *this;
360}
361
362/*!
363 \fn QDebug &QDebug::space()
364
365 Writes a space character to the debug stream and returns a reference to
366 the stream.
367
368 The stream remembers that automatic insertion of spaces is
369 enabled for future writes.
370
371 \sa nospace(), maybeSpace()
372*/
373
374/*!
375 \fn QDebug &QDebug::nospace()
376
377 Disables automatic insertion of spaces and returns a reference to the stream.
378
379 \sa space(), maybeSpace()
380*/
381
382/*!
383 \fn QDebug &QDebug::maybeSpace()
384
385 Writes a space character to the debug stream, depending on the current
386 setting for automatic insertion of spaces, and returns a reference to the stream.
387
388 \sa space(), nospace()
389*/
390
391/*!
392 \fn bool QDebug::autoInsertSpaces() const
393
394 Returns \c true if this QDebug instance will automatically insert spaces
395 between writes.
396
397 \since 5.0
398
399 \sa QDebugStateSaver
400*/
401
402/*!
403 \fn void QDebug::setAutoInsertSpaces(bool b)
404
405 Enables automatic insertion of spaces between writes if \a b is true; otherwise
406 automatic insertion of spaces is disabled.
407
408 \since 5.0
409
410 \sa QDebugStateSaver
411*/
412
413
414/*!
415 \fn QDebug &QDebug::quote()
416 \since 5.4
417
418 Enables automatic insertion of quotation characters around QChar, QString and QByteArray
419 contents and returns a reference to the stream.
420
421 Quoting is enabled by default.
422
423 \sa noquote(), maybeQuote()
424*/
425
426/*!
427 \fn QDebug &QDebug::noquote()
428 \since 5.4
429
430 Disables automatic insertion of quotation characters around QChar, QString and QByteArray
431 contents and returns a reference to the stream.
432
433 When quoting is disabled, these types are printed without quotation
434 characters and without escaping of non-printable characters.
435
436 \sa quote(), maybeQuote()
437*/
438
439/*!
440 \fn QDebug &QDebug::maybeQuote(char c)
441 \since 5.4
442
443 Writes a character \a c to the debug stream, depending on the
444 current setting for automatic insertion of quotes, and returns a reference to the stream.
445
446 The default character is a double quote \c{"}.
447
448 \sa quote(), noquote()
449*/
450
451/*!
452 \fn int QDebug::verbosity() const
453 \since 5.6
454
455 Returns the verbosity of the debug stream.
456
457 Streaming operators can check the value to decide whether
458 verbose output is desired and print more information depending on the
459 level. Higher values indicate that more information is desired.
460
461 The allowed range is from 0 to 7. The default value is 2.
462
463 \sa setVerbosity(), VerbosityLevel
464*/
465
466/*!
467 \fn void QDebug::setVerbosity(int verbosityLevel)
468 \since 5.6
469
470 Sets the verbosity of the stream to \a verbosityLevel.
471
472 The allowed range is from 0 to 7. The default value is 2.
473
474 \sa verbosity(), VerbosityLevel
475*/
476
477/*!
478 \fn QDebug &QDebug::verbosity(int verbosityLevel)
479 \since 5.13
480
481 Sets the verbosity of the stream to \a verbosityLevel and returns a reference to the stream.
482
483 The allowed range is from 0 to 7. The default value is 2.
484
485 \sa verbosity(), setVerbosity(), VerbosityLevel
486*/
487
488/*!
489 \enum QDebug::VerbosityLevel
490 \since 5.13
491
492 This enum describes the range of verbosity levels.
493
494 \value MinimumVerbosity
495 \value DefaultVerbosity
496 \value MaximumVerbosity
497
498 \sa verbosity(), setVerbosity()
499*/
500
501/*!
502 \fn QDebug &QDebug::operator<<(QChar t)
503
504 Writes the character, \a t, to the stream and returns a reference to the
505 stream. Normally, QDebug prints control characters and non-US-ASCII
506 characters as their C escape sequences or their Unicode value (\\u1234). To
507 print non-printable characters without transformation, enable the noquote()
508 functionality, but note that some QDebug backends may not be 8-bit clean
509 and may not be able to represent \c t.
510*/
511
512/*!
513 \fn QDebug &QDebug::operator<<(bool t)
514
515 Writes the boolean value, \a t, to the stream and returns a reference to the
516 stream.
517*/
518
519/*!
520 \fn QDebug &QDebug::operator<<(char t)
521
522 Writes the character, \a t, to the stream and returns a reference to the
523 stream.
524*/
525
526/*!
527 \fn QDebug &QDebug::operator<<(signed short t)
528
529 Writes the signed short integer, \a t, to the stream and returns a reference
530 to the stream.
531*/
532
533/*!
534 \fn QDebug &QDebug::operator<<(unsigned short t)
535
536 Writes then unsigned short integer, \a t, to the stream and returns a
537 reference to the stream.
538*/
539
540/*!
541 \fn QDebug &QDebug::operator<<(signed int t)
542
543 Writes the signed integer, \a t, to the stream and returns a reference
544 to the stream.
545*/
546
547/*!
548 \fn QDebug &QDebug::operator<<(unsigned int t)
549
550 Writes then unsigned integer, \a t, to the stream and returns a reference to
551 the stream.
552*/
553
554/*!
555 \fn QDebug &QDebug::operator<<(signed long t)
556
557 Writes the signed long integer, \a t, to the stream and returns a reference
558 to the stream.
559*/
560
561/*!
562 \fn QDebug &QDebug::operator<<(unsigned long t)
563
564 Writes then unsigned long integer, \a t, to the stream and returns a reference
565 to the stream.
566*/
567
568/*!
569 \fn QDebug &QDebug::operator<<(qint64 t)
570
571 Writes the signed 64-bit integer, \a t, to the stream and returns a reference
572 to the stream.
573*/
574
575/*!
576 \fn QDebug &QDebug::operator<<(quint64 t)
577
578 Writes then unsigned 64-bit integer, \a t, to the stream and returns a
579 reference to the stream.
580*/
581
582/*!
583 \fn QDebug &QDebug::operator<<(float t)
584
585 Writes the 32-bit floating point number, \a t, to the stream and returns a
586 reference to the stream.
587*/
588
589/*!
590 \fn QDebug &QDebug::operator<<(double t)
591
592 Writes the 64-bit floating point number, \a t, to the stream and returns a
593 reference to the stream.
594*/
595
596/*!
597 \fn QDebug &QDebug::operator<<(const char *t)
598
599 Writes the '\\0'-terminated UTF-8 string, \a t, to the stream and returns a
600 reference to the stream. The string is never quoted or escaped for the
601 output. Note that QDebug buffers internally as UTF-16 and may need to
602 transform to 8-bit using the locale's codec in order to use some backends,
603 which may cause garbled output (mojibake). Restricting to US-ASCII strings
604 is recommended.
605*/
606
607/*!
608 \fn QDebug &QDebug::operator<<(const char16_t *t)
609 \since 6.0
610
611 Writes the u'\\0'-terminated UTF-16 string, \a t, to the stream and returns
612 a reference to the stream. The string is never quoted or escaped for the
613 output. Note that QDebug buffers internally as UTF-16 and may need to
614 transform to 8-bit using the locale's codec in order to use some backends,
615 which may cause garbled output (mojibake). Restricting to US-ASCII strings
616 is recommended.
617*/
618
619/*!
620 \fn QDebug &QDebug::operator<<(char16_t t)
621 \since 5.5
622
623 Writes the UTF-16 character, \a t, to the stream and returns a reference
624 to the stream.
625*/
626
627/*!
628 \fn QDebug &QDebug::operator<<(char32_t t)
629 \since 5.5
630
631 Writes the UTF-32 character, \a t, to the stream and returns a reference
632 to the stream.
633*/
634
635/*!
636 \fn QDebug &QDebug::operator<<(const QString &t)
637
638 Writes the string, \a t, to the stream and returns a reference to the
639 stream. Normally, QDebug prints the string inside quotes and transforms
640 non-printable characters to their Unicode values (\\u1234).
641
642 To print non-printable characters without transformation, enable the
643 noquote() functionality. Note that some QDebug backends might not be 8-bit
644 clean.
645
646 Output examples:
647 \snippet code/src_corelib_io_qdebug.cpp 0
648*/
649
650/*!
651 \since 5.10
652 \fn QDebug &QDebug::operator<<(QStringView s)
653
654 Writes the string view, \a s, to the stream and returns a reference to the
655 stream. Normally, QDebug prints the string inside quotes and transforms
656 non-printable characters to their Unicode values (\\u1234).
657
658 To print non-printable characters without transformation, enable the
659 noquote() functionality. Note that some QDebug backends might not be 8-bit
660 clean.
661
662 See the QString overload for examples.
663*/
664
665/*!
666 \fn QDebug &QDebug::operator<<(QLatin1String t)
667
668 Writes the string, \a t, to the stream and returns a reference to the
669 stream. Normally, QDebug prints the string inside quotes and transforms
670 non-printable characters to their Unicode values (\\u1234).
671
672 To print non-printable characters without transformation, enable the
673 noquote() functionality. Note that some QDebug backends might not be 8-bit
674 clean.
675
676 See the QString overload for examples.
677*/
678
679/*!
680 \fn QDebug &QDebug::operator<<(const QByteArray &t)
681
682 Writes the byte array, \a t, to the stream and returns a reference to the
683 stream. Normally, QDebug prints the array inside quotes and transforms
684 control or non-US-ASCII characters to their C escape sequences (\\xAB). This
685 way, the output is always 7-bit clean and the string can be copied from the
686 output and pasted back into C++ sources, if necessary.
687
688 To print non-printable characters without transformation, enable the
689 noquote() functionality. Note that some QDebug backends might not be 8-bit
690 clean.
691
692 Output examples:
693 \snippet code/src_corelib_io_qdebug.cpp 1
694
695 Note how QDebug needed to close and reopen the string in the way C and C++
696 languages concatenate string literals so that the letter 'b' is not
697 interpreted as part of the previous hexadecimal escape sequence.
698*/
699
700/*!
701 \fn QDebug &QDebug::operator<<(const void *t)
702
703 Writes a pointer, \a t, to the stream and returns a reference to the stream.
704*/
705
706/*!
707 \fn QDebug &QDebug::operator<<(QTextStreamFunction f)
708 \internal
709*/
710
711/*!
712 \fn QDebug &QDebug::operator<<(QTextStreamManipulator m)
713 \internal
714*/
715
716/*!
717 \fn template <class T> QString QDebug::toString(T &&object)
718 \since 6.0
719
720 \include qdebug-toString.qdocinc
721*/
722
723/*!
724 \fn template <class T> QDebug operator<<(QDebug debug, const QList<T> &list)
725 \relates QDebug
726
727 Writes the contents of \a list to \a debug. \c T needs to
728 support streaming into QDebug.
729*/
730
731/*!
732 \fn template <typename T, typename Alloc> QDebug operator<<(QDebug debug, const std::list<T, Alloc> &vec)
733 \relates QDebug
734 \since 5.7
735
736 Writes the contents of list \a vec to \a debug. \c T needs to
737 support streaming into QDebug.
738*/
739
740/*!
741 \fn template <typename T, typename Alloc> QDebug operator<<(QDebug debug, const std::vector<T, Alloc> &vec)
742 \relates QDebug
743 \since 5.7
744
745 Writes the contents of vector \a vec to \a debug. \c T needs to
746 support streaming into QDebug.
747*/
748
749/*!
750 \fn template <typename T> QDebug operator<<(QDebug debug, const QSet<T> &set)
751 \relates QDebug
752
753 Writes the contents of \a set to \a debug. \c T needs to
754 support streaming into QDebug.
755*/
756
757/*!
758 \fn template <class Key, class T> QDebug operator<<(QDebug debug, const QMap<Key, T> &map)
759 \relates QDebug
760
761 Writes the contents of \a map to \a debug. Both \c Key and
762 \c T need to support streaming into QDebug.
763*/
764
765/*!
766 \fn template <typename Key, typename T, typename Compare, typename Alloc> QDebug operator<<(QDebug debug, const std::map<Key, T, Compare, Alloc> &map)
767 \relates QDebug
768 \since 5.7
769
770 Writes the contents of \a map to \a debug. Both \c Key and
771 \c T need to support streaming into QDebug.
772*/
773
774/*!
775 \fn template <typename Key, typename T, typename Compare, typename Alloc> QDebug operator<<(QDebug debug, const std::multimap<Key, T, Compare, Alloc> &map)
776 \relates QDebug
777 \since 5.7
778
779 Writes the contents of \a map to \a debug. Both \c Key and
780 \c T need to support streaming into QDebug.
781*/
782
783/*!
784 \fn template <class Key, class T> QDebug operator<<(QDebug debug, const QHash<Key, T> &hash)
785 \relates QDebug
786
787 Writes the contents of \a hash to \a debug. Both \c Key and
788 \c T need to support streaming into QDebug.
789*/
790
791/*!
792 \fn template <class T1, class T2> QDebug operator<<(QDebug debug, const QPair<T1, T2> &pair)
793 \relates QDebug
794
795 Writes the contents of \a pair to \a debug. Both \c T1 and
796 \c T2 need to support streaming into QDebug.
797*/
798
799/*!
800 \fn template<typename T> QDebug operator<<(QDebug debug, const QFlags<T> &flags)
801 \relates QDebug
802 \since 4.7
803
804 Writes \a flags to \a debug.
805*/
806
807/*!
808 \fn template<typename T> QDebug operator<<(QDebug debug, const QSharedPointer<T> &ptr)
809 \relates QSharedPointer
810 \since 5.7
811
812 Writes the pointer tracked by \a ptr into the debug object \a debug for
813 debugging purposes.
814
815 \sa {Debugging Techniques}
816*/
817
818/*!
819 \fn QDebug &QDebug::operator<<(std::nullptr_t)
820 \internal
821 */
822
823/*!
824 \class QDebugStateSaver
825 \inmodule QtCore
826 \brief Convenience class for custom QDebug operators.
827
828 Saves the settings used by QDebug, and restores them upon destruction,
829 then calls \l {QDebug::maybeSpace()}{maybeSpace()}, to separate arguments with a space if
830 \l {QDebug::autoInsertSpaces()}{autoInsertSpaces()} was true at the time of constructing the QDebugStateSaver.
831
832 The automatic insertion of spaces between writes is one of the settings
833 that QDebugStateSaver stores for the duration of the current block.
834
835 The settings of the internal QTextStream are also saved and restored,
836 so that using << Qt::hex in a QDebug operator doesn't affect other QDebug
837 operators.
838
839 \since 5.1
840*/
841
842class QDebugStateSaverPrivate
843{
844public:
845 QDebugStateSaverPrivate(QDebug::Stream *stream)
846 : m_stream(stream),
847 m_spaces(stream->space),
848 m_noQuotes(stream->noQuotes),
849 m_verbosity(stream->verbosity),
850 m_streamParams(stream->ts.d_ptr->params)
851 {
852 }
853 void restoreState()
854 {
855 const bool currentSpaces = m_stream->space;
856 if (currentSpaces && !m_spaces)
857 if (m_stream->buffer.endsWith(QLatin1Char(' ')))
858 m_stream->buffer.chop(1);
859
860 m_stream->space = m_spaces;
861 m_stream->noQuotes = m_noQuotes;
862 m_stream->ts.d_ptr->params = m_streamParams;
863 m_stream->verbosity = m_verbosity;
864
865 if (!currentSpaces && m_spaces)
866 m_stream->ts << ' ';
867 }
868
869 QDebug::Stream *m_stream;
870
871 // QDebug state
872 const bool m_spaces;
873 const bool m_noQuotes;
874 const int m_verbosity;
875
876 // QTextStream state
877 const QTextStreamPrivate::Params m_streamParams;
878};
879
880
881/*!
882 Creates a QDebugStateSaver instance, which saves the settings
883 currently used by \a dbg.
884
885 \sa QDebug::setAutoInsertSpaces(), QDebug::autoInsertSpaces()
886*/
887QDebugStateSaver::QDebugStateSaver(QDebug &dbg)
888 : d(new QDebugStateSaverPrivate(dbg.stream))
889{
890}
891
892/*!
893 Destroys a QDebugStateSaver instance, which restores the settings
894 used when the QDebugStateSaver instance was created.
895
896 \sa QDebug::setAutoInsertSpaces(), QDebug::autoInsertSpaces()
897*/
898QDebugStateSaver::~QDebugStateSaver()
899{
900 d->restoreState();
901}
902
903/*!
904 \internal
905
906 Specialization of the primary template in qdebug.h to out-of-line
907 the common case of QFlags<T>::Int being int.
908
909 Just call the generic version so the two don't get out of sync.
910*/
911void qt_QMetaEnum_flagDebugOperator(QDebug &debug, size_t sizeofT, int value)
912{
913 qt_QMetaEnum_flagDebugOperator<int>(debug, sizeofT, value);
914}
915
916#ifndef QT_NO_QOBJECT
917/*!
918 \fn QDebug qt_QMetaEnum_debugOperator(QDebug &, int value, const QMetaObject *, const char *name)
919 \internal
920
921 Formats the given enum \a value for debug output.
922
923 The supported verbosity are:
924
925 0: Just the key, or value with enum name if no key is found:
926
927 MyEnum2
928 MyEnum(123)
929 MyScopedEnum::Enum3
930 MyScopedEnum(456)
931
932 1: Same as 0, but treating all enums as scoped:
933
934 MyEnum::MyEnum2
935 MyEnum(123)
936 MyScopedEnum::Enum3
937 MyScopedEnum(456)
938
939 2: The QDebug default. Same as 0, and includes class/namespace scope:
940
941 MyNamespace::MyClass::MyEnum2
942 MyNamespace::MyClass::MyEnum(123)
943 MyNamespace::MyClass::MyScopedEnum::Enum3
944 MyNamespace::MyClass::MyScopedEnum(456)
945
946 3: Same as 2, but treating all enums as scoped:
947
948 MyNamespace::MyClass::MyEnum::MyEnum2
949 MyNamespace::MyClass::MyEnum(123)
950 MyNamespace::MyClass::MyScopedEnum::Enum3
951 MyNamespace::MyClass::MyScopedEnum(456)
952 */
953QDebug qt_QMetaEnum_debugOperator(QDebug &dbg, qint64 value, const QMetaObject *meta, const char *name)
954{
955 QDebugStateSaver saver(dbg);
956 dbg.nospace();
957 QMetaEnum me = meta->enumerator(meta->indexOfEnumerator(name));
958
959 const int verbosity = dbg.verbosity();
960 if (verbosity >= QDebug::DefaultVerbosity) {
961 if (const char *scope = me.scope())
962 dbg << scope << u"::";
963 }
964
965 const char *key = me.valueToKey(value);
966 const bool scoped = me.isScoped() || verbosity & 1;
967 if (scoped || !key)
968 dbg << me.enumName() << (!key ? u"(" : u"::");
969
970 if (key)
971 dbg << key;
972 else
973 dbg << value << ')';
974
975 return dbg;
976}
977
978/*!
979 \fn QDebug qt_QMetaEnum_flagDebugOperator(QDebug &, quint64 value, const QMetaObject *, const char *name)
980 \internal
981
982 Formats the given flag \a value for debug output.
983
984 The supported verbosity are:
985
986 0: Just the key(s):
987
988 MyFlag1
989 MyFlag2|MyFlag3
990 MyScopedFlag(MyFlag2)
991 MyScopedFlag(MyFlag2|MyFlag3)
992
993 1: Same as 0, but treating all flags as scoped:
994
995 MyFlag(MyFlag1)
996 MyFlag(MyFlag2|MyFlag3)
997 MyScopedFlag(MyFlag2)
998 MyScopedFlag(MyFlag2|MyFlag3)
999
1000 2: The QDebug default. Same as 1, and includes class/namespace scope:
1001
1002 QFlags<MyNamespace::MyClass::MyFlag>(MyFlag1)
1003 QFlags<MyNamespace::MyClass::MyFlag>(MyFlag2|MyFlag3)
1004 QFlags<MyNamespace::MyClass::MyScopedFlag>(MyFlag2)
1005 QFlags<MyNamespace::MyClass::MyScopedFlag>(MyFlag2|MyFlag3)
1006 */
1007QDebug qt_QMetaEnum_flagDebugOperator(QDebug &debug, quint64 value, const QMetaObject *meta, const char *name)
1008{
1009 const int verbosity = debug.verbosity();
1010
1011 QDebugStateSaver saver(debug);
1012 debug.resetFormat();
1013 debug.noquote();
1014 debug.nospace();
1015
1016 const QMetaEnum me = meta->enumerator(meta->indexOfEnumerator(name));
1017
1018 const bool classScope = verbosity >= QDebug::DefaultVerbosity;
1019 if (classScope) {
1020 debug << u"QFlags<";
1021
1022 if (const char *scope = me.scope())
1023 debug << scope << u"::";
1024 }
1025
1026 const bool enumScope = me.isScoped() || verbosity > QDebug::MinimumVerbosity;
1027 if (enumScope) {
1028 debug << me.enumName();
1029 if (classScope)
1030 debug << '>';
1031 debug << '(';
1032 }
1033
1034 debug << me.valueToKeys(value);
1035
1036 if (enumScope)
1037 debug << ')';
1038
1039 return debug;
1040}
1041#endif // !QT_NO_QOBJECT
1042
1043QT_END_NAMESPACE
1044