I. Function Documentation▲
I-1. T *q_check_ptr(T *p)▲
Uses Q_CHECK_PTR on p, then returns p.
This can be used as an inline version of Q_CHECK_PTR.
II. Macro Documentation▲
II-1. void Q_ASSERT(bool test)▲
Prints a warning message containing the source code file name and line number if test is false.
Q_ASSERT() is useful for testing pre- and post-conditions during development. It does nothing if QT_NO_DEBUG was defined during compilation.
Example:
// File: div.cpp
#include <QtGlobal>
int
divide(int
a, int
b)
{
Q_ASSERT(b !=
0
);
return
a /
b;
}
If b is zero, the Q_ASSERT statement will output the following message using the qFatal() function:
ASSERT
:
"b != 0"
in file div.cpp, line 7
II-1-1. See Also▲
See also Q_ASSERT_X(), qFatal(), Debugging Techniques
II-2. void Q_ASSERT_X(bool test, const char *where, const char *what)▲
Prints the message what together with the location where, the source file name and line number if test is false.
Q_ASSERT_X is useful for testing pre- and post-conditions during development. It does nothing if QT_NO_DEBUG was defined during compilation.
Example:
// File: div.cpp
#include <QtGlobal>
int
divide(int
a, int
b)
{
Q_ASSERT_X(b !=
0
, "divide"
, "division by zero"
);
return
a /
b;
}
If b is zero, the Q_ASSERT_X statement will output the following message using the qFatal() function:
ASSERT failure in divide: "division by zero"
, file div.cpp, line 7
II-2-1. See Also▲
See also Q_ASSERT(), qFatal(), Debugging Techniques
II-3. void Q_ASSUME(bool expr)▲
Causes the compiler to assume that expr is true. This macro is useful for improving code generation, by providing the compiler with hints about conditions that it would not otherwise know about. However, there is no guarantee that the compiler will actually use those hints.
This macro could be considered a "lighter" version of Q_ASSERT(). While Q_ASSERT will abort the program's execution if the condition is false, Q_ASSUME will tell the compiler not to generate code for those conditions. Therefore, it is important that the assumptions always hold, otherwise undefined behavior may occur.
If expr is a constantly false condition, Q_ASSUME will tell the compiler that the current code execution cannot be reached. That is, Q_ASSUME(false) is equivalent to Q_UNREACHABLE().
In debug builds the condition is enforced by an assert to facilitate debugging.
Q_LIKELY() tells the compiler that the expression is likely, but not the only possibility. Q_ASSUME tells the compiler that it is the only possibility.
II-3-1. See Also▲
See also Q_ASSERT(), Q_UNREACHABLE(), Q_LIKELY()
II-4. void Q_CHECK_PTR(void *pointer)▲
If pointer is nullptr, prints a message containing the source code's file name and line number, saying that the program ran out of memory and aborts program execution. It throws std::bad_alloc instead if exceptions are enabled.
Q_CHECK_PTR does nothing if QT_NO_DEBUG and QT_NO_EXCEPTIONS were defined during compilation. Therefore you must not use Q_CHECK_PTR to check for successful memory allocations because the check will be disabled in some cases.
Example:
int
*
a;
Q_CHECK_PTR(a =
new
int
[80
]); // WRONG!
a =
new
(nothrow) int
[80
]; // Right
Q_CHECK_PTR(a);
II-4-1. See Also▲
See also qWarning(), Debugging Techniques
II-5. void Q_UNREACHABLE▲
Tells the compiler that the current point cannot be reached by any execution, so it may optimize any code paths leading here as dead code, as well as code continuing from here.
This macro is useful to mark impossible conditions. For example, given the following enum:
enum
Shapes {
Rectangle,
Triangle,
Circle,
NumShapes
}
;
One can write a switch table like so:
switch
(shape) {
case
Rectangle:
return
rectangle();
case
Triangle:
return
triangle();
case
Circle:
return
circle();
case
NumShapes:
Q_UNREACHABLE();
break
;
}
The advantage of inserting Q_UNREACHABLE() at that point is that the compiler is told not to generate code for a shape variable containing that value. If the macro is missing, the compiler will still generate the necessary comparisons for that value. If the case label were removed, some compilers could produce a warning that some enum values were not checked.
By using this macro in impossible conditions, code coverage may be improved as dead code paths may be eliminated.
In debug builds the condition is enforced by an assert to facilitate debugging.
Use the macro Q_UNREACHABLE_RETURN() to insert return statements for compilers that need them, without causing warnings for compilers that complain about its presence.
II-5-1. See Also▲
See also Q_ASSERT(), Q_ASSUME(), qFatal(), Q_UNREACHABLE_RETURN()
II-6. [since 6.5] void Q_UNREACHABLE_RETURN(...)▲
This is equivalent to
Q_UNREACHABLE();
return
__VA_ARGS__;
except it omits the return on compilers that would warn about it.
This macro was introduced in Qt 6.5.
II-6-1. See Also▲
See also Q_UNREACHABLE()