<QtGlobal> - Global Qt Declarations

The <QtGlobal> header file includes the fundamental global declarations. It is included by most other Qt header files. More...

Header: #include <QtGlobal>

Functions

typename std::add_const<T>::type &qAsConst(T &t)
void qAsConst(const T &&t)
T qExchange(T &obj, U &&newValue)

Macros

Detailed Description

The global declarations include types, functions and macros.

The type definitions are partly convenience definitions for basic types (some of which guarantee certain bit-sizes on all platforms supported by Qt), partly types related to Qt message handling. The functions are related to generating messages, Qt version handling and comparing and adjusting object values. And finally, some of the declared macros enable programmers to add compiler or platform specific code to their applications, while others are convenience macros for larger operations.

Types

The header file declares several type definitions that guarantee a specified bit-size on all platforms supported by Qt for various basic types, for example qint8 which is a signed char guaranteed to be 8-bit on all platforms supported by Qt. The header file also declares the qlonglong type definition for long long int (__int64 on Windows).

Several convenience type definitions are declared: qreal for double or float, uchar for unsigned char, uint for unsigned int, ulong for unsigned long and ushort for unsigned short.

Finally, the QtMsgType definition identifies the various messages that can be generated and sent to a Qt message handler; QtMessageHandler is a type definition for a pointer to a function with the signature void myMessageHandler(QtMsgType, const QMessageLogContext &, const char *). QMessageLogContext class contains the line, file, and function the message was logged at. This information is created by the QMessageLogger class.

Functions

The <QtGlobal> header file contains several functions comparing and adjusting an object's value. These functions take a template type as argument: You can retrieve the absolute value of an object using the qAbs() function, and you can bound a given object's value by given minimum and maximum values using the qBound() function. You can retrieve the minimum and maximum of two given objects using qMin() and qMax() respectively. All these functions return a corresponding template type; the template types can be replaced by any other type.

Example:

int myValue = 10;
int minValue = 2;
int maxValue = 6;

int boundedValue = qBound(minValue, myValue, maxValue);
// boundedValue == 6

<QtGlobal> also contains functions that generate messages from the given string argument: qDebug(), qInfo(), qWarning(), qCritical(), and qFatal(). These functions call the message handler with the given message.

Example:

if (!driver()->isOpen() || driver()->isOpenError()) {
    qWarning("QSqlQuery::exec: database not open");
    return false;
}

The remaining functions are qRound() and qRound64(), which both accept a double or float value as their argument returning the value rounded up to the nearest integer and 64-bit integer respectively, the qInstallMessageHandler() function which installs the given QtMessageHandler, and the qVersion() function which returns the version number of Qt at runtime as a string.

Macros

The <QtGlobal> header file provides a range of macros (Q_CC_*) that are defined if the application is compiled using the specified platforms. For example, the Q_CC_SUN macro is defined if the application is compiled using Forte Developer, or Sun Studio C++. The header file also declares a range of macros (Q_OS_*) that are defined for the specified platforms. For example, Q_OS_UNIX which is defined for the Unix-based systems.

The purpose of these macros is to enable programmers to add compiler or platform specific code to their application.

The remaining macros are convenience macros for larger operations: The QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRANSLATE_NOOP3() macros provide the possibility of marking strings for delayed translation. QT_TR_N_NOOP(), QT_TRANSLATE_N_NOOP(), and QT_TRANSLATE_N_NOOP3() are numerator dependent variants of these. The Q_ASSERT() and Q_ASSERT_X() enables warning messages of various level of refinement. The Q_FOREACH() and foreach() macros implement Qt's foreach loop.

The Q_INT64_C() and Q_UINT64_C() macros wrap signed and unsigned 64-bit integer literals in a platform-independent way. The Q_CHECK_PTR() macro prints a warning containing the source code's file name and line number, saying that the program ran out of memory, if the pointer is nullptr. The qPrintable() and qUtf8Printable() macros represent an easy way of printing text.

The QT_POINTER_SIZE macro expands to the size of a pointer in bytes.

The macros QT_VERSION and QT_VERSION_STR expand to a numeric value or a string, respectively. These identify the version of Qt that the application is compiled with.

See also <QtAlgorithms> and QSysInfo.

Function Documentation

[since 5.7] template <typename T> typename std::add_const<T>::type &qAsConst(T &t)

Returns t cast to const T.

This function is a Qt implementation of C++17's std::as_const(), a cast function like std::move(). But while std::move() turns lvalues into rvalues, this function turns non-const lvalues into const lvalues. Like std::as_const(), it doesn't work on rvalues, because it cannot be efficiently implemented for rvalues without leaving dangling references.

Its main use in Qt is to prevent implicitly-shared Qt containers from detaching:

    QString s = ...;
    for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared)
        process(ch);
    for (QChar ch : qAsConst(s)) // ok, no detach attempt
        process(ch);

Of course, in this case, you could (and probably should) have declared s as const in the first place:

    const QString s = ...;
    for (QChar ch : s) // ok, no detach attempt on const objects
        process(ch);

but often that is not easily possible.

It is important to note that qAsConst() does not copy its argument, it just performs a const_cast<const T&>(t). This is also the reason why it is designed to fail for rvalues: The returned reference would go stale too soon. So while this works (but detaches the returned object):

    for (QChar ch : funcReturningQString())
        process(ch); // OK, the returned object is kept alive for the loop's duration

this would not:

    for (QChar ch : qAsConst(funcReturningQString()))
        process(ch); // ERROR: ch is copied from deleted memory

To prevent this construct from compiling (and failing at runtime), qAsConst() has a second, deleted, overload which binds to rvalues.

This function was introduced in Qt 5.7.

[since 5.7] template <typename T> void qAsConst(const T &&t)

This is an overloaded function.

This overload is deleted to prevent a dangling reference in code like

    for (QChar ch : qAsConst(funcReturningQString()))
        process(ch); // ERROR: ch is copied from deleted memory

This function was introduced in Qt 5.7.

[since 5.14] template <typename T, typename U> T qExchange(T &obj, U &&newValue)

Replaces the value of obj with newValue and returns the old value of obj.

This is Qt's implementation of std::exchange(). It differs from std::exchange() only in that it is constexpr already in C++14, and available on all supported compilers.

Here is how to use qExchange() to implement move constructors:

MyClass(MyClass &&other)
  : m_pointer{qExchange(other.m_pointer, nullptr)},
    m_int{qExchange(other.m_int, 0)},
    m_vector{std::move(other.m_vector)},
    ...

For members of class type, we can use std::move(), as their move-constructor will do the right thing. But for scalar types such as raw pointers or integer type, move is the same as copy, which, particularly for pointers, is not what we expect. So, we cannot use std::move() for such types, but we can use std::exchange()/qExchange() to make sure the source object's member is already reset by the time we get to the initialization of our next data member, which might come in handy if the constructor exits with an exception.

Here is how to use qExchange() to write a loop that consumes the collection it iterates over:

for (auto &e : qExchange(collection, {})
    doSomethingWith(e);

Which is equivalent to the following, much more verbose code:

{
    auto tmp = std::move(collection);
    collection = {};                    // or collection.clear()
    for (auto &e : tmp)
        doSomethingWith(e);
}                                       // destroys 'tmp'

This is perfectly safe, as the for-loop keeps the result of qExchange() alive for as long as the loop runs, saving the declaration of a temporary variable. Be aware, though, that qExchange() returns a non-const object, so Qt containers may detach.

This function was introduced in Qt 5.14.

Macro Documentation

QT_POINTER_SIZE

Expands to the size of a pointer in bytes (4 or 8). This is equivalent to sizeof(void *) but can be used in a preprocessor directive.

Q_BIG_ENDIAN

This macro represents a value you can compare to the macro Q_BYTE_ORDER to determine the endian-ness of your system. In a big-endian system, the most significant byte is stored at the lowest address. The other bytes follow in decreasing order of significance.

#if Q_BYTE_ORDER == Q_BIG_ENDIAN
...
#endif

See also Q_BYTE_ORDER and Q_LITTLE_ENDIAN.

Q_BYTE_ORDER

This macro can be used to determine the byte order your system uses for storing data in memory. i.e., whether your system is little-endian or big-endian. It is set by Qt to one of the macros Q_LITTLE_ENDIAN or Q_BIG_ENDIAN. You normally won't need to worry about endian-ness, but you might, for example if you need to know which byte of an integer or UTF-16 character is stored in the lowest address. Endian-ness is important in networking, where computers with different values for Q_BYTE_ORDER must pass data back and forth.

Use this macro as in the following examples.

#if Q_BYTE_ORDER == Q_BIG_ENDIAN
...
#endif

or

#if Q_BYTE_ORDER == Q_LITTLE_ENDIAN
...
#endif

See also Q_BIG_ENDIAN and Q_LITTLE_ENDIAN.

Q_CC_BOR

Defined if the application is compiled using Borland/Turbo C++.

Q_CC_CDS

Defined if the application is compiled using Reliant C++.

Q_CC_CLANG

Defined if the application is compiled using Clang.

Q_CC_COMEAU

Defined if the application is compiled using Comeau C++.

Q_CC_DEC

Defined if the application is compiled using DEC C++.

Q_CC_EDG

Defined if the application is compiled using Edison Design Group C++.

Q_CC_GHS

Defined if the application is compiled using Green Hills Optimizing C++ Compilers.

Q_CC_GNU

Defined if the application is compiled using GNU C++.

Q_CC_HIGHC

Defined if the application is compiled using MetaWare High C/C++.

Q_CC_HPACC

Defined if the application is compiled using HP aC++.

Q_CC_KAI

Defined if the application is compiled using KAI C++.

Q_CC_MIPS

Defined if the application is compiled using MIPSpro C++.

Q_CC_MSVC

Defined if the application is compiled using Microsoft Visual C/C++, Intel C++ for Windows.

Q_CC_OC

Defined if the application is compiled using CenterLine C++.

Q_CC_PGI

Defined if the application is compiled using Portland Group C++.

Q_CC_SUN

Defined if the application is compiled using Forte Developer, or Sun Studio C++.

Q_CC_SYM

Defined if the application is compiled using Digital Mars C/C++ (used to be Symantec C++).

Q_CC_USLC

Defined if the application is compiled using SCO OUDK and UDK.

Q_CC_WAT

Defined if the application is compiled using Watcom C++.

[since 6.4] Q_CONSTINIT

Enforces constant initialization when supported by the compiler.

If the compiler supports the C++20 constinit keyword, Clang's [[clang::require_constant_initialization]] or GCC's __constinit, then this macro expands to the first one of these that is available, otherwise it expands to nothing.

Variables marked as constinit cause a compile-error if their initialization would have to be performed at runtime.

For constants, you can use constexpr since C++11, but constexpr makes variables const, too, whereas constinit ensures constant initialization, but doesn't make the variable const:

KeywordAddedimmutableconstant-initialized
constC++98yesnot required
constexprC++11yesrequired
constinitC++20norequired

This macro was introduced in Qt 6.4.

Q_DECL_EXPORT

This macro marks a symbol for shared library export (see Creating Shared Libraries).

See also Q_DECL_IMPORT.

Q_DECL_IMPORT

This macro declares a symbol to be an import from a shared library (see Creating Shared Libraries).

See also Q_DECL_EXPORT.

[since 5.8] void Q_FALLTHROUGH

Can be used in switch statements at the end of case block to tell the compiler and other developers that that the lack of a break statement is intentional.

This is useful since a missing break statement is often a bug, and some compilers can be configured to emit warnings when one is not found.

This macro was introduced in Qt 5.8.

See also Q_UNREACHABLE().

const char*Q_FUNC_INFO

Expands to a string that describe the function the macro resides in. How this string looks more specifically is compiler dependent. With GNU GCC it is typically the function signature, while with other compilers it might be the line and column number.

Q_FUNC_INFO can be conveniently used with qDebug(). For example, this function:

template<typename TInputType>
const TInputType &myMin(const TInputType &value1, const TInputType &value2)
{
    qDebug() << Q_FUNC_INFO << "was called with value1:" << value1 << "value2:" << value2;

    if(value1 < value2)
        return value1;
    else
        return value2;
}

when instantiated with the integer type, will with the GCC compiler produce:

const TInputType& myMin(const TInputType&, const TInputType&) [with TInputType = int] was called with value1: 3 value2: 4

If this macro is used outside a function, the behavior is undefined.

Q_LIKELY(expr)

Hints to the compiler that the enclosed condition, expr, is likely to evaluate to true.

Use of this macro can help the compiler to optimize the code.

Example:

    // the condition inside the "if" will be successful most of the times
    for (int i = 1; i <= 365; i++) {
        if (Q_LIKELY(isWorkingDay(i))) {
            ...
        }
        ...
    }

See also Q_UNLIKELY() and Q_ASSUME().

Q_LITTLE_ENDIAN

This macro represents a value you can compare to the macro Q_BYTE_ORDER to determine the endian-ness of your system. In a little-endian system, the least significant byte is stored at the lowest address. The other bytes follow in increasing order of significance.

#if Q_BYTE_ORDER == Q_LITTLE_ENDIAN
...
#endif

See also Q_BYTE_ORDER and Q_BIG_ENDIAN.

Q_OS_AIX

Defined on AIX.

Q_OS_ANDROID

Defined on Android.

Q_OS_BSD4

Defined on Any BSD 4.4 system.

Q_OS_CYGWIN

Defined on Cygwin.

Q_OS_DARWIN

Defined on Darwin-based operating systems such as macOS, iOS, watchOS, and tvOS.

Q_OS_FREEBSD

Defined on FreeBSD.

Q_OS_HPUX

Defined on HP-UX.

Q_OS_HURD

Defined on GNU Hurd.

Q_OS_IOS

Defined on iOS.

Q_OS_LINUX

Defined on Linux.

Q_OS_LYNX

Defined on LynxOS.

Q_OS_MAC

Deprecated synonym for Q_OS_DARWIN. Do not use.

Q_OS_MACOS

Defined on macOS.

Q_OS_NETBSD

Defined on NetBSD.

Q_OS_OPENBSD

Defined on OpenBSD.

Q_OS_OSX

Deprecated synonym for Q_OS_MACOS. Do not use.

Q_OS_QNX

Defined on QNX Neutrino.

Q_OS_SOLARIS

Defined on Sun Solaris.

Q_OS_TVOS

Defined on tvOS.

Q_OS_UNIX

Defined on Any UNIX BSD/SYSV system.

Q_OS_WASM

Defined on Web Assembly.

Q_OS_WATCHOS

Defined on watchOS.

Q_OS_WIN32

Defined on 32-bit and 64-bit versions of Windows.

Q_OS_WIN64

Defined on 64-bit versions of Windows.

Q_OS_WIN

Defined on all supported versions of Windows. That is, if Q_OS_WIN32 or Q_OS_WIN64 is defined.

Q_OS_WINDOWS

This is a synonym for Q_OS_WIN.

Q_PROCESSOR_X86

Defined if the application is compiled for x86 processors. Qt currently supports two x86 variants: Q_PROCESSOR_X86_32 and Q_PROCESSOR_X86_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_S390

Defined if the application is compiled for S/390 processors. Qt supports one optional variant of S/390: Q_PROCESSOR_S390_X.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ALPHA

Defined if the application is compiled for Alpha processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM

Defined if the application is compiled for ARM processors. Qt currently supports three optional ARM revisions: Q_PROCESSOR_ARM_V5, Q_PROCESSOR_ARM_V6, and Q_PROCESSOR_ARM_V7.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V5

Defined if the application is compiled for ARMv5 processors. The Q_PROCESSOR_ARM macro is also defined when Q_PROCESSOR_ARM_V5 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V6

Defined if the application is compiled for ARMv6 processors. The Q_PROCESSOR_ARM and Q_PROCESSOR_ARM_V5 macros are also defined when Q_PROCESSOR_ARM_V6 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V7

Defined if the application is compiled for ARMv7 processors. The Q_PROCESSOR_ARM, Q_PROCESSOR_ARM_V5, and Q_PROCESSOR_ARM_V6 macros are also defined when Q_PROCESSOR_ARM_V7 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_AVR32

Defined if the application is compiled for AVR32 processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_BLACKFIN

Defined if the application is compiled for Blackfin processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_IA64

Defined if the application is compiled for IA-64 processors. This includes all Itanium and Itanium 2 processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS

Defined if the application is compiled for MIPS processors. Qt currently supports seven MIPS revisions: Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, Q_PROCESSOR_MIPS_IV, Q_PROCESSOR_MIPS_V, Q_PROCESSOR_MIPS_32, and Q_PROCESSOR_MIPS_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_32

Defined if the application is compiled for MIPS32 processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, and Q_PROCESSOR_MIPS_II macros are also defined when Q_PROCESSOR_MIPS_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_64

Defined if the application is compiled for MIPS64 processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, Q_PROCESSOR_MIPS_IV, and Q_PROCESSOR_MIPS_V macros are also defined when Q_PROCESSOR_MIPS_64 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_I

Defined if the application is compiled for MIPS-I processors. The Q_PROCESSOR_MIPS macro is also defined when Q_PROCESSOR_MIPS_I is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_II

Defined if the application is compiled for MIPS-II processors. The Q_PROCESSOR_MIPS and Q_PROCESSOR_MIPS_I macros are also defined when Q_PROCESSOR_MIPS_II is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_III

Defined if the application is compiled for MIPS-III processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, and Q_PROCESSOR_MIPS_II macros are also defined when Q_PROCESSOR_MIPS_III is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_IV

Defined if the application is compiled for MIPS-IV processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, and Q_PROCESSOR_MIPS_III macros are also defined when Q_PROCESSOR_MIPS_IV is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_V

Defined if the application is compiled for MIPS-V processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, and Q_PROCESSOR_MIPS_IV macros are also defined when Q_PROCESSOR_MIPS_V is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER

Defined if the application is compiled for POWER processors. Qt currently supports two Power variants: Q_PROCESSOR_POWER_32 and Q_PROCESSOR_POWER_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER_32

Defined if the application is compiled for 32-bit Power processors. The Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER_64

Defined if the application is compiled for 64-bit Power processors. The Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_64 is defined.

See also QSysInfo::buildCpuArchitecture().

[since 5.13] Q_PROCESSOR_RISCV

Defined if the application is compiled for RISC-V processors. Qt currently supports two RISC-V variants: Q_PROCESSOR_RISCV_32 and Q_PROCESSOR_RISCV_64.

This macro was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

[since 5.13] Q_PROCESSOR_RISCV_32

Defined if the application is compiled for 32-bit RISC-V processors. The Q_PROCESSOR_RISCV macro is also defined when Q_PROCESSOR_RISCV_32 is defined.

This macro was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

[since 5.13] Q_PROCESSOR_RISCV_64

Defined if the application is compiled for 64-bit RISC-V processors. The Q_PROCESSOR_RISCV macro is also defined when Q_PROCESSOR_RISCV_64 is defined.

This macro was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_S390_X

Defined if the application is compiled for S/390x processors. The Q_PROCESSOR_S390 macro is also defined when Q_PROCESSOR_S390_X is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SH

Defined if the application is compiled for SuperH processors. Qt currently supports one SuperH revision: Q_PROCESSOR_SH_4A.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SH_4A

Defined if the application is compiled for SuperH 4A processors. The Q_PROCESSOR_SH macro is also defined when Q_PROCESSOR_SH_4A is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SPARC

Defined if the application is compiled for SPARC processors. Qt currently supports one optional SPARC revision: Q_PROCESSOR_SPARC_V9.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SPARC_V9

Defined if the application is compiled for SPARC V9 processors. The Q_PROCESSOR_SPARC macro is also defined when Q_PROCESSOR_SPARC_V9 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_X86_32

Defined if the application is compiled for 32-bit x86 processors. This includes all i386, i486, i586, and i686 processors. The Q_PROCESSOR_X86 macro is also defined when Q_PROCESSOR_X86_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_X86_64

Defined if the application is compiled for 64-bit x86 processors. This includes all AMD64, Intel 64, and other x86_64/x64 processors. The Q_PROCESSOR_X86 macro is also defined when Q_PROCESSOR_X86_64 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_UNLIKELY(expr)

Hints to the compiler that the enclosed condition, expr, is likely to evaluate to false.

Use of this macro can help the compiler to optimize the code.

Example:

bool readConfiguration(const QFile &file)
{
    // We expect to be asked to read an existing file
    if (Q_UNLIKELY(!file.exists())) {
        qWarning() << "File not found";
        return false;
    }

    ...
    return true;
}

See also Q_LIKELY().

Q_UNUSED(name)

Indicates to the compiler that the parameter with the specified name is not used in the body of a function. This can be used to suppress compiler warnings while allowing functions to be defined with meaningful parameter names in their signatures.

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.