src/corelib/global/qglobal.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qplatformdefs.h"
  43 #include "qstring.h"
  44 #include "qvector.h"
  45 #include "qlist.h"
  46 #include "qthreadstorage.h"
  47 #include "qdir.h"
  48 #include "qdatetime.h"
  49
  50 #ifndef QT_NO_QOBJECT
  51 #include <private/qthread_p.h>
  52 #endif
  53
  54 #include <stdlib.h>
  55 #include <limits.h>
  56 #include <stdarg.h>
  57 #include <string.h>
  58
  59 #ifndef QT_NO_EXCEPTIONS
  60 #  include <string>
  61 #  include <exception>
  62 #endif
  63
  64 #if !defined(Q_OS_WINCE)
  65 #  include <errno.h>
  66 #  if defined(Q_CC_MSVC)
  67 #    include <crtdbg.h>
  68 #  endif
  69 #endif
  70
  71 #if defined(Q_OS_VXWORKS)
  72 #  include <envLib.h>
  73 #endif
  74
  75 #if defined(Q_OS_MAC) && !defined(Q_OS_IOS)
  76 #include <CoreServices/CoreServices.h>
  77 #endif
  78
  79 QT_BEGIN_NAMESPACE
  80
  81 #if !QT_DEPRECATED_SINCE(5, 0)
  82 // Make sure they're defined to be exported
  83 Q_CORE_EXPORT void *qMemCopy(void *dest, const void *src, size_t n);
  84 Q_CORE_EXPORT void *qMemSet(void *dest, int c, size_t n);
  85 #endif
  86
  87 /*!
  88     \class QFlag
  89     \inmodule QtCore
  90     \brief The QFlag class is a helper data type for QFlags.
  91
  92     It is equivalent to a plain \c int, except with respect to
  93     function overloading and type conversions. You should never need
  94     to use this class in your applications.
  95
  96     \sa QFlags
  97 */
  98
  99 /*!
 100     \fn QFlag::QFlag(int value)
 101
 102     Constructs a QFlag object that stores the given \a value.
 103 */
 104
 105 /*!
 106     \fn QFlag::operator int() const
 107
 108     Returns the value stored by the QFlag object.
 109 */
 110
 111 /*!
 112     \class QFlags
 113     \inmodule QtCore
 114     \brief The QFlags class provides a type-safe way of storing
 115     OR-combinations of enum values.
 116
 117
 118     \ingroup tools
 119
 120     The QFlags<Enum> class is a template class, where Enum is an enum
 121     type. QFlags is used throughout Qt for storing combinations of
 122     enum values.
 123
 124     The traditional C++ approach for storing OR-combinations of enum
 125     values is to use an \c int or \c uint variable. The inconvenience
 126     with this approach is that there's no type checking at all; any
 127     enum value can be OR'd with any other enum value and passed on to
 128     a function that takes an \c int or \c uint.
 129
 130     Qt uses QFlags to provide type safety. For example, the
 131     Qt::Alignment type is simply a typedef for
 132     QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() takes a
 133     Qt::Alignment parameter, which means that any combination of
 134     Qt::AlignmentFlag values, or 0, is legal:
 135
 136     \snippet code/src_corelib_global_qglobal.cpp 0
 137
 138     If you try to pass a value from another enum or just a plain
 139     integer other than 0, the compiler will report an error. If you
 140     need to cast integer values to flags in a untyped fashion, you can
 141     use the explicit QFlags constructor as cast operator.
 142
 143     If you want to use QFlags for your own enum types, use
 144     the Q_DECLARE_FLAGS() and Q_DECLARE_OPERATORS_FOR_FLAGS().
 145
 146     Example:
 147
 148     \snippet code/src_corelib_global_qglobal.cpp 1
 149
 150     You can then use the \c MyClass::Options type to store
 151     combinations of \c MyClass::Option values.
 152
 153     \section1 Flags and the Meta-Object System
 154
 155     The Q_DECLARE_FLAGS() macro does not expose the flags to the meta-object
 156     system, so they cannot be used by Qt Script or edited in Qt Designer.
 157     To make the flags available for these purposes, the Q_FLAGS() macro must
 158     be used:
 159
 160     \snippet code/src_corelib_global_qglobal.cpp meta-object flags
 161
 162     \section1 Naming Convention
 163
 164     A sensible naming convention for enum types and associated QFlags
 165     types is to give a singular name to the enum type (e.g., \c
 166     Option) and a plural name to the QFlags type (e.g., \c Options).
 167     When a singular name is desired for the QFlags type (e.g., \c
 168     Alignment), you can use \c Flag as the suffix for the enum type
 169     (e.g., \c AlignmentFlag).
 170
 171     \sa QFlag
 172 */
 173
 174 /*!
 175     \typedef QFlags::Int
 176     \since 5.0
 177
 178     Typedef for the integer type used for storage as well as for
 179     implicit conversion. Either \c int or \c{unsigned int}, depending
 180     on whether the enum's underlying type is signed or unsigned.
 181 */
 182
 183 /*!
 184     \typedef QFlags::enum_type
 185
 186     Typedef for the Enum template type.
 187 */
 188
 189 /*!
 190     \fn QFlags::QFlags(const QFlags &other)
 191
 192     Constructs a copy of \a other.
 193 */
 194
 195 /*!
 196     \fn QFlags::QFlags(Enum flag)
 197
 198     Constructs a QFlags object storing the given \a flag.
 199 */
 200
 201 /*!
 202     \fn QFlags::QFlags(Zero zero)
 203
 204     Constructs a QFlags object with no flags set. \a zero must be a
 205     literal 0 value.
 206 */
 207
 208 /*!
 209     \fn QFlags::QFlags(QFlag value)
 210
 211     Constructs a QFlags object initialized with the given integer \a
 212     value.
 213
 214     The QFlag type is a helper type. By using it here instead of \c
 215     int, we effectively ensure that arbitrary enum values cannot be
 216     cast to a QFlags, whereas untyped enum values (i.e., \c int
 217     values) can.
 218 */
 219
 220 /*!
 221     \fn QFlags &QFlags::operator=(const QFlags &other)
 222
 223     Assigns \a other to this object and returns a reference to this
 224     object.
 225 */
 226
 227 /*!
 228     \fn QFlags &QFlags::operator&=(int mask)
 229
 230     Performs a bitwise AND operation with \a mask and stores the
 231     result in this QFlags object. Returns a reference to this object.
 232
 233     \sa operator&(), operator|=(), operator^=()
 234 */
 235
 236 /*!
 237     \fn QFlags &QFlags::operator&=(uint mask)
 238
 239     \overload
 240 */
 241
 242 /*!
 243     \fn QFlags &QFlags::operator|=(QFlags other)
 244
 245     Performs a bitwise OR operation with \a other and stores the
 246     result in this QFlags object. Returns a reference to this object.
 247
 248     \sa operator|(), operator&=(), operator^=()
 249 */
 250
 251 /*!
 252     \fn QFlags &QFlags::operator|=(Enum other)
 253
 254     \overload
 255 */
 256
 257 /*!
 258     \fn QFlags &QFlags::operator^=(QFlags other)
 259
 260     Performs a bitwise XOR operation with \a other and stores the
 261     result in this QFlags object. Returns a reference to this object.
 262
 263     \sa operator^(), operator&=(), operator|=()
 264 */
 265
 266 /*!
 267     \fn QFlags &QFlags::operator^=(Enum other)
 268
 269     \overload
 270 */
 271
 272 /*!
 273     \fn QFlags::operator Int() const
 274
 275     Returns the value stored in the QFlags object as an integer.
 276
 277     \sa Int
 278 */
 279
 280 /*!
 281     \fn QFlags QFlags::operator|(QFlags other) const
 282
 283     Returns a QFlags object containing the result of the bitwise OR
 284     operation on this object and \a other.
 285
 286     \sa operator|=(), operator^(), operator&(), operator~()
 287 */
 288
 289 /*!
 290     \fn QFlags QFlags::operator|(Enum other) const
 291
 292     \overload
 293 */
 294
 295 /*!
 296     \fn QFlags QFlags::operator^(QFlags other) const
 297
 298     Returns a QFlags object containing the result of the bitwise XOR
 299     operation on this object and \a other.
 300
 301     \sa operator^=(), operator&(), operator|(), operator~()
 302 */
 303
 304 /*!
 305     \fn QFlags QFlags::operator^(Enum other) const
 306
 307     \overload
 308 */
 309
 310 /*!
 311     \fn QFlags QFlags::operator&(int mask) const
 312
 313     Returns a QFlags object containing the result of the bitwise AND
 314     operation on this object and \a mask.
 315
 316     \sa operator&=(), operator|(), operator^(), operator~()
 317 */
 318
 319 /*!
 320     \fn QFlags QFlags::operator&(uint mask) const
 321
 322     \overload
 323 */
 324
 325 /*!
 326     \fn QFlags QFlags::operator&(Enum mask) const
 327
 328     \overload
 329 */
 330
 331 /*!
 332     \fn QFlags QFlags::operator~() const
 333
 334     Returns a QFlags object that contains the bitwise negation of
 335     this object.
 336
 337     \sa operator&(), operator|(), operator^()
 338 */
 339
 340 /*!
 341     \fn bool QFlags::operator!() const
 342
 343     Returns true if no flag is set (i.e., if the value stored by the
 344     QFlags object is 0); otherwise returns false.
 345 */
 346
 347 /*!
 348     \fn bool QFlags::testFlag(Enum flag) const
 349     \since 4.2
 350
 351     Returns true if the \a flag is set, otherwise false.
 352 */
 353
 354 /*!
 355   \macro Q_DISABLE_COPY(Class)
 356   \relates QObject
 357
 358   Disables the use of copy constructors and assignment operators
 359   for the given \a Class.
 360
 361   Instances of subclasses of QObject should not be thought of as
 362   values that can be copied or assigned, but as unique identities.
 363   This means that when you create your own subclass of QObject
 364   (director or indirect), you should \e not give it a copy constructor
 365   or an assignment operator.  However, it may not enough to simply
 366   omit them from your class, because, if you mistakenly write some code
 367   that requires a copy constructor or an assignment operator (it's easy
 368   to do), your compiler will thoughtfully create it for you. You must
 369   do more.
 370
 371   The curious user will have seen that the Qt classes derived
 372   from QObject typically include this macro in a private section:
 373
 374   \snippet code/src_corelib_global_qglobal.cpp 43
 375
 376   It declares a copy constructor and an assignment operator in the
 377   private section, so that if you use them by mistake, the compiler
 378   will report an error.
 379
 380   \snippet code/src_corelib_global_qglobal.cpp 44
 381
 382   But even this might not catch absolutely every case. You might be
 383   tempted to do something like this:
 384
 385   \snippet code/src_corelib_global_qglobal.cpp 45
 386
 387   First of all, don't do that. Most compilers will generate code that
 388   uses the copy constructor, so the privacy violation error will be
 389   reported, but your C++ compiler is not required to generate code for
 390   this statement in a specific way. It could generate code using
 391   \e{neither} the copy constructor \e{nor} the assignment operator we
 392   made private. In that case, no error would be reported, but your
 393   application would probably crash when you called a member function
 394   of \c{w}.
 395 */
 396
 397 /*!
 398     \macro Q_DECLARE_FLAGS(Flags, Enum)
 399     \relates QFlags
 400
 401     The Q_DECLARE_FLAGS() macro expands to
 402
 403     \snippet code/src_corelib_global_qglobal.cpp 2
 404
 405     \a Enum is the name of an existing enum type, whereas \a Flags is
 406     the name of the QFlags<\e{Enum}> typedef.
 407
 408     See the QFlags documentation for details.
 409
 410     \sa Q_DECLARE_OPERATORS_FOR_FLAGS()
 411 */
 412
 413 /*!
 414     \macro Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)
 415     \relates QFlags
 416
 417     The Q_DECLARE_OPERATORS_FOR_FLAGS() macro declares global \c
 418     operator|() functions for \a Flags, which is of type QFlags<T>.
 419
 420     See the QFlags documentation for details.
 421
 422     \sa Q_DECLARE_FLAGS()
 423 */
 424
 425 /*!
 426     \headerfile <QtGlobal>
 427     \title Global Qt Declarations
 428     \ingroup funclists
 429
 430     \brief The <QtGlobal> header file includes the fundamental global
 431     declarations. It is included by most other Qt header files.
 432
 433     The global declarations include \l{types}, \l{functions} and
 434     \l{macros}.
 435
 436     The type definitions are partly convenience definitions for basic
 437     types (some of which guarantee certain bit-sizes on all platforms
 438     supported by Qt), partly types related to Qt message handling. The
 439     functions are related to generating messages, Qt version handling
 440     and comparing and adjusting object values. And finally, some of
 441     the declared macros enable programmers to add compiler or platform
 442     specific code to their applications, while others are convenience
 443     macros for larger operations.
 444
 445     \section1 Types
 446
 447     The header file declares several type definitions that guarantee a
 448     specified bit-size on all platforms supported by Qt for various
 449     basic types, for example \l qint8 which is a signed char
 450     guaranteed to be 8-bit on all platforms supported by Qt. The
 451     header file also declares the \l qlonglong type definition for \c
 452     {long long int } (\c __int64 on Windows).
 453
 454     Several convenience type definitions are declared: \l qreal for \c
 455     double, \l uchar for \c unsigned char, \l uint for \c unsigned
 456     int, \l ulong for \c unsigned long and \l ushort for \c unsigned
 457     short.
 458
 459     Finally, the QtMsgType definition identifies the various messages
 460     that can be generated and sent to a Qt message handler;
 461     QtMessageHandler is a type definition for a pointer to a function with
 462     the signature
 463     \c {void myMessageHandler(QtMsgType, const QMessageLogContext &, const char *)}.
 464     QMessageLogContext class contains the line, file, and function the
 465     message was logged at. This information is created by the QMessageLogger
 466     class.
 467
 468     \section1 Functions
 469
 470     The <QtGlobal> header file contains several functions comparing
 471     and adjusting an object's value. These functions take a template
 472     type as argument: You can retrieve the absolute value of an object
 473     using the qAbs() function, and you can bound a given object's
 474     value by given minimum and maximum values using the qBound()
 475     function. You can retrieve the minimum and maximum of two given
 476     objects using qMin() and qMax() respectively. All these functions
 477     return a corresponding template type; the template types can be
 478     replaced by any other type.
 479
 480     Example:
 481
 482     \snippet code/src_corelib_global_qglobal.cpp 3
 483
 484     <QtGlobal> also contains functions that generate messages from the
 485     given string argument: qCritical(), qDebug(), qFatal() and
 486     qWarning(). These functions call the message handler with the
 487     given message.
 488
 489     Example:
 490
 491     \snippet code/src_corelib_global_qglobal.cpp 4
 492
 493     The remaining functions are qRound() and qRound64(), which both
 494     accept a \l qreal value as their argument returning the value
 495     rounded up to the nearest integer and 64-bit integer respectively,
 496     the qInstallMessageHandler() function which installs the given
 497     QtMessageHandler, and the qVersion() function which returns the
 498     version number of Qt at run-time as a string.
 499
 500     \section1 Macros
 501
 502     The <QtGlobal> header file provides a range of macros (Q_CC_*)
 503     that are defined if the application is compiled using the
 504     specified platforms. For example, the Q_CC_SUN macro is defined if
 505     the application is compiled using Forte Developer, or Sun Studio
 506     C++.  The header file also declares a range of macros (Q_OS_*)
 507     that are defined for the specified platforms. For example,
 508     Q_OS_X11 which is defined for the X Window System.
 509
 510     The purpose of these macros is to enable programmers to add
 511     compiler or platform specific code to their application.
 512
 513     The remaining macros are convenience macros for larger operations:
 514     The QT_TRANSLATE_NOOP() and QT_TR_NOOP() macros provide the
 515     possibility of marking text for dynamic translation,
 516     i.e. translation without changing the stored source text. The
 517     Q_ASSERT() and Q_ASSERT_X() enables warning messages of various
 518     level of refinement. The Q_FOREACH() and foreach() macros
 519     implement Qt's foreach loop.
 520
 521     The Q_INT64_C() and Q_UINT64_C() macros wrap signed and unsigned
 522     64-bit integer literals in a platform-independent way. The
 523     Q_CHECK_PTR() macro prints a warning containing the source code's
 524     file name and line number, saying that the program ran out of
 525     memory, if the pointer is 0. The qPrintable() macro represent an
 526     easy way of printing text.
 527
 528     Finally, the QT_POINTER_SIZE macro expands to the size of a
 529     pointer in bytes, and the QT_VERSION and QT_VERSION_STR macros
 530     expand to a numeric value or a string, respectively, specifying
 531     Qt's version number, i.e the version the application is compiled
 532     against.
 533
 534     \sa <QtAlgorithms>, QSysInfo
 535 */
 536
 537 /*!
 538     \typedef qreal
 539     \relates <QtGlobal>
 540
 541     Typedef for \c double on all platforms except for those using CPUs with
 542     ARM architectures.
 543     On ARM-based platforms, \c qreal is a typedef for \c float for performance
 544     reasons.
 545 */
 546
 547 /*! \typedef uchar
 548     \relates <QtGlobal>
 549
 550     Convenience typedef for \c{unsigned char}.
 551 */
 552
 553 /*! \typedef ushort
 554     \relates <QtGlobal>
 555
 556     Convenience typedef for \c{unsigned short}.
 557 */
 558
 559 /*! \typedef uint
 560     \relates <QtGlobal>
 561
 562     Convenience typedef for \c{unsigned int}.
 563 */
 564
 565 /*! \typedef ulong
 566     \relates <QtGlobal>
 567
 568     Convenience typedef for \c{unsigned long}.
 569 */
 570
 571 /*! \typedef qint8
 572     \relates <QtGlobal>
 573
 574     Typedef for \c{signed char}. This type is guaranteed to be 8-bit
 575     on all platforms supported by Qt.
 576 */
 577
 578 /*!
 579     \typedef quint8
 580     \relates <QtGlobal>
 581
 582     Typedef for \c{unsigned char}. This type is guaranteed to
 583     be 8-bit on all platforms supported by Qt.
 584 */
 585
 586 /*! \typedef qint16
 587     \relates <QtGlobal>
 588
 589     Typedef for \c{signed short}. This type is guaranteed to be
 590     16-bit on all platforms supported by Qt.
 591 */
 592
 593 /*!
 594     \typedef quint16
 595     \relates <QtGlobal>
 596
 597     Typedef for \c{unsigned short}. This type is guaranteed to
 598     be 16-bit on all platforms supported by Qt.
 599 */
 600
 601 /*! \typedef qint32
 602     \relates <QtGlobal>
 603
 604     Typedef for \c{signed int}. This type is guaranteed to be 32-bit
 605     on all platforms supported by Qt.
 606 */
 607
 608 /*!
 609     \typedef quint32
 610     \relates <QtGlobal>
 611
 612     Typedef for \c{unsigned int}. This type is guaranteed to
 613     be 32-bit on all platforms supported by Qt.
 614 */
 615
 616 /*! \typedef qint64
 617     \relates <QtGlobal>
 618
 619     Typedef for \c{long long int} (\c __int64 on Windows). This type
 620     is guaranteed to be 64-bit on all platforms supported by Qt.
 621
 622     Literals of this type can be created using the Q_INT64_C() macro:
 623
 624     \snippet code/src_corelib_global_qglobal.cpp 5
 625
 626     \sa Q_INT64_C(), quint64, qlonglong
 627 */
 628
 629 /*!
 630     \typedef quint64
 631     \relates <QtGlobal>
 632
 633     Typedef for \c{unsigned long long int} (\c{unsigned __int64} on
 634     Windows). This type is guaranteed to be 64-bit on all platforms
 635     supported by Qt.
 636
 637     Literals of this type can be created using the Q_UINT64_C()
 638     macro:
 639
 640     \snippet code/src_corelib_global_qglobal.cpp 6
 641
 642     \sa Q_UINT64_C(), qint64, qulonglong
 643 */
 644
 645 /*!
 646     \typedef quintptr
 647     \relates <QtGlobal>
 648
 649     Integral type for representing a pointers (useful for hashing,
 650     etc.).
 651
 652     Typedef for either quint32 or quint64. This type is guaranteed to
 653     be the same size as a pointer on all platforms supported by Qt. On
 654     a system with 32-bit pointers, quintptr is a typedef for quint32;
 655     on a system with 64-bit pointers, quintptr is a typedef for
 656     quint64.
 657
 658     Note that quintptr is unsigned. Use qptrdiff for signed values.
 659
 660     \sa qptrdiff, quint32, quint64
 661 */
 662
 663 /*!
 664     \typedef qptrdiff
 665     \relates <QtGlobal>
 666
 667     Integral type for representing pointer differences.
 668
 669     Typedef for either qint32 or qint64. This type is guaranteed to be
 670     the same size as a pointer on all platforms supported by Qt. On a
 671     system with 32-bit pointers, quintptr is a typedef for quint32; on
 672     a system with 64-bit pointers, quintptr is a typedef for quint64.
 673
 674     Note that qptrdiff is signed. Use quintptr for unsigned values.
 675
 676     \sa quintptr, qint32, qint64
 677 */
 678
 679 /*!
 680     \enum QtMsgType
 681     \relates <QtGlobal>
 682
 683     This enum describes the messages that can be sent to a message
 684     handler (QtMsgHandler). You can use the enum to identify and
 685     associate the various message types with the appropriate
 686     actions.
 687
 688     \value QtDebugMsg
 689            A message generated by the qDebug() function.
 690     \value QtWarningMsg
 691            A message generated by the qWarning() function.
 692     \value QtCriticalMsg
 693            A message generated by the qCritical() function.
 694     \value QtFatalMsg
 695            A message generated by the qFatal() function.
 696     \value QtSystemMsg
 697
 698
 699     \sa QtMessageHandler, qInstallMessageHandler()
 700 */
 701
 702 /*! \typedef QFunctionPointer
 703     \relates <QtGlobal>
 704
 705     This is a typedef for \c{void (*)()}, a pointer to a function that takes
 706     no arguments and returns void.
 707 */
 708
 709 /*! \macro qint64 Q_INT64_C(literal)
 710     \relates <QtGlobal>
 711
 712     Wraps the signed 64-bit integer \a literal in a
 713     platform-independent way.
 714
 715     Example:
 716
 717     \snippet code/src_corelib_global_qglobal.cpp 8
 718
 719     \sa qint64, Q_UINT64_C()
 720 */
 721
 722 /*! \macro quint64 Q_UINT64_C(literal)
 723     \relates <QtGlobal>
 724
 725     Wraps the unsigned 64-bit integer \a literal in a
 726     platform-independent way.
 727
 728     Example:
 729
 730     \snippet code/src_corelib_global_qglobal.cpp 9
 731
 732     \sa quint64, Q_INT64_C()
 733 */
 734
 735 /*! \typedef qlonglong
 736     \relates <QtGlobal>
 737
 738     Typedef for \c{long long int} (\c __int64 on Windows). This is
 739     the same as \l qint64.
 740
 741     \sa qulonglong, qint64
 742 */
 743
 744 /*!
 745     \typedef qulonglong
 746     \relates <QtGlobal>
 747
 748     Typedef for \c{unsigned long long int} (\c{unsigned __int64} on
 749     Windows). This is the same as \l quint64.
 750
 751     \sa quint64, qlonglong
 752 */
 753
 754 /*! \fn T qAbs(const T &value)
 755     \relates <QtGlobal>
 756
 757     Compares \a value to the 0 of type T and returns the absolute
 758     value. Thus if T is \e {double}, then \a value is compared to
 759     \e{(double) 0}.
 760
 761     Example:
 762
 763     \snippet code/src_corelib_global_qglobal.cpp 10
 764 */
 765
 766 /*! \fn int qRound(qreal value)
 767     \relates <QtGlobal>
 768
 769     Rounds \a value to the nearest integer.
 770
 771     Example:
 772
 773     \snippet code/src_corelib_global_qglobal.cpp 11
 774 */
 775
 776 /*! \fn qint64 qRound64(qreal value)
 777     \relates <QtGlobal>
 778
 779     Rounds \a value to the nearest 64-bit integer.
 780
 781     Example:
 782
 783     \snippet code/src_corelib_global_qglobal.cpp 12
 784 */
 785
 786 /*! \fn const T &qMin(const T &value1, const T &value2)
 787     \relates <QtGlobal>
 788
 789     Returns the minimum of \a value1 and \a value2.
 790
 791     Example:
 792
 793     \snippet code/src_corelib_global_qglobal.cpp 13
 794
 795     \sa qMax(), qBound()
 796 */
 797
 798 /*! \fn const T &qMax(const T &value1, const T &value2)
 799     \relates <QtGlobal>
 800
 801     Returns the maximum of \a value1 and \a value2.
 802
 803     Example:
 804
 805     \snippet code/src_corelib_global_qglobal.cpp 14
 806
 807     \sa qMin(), qBound()
 808 */
 809
 810 /*! \fn const T &qBound(const T &min, const T &value, const T &max)
 811     \relates <QtGlobal>
 812
 813     Returns \a value bounded by \a min and \a max. This is equivalent
 814     to qMax(\a min, qMin(\a value, \a max)).
 815
 816     Example:
 817
 818     \snippet code/src_corelib_global_qglobal.cpp 15
 819
 820     \sa qMin(), qMax()
 821 */
 822
 823 /*!
 824     \macro QT_VERSION_CHECK
 825     \relates <QtGlobal>
 826
 827     Turns the major, minor and patch numbers of a version into an
 828     integer, 0xMMNNPP (MM = major, NN = minor, PP = patch). This can
 829     be compared with another similarly processed version id.
 830
 831     \sa QT_VERSION
 832 */
 833
 834 /*!
 835     \macro QT_VERSION
 836     \relates <QtGlobal>
 837
 838     This macro expands a numeric value of the form 0xMMNNPP (MM =
 839     major, NN = minor, PP = patch) that specifies Qt's version
 840     number. For example, if you compile your application against Qt
 841     4.1.2, the QT_VERSION macro will expand to 0x040102.
 842
 843     You can use QT_VERSION to use the latest Qt features where
 844     available.
 845
 846     Example:
 847
 848     \snippet code/src_corelib_global_qglobal.cpp 16
 849
 850     \sa QT_VERSION_STR, qVersion()
 851 */
 852
 853 /*!
 854     \macro QT_VERSION_STR
 855     \relates <QtGlobal>
 856
 857     This macro expands to a string that specifies Qt's version number
 858     (for example, "4.1.2"). This is the version against which the
 859     application is compiled.
 860
 861     \sa qVersion(), QT_VERSION
 862 */
 863
 864 /*!
 865     \relates <QtGlobal>
 866
 867     Returns the version number of Qt at run-time as a string (for
 868     example, "4.1.2"). This may be a different version than the
 869     version the application was compiled against.
 870
 871     \sa QT_VERSION_STR
 872 */
 873
 874 const char *qVersion() Q_DECL_NOTHROW
 875 {
 876     return QT_VERSION_STR;
 877 }
 878
 879 bool qSharedBuild() Q_DECL_NOTHROW
 880 {
 881 #ifdef QT_SHARED
 882     return true;
 883 #else
 884     return false;
 885 #endif
 886 }
 887
 888 /*****************************************************************************
 889   System detection routines
 890  *****************************************************************************/
 891
 892 /*!
 893     \class QSysInfo
 894     \inmodule QtCore
 895     \brief The QSysInfo class provides information about the system.
 896
 897     \list
 898     \li \l WordSize specifies the size of a pointer for the platform
 899        on which the application is compiled.
 900     \li \l ByteOrder specifies whether the platform is big-endian or
 901        little-endian.
 902     \li \l WindowsVersion specifies the version of the Windows operating
 903        system on which the application is run (Windows only)
 904     \li \l MacintoshVersion specifies the version of the Macintosh
 905        operating system on which the application is run (Mac only).
 906     \endlist
 907
 908     Some constants are defined only on certain platforms. You can use
 909     the preprocessor symbols Q_OS_WIN and Q_OS_MAC to test that
 910     the application is compiled under Windows or Mac.
 911
 912     \sa QLibraryInfo
 913 */
 914
 915 /*!
 916     \enum QSysInfo::Sizes
 917
 918     This enum provides platform-specific information about the sizes of data
 919     structures used by the underlying architecture.
 920
 921     \value WordSize The size in bits of a pointer for the platform on which
 922            the application is compiled (32 or 64).
 923 */
 924
 925 /*!
 926     \variable QSysInfo::WindowsVersion
 927     \brief the version of the Windows operating system on which the
 928            application is run (Windows only)
 929 */
 930
 931 /*!
 932     \fn QSysInfo::WindowsVersion QSysInfo::windowsVersion()
 933     \since 4.4
 934
 935     Returns the version of the Windows operating system on which the
 936     application is run (Windows only).
 937 */
 938
 939 /*!
 940     \variable QSysInfo::MacintoshVersion
 941     \brief the version of the Macintosh operating system on which
 942            the application is run (Mac only).
 943 */
 944
 945 /*!
 946     \fn QSysInfo::MacVersion QSysInfo::macVersion()
 947
 948     Returns the version of Mac OS X on which the application is run (Mac OS X
 949     Only).
 950 */
 951
 952 /*!
 953     \enum QSysInfo::Endian
 954
 955     \value BigEndian  Big-endian byte order (also called Network byte order)
 956     \value LittleEndian  Little-endian byte order
 957     \value ByteOrder  Equals BigEndian or LittleEndian, depending on
 958                       the platform's byte order.
 959 */
 960
 961 /*!
 962     \enum QSysInfo::WinVersion
 963
 964     This enum provides symbolic names for the various versions of the
 965     Windows operating system. On Windows, the
 966     QSysInfo::WindowsVersion variable gives the version of the system
 967     on which the application is run.
 968
 969     MS-DOS-based versions:
 970
 971     \value WV_32s   Windows 3.1 with Win 32s
 972     \value WV_95    Windows 95
 973     \value WV_98    Windows 98
 974     \value WV_Me    Windows Me
 975
 976     NT-based versions (note that each operating system version is only represented once rather than each Windows edition):
 977
 978     \value WV_NT    Windows NT (operating system version 4.0)
 979     \value WV_2000  Windows 2000 (operating system version 5.0)
 980     \value WV_XP    Windows XP (operating system version 5.1)
 981     \value WV_2003  Windows Server 2003, Windows Server 2003 R2, Windows Home Server, Windows XP Professional x64 Edition (operating system version 5.2)
 982     \value WV_VISTA Windows Vista, Windows Server 2008 (operating system version 6.0)
 983     \value WV_WINDOWS7 Windows 7, Windows Server 2008 R2 (operating system version 6.1)
 984     \value WV_WINDOWS8 Windows 8 (operating system version 6.2)
 985
 986     Alternatively, you may use the following macros which correspond directly to the Windows operating system version number:
 987
 988     \value WV_4_0   Operating system version 4.0, corresponds to Windows NT
 989     \value WV_5_0   Operating system version 5.0, corresponds to Windows 2000
 990     \value WV_5_1   Operating system version 5.1, corresponds to Windows XP
 991     \value WV_5_2   Operating system version 5.2, corresponds to Windows Server 2003, Windows Server 2003 R2, Windows Home Server, and Windows XP Professional x64 Edition
 992     \value WV_6_0   Operating system version 6.0, corresponds to Windows Vista and Windows Server 2008
 993     \value WV_6_1   Operating system version 6.1, corresponds to Windows 7 and Windows Server 2008 R2
 994     \value WV_6_2   Operating system version 6.2, corresponds to Windows 8
 995
 996     CE-based versions:
 997
 998     \value WV_CE    Windows CE
 999     \value WV_CENET Windows CE .NET
1000     \value WV_CE_5  Windows CE 5.x
1001     \value WV_CE_6  Windows CE 6.x
1002
1003     The following masks can be used for testing whether a Windows
1004     version is MS-DOS-based, NT-based, or CE-based:
1005
1006     \value WV_DOS_based MS-DOS-based version of Windows
1007     \value WV_NT_based  NT-based version of Windows
1008     \value WV_CE_based  CE-based version of Windows
1009
1010     \sa MacVersion
1011 */
1012
1013 /*!
1014     \enum QSysInfo::MacVersion
1015
1016     This enum provides symbolic names for the various versions of the
1017     Macintosh operating system. On Mac, the
1018     QSysInfo::MacintoshVersion variable gives the version of the
1019     system on which the application is run.
1020
1021     \value MV_9        Mac OS 9 (unsupported)
1022     \value MV_10_0     Mac OS X 10.0 (unsupported)
1023     \value MV_10_1     Mac OS X 10.1 (unsupported)
1024     \value MV_10_2     Mac OS X 10.2 (unsupported)
1025     \value MV_10_3     Mac OS X 10.3
1026     \value MV_10_4     Mac OS X 10.4
1027     \value MV_10_5     Mac OS X 10.5
1028     \value MV_10_6     Mac OS X 10.6
1029     \value MV_10_7     Mac OS X 10.7
1030     \value MV_10_8     Mac OS X 10.8
1031     \value MV_Unknown  An unknown and currently unsupported platform
1032
1033     \value MV_CHEETAH  Apple codename for MV_10_0
1034     \value MV_PUMA     Apple codename for MV_10_1
1035     \value MV_JAGUAR   Apple codename for MV_10_2
1036     \value MV_PANTHER  Apple codename for MV_10_3
1037     \value MV_TIGER    Apple codename for MV_10_4
1038     \value MV_LEOPARD  Apple codename for MV_10_5
1039     \value MV_SNOWLEOPARD  Apple codename for MV_10_6
1040     \value MV_LION     Apple codename for MV_10_7
1041     \value MV_MOUNTAINLION Apple codename for MV_10_8
1042
1043     \sa WinVersion
1044 */
1045
1046 /*!
1047     \macro Q_OS_DARWIN
1048     \relates <QtGlobal>
1049
1050     Defined on Darwin OS (synonym for Q_OS_MAC).
1051 */
1052
1053 /*!
1054     \macro Q_OS_WIN32
1055     \relates <QtGlobal>
1056
1057     Defined on all supported versions of Windows.
1058 */
1059
1060 /*!
1061     \macro Q_OS_WINCE
1062     \relates <QtGlobal>
1063
1064     Defined on Windows CE.
1065 */
1066
1067 /*!
1068     \macro Q_OS_CYGWIN
1069     \relates <QtGlobal>
1070
1071     Defined on Cygwin.
1072 */
1073
1074 /*!
1075     \macro Q_OS_SOLARIS
1076     \relates <QtGlobal>
1077
1078     Defined on Sun Solaris.
1079 */
1080
1081 /*!
1082     \macro Q_OS_HPUX
1083     \relates <QtGlobal>
1084
1085     Defined on HP-UX.
1086 */
1087
1088 /*!
1089     \macro Q_OS_ULTRIX
1090     \relates <QtGlobal>
1091
1092     Defined on DEC Ultrix.
1093 */
1094
1095 /*!
1096     \macro Q_OS_LINUX
1097     \relates <QtGlobal>
1098
1099     Defined on Linux.
1100 */
1101
1102 /*!
1103     \macro Q_OS_FREEBSD
1104     \relates <QtGlobal>
1105
1106     Defined on FreeBSD.
1107 */
1108
1109 /*!
1110     \macro Q_OS_NETBSD
1111     \relates <QtGlobal>
1112
1113     Defined on NetBSD.
1114 */
1115
1116 /*!
1117     \macro Q_OS_OPENBSD
1118     \relates <QtGlobal>
1119
1120     Defined on OpenBSD.
1121 */
1122
1123 /*!
1124     \macro Q_OS_BSDI
1125     \relates <QtGlobal>
1126
1127     Defined on BSD/OS.
1128 */
1129
1130 /*!
1131     \macro Q_OS_IRIX
1132     \relates <QtGlobal>
1133
1134     Defined on SGI Irix.
1135 */
1136
1137 /*!
1138     \macro Q_OS_OSF
1139     \relates <QtGlobal>
1140
1141     Defined on HP Tru64 UNIX.
1142 */
1143
1144 /*!
1145     \macro Q_OS_SCO
1146     \relates <QtGlobal>
1147
1148     Defined on SCO OpenServer 5.
1149 */
1150
1151 /*!
1152     \macro Q_OS_UNIXWARE
1153     \relates <QtGlobal>
1154
1155     Defined on UnixWare 7, Open UNIX 8.
1156 */
1157
1158 /*!
1159     \macro Q_OS_AIX
1160     \relates <QtGlobal>
1161
1162     Defined on AIX.
1163 */
1164
1165 /*!
1166     \macro Q_OS_HURD
1167     \relates <QtGlobal>
1168
1169     Defined on GNU Hurd.
1170 */
1171
1172 /*!
1173     \macro Q_OS_DGUX
1174     \relates <QtGlobal>
1175
1176     Defined on DG/UX.
1177 */
1178
1179 /*!
1180     \macro Q_OS_RELIANT
1181     \relates <QtGlobal>
1182
1183     Defined on Reliant UNIX.
1184 */
1185
1186 /*!
1187     \macro Q_OS_DYNIX
1188     \relates <QtGlobal>
1189
1190     Defined on DYNIX/ptx.
1191 */
1192
1193 /*!
1194     \macro Q_OS_QNX
1195     \relates <QtGlobal>
1196
1197     Defined on QNX Neutrino.
1198 */
1199
1200 /*!
1201     \macro Q_OS_LYNX
1202     \relates <QtGlobal>
1203
1204     Defined on LynxOS.
1205 */
1206
1207 /*!
1208     \macro Q_OS_BSD4
1209     \relates <QtGlobal>
1210
1211     Defined on Any BSD 4.4 system.
1212 */
1213
1214 /*!
1215     \macro Q_OS_UNIX
1216     \relates <QtGlobal>
1217
1218     Defined on Any UNIX BSD/SYSV system.
1219 */
1220
1221 /*!
1222     \macro Q_CC_SYM
1223     \relates <QtGlobal>
1224
1225     Defined if the application is compiled using Digital Mars C/C++
1226     (used to be Symantec C++).
1227 */
1228
1229 /*!
1230     \macro Q_CC_MSVC
1231     \relates <QtGlobal>
1232
1233     Defined if the application is compiled using Microsoft Visual
1234     C/C++, Intel C++ for Windows.
1235 */
1236
1237 /*!
1238     \macro Q_CC_BOR
1239     \relates <QtGlobal>
1240
1241     Defined if the application is compiled using Borland/Turbo C++.
1242 */
1243
1244 /*!
1245     \macro Q_CC_WAT
1246     \relates <QtGlobal>
1247
1248     Defined if the application is compiled using Watcom C++.
1249 */
1250
1251 /*!
1252     \macro Q_CC_GNU
1253     \relates <QtGlobal>
1254
1255     Defined if the application is compiled using GNU C++.
1256 */
1257
1258 /*!
1259     \macro Q_CC_COMEAU
1260     \relates <QtGlobal>
1261
1262     Defined if the application is compiled using Comeau C++.
1263 */
1264
1265 /*!
1266     \macro Q_CC_EDG
1267     \relates <QtGlobal>
1268
1269     Defined if the application is compiled using Edison Design Group
1270     C++.
1271 */
1272
1273 /*!
1274     \macro Q_CC_OC
1275     \relates <QtGlobal>
1276
1277     Defined if the application is compiled using CenterLine C++.
1278 */
1279
1280 /*!
1281     \macro Q_CC_SUN
1282     \relates <QtGlobal>
1283
1284     Defined if the application is compiled using Forte Developer, or
1285     Sun Studio C++.
1286 */
1287
1288 /*!
1289     \macro Q_CC_MIPS
1290     \relates <QtGlobal>
1291
1292     Defined if the application is compiled using MIPSpro C++.
1293 */
1294
1295 /*!
1296     \macro Q_CC_DEC
1297     \relates <QtGlobal>
1298
1299     Defined if the application is compiled using DEC C++.
1300 */
1301
1302 /*!
1303     \macro Q_CC_HPACC
1304     \relates <QtGlobal>
1305
1306     Defined if the application is compiled using HP aC++.
1307 */
1308
1309 /*!
1310     \macro Q_CC_USLC
1311     \relates <QtGlobal>
1312
1313     Defined if the application is compiled using SCO OUDK and UDK.
1314 */
1315
1316 /*!
1317     \macro Q_CC_CDS
1318     \relates <QtGlobal>
1319
1320     Defined if the application is compiled using Reliant C++.
1321 */
1322
1323 /*!
1324     \macro Q_CC_KAI
1325     \relates <QtGlobal>
1326
1327     Defined if the application is compiled using KAI C++.
1328 */
1329
1330 /*!
1331     \macro Q_CC_INTEL
1332     \relates <QtGlobal>
1333
1334     Defined if the application is compiled using Intel C++ for Linux,
1335     Intel C++ for Windows.
1336 */
1337
1338 /*!
1339     \macro Q_CC_HIGHC
1340     \relates <QtGlobal>
1341
1342     Defined if the application is compiled using MetaWare High C/C++.
1343 */
1344
1345 /*!
1346     \macro Q_CC_PGI
1347     \relates <QtGlobal>
1348
1349     Defined if the application is compiled using Portland Group C++.
1350 */
1351
1352 /*!
1353     \macro Q_CC_GHS
1354     \relates <QtGlobal>
1355
1356     Defined if the application is compiled using Green Hills
1357     Optimizing C++ Compilers.
1358 */
1359
1360 /*!
1361   \macro Q_OS_MAC
1362   \relates <QtGlobal>
1363
1364   Defined on MAC OS (synonym for Darwin).
1365  */
1366
1367 /*!
1368     \macro Q_PROCESSOR_ALPHA
1369     \relates <QtGlobal>
1370
1371     Defined if the application is compiled for Alpha processors.
1372 */
1373
1374 /*!
1375     \macro Q_PROCESSOR_ARM
1376     \relates <QtGlobal>
1377
1378     Defined if the application is compiled for ARM processors. Qt currently
1379     supports three optional ARM revisions: \l Q_PROCESSOR_ARM_V5, \l
1380     Q_PROCESSOR_ARM_V6, and \l Q_PROCESSOR_ARM_V7.
1381 */
1382 /*!
1383     \macro Q_PROCESSOR_ARM_V5
1384     \relates <QtGlobal>
1385
1386     Defined if the application is compiled for ARMv5 processors. The \l
1387     Q_PROCESSOR_ARM macro is also defined when Q_PROCESSOR_ARM_V5 is defined.
1388 */
1389 /*!
1390     \macro Q_PROCESSOR_ARM_V6
1391     \relates <QtGlobal>
1392
1393     Defined if the application is compiled for ARMv6 processors. The \l
1394     Q_PROCESSOR_ARM and \l Q_PROCESSOR_ARM_V5 macros are also defined when
1395     Q_PROCESSOR_ARM_V6 is defined.
1396 */
1397 /*!
1398     \macro Q_PROCESSOR_ARM_V7
1399     \relates <QtGlobal>
1400
1401     Defined if the application is compiled for ARMv7 processors. The \l
1402     Q_PROCESSOR_ARM, \l Q_PROCESSOR_ARM_V5, and \l Q_PROCESSOR_ARM_V6 macros
1403     are also defined when Q_PROCESSOR_ARM_V7 is defined.
1404 */
1405
1406 /*!
1407     \macro Q_PROCESSOR_AVR32
1408     \relates <QtGlobal>
1409
1410     Defined if the application is compiled for AVR32 processors.
1411 */
1412
1413 /*!
1414     \macro Q_PROCESSOR_BLACKFIN
1415     \relates <QtGlobal>
1416
1417     Defined if the application is compiled for Blackfin processors.
1418 */
1419
1420 /*!
1421     \macro Q_PROCESSOR_IA64
1422     \relates <QtGlobal>
1423
1424     Defined if the application is compiled for IA-64 processors. This includes
1425     all Itanium and Itanium 2 processors.
1426 */
1427
1428 /*!
1429     \macro Q_PROCESSOR_MIPS
1430     \relates <QtGlobal>
1431
1432     Defined if the application is compiled for MIPS processors. Qt currently
1433     supports seven MIPS revisions: \l Q_PROCESSOR_MIPS_I, \l
1434     Q_PROCESSOR_MIPS_II, \l Q_PROCESSOR_MIPS_III, \l Q_PROCESSOR_MIPS_IV, \l
1435     Q_PROCESSOR_MIPS_V, \l Q_PROCESSOR_MIPS_32, and \l Q_PROCESSOR_MIPS_64.
1436 */
1437 /*!
1438     \macro Q_PROCESSOR_MIPS_I
1439     \relates <QtGlobal>
1440
1441     Defined if the application is compiled for MIPS-I processors. The \l
1442     Q_PROCESSOR_MIPS macro is also defined when Q_PROCESSOR_MIPS_I is defined.
1443 */
1444 /*!
1445     \macro Q_PROCESSOR_MIPS_II
1446     \relates <QtGlobal>
1447
1448     Defined if the application is compiled for MIPS-II processors. The \l
1449     Q_PROCESSOR_MIPS and \l Q_PROCESSOR_MIPS_I macros are also defined when
1450     Q_PROCESSOR_MIPS_II is defined.
1451 */
1452 /*!
1453     \macro Q_PROCESSOR_MIPS_32
1454     \relates <QtGlobal>
1455
1456     Defined if the application is compiled for MIPS32 processors. The \l
1457     Q_PROCESSOR_MIPS, \l Q_PROCESSOR_MIPS_I, and \l Q_PROCESSOR_MIPS_II macros
1458     are also defined when Q_PROCESSOR_MIPS_32 is defined.
1459 */
1460 /*!
1461     \macro Q_PROCESSOR_MIPS_III
1462     \relates <QtGlobal>
1463
1464     Defined if the application is compiled for MIPS-III processors. The \l
1465     Q_PROCESSOR_MIPS, \l Q_PROCESSOR_MIPS_I, and \l Q_PROCESSOR_MIPS_II macros
1466     are also defined when Q_PROCESSOR_MIPS_III is defined.
1467 */
1468 /*!
1469     \macro Q_PROCESSOR_MIPS_IV
1470     \relates <QtGlobal>
1471
1472     Defined if the application is compiled for MIPS-IV processors. The \l
1473     Q_PROCESSOR_MIPS, \l Q_PROCESSOR_MIPS_I, \l Q_PROCESSOR_MIPS_II, and \l
1474     Q_PROCESSOR_MIPS_III macros are also defined when Q_PROCESSOR_MIPS_IV is
1475     defined.
1476 */
1477 /*!
1478     \macro Q_PROCESSOR_MIPS_V
1479     \relates <QtGlobal>
1480
1481     Defined if the application is compiled for MIPS-V processors. The \l
1482     Q_PROCESSOR_MIPS, \l Q_PROCESSOR_MIPS_I, \l Q_PROCESSOR_MIPS_II, \l
1483     Q_PROCESSOR_MIPS_III, and \l Q_PROCESSOR_MIPS_IV macros are also defined
1484     when Q_PROCESSOR_MIPS_V is defined.
1485 */
1486 /*!
1487     \macro Q_PROCESSOR_MIPS_64
1488     \relates <QtGlobal>
1489
1490     Defined if the application is compiled for MIPS64 processors. The \l
1491     Q_PROCESSOR_MIPS, \l Q_PROCESSOR_MIPS_I, \l Q_PROCESSOR_MIPS_II, \l
1492     Q_PROCESSOR_MIPS_III, \l Q_PROCESSOR_MIPS_IV, and \l Q_PROCESSOR_MIPS_V
1493     macros are also defined when Q_PROCESSOR_MIPS_64 is defined.
1494 */
1495
1496 /*!
1497     \macro Q_PROCESSOR_POWER
1498     \relates <QtGlobal>
1499
1500     Defined if the application is compiled for POWER processors. Qt currently
1501     supports two Power variants: \l Q_PROCESSOR_POWER_32 and \l
1502     Q_PROCESSOR_POWER_64.
1503 */
1504 /*!
1505     \macro Q_PROCESSOR_POWER_32
1506     \relates <QtGlobal>
1507
1508     Defined if the application is compiled for 32-bit Power processors. The \l
1509     Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_32 is
1510     defined.
1511 */
1512 /*!
1513     \macro Q_PROCESSOR_POWER_64
1514     \relates <QtGlobal>
1515
1516     Defined if the application is compiled for 64-bit Power processors. The \l
1517     Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_64 is
1518     defined.
1519 */
1520
1521 /*!
1522     \macro Q_PROCESSOR_S390
1523     \relates <QtGlobal>
1524
1525     Defined if the application is compiled for S/390 processors. Qt supports
1526     one optional variant of S/390: Q_PROCESSOR_S390_X.
1527 */
1528 /*!
1529     \macro Q_PROCESSOR_S390_X
1530     \relates <QtGlobal>
1531
1532     Defined if the application is compiled for S/390x processors. The \l
1533     Q_PROCESSOR_S390 macro is also defined when Q_PROCESSOR_S390_X is defined.
1534 */
1535
1536 /*!
1537     \macro Q_PROCESSOR_SH
1538     \relates <QtGlobal>
1539
1540     Defined if the application is compiled for SuperH processors. Qt currently
1541     supports one SuperH revision: \l Q_PROCESSOR_SH_4A.
1542 */
1543 /*!
1544     \macro Q_PROCESSOR_SH_4A
1545     \relates <QtGlobal>
1546
1547     Defined if the application is compiled for SuperH 4A processors. The \l
1548     Q_PROCESSOR_SH macro is also defined when Q_PROCESSOR_SH_4A is defined.
1549 */
1550
1551 /*!
1552     \macro Q_PROCESSOR_SPARC
1553     \relates <QtGlobal>
1554
1555     Defined if the application is compiled for SPARC processors. Qt currently
1556     supports one optional SPARC revision: \l Q_PROCESSOR_SPARC_V9.
1557 */
1558 /*!
1559     \macro Q_PROCESSOR_SPARC_V9
1560     \relates <QtGlobal>
1561
1562     Defined if the application is compiled for SPARC V9 processors. The \l
1563     Q_PROCESSOR_SPARC macro is also defined when Q_PROCESSOR_SPARC_V9 is
1564     defined.
1565 */
1566
1567 /*!
1568     \macro Q_PROCESSOR_X86
1569     \relates <QtGlobal>
1570
1571     Defined if the application is compiled for x86 processors. Qt currently
1572     supports two x86 variants: \l Q_PROCESSOR_X86_32 and \l Q_PROCESSOR_X86_64.
1573 */
1574 /*!
1575     \macro Q_PROCESSOR_X86_32
1576     \relates <QtGlobal>
1577
1578     Defined if the application is compiled for 32-bit x86 processors. This
1579     includes all i386, i486, i586, and i686 processors. The \l Q_PROCESSOR_X86
1580     macro is also defined when Q_PROCESSOR_X86_32 is defined.
1581 */
1582 /*!
1583     \macro Q_PROCESSOR_X86_64
1584     \relates <QtGlobal>
1585
1586     Defined if the application is compiled for 64-bit x86 processors. This
1587     includes all AMD64, Intel 64, and other x86_64/x64 processors. The \l
1588     Q_PROCESSOR_X86 macro is also defined when Q_PROCESSOR_X86_64 is defined.
1589 */
1590
1591 /*!
1592   \macro QT_DISABLE_DEPRECATED_BEFORE
1593   \relates <QtGlobal>
1594
1595   This macro can be defined in the project file to disable functions deprecated in
1596   a specified version of Qt or any earlier version. The default version number is 5.0,
1597   meaning that functions deprecated in or before Qt 5.0 will not be included.
1598
1599   Examples:
1600   When using a future release of Qt 5, set QT_DISABLE_DEPRECATED_BEFORE=0x050100 to
1601   disable functions deprecated in Qt 5.1 and earlier. In any release, set
1602   QT_DISABLE_DEPRECATED_BEFORE=0x000000 to enable any functions, including the ones
1603   deprecated in Qt 5.0
1604  */
1605
1606 #if defined(QT_BUILD_QMAKE)
1607 // needed to bootstrap qmake
1608 static const unsigned int qt_one = 1;
1609 const int QSysInfo::ByteOrder = ((*((unsigned char *) &qt_one) == 0) ? BigEndian : LittleEndian);
1610 #endif
1611
1612 #if defined(Q_OS_MAC) && !defined(Q_OS_IOS)
1613
1614 QT_BEGIN_INCLUDE_NAMESPACE
1615 #include "private/qcore_mac_p.h"
1616 #include "qnamespace.h"
1617 QT_END_INCLUDE_NAMESPACE
1618
1619 Q_CORE_EXPORT OSErr qt_mac_create_fsref(const QString &file, FSRef *fsref)
1620 {
1621     return FSPathMakeRef(reinterpret_cast<const UInt8 *>(file.toUtf8().constData()), fsref, 0);
1622 }
1623
1624 Q_CORE_EXPORT void qt_mac_to_pascal_string(QString s, Str255 str, TextEncoding encoding=0, int len=-1)
1625 {
1626     Q_UNUSED(encoding);
1627     Q_UNUSED(len);
1628     CFStringGetPascalString(QCFString(s), str, 256, CFStringGetSystemEncoding());
1629 }
1630
1631 Q_CORE_EXPORT QString qt_mac_from_pascal_string(const Str255 pstr) {
1632     return QCFString(CFStringCreateWithPascalString(0, pstr, CFStringGetSystemEncoding()));
1633 }
1634 #endif // defined(Q_OS_MAC) && !defined(Q_OS_IOS)
1635
1636 #if defined(Q_OS_MAC)
1637
1638 QSysInfo::MacVersion QSysInfo::macVersion()
1639 {
1640 #ifndef Q_OS_IOS
1641     SInt32 gestalt_version;
1642     if (Gestalt(gestaltSystemVersion, &gestalt_version) == noErr) {
1643         return QSysInfo::MacVersion(((gestalt_version & 0x00F0) >> 4) + 2);
1644     }
1645 #endif
1646     return QSysInfo::MV_Unknown;
1647 }
1648 const QSysInfo::MacVersion QSysInfo::MacintoshVersion = QSysInfo::macVersion();
1649
1650 #elif defined(Q_OS_WIN) || defined(Q_OS_CYGWIN) || defined(Q_OS_WINCE)
1651
1652 QT_BEGIN_INCLUDE_NAMESPACE
1653 #include "qt_windows.h"
1654 QT_END_INCLUDE_NAMESPACE
1655
1656 QSysInfo::WinVersion QSysInfo::windowsVersion()
1657 {
1658 #ifndef VER_PLATFORM_WIN32s
1659 #define VER_PLATFORM_WIN32s            0
1660 #endif
1661 #ifndef VER_PLATFORM_WIN32_WINDOWS
1662 #define VER_PLATFORM_WIN32_WINDOWS  1
1663 #endif
1664 #ifndef VER_PLATFORM_WIN32_NT
1665 #define VER_PLATFORM_WIN32_NT            2
1666 #endif
1667 #ifndef VER_PLATFORM_WIN32_CE
1668 #define VER_PLATFORM_WIN32_CE            3
1669 #endif
1670
1671     static QSysInfo::WinVersion winver;
1672     if (winver)
1673         return winver;
1674     winver = QSysInfo::WV_NT;
1675     OSVERSIONINFO osver;
1676     osver.dwOSVersionInfoSize = sizeof(osver);
1677     GetVersionEx(&osver);
1678 #ifdef Q_OS_WINCE
1679     DWORD qt_cever = 0;
1680     qt_cever = osver.dwMajorVersion * 100;
1681     qt_cever += osver.dwMinorVersion * 10;
1682 #endif
1683     switch (osver.dwPlatformId) {
1684     case VER_PLATFORM_WIN32s:
1685         winver = QSysInfo::WV_32s;
1686         break;
1687     case VER_PLATFORM_WIN32_WINDOWS:
1688         // We treat Windows Me (minor 90) the same as Windows 98
1689         if (osver.dwMinorVersion == 90)
1690             winver = QSysInfo::WV_Me;
1691         else if (osver.dwMinorVersion == 10)
1692             winver = QSysInfo::WV_98;
1693         else
1694             winver = QSysInfo::WV_95;
1695         break;
1696 #ifdef Q_OS_WINCE
1697     case VER_PLATFORM_WIN32_CE:
1698         if (qt_cever >= 600)
1699             winver = QSysInfo::WV_CE_6;
1700         if (qt_cever >= 500)
1701             winver = QSysInfo::WV_CE_5;
1702         else if (qt_cever >= 400)
1703             winver = QSysInfo::WV_CENET;
1704         else
1705             winver = QSysInfo::WV_CE;
1706         break;
1707 #endif
1708     default: // VER_PLATFORM_WIN32_NT
1709         if (osver.dwMajorVersion < 5) {
1710             winver = QSysInfo::WV_NT;
1711         } else if (osver.dwMajorVersion == 5 && osver.dwMinorVersion == 0) {
1712             winver = QSysInfo::WV_2000;
1713         } else if (osver.dwMajorVersion == 5 && osver.dwMinorVersion == 1) {
1714             winver = QSysInfo::WV_XP;
1715         } else if (osver.dwMajorVersion == 5 && osver.dwMinorVersion == 2) {
1716             winver = QSysInfo::WV_2003;
1717         } else if (osver.dwMajorVersion == 6 && osver.dwMinorVersion == 0) {
1718             winver = QSysInfo::WV_VISTA;
1719         } else if (osver.dwMajorVersion == 6 && osver.dwMinorVersion == 1) {
1720             winver = QSysInfo::WV_WINDOWS7;
1721         } else if (osver.dwMajorVersion == 6 && osver.dwMinorVersion == 2) {
1722             winver = QSysInfo::WV_WINDOWS8;
1723         } else {
1724             qWarning("Qt: Untested Windows version %d.%d detected!",
1725                      int(osver.dwMajorVersion), int(osver.dwMinorVersion));
1726             winver = QSysInfo::WV_NT_based;
1727         }
1728     }
1729
1730 #ifdef QT_DEBUG
1731     {
1732         QByteArray override = qgetenv("QT_WINVER_OVERRIDE");
1733         if (override.isEmpty())
1734             return winver;
1735
1736         if (override == "Me")
1737             winver = QSysInfo::WV_Me;
1738         if (override == "95")
1739             winver = QSysInfo::WV_95;
1740         else if (override == "98")
1741             winver = QSysInfo::WV_98;
1742         else if (override == "NT")
1743             winver = QSysInfo::WV_NT;
1744         else if (override == "2000")
1745             winver = QSysInfo::WV_2000;
1746         else if (override == "2003")
1747             winver = QSysInfo::WV_2003;
1748         else if (override == "XP")
1749             winver = QSysInfo::WV_XP;
1750         else if (override == "VISTA")
1751             winver = QSysInfo::WV_VISTA;
1752         else if (override == "WINDOWS7")
1753             winver = QSysInfo::WV_WINDOWS7;
1754         else if (override == "WINDOWS8")
1755             winver = QSysInfo::WV_WINDOWS8;
1756     }
1757 #endif
1758
1759     return winver;
1760 }
1761
1762 const QSysInfo::WinVersion QSysInfo::WindowsVersion = QSysInfo::windowsVersion();
1763
1764 #endif
1765
1766 /*!
1767     \macro void Q_ASSERT(bool test)
1768     \relates <QtGlobal>
1769
1770     Prints a warning message containing the source code file name and
1771     line number if \a test is false.
1772
1773     Q_ASSERT() is useful for testing pre- and post-conditions
1774     during development. It does nothing if \c QT_NO_DEBUG was defined
1775     during compilation.
1776
1777     Example:
1778
1779     \snippet code/src_corelib_global_qglobal.cpp 17
1780
1781     If \c b is zero, the Q_ASSERT statement will output the following
1782     message using the qFatal() function:
1783
1784     \snippet code/src_corelib_global_qglobal.cpp 18
1785
1786     \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
1787 */
1788
1789 /*!
1790     \macro void Q_ASSERT_X(bool test, const char *where, const char *what)
1791     \relates <QtGlobal>
1792
1793     Prints the message \a what together with the location \a where,
1794     the source file name and line number if \a test is false.
1795
1796     Q_ASSERT_X is useful for testing pre- and post-conditions during
1797     development. It does nothing if \c QT_NO_DEBUG was defined during
1798     compilation.
1799
1800     Example:
1801
1802     \snippet code/src_corelib_global_qglobal.cpp 19
1803
1804     If \c b is zero, the Q_ASSERT_X statement will output the following
1805     message using the qFatal() function:
1806
1807     \snippet code/src_corelib_global_qglobal.cpp 20
1808
1809     \sa Q_ASSERT(), qFatal(), {Debugging Techniques}
1810 */
1811
1812 /*!
1813     \macro void Q_ASSUME(bool expr)
1814     \relates <QtGlobal>
1815     \since 5.0
1816
1817     Causes the compiler to assume that \a expr is true. This macro is useful
1818     for improving code generation, by providing the compiler with hints about
1819     conditions that it would not otherwise know about. However, there is no
1820     guarantee that the compiler will actually use those hints.
1821
1822     This macro could be considered a "lighter" version of \l{Q_ASSERT}. While
1823     Q_ASSERT will abort the program's execution if the condition is false,
1824     Q_ASSUME will tell the compiler not to generate code for those conditions.
1825     Therefore, it is important that the assumptions always hold, otherwise
1826     undefined behaviour may occur.
1827
1828     If \a expr is a constantly false condition, Q_ASSUME will tell the compiler
1829     that the current code execution cannot be reached. That is, Q_ASSUME(false)
1830     is equivalent to Q_UNREACHABLE().
1831
1832     \note Q_LIKELY() tells the compiler that the expression is likely, but not
1833     the only possibility. Q_ASSUME tells the compiler that it is the only
1834     possibility.
1835
1836     \sa Q_ASSERT(), Q_UNREACHABLE(), Q_LIKELY()
1837 */
1838
1839 /*!
1840     \macro void Q_UNREACHABLE()
1841     \relates <QtGlobal>
1842     \since 5.0
1843
1844     Tells the compiler that the current point cannot be reached by any
1845     execution, so it may optimize any code paths leading here as dead code, as
1846     well as code continuing from here.
1847
1848     This macro is useful to mark impossible conditions. For example, given the
1849     following enum:
1850
1851     \snippet code/src_corelib_global_qglobal.cpp qunreachable-enum
1852
1853     One can write a switch table like so:
1854
1855     \snippet code/src_corelib_global_qglobal.cpp qunreachable-switch
1856
1857     The advantage of inserting Q_UNREACHABLE() at that point is that the
1858     compiler is told not to generate code for a shape variable containing that
1859     value. If the macro is missing, the compiler will still generate the
1860     necessary comparisons for that value. If the case label were removed, some
1861     compilers could produce a warning that some enum values were not checked.
1862
1863     By using this macro in impossible conditions, code coverage may be improved
1864     as dead code paths may be eliminated.
1865
1866     \sa Q_ASSERT(), Q_ASSUME(), qFatal()
1867 */
1868
1869 /*!
1870     \macro void Q_CHECK_PTR(void *pointer)
1871     \relates <QtGlobal>
1872
1873     If \a pointer is 0, prints a warning message containing the source
1874     code's file name and line number, saying that the program ran out
1875     of memory.
1876
1877     Q_CHECK_PTR does nothing if \c QT_NO_DEBUG was defined during
1878     compilation.
1879
1880     Example:
1881
1882     \snippet code/src_corelib_global_qglobal.cpp 21
1883
1884     \sa qWarning(), {Debugging Techniques}
1885 */
1886
1887 /*!
1888     \fn T *q_check_ptr(T *pointer)
1889     \relates <QtGlobal>
1890
1891     Uses Q_CHECK_PTR on \a pointer, then returns \a pointer.
1892
1893     This can be used as an inline version of Q_CHECK_PTR.
1894 */
1895
1896 /*!
1897     \macro const char* Q_FUNC_INFO()
1898     \relates <QtGlobal>
1899
1900     Expands to a string that describe the function the macro resides in. How this string looks
1901     more specifically is compiler dependent. With GNU GCC it is typically the function signature,
1902     while with other compilers it might be the line and column number.
1903
1904     Q_FUNC_INFO can be conveniently used with qDebug(). For example, this function:
1905
1906     \snippet code/src_corelib_global_qglobal.cpp 22
1907
1908     when instantiated with the integer type, will with the GCC compiler produce:
1909
1910     \tt{const TInputType& myMin(const TInputType&, const TInputType&) [with TInputType = int] was called with value1: 3 value2: 4}
1911
1912     If this macro is used outside a function, the behavior is undefined.
1913  */
1914
1915 /*
1916   The Q_CHECK_PTR macro calls this function if an allocation check
1917   fails.
1918 */
1919 void qt_check_pointer(const char *n, int l)
1920 {
1921     qFatal("In file %s, line %d: Out of memory", n, l);
1922 }
1923
1924 /*
1925    \internal
1926    Allows you to throw an exception without including <new>
1927    Called internally from Q_CHECK_PTR on certain OS combinations
1928 */
1929 void qBadAlloc()
1930 {
1931     QT_THROW(std::bad_alloc());
1932 }
1933
1934 #ifndef QT_NO_EXCEPTIONS
1935 /*
1936    \internal
1937    Allows you to call std::terminate() without including <exception>.
1938    Called internally from QT_TERMINATE_ON_EXCEPTION
1939 */
1940 Q_NORETURN void qTerminate() Q_DECL_NOTHROW
1941 {
1942     std::terminate();
1943 }
1944 #endif
1945
1946 /*
1947   The Q_ASSERT macro calls this function when the test fails.
1948 */
1949 void qt_assert(const char *assertion, const char *file, int line) Q_DECL_NOTHROW
1950 {
1951     qFatal("ASSERT: \"%s\" in file %s, line %d", assertion, file, line);
1952 }
1953
1954 /*
1955   The Q_ASSERT_X macro calls this function when the test fails.
1956 */
1957 void qt_assert_x(const char *where, const char *what, const char *file, int line) Q_DECL_NOTHROW
1958 {
1959     qFatal("ASSERT failure in %s: \"%s\", file %s, line %d", where, what, file, line);
1960 }
1961
1962
1963 /*
1964     Dijkstra's bisection algorithm to find the square root of an integer.
1965     Deliberately not exported as part of the Qt API, but used in both
1966     qsimplerichtext.cpp and qgfxraster_qws.cpp
1967 */
1968 Q_CORE_EXPORT unsigned int qt_int_sqrt(unsigned int n)
1969 {
1970     // n must be in the range 0...UINT_MAX/2-1
1971     if (n >= (UINT_MAX>>2)) {
1972         unsigned int r = 2 * qt_int_sqrt(n / 4);
1973         unsigned int r2 = r + 1;
1974         return (n >= r2 * r2) ? r2 : r;
1975     }
1976     uint h, p= 0, q= 1, r= n;
1977     while (q <= n)
1978         q <<= 2;
1979     while (q != 1) {
1980         q >>= 2;
1981         h= p + q;
1982         p >>= 1;
1983         if (r >= h) {
1984             p += q;
1985             r -= h;
1986         }
1987     }
1988     return p;
1989 }
1990
1991 void *qMemCopy(void *dest, const void *src, size_t n) { return memcpy(dest, src, n); }
1992 void *qMemSet(void *dest, int c, size_t n) { return memset(dest, c, n); }
1993
1994 #if !defined(Q_OS_WIN) && !defined(QT_NO_THREAD) && !defined(Q_OS_INTEGRITY) && !defined(Q_OS_QNX) && \
1995     defined(_POSIX_THREAD_SAFE_FUNCTIONS) && _POSIX_VERSION >= 200112L
1996 namespace {
1997     // There are two incompatible versions of strerror_r:
1998     // a) the XSI/POSIX.1 version, which returns an int,
1999     //    indicating success or not
2000     // b) the GNU version, which returns a char*, which may or may not
2001     //    be the beginning of the buffer we used
2002     // The GNU libc manpage for strerror_r says you should use the XSI
2003     // version in portable code. However, it's impossible to do that if
2004     // _GNU_SOURCE is defined so we use C++ overloading to decide what to do
2005     // depending on the return type
2006     static inline QString fromstrerror_helper(int, const QByteArray &buf)
2007     {
2008         return QString::fromLocal8Bit(buf);
2009     }
2010     static inline QString fromstrerror_helper(const char *str, const QByteArray &)
2011     {
2012         return QString::fromLocal8Bit(str);
2013     }
2014 }
2015 #endif
2016
2017 QString qt_error_string(int errorCode)
2018 {
2019     const char *s = 0;
2020     QString ret;
2021     if (errorCode == -1) {
2022 #if defined(Q_OS_WIN)
2023         errorCode = GetLastError();
2024 #else
2025         errorCode = errno;
2026 #endif
2027     }
2028     switch (errorCode) {
2029     case 0:
2030         break;
2031     case EACCES:
2032         s = QT_TRANSLATE_NOOP("QIODevice", "Permission denied");
2033         break;
2034     case EMFILE:
2035         s = QT_TRANSLATE_NOOP("QIODevice", "Too many open files");
2036         break;
2037     case ENOENT:
2038         s = QT_TRANSLATE_NOOP("QIODevice", "No such file or directory");
2039         break;
2040     case ENOSPC:
2041         s = QT_TRANSLATE_NOOP("QIODevice", "No space left on device");
2042         break;
2043     default: {
2044 #ifdef Q_OS_WIN
2045         wchar_t *string = 0;
2046         FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER|FORMAT_MESSAGE_FROM_SYSTEM,
2047                       NULL,
2048                       errorCode,
2049                       MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
2050                       (LPWSTR)&string,
2051                       0,
2052                       NULL);
2053         ret = QString::fromWCharArray(string);
2054         LocalFree((HLOCAL)string);
2055
2056         if (ret.isEmpty() && errorCode == ERROR_MOD_NOT_FOUND)
2057             ret = QString::fromLatin1("The specified module could not be found.");
2058 #elif !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS) && _POSIX_VERSION >= 200112L && !defined(Q_OS_INTEGRITY) && !defined(Q_OS_QNX)
2059         QByteArray buf(1024, '\0');
2060         ret = fromstrerror_helper(strerror_r(errorCode, buf.data(), buf.size()), buf);
2061 #else
2062         ret = QString::fromLocal8Bit(strerror(errorCode));
2063 #endif
2064     break; }
2065     }
2066     if (s)
2067         // ######## this breaks moc build currently
2068 //         ret = QCoreApplication::translate("QIODevice", s);
2069         ret = QString::fromLatin1(s);
2070     return ret.trimmed();
2071 }
2072
2073 // getenv is declared as deprecated in VS2005. This function
2074 // makes use of the new secure getenv function.
2075 /*!
2076     \relates <QtGlobal>
2077
2078     Returns the value of the environment variable with name \a
2079     varName. To get the variable string, use QByteArray::constData().
2080
2081     \note qgetenv() was introduced because getenv() from the standard
2082     C library was deprecated in VC2005 (and later versions). qgetenv()
2083     uses the new replacement function in VC, and calls the standard C
2084     library's implementation on all other platforms.
2085
2086     \sa qputenv()
2087 */
2088 QByteArray qgetenv(const char *varName)
2089 {
2090 #if defined(_MSC_VER) && _MSC_VER >= 1400
2091     size_t requiredSize = 0;
2092     QByteArray buffer;
2093     getenv_s(&requiredSize, 0, 0, varName);
2094     if (requiredSize == 0)
2095         return buffer;
2096     buffer.resize(int(requiredSize));
2097     getenv_s(&requiredSize, buffer.data(), requiredSize, varName);
2098     // requiredSize includes the terminating null, which we don't want.
2099     Q_ASSERT(buffer.endsWith('\0'));
2100     buffer.chop(1);
2101     return buffer;
2102 #else
2103     return QByteArray(::getenv(varName));
2104 #endif
2105 }
2106
2107 /*!
2108     \relates <QtGlobal>
2109     \internal
2110
2111     This function checks whether the environment variable \a varName
2112     is empty.
2113
2114     Equivalent to
2115     \code
2116     qgetenv(varName).isEmpty()
2117     \endcode
2118     except that it's potentially much faster, and can't throw exceptions.
2119
2120     \sa qgetenv(), qEnvironmentVariableIsSet()
2121 */
2122 bool qEnvironmentVariableIsEmpty(const char *varName) Q_DECL_NOEXCEPT
2123 {
2124 #if defined(_MSC_VER) && _MSC_VER >= 1400
2125     // we provide a buffer that can only hold the empty string, so
2126     // when the env.var isn't empty, we'll get an ERANGE error (buffer
2127     // too small):
2128     size_t dummy;
2129     char buffer = '\0';
2130     return getenv_s(&dummy, &buffer, 1, varName) != ERANGE;
2131 #else
2132     const char * const value = ::getenv(varName);
2133     return !value || !*value;
2134 #endif
2135 }
2136
2137 /*!
2138     \relates <QtGlobal>
2139     \internal
2140
2141     This function checks whether the environment variable \a varName
2142     is set.
2143
2144     Equivalent to
2145     \code
2146     !qgetenv(varName).isNull()
2147     \endcode
2148     except that it's potentially much faster, and can't throw exceptions.
2149
2150     \sa qgetenv(), qEnvironmentVariableIsEmpty()
2151 */
2152 bool qEnvironmentVariableIsSet(const char *varName) Q_DECL_NOEXCEPT
2153 {
2154 #if defined(_MSC_VER) && _MSC_VER >= 1400
2155     size_t requiredSize = 0;
2156     (void)getenv_s(&requiredSize, 0, 0, varName);
2157     return requiredSize != 0;
2158 #else
2159     return ::getenv(varName) != 0;
2160 #endif
2161 }
2162
2163 /*!
2164     \relates <QtGlobal>
2165
2166     This function sets the \a value of the environment variable named
2167     \a varName. It will create the variable if it does not exist. It
2168     returns 0 if the variable could not be set.
2169
2170     \note qputenv() was introduced because putenv() from the standard
2171     C library was deprecated in VC2005 (and later versions). qputenv()
2172     uses the replacement function in VC, and calls the standard C
2173     library's implementation on all other platforms.
2174
2175     \sa qgetenv()
2176 */
2177 bool qputenv(const char *varName, const QByteArray& value)
2178 {
2179 #if defined(_MSC_VER) && _MSC_VER >= 1400
2180     return _putenv_s(varName, value.constData()) == 0;
2181 #elif defined(_POSIX_VERSION) && (_POSIX_VERSION-0) >= 200112L
2182     // POSIX.1-2001 has setenv
2183     return setenv(varName, value.constData(), true) == 0;
2184 #else
2185     QByteArray buffer(varName);
2186     buffer += '=';
2187     buffer += value;
2188     char* envVar = qstrdup(buffer.constData());
2189     int result = putenv(envVar);
2190     if (result != 0) // error. we have to delete the string.
2191         delete[] envVar;
2192     return result == 0;
2193 #endif
2194 }
2195
2196 #if defined(Q_OS_UNIX) && !defined(QT_NO_THREAD)
2197
2198 #  if defined(Q_OS_INTEGRITY) && defined(__GHS_VERSION_NUMBER) && (__GHS_VERSION_NUMBER < 500)
2199 // older versions of INTEGRITY used a long instead of a uint for the seed.
2200 typedef long SeedStorageType;
2201 #  else
2202 typedef uint SeedStorageType;
2203 #  endif
2204
2205 typedef QThreadStorage<SeedStorageType *> SeedStorage;
2206 Q_GLOBAL_STATIC(SeedStorage, randTLS)  // Thread Local Storage for seed value
2207
2208 #endif
2209
2210 /*!
2211     \relates <QtGlobal>
2212     \since 4.2
2213
2214     Thread-safe version of the standard C++ \c srand() function.
2215
2216     Sets the argument \a seed to be used to generate a new random number sequence of
2217     pseudo random integers to be returned by qrand().
2218
2219     The sequence of random numbers generated is deterministic per thread. For example,
2220     if two threads call qsrand(1) and subsequently calls qrand(), the threads will get
2221     the same random number sequence.
2222
2223     \sa qrand()
2224 */
2225 void qsrand(uint seed)
2226 {
2227 #if defined(Q_OS_UNIX) && !defined(QT_NO_THREAD)
2228     SeedStorage *seedStorage = randTLS();
2229     if (seedStorage) {
2230         SeedStorageType *pseed = seedStorage->localData();
2231         if (!pseed)
2232             seedStorage->setLocalData(pseed = new SeedStorageType);
2233         *pseed = seed;
2234     } else {
2235         //global static seed storage should always exist,
2236         //except after being deleted by QGlobalStaticDeleter.
2237         //But since it still can be called from destructor of another
2238         //global static object, fallback to srand(seed)
2239         srand(seed);
2240     }
2241 #else
2242     // On Windows srand() and rand() already use Thread-Local-Storage
2243     // to store the seed between calls
2244     // this is also valid for QT_NO_THREAD
2245     srand(seed);
2246 #endif
2247 }
2248
2249 /*!
2250     \relates <QtGlobal>
2251     \since 4.2
2252
2253     Thread-safe version of the standard C++ \c rand() function.
2254
2255     Returns a value between 0 and \c RAND_MAX (defined in \c <cstdlib> and
2256     \c <stdlib.h>), the next number in the current sequence of pseudo-random
2257     integers.
2258
2259     Use \c qsrand() to initialize the pseudo-random number generator with
2260     a seed value.
2261
2262     \sa qsrand()
2263 */
2264 int qrand()
2265 {
2266 #if defined(Q_OS_UNIX) && !defined(QT_NO_THREAD) && defined(_POSIX_THREAD_SAFE_FUNCTIONS) && (_POSIX_THREAD_SAFE_FUNCTIONS - 0 > 0)
2267     SeedStorage *seedStorage = randTLS();
2268     if (seedStorage) {
2269         SeedStorageType *pseed = seedStorage->localData();
2270         if (!pseed) {
2271             seedStorage->setLocalData(pseed = new SeedStorageType);
2272             *pseed = 1;
2273         }
2274         return rand_r(pseed);
2275     } else {
2276         //global static seed storage should always exist,
2277         //except after being deleted by QGlobalStaticDeleter.
2278         //But since it still can be called from destructor of another
2279         //global static object, fallback to rand()
2280         return rand();
2281     }
2282 #else
2283     // On Windows srand() and rand() already use Thread-Local-Storage
2284     // to store the seed between calls
2285     // this is also valid for QT_NO_THREAD
2286     return rand();
2287 #endif
2288 }
2289
2290 /*!
2291     \macro forever
2292     \relates <QtGlobal>
2293
2294     This macro is provided for convenience for writing infinite
2295     loops.
2296
2297     Example:
2298
2299     \snippet code/src_corelib_global_qglobal.cpp 31
2300
2301     It is equivalent to \c{for (;;)}.
2302
2303     If you're worried about namespace pollution, you can disable this
2304     macro by adding the following line to your \c .pro file:
2305
2306     \snippet code/src_corelib_global_qglobal.cpp 32
2307
2308     \sa Q_FOREVER
2309 */
2310
2311 /*!
2312     \macro Q_FOREVER
2313     \relates <QtGlobal>
2314
2315     Same as \l{forever}.
2316
2317     This macro is available even when \c no_keywords is specified
2318     using the \c .pro file's \c CONFIG variable.
2319
2320     \sa foreach()
2321 */
2322
2323 /*!
2324     \macro foreach(variable, container)
2325     \relates <QtGlobal>
2326
2327     This macro is used to implement Qt's \c foreach loop. The \a
2328     variable parameter is a variable name or variable definition; the
2329     \a container parameter is a Qt container whose value type
2330     corresponds to the type of the variable. See \l{The foreach
2331     Keyword} for details.
2332
2333     If you're worried about namespace pollution, you can disable this
2334     macro by adding the following line to your \c .pro file:
2335
2336     \snippet code/src_corelib_global_qglobal.cpp 33
2337
2338     \sa Q_FOREACH()
2339 */
2340
2341 /*!
2342     \macro Q_FOREACH(variable, container)
2343     \relates <QtGlobal>
2344
2345     Same as foreach(\a variable, \a container).
2346
2347     This macro is available even when \c no_keywords is specified
2348     using the \c .pro file's \c CONFIG variable.
2349
2350     \sa foreach()
2351 */
2352
2353 /*!
2354     \macro QT_TR_NOOP(sourceText)
2355     \relates <QtGlobal>
2356
2357     Marks the string literal \a sourceText for dynamic translation in
2358     the current context (class), i.e the stored \a sourceText will not
2359     be altered.
2360
2361     The macro expands to \a sourceText.
2362
2363     Example:
2364
2365     \snippet code/src_corelib_global_qglobal.cpp 34
2366
2367     The macro QT_TR_NOOP_UTF8() is identical except that it tells lupdate
2368     that the source string is encoded in UTF-8. Corresponding variants
2369     exist in the QT_TRANSLATE_NOOP() family of macros, too.
2370
2371     \sa QT_TRANSLATE_NOOP(), {Internationalization with Qt}
2372 */
2373
2374 /*!
2375     \macro QT_TRANSLATE_NOOP(context, sourceText)
2376     \relates <QtGlobal>
2377
2378     Marks the string literal \a sourceText for dynamic translation in
2379     the given \a context; i.e, the stored \a sourceText will not be
2380     altered. The \a context is typically a class and also needs to
2381     be specified as string literal.
2382
2383     The macro expands to \a sourceText.
2384
2385     Example:
2386
2387     \snippet code/src_corelib_global_qglobal.cpp 35
2388
2389     \sa QT_TR_NOOP(), QT_TRANSLATE_NOOP3(), {Internationalization with Qt}
2390 */
2391
2392 /*!
2393     \macro QT_TRANSLATE_NOOP3(context, sourceText, comment)
2394     \relates <QtGlobal>
2395     \since 4.4
2396
2397     Marks the string literal \a sourceText for dynamic translation in the
2398     given \a context and with \a comment, i.e the stored \a sourceText will
2399     not be altered. The \a context is typically a class and also needs to
2400     be specified as string literal. The string literal \a comment
2401     will be available for translators using e.g. Qt Linguist.
2402
2403     The macro expands to anonymous struct of the two string
2404     literals passed as \a sourceText and \a comment.
2405
2406     Example:
2407
2408     \snippet code/src_corelib_global_qglobal.cpp 36
2409
2410     \sa QT_TR_NOOP(), QT_TRANSLATE_NOOP(), {Internationalization with Qt}
2411 */
2412
2413 /*!
2414     \fn QString qtTrId(const char *id, int n = -1)
2415     \relates <QtGlobal>
2416     \reentrant
2417     \since 4.6
2418
2419     \brief The qtTrId function finds and returns a translated string.
2420
2421     Returns a translated string identified by \a id.
2422     If no matching string is found, the id itself is returned. This
2423     should not happen under normal conditions.
2424
2425     If \a n >= 0, all occurrences of \c %n in the resulting string
2426     are replaced with a decimal representation of \a n. In addition,
2427     depending on \a n's value, the translation text may vary.
2428
2429     Meta data and comments can be passed as documented for QObject::tr().
2430     In addition, it is possible to supply a source string template like that:
2431
2432     \tt{//% <C string>}
2433
2434     or
2435
2436     \tt{\\begincomment% <C string> \\endcomment}
2437
2438     Example:
2439
2440     \snippet code/src_corelib_global_qglobal.cpp qttrid
2441
2442     Creating QM files suitable for use with this function requires passing
2443     the \c -idbased option to the \c lrelease tool.
2444
2445     \warning This method is reentrant only if all translators are
2446     installed \e before calling this method. Installing or removing
2447     translators while performing translations is not supported. Doing
2448     so will probably result in crashes or other undesirable behavior.
2449
2450     \sa QObject::tr(), QCoreApplication::translate(), {Internationalization with Qt}
2451 */
2452
2453 /*!
2454     \macro QT_TRID_NOOP(id)
2455     \relates <QtGlobal>
2456     \since 4.6
2457
2458     \brief The QT_TRID_NOOP macro marks an id for dynamic translation.
2459
2460     The only purpose of this macro is to provide an anchor for attaching
2461     meta data like to qtTrId().
2462
2463     The macro expands to \a id.
2464
2465     Example:
2466
2467     \snippet code/src_corelib_global_qglobal.cpp qttrid_noop
2468
2469     \sa qtTrId(), {Internationalization with Qt}
2470 */
2471
2472 /*!
2473     \macro Q_LIKELY(expr)
2474     \relates <QtGlobal>
2475     \since 4.8
2476
2477     \brief Hints to the compiler that the enclosed condition, \a expr, is
2478     likely to evaluate to \c true.
2479
2480     Use of this macro can help the compiler to optimize the code.
2481
2482     Example:
2483
2484     \snippet code/src_corelib_global_qglobal.cpp qlikely
2485
2486     \sa Q_UNLIKELY()
2487 */
2488
2489 /*!
2490     \macro Q_UNLIKELY(expr)
2491     \relates <QtGlobal>
2492     \since 4.8
2493
2494     \brief Hints to the compiler that the enclosed condition, \a expr, is
2495     likely to evaluate to \c false.
2496
2497     Use of this macro can help the compiler to optimize the code.
2498
2499     Example:
2500
2501     \snippet code/src_corelib_global_qglobal.cpp qunlikely
2502
2503     \sa Q_LIKELY()
2504 */
2505
2506 /*!
2507     \macro QT_POINTER_SIZE
2508     \relates <QtGlobal>
2509
2510     Expands to the size of a pointer in bytes (4 or 8). This is
2511     equivalent to \c sizeof(void *) but can be used in a preprocessor
2512     directive.
2513 */
2514
2515 /*!
2516     \macro QABS(n)
2517     \relates <QtGlobal>
2518     \obsolete
2519
2520     Use qAbs(\a n) instead.
2521
2522     \sa QMIN(), QMAX()
2523 */
2524
2525 /*!
2526     \macro QMIN(x, y)
2527     \relates <QtGlobal>
2528     \obsolete
2529
2530     Use qMin(\a x, \a y) instead.
2531
2532     \sa QMAX(), QABS()
2533 */
2534
2535 /*!
2536     \macro QMAX(x, y)
2537     \relates <QtGlobal>
2538     \obsolete
2539
2540     Use qMax(\a x, \a y) instead.
2541
2542     \sa QMIN(), QABS()
2543 */
2544
2545 /*!
2546     \macro const char *qPrintable(const QString &str)
2547     \relates <QtGlobal>
2548
2549     Returns \a str as a \c{const char *}. This is equivalent to
2550     \a{str}.toLocal8Bit().constData().
2551
2552     The char pointer will be invalid after the statement in which
2553     qPrintable() is used. This is because the array returned by
2554     toLocal8Bit() will fall out of scope.
2555
2556     Example:
2557
2558     \snippet code/src_corelib_global_qglobal.cpp 37
2559
2560
2561     \sa qDebug(), qWarning(), qCritical(), qFatal()
2562 */
2563
2564 /*!
2565     \macro Q_DECLARE_TYPEINFO(Type, Flags)
2566     \relates <QtGlobal>
2567
2568     You can use this macro to specify information about a custom type
2569     \a Type. With accurate type information, Qt's \l{Container Classes}
2570     {generic containers} can choose appropriate storage methods and
2571     algorithms.
2572
2573     \a Flags can be one of the following:
2574
2575     \list
2576     \li \c Q_PRIMITIVE_TYPE specifies that \a Type is a POD (plain old
2577        data) type with no constructor or destructor, or else a type where
2578        every bit pattern is a valid object and memcpy() creates a valid
2579        independent copy of the object.
2580     \li \c Q_MOVABLE_TYPE specifies that \a Type has a constructor
2581        and/or a destructor but can be moved in memory using \c
2582        memcpy().
2583     \li \c Q_COMPLEX_TYPE (the default) specifies that \a Type has
2584        constructors and/or a destructor and that it may not be moved
2585        in memory.
2586     \endlist
2587
2588     Example of a "primitive" type:
2589
2590     \snippet code/src_corelib_global_qglobal.cpp 38
2591
2592     An example of a non-POD "primitive" type is QUuid: Even though
2593     QUuid has constructors (and therefore isn't POD), every bit
2594     pattern still represents a valid object, and memcpy() can be used
2595     to create a valid independent copy of a QUuid object.
2596
2597     Example of a movable type:
2598
2599     \snippet code/src_corelib_global_qglobal.cpp 39
2600 */
2601
2602 /*!
2603     \macro Q_UNUSED(name)
2604     \relates <QtGlobal>
2605
2606     Indicates to the compiler that the parameter with the specified
2607     \a name is not used in the body of a function. This can be used to
2608     suppress compiler warnings while allowing functions to be defined
2609     with meaningful parameter names in their signatures.
2610 */
2611
2612 struct QInternal_CallBackTable {
2613     QVector<QList<qInternalCallback> > callbacks;
2614 };
2615
2616 Q_GLOBAL_STATIC(QInternal_CallBackTable, global_callback_table)
2617
2618 bool QInternal::registerCallback(Callback cb, qInternalCallback callback)
2619 {
2620     if (cb >= 0 && cb < QInternal::LastCallback) {
2621         QInternal_CallBackTable *cbt = global_callback_table();
2622         cbt->callbacks.resize(cb + 1);
2623         cbt->callbacks[cb].append(callback);
2624         return true;
2625     }
2626     return false;
2627 }
2628
2629 bool QInternal::unregisterCallback(Callback cb, qInternalCallback callback)
2630 {
2631     if (cb >= 0 && cb < QInternal::LastCallback) {
2632         QInternal_CallBackTable *cbt = global_callback_table();
2633         return (bool) cbt->callbacks[cb].removeAll(callback);
2634     }
2635     return false;
2636 }
2637
2638 bool QInternal::activateCallbacks(Callback cb, void **parameters)
2639 {
2640     Q_ASSERT_X(cb >= 0, "QInternal::activateCallback()", "Callback id must be a valid id");
2641
2642     QInternal_CallBackTable *cbt = global_callback_table();
2643     if (cbt && cb < cbt->callbacks.size()) {
2644         QList<qInternalCallback> callbacks = cbt->callbacks[cb];
2645         bool ret = false;
2646         for (int i=0; i<callbacks.size(); ++i)
2647             ret |= (callbacks.at(i))(parameters);
2648         return ret;
2649     }
2650     return false;
2651 }
2652
2653 /*!
2654     \macro Q_BYTE_ORDER
2655     \relates <QtGlobal>
2656
2657     This macro can be used to determine the byte order your system
2658     uses for storing data in memory. i.e., whether your system is
2659     little-endian or big-endian. It is set by Qt to one of the macros
2660     Q_LITTLE_ENDIAN or Q_BIG_ENDIAN. You normally won't need to worry
2661     about endian-ness, but you might, for example if you need to know
2662     which byte of an integer or UTF-16 character is stored in the
2663     lowest address. Endian-ness is important in networking, where
2664     computers with different values for Q_BYTE_ORDER must pass data
2665     back and forth.
2666
2667     Use this macro as in the following examples.
2668
2669     \snippet code/src_corelib_global_qglobal.cpp 40
2670
2671     \sa Q_BIG_ENDIAN, Q_LITTLE_ENDIAN
2672 */
2673
2674 /*!
2675     \macro Q_LITTLE_ENDIAN
2676     \relates <QtGlobal>
2677
2678     This macro represents a value you can compare to the macro
2679     Q_BYTE_ORDER to determine the endian-ness of your system.  In a
2680     little-endian system, the least significant byte is stored at the
2681     lowest address. The other bytes follow in increasing order of
2682     significance.
2683
2684     \snippet code/src_corelib_global_qglobal.cpp 41
2685
2686     \sa Q_BYTE_ORDER, Q_BIG_ENDIAN
2687 */
2688
2689 /*!
2690     \macro Q_BIG_ENDIAN
2691     \relates <QtGlobal>
2692
2693     This macro represents a value you can compare to the macro
2694     Q_BYTE_ORDER to determine the endian-ness of your system.  In a
2695     big-endian system, the most significant byte is stored at the
2696     lowest address. The other bytes follow in decreasing order of
2697     significance.
2698
2699     \snippet code/src_corelib_global_qglobal.cpp 42
2700
2701     \sa Q_BYTE_ORDER, Q_LITTLE_ENDIAN
2702 */
2703
2704 /*!
2705     \macro Q_GLOBAL_STATIC(type, name)
2706     \internal
2707
2708     Declares a global static variable with the given \a type and \a name.
2709
2710     Use this macro to instantiate an object in a thread-safe way, creating
2711     a global pointer that can be used to refer to it.
2712
2713     \warning This macro is subject to a race condition that can cause the object
2714     to be constructed twice. However, if this occurs, the second instance will
2715     be immediately deleted.
2716
2717     See also
2718     \l{http://www.aristeia.com/publications.html}{"C++ and the perils of Double-Checked Locking"}
2719     by Scott Meyers and Andrei Alexandrescu.
2720 */
2721
2722 /*!
2723     \macro Q_GLOBAL_STATIC_WITH_ARGS(type, name, arguments)
2724     \internal
2725
2726     Declares a global static variable with the specified \a type and \a name.
2727
2728     Use this macro to instantiate an object using the \a arguments specified
2729     in a thread-safe way, creating a global pointer that can be used to refer
2730     to it.
2731
2732     \warning This macro is subject to a race condition that can cause the object
2733     to be constructed twice. However, if this occurs, the second instance will
2734     be immediately deleted.
2735
2736     See also
2737     \l{http://www.aristeia.com/publications.html}{"C++ and the perils of Double-Checked Locking"}
2738     by Scott Meyers and Andrei Alexandrescu.
2739 */
2740
2741 /*!
2742     \macro QT_NAMESPACE
2743     \internal
2744
2745     If this macro is defined to \c ns all Qt classes are put in a namespace
2746     called \c ns. Also, moc will output code putting metaobjects etc.
2747     into namespace \c ns.
2748
2749     \sa QT_BEGIN_NAMESPACE, QT_END_NAMESPACE,
2750     QT_PREPEND_NAMESPACE, QT_USE_NAMESPACE,
2751     QT_BEGIN_INCLUDE_NAMESPACE, QT_END_INCLUDE_NAMESPACE,
2752     QT_BEGIN_MOC_NAMESPACE, QT_END_MOC_NAMESPACE,
2753 */
2754
2755 /*!
2756     \macro QT_PREPEND_NAMESPACE(identifier)
2757     \internal
2758
2759     This macro qualifies \a identifier with the full namespace.
2760     It expands to \c{::QT_NAMESPACE::identifier} if \c QT_NAMESPACE is defined
2761     and only \a identifier otherwise.
2762
2763     \sa QT_NAMESPACE
2764 */
2765
2766 /*!
2767     \macro QT_USE_NAMESPACE
2768     \internal
2769
2770     This macro expands to using QT_NAMESPACE if QT_NAMESPACE is defined
2771     and nothing otherwise.
2772
2773     \sa QT_NAMESPACE
2774 */
2775
2776 /*!
2777     \macro QT_BEGIN_NAMESPACE
2778     \internal
2779
2780     This macro expands to
2781
2782     \snippet code/src_corelib_global_qglobal.cpp begin namespace macro
2783
2784     if \c QT_NAMESPACE is defined and nothing otherwise. If should always
2785     appear in the file-level scope and be followed by \c QT_END_NAMESPACE
2786     at the same logical level with respect to preprocessor conditionals
2787     in the same file.
2788
2789     As a rule of thumb, \c QT_BEGIN_NAMESPACE should appear in all Qt header
2790     and Qt source files after the last \c{#include} line and before the first
2791     declaration. In Qt headers using \c QT_BEGIN_HEADER, \c QT_BEGIN_NAMESPACE
2792     follows \c QT_BEGIN_HEADER immediately.
2793
2794     If that rule can't be followed because, e.g., \c{#include} lines and
2795     declarations are wildly mixed, place \c QT_BEGIN_NAMESPACE before
2796     the first declaration and wrap the \c{#include} lines in
2797     \c QT_BEGIN_INCLUDE_NAMESPACE and \c QT_END_INCLUDE_NAMESPACE.
2798
2799     When using the \c QT_NAMESPACE feature in user code
2800     (e.g., when building plugins statically linked to Qt) where
2801     the user code is not intended to go into the \c QT_NAMESPACE
2802     namespace, all forward declarations of Qt classes need to
2803     be wrapped in \c QT_BEGIN_NAMESPACE and \c QT_END_NAMESPACE.
2804     After that, a \c QT_USE_NAMESPACE should follow.
2805     No further changes should be needed.
2806
2807     \sa QT_NAMESPACE
2808 */
2809
2810 /*!
2811     \macro QT_END_NAMESPACE
2812     \internal
2813
2814     This macro expands to
2815
2816     \snippet code/src_corelib_global_qglobal.cpp end namespace macro
2817
2818     if \c QT_NAMESPACE is defined and nothing otherwise. It is used to cancel
2819     the effect of \c QT_BEGIN_NAMESPACE.
2820
2821     If a source file ends with a \c{#include} directive that includes a moc file,
2822     \c QT_END_NAMESPACE should be placed before that \c{#include}.
2823
2824     \sa QT_NAMESPACE
2825 */
2826
2827 /*!
2828     \macro QT_BEGIN_INCLUDE_NAMESPACE
2829     \internal
2830
2831     This macro is equivalent to \c QT_END_NAMESPACE.
2832     It only serves as syntactic sugar and is intended
2833     to be used before #include lines within a
2834     \c QT_BEGIN_NAMESPACE ... \c QT_END_NAMESPACE block.
2835
2836     \sa QT_NAMESPACE
2837 */
2838
2839 /*!
2840     \macro QT_END_INCLUDE_NAMESPACE
2841     \internal
2842
2843     This macro is equivalent to \c QT_BEGIN_NAMESPACE.
2844     It only serves as syntactic sugar and is intended
2845     to be used after #include lines within a
2846     \c QT_BEGIN_NAMESPACE ... \c QT_END_NAMESPACE block.
2847
2848     \sa QT_NAMESPACE
2849 */
2850
2851 /*!
2852     \macro QT_BEGIN_MOC_NAMESPACE
2853     \internal
2854
2855     This macro is output by moc at the beginning of
2856     moc files. It is equivalent to \c QT_USE_NAMESPACE.
2857
2858     \sa QT_NAMESPACE
2859 */
2860
2861 /*!
2862     \macro QT_END_MOC_NAMESPACE
2863     \internal
2864
2865     This macro is output by moc at the beginning of
2866     moc files. It expands to nothing.
2867
2868     \sa QT_NAMESPACE
2869 */
2870
2871 /*!
2872  \fn bool qFuzzyCompare(double p1, double p2)
2873  \relates <QtGlobal>
2874  \since 4.4
2875  \threadsafe
2876
2877  Compares the floating point value \a p1 and \a p2 and
2878  returns \c true if they are considered equal, otherwise \c false.
2879
2880  Note that comparing values where either \a p1 or \a p2 is 0.0 will not work.
2881  The solution to this is to compare against values greater than or equal to 1.0.
2882
2883  \snippet code/src_corelib_global_qglobal.cpp 46
2884
2885  The two numbers are compared in a relative way, where the
2886  exactness is stronger the smaller the numbers are.
2887  */
2888
2889 /*!
2890  \fn bool qFuzzyCompare(float p1, float p2)
2891  \relates <QtGlobal>
2892  \since 4.4
2893  \threadsafe
2894
2895  Compares the floating point value \a p1 and \a p2 and
2896  returns \c true if they are considered equal, otherwise \c false.
2897
2898  The two numbers are compared in a relative way, where the
2899  exactness is stronger the smaller the numbers are.
2900  */
2901
2902 /*!
2903     \macro QT_REQUIRE_VERSION(int argc, char **argv, const char *version)
2904     \relates <QtGlobal>
2905
2906     This macro can be used to ensure that the application is run
2907     against a recent enough version of Qt. This is especially useful
2908     if your application depends on a specific bug fix introduced in a
2909     bug-fix release (e.g., 4.0.2).
2910
2911     The \a argc and \a argv parameters are the \c main() function's
2912     \c argc and \c argv parameters. The \a version parameter is a
2913     string literal that specifies which version of Qt the application
2914     requires (e.g., "4.0.2").
2915
2916     Example:
2917
2918     \snippet code/src_gui_dialogs_qmessagebox.cpp 4
2919 */
2920
2921 /*!
2922     \macro Q_DECL_EXPORT
2923     \relates <QtGlobal>
2924
2925     This macro marks a symbol for shared library export (see
2926      \l{sharedlibrary.html}{Creating Shared Libraries}).
2927
2928     \sa Q_DECL_IMPORT
2929 */
2930
2931 /*!
2932     \macro Q_DECL_IMPORT
2933     \relates <QtGlobal>
2934
2935     This macro declares a symbol to be an import from a shared library (see
2936     \l{sharedlibrary.html}{Creating Shared Libraries}).
2937
2938     \sa Q_DECL_EXPORT
2939 */
2940
2941 /*!
2942     \macro Q_DECL_CONSTEXPR
2943     \relates <QtGlobal>
2944
2945     This macro can be used to declare variable that should be constructed at compile-time,
2946     or an inline function that can be computed at compile-time.
2947
2948     It expands to "constexpr" if your compiler supports that C++11 keyword, or to nothing
2949     otherwise.
2950 */
2951
2952 /*!
2953     \macro qDebug(const char *message, ...)
2954     \relates <QtGlobal>
2955
2956     Calls the message handler with the debug message \a message. If no
2957     message handler has been installed, the message is printed to
2958     stderr. Under Windows, the message is sent to the console, if it is a
2959     console application; otherwise, it is sent to the debugger. On Blackberry the
2960     message is sent to slogger2. This function does nothing if \c QT_NO_DEBUG_OUTPUT
2961     was defined during compilation.
2962
2963     If you pass the function a format string and a list of arguments,
2964     it works in similar way to the C printf() function. The format
2965     should be a Latin-1 string.
2966
2967     Example:
2968
2969     \snippet code/src_corelib_global_qglobal.cpp 24
2970
2971     If you include \c <QtDebug>, a more convenient syntax is also
2972     available:
2973
2974     \snippet code/src_corelib_global_qglobal.cpp 25
2975
2976     With this syntax, the function returns a QDebug object that is
2977     configured to use the QtDebugMsg message type. It automatically
2978     puts a single space between each item, and outputs a newline at
2979     the end. It supports many C++ and Qt types.
2980
2981     To suppress the output at run-time, install your own message handler
2982     with qInstallMessageHandler().
2983
2984     \sa qWarning(), qCritical(), qFatal(), qInstallMessageHandler(),
2985         {Debugging Techniques}
2986 */
2987
2988 /*!
2989     \macro qWarning(const char *message, ...)
2990     \relates <QtGlobal>
2991
2992     Calls the message handler with the warning message \a message. If no
2993     message handler has been installed, the message is printed to
2994     stderr. Under Windows, the message is sent to the debugger.
2995     On Blackberry the message is sent to slogger2. This
2996     function does nothing if \c QT_NO_WARNING_OUTPUT was defined
2997     during compilation; it exits if the environment variable \c
2998     QT_FATAL_WARNINGS is defined.
2999
3000     This function takes a format string and a list of arguments,
3001     similar to the C printf() function. The format should be a Latin-1
3002     string.
3003
3004     Example:
3005     \snippet code/src_corelib_global_qglobal.cpp 26
3006
3007     If you include <QtDebug>, a more convenient syntax is
3008     also available:
3009
3010     \snippet code/src_corelib_global_qglobal.cpp 27
3011
3012     This syntax inserts a space between each item, and
3013     appends a newline at the end.
3014
3015     To suppress the output at runtime, install your own message handler
3016     with qInstallMessageHandler().
3017
3018     \sa qDebug(), qCritical(), qFatal(), qInstallMessageHandler(),
3019         {Debugging Techniques}
3020 */
3021
3022 /*!
3023     \macro qCritical(const char *message, ...)
3024     \relates <QtGlobal>
3025
3026     Calls the message handler with the critical message \a message. If no
3027     message handler has been installed, the message is printed to
3028     stderr. Under Windows, the message is sent to the debugger.
3029     On Blackberry the message is sent to slogger2.
3030
3031     This function takes a format string and a list of arguments,
3032     similar to the C printf() function. The format should be a Latin-1
3033     string.
3034
3035     Example:
3036     \snippet code/src_corelib_global_qglobal.cpp 28
3037
3038     If you include <QtDebug>, a more convenient syntax is
3039     also available:
3040
3041     \snippet code/src_corelib_global_qglobal.cpp 29
3042
3043     A space is inserted between the items, and a newline is
3044     appended at the end.
3045
3046     To suppress the output at runtime, install your own message handler
3047     with qInstallMessageHandler().
3048
3049     \sa qDebug(), qWarning(), qFatal(), qInstallMessageHandler(),
3050         {Debugging Techniques}
3051 */
3052
3053 /*!
3054     \macro qFatal(const char *message, ...)
3055     \relates <QtGlobal>
3056
3057     Calls the message handler with the fatal message \a message. If no
3058     message handler has been installed, the message is printed to
3059     stderr. Under Windows, the message is sent to the debugger.
3060     On Blackberry the message is sent to slogger2.
3061
3062     If you are using the \b{default message handler} this function will
3063     abort on Unix systems to create a core dump. On Windows, for debug builds,
3064     this function will report a _CRT_ERROR enabling you to connect a debugger
3065     to the application.
3066
3067     This function takes a format string and a list of arguments,
3068     similar to the C printf() function.
3069
3070     Example:
3071     \snippet code/src_corelib_global_qglobal.cpp 30
3072
3073     To suppress the output at runtime, install your own message handler
3074     with qInstallMessageHandler().
3075
3076     \sa qDebug(), qCritical(), qWarning(), qInstallMessageHandler(),
3077         {Debugging Techniques}
3078 */
3079
3080 /*!
3081     \macro qMove(x)
3082     \relates <QtGlobal>
3083
3084     It expands to "std::move" if your compiler supports that C++11 function, or to nothing
3085     otherwise.
3086 */
3087
3088 /*!
3089     \macro Q_DECL_NOTHROW
3090     \relates <QtGlobal>
3091     \since 5.0
3092
3093     This macro marks a function as never throwing, under no
3094     circumstances. If the function does nevertheless throw, the
3095     behaviour is undefined.
3096
3097     The macro expands to either "throw()", if that has some benefit on
3098     the compiler, or to C++11 noexcept, if available, or to nothing
3099     otherwise.
3100
3101     If you need C++11 noexcept semantics, don't use this macro, use
3102     Q_DECL_NOEXCEPT/Q_DECL_NOEXCEPT_EXPR instead.
3103
3104     \sa Q_DECL_NOEXCEPT, Q_DECL_NOEXCEPT_EXPR
3105 */
3106
3107 /*!
3108     \macro QT_TERMINATE_ON_EXCEPTION(expr)
3109     \relates <QtGlobal>
3110     \internal
3111
3112     In general, use of the Q_DECL_NOEXCEPT macro is preferred over
3113     Q_DECL_NOTHROW, because it exhibits well-defined behavior and
3114     supports the more powerful Q_DECL_NOEXCEPT_EXPR variant. However,
3115     use of Q_DECL_NOTHROW has the advantage that Windows builds
3116     benefit on a wide range or compiler versions that do not yet
3117     support the C++11 noexcept feature.
3118
3119     It may therefore be beneficial to use Q_DECL_NOTHROW and emulate
3120     the C++11 behavior manually with an embedded try/catch.
3121
3122     Qt provides the QT_TERMINATE_ON_EXCEPTION(expr) macro for this
3123     purpose. It either expands to \c expr (if Qt is compiled without
3124     exception support or the compiler supports C++11 noexcept
3125     semantics) or to
3126     \code
3127     try { expr; } catch(...) { qTerminate(); }
3128     \endcode
3129     otherwise.
3130
3131     Since this macro expands to just \c expr if the compiler supports
3132     C++11 noexcept, expecting the compiler to take over responsibility
3133     of calling std::terminate() in that case, it should not be used
3134     outside Q_DECL_NOTHROW functions.
3135
3136     \sa Q_DECL_NOEXCEPT, Q_DECL_NOTHROW, qTerminate()
3137 */
3138
3139 /*!
3140     \macro Q_DECL_NOEXCEPT
3141     \relates <QtGlobal>
3142     \since 5.0
3143
3144     This macro marks a function as never throwing. If the function
3145     does nevertheless throw, the behaviour is defined:
3146     std::terminate() is called.
3147
3148     The macro expands to C++11 noexcept, if available, or to nothing
3149     otherwise.
3150
3151     If you need the operator version of C++11 noexcept, use
3152     Q_DECL_NOEXCEPT_EXPR(x).
3153
3154     If you don't need C++11 noexcept semantics, e.g. because your
3155     function can't possibly throw, don't use this macro, use
3156     Q_DECL_NOTHROW instead.
3157
3158     \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT_EXPR
3159 */
3160
3161 /*!
3162     \macro Q_DECL_NOEXCEPT_EXPR(x)
3163     \relates <QtGlobal>
3164     \since 5.0
3165
3166     This macro marks a function as non-throwing if \a x is true. If
3167     the function does nevertheless throw, the behaviour is defined:
3168     std::terminate() is called.
3169
3170     The macro expands to C++11 noexcept(x), if available, or to
3171     nothing otherwise.
3172
3173     If you need the always-true version of C++11 noexcept, use
3174     Q_DECL_NOEXCEPT.
3175
3176     If you don't need C++11 noexcept semantics, e.g. because your
3177     function can't possibly throw, don't use this macro, use
3178     Q_DECL_NOTHROW instead.
3179
3180     \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT_EXPR
3181 */
3182
3183 /*!
3184     \macro Q_DECL_OVERRIDE
3185     \since 5.0
3186     \relates <QtGlobal>
3187
3188     This macro can be used to declare an overriding virtual
3189     function. Use of this markup will allow the compiler to generate
3190     an error if the overriding virtual function does not in fact
3191     override anything.
3192
3193     It expands to "override" if your compiler supports that C++11
3194     contextual keyword, or to nothing otherwise.
3195
3196     The macro goes at the end of the function, usually after the
3197     \c{const}, if any:
3198     \code
3199     // generate error if this doesn't actually override anything:
3200     virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_OVERRIDE;
3201     \endcode
3202
3203     \sa Q_DECL_FINAL
3204 */
3205
3206 /*!
3207     \macro Q_DECL_FINAL
3208     \since 5.0
3209     \relates <QtGlobal>
3210
3211     This macro can be used to declare an overriding virtual or a class
3212     as "final", with Java semantics. Further-derived classes can then
3213     no longer override this virtual function, or inherit from this
3214     class, respectively.
3215
3216     It expands to "final" if your compiler supports that C++11
3217     contextual keyword, or something non-standard if your compiler
3218     supports something close enough to the C++11 semantics, or to
3219     nothing otherwise.
3220
3221     The macro goes at the end of the function, usually after the
3222     \c{const}, if any:
3223     \code
3224     // more-derived classes no longer permitted to override this:
3225     virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_FINAL;
3226     \endcode
3227
3228     For classes, it goes in front of the \c{:} in the class
3229     definition, if any:
3230     \code
3231     class QRect Q_DECL_FINAL { // cannot be derived from
3232         // ...
3233     };
3234     \endcode
3235
3236     \sa Q_DECL_OVERRIDE
3237 */
3238
3239 QT_END_NAMESPACE