/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the QtCore module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "qplatformdefs.h"

#include "qstring.h"

#include "qvector.h"

#include "qlist.h"

#include "qthreadstorage.h"

#include "qdir.h"

#include "qstringlist.h"

#include "qdatetime.h"

#ifndef QT_NO_QOBJECT

#include <private/qthread_p.h>

#endif

#include <stdio.h>

#include <stdlib.h>

#include <limits.h>

#include <stdarg.h>

#include <string.h>

#ifndef QT_NO_EXCEPTIONS

#  include <string>

#  include <exception>

#endif

#if !defined(Q_OS_WINCE)

#  include <errno.h>

#  if defined(Q_CC_MSVC)

#    include <crtdbg.h>

#  endif

#endif

#if defined(Q_OS_VXWORKS)

#  include <envLib.h>

#endif

#if defined(Q_CC_MWERKS) && defined(Q_OS_MACX)

#include <CoreServices/CoreServices.h>

#endif

#if defined(Q_OS_SYMBIAN)

#include <e32def.h>

#include <e32debug.h>

#include <flogger.h>

#include <f32file.h>

#include <e32math.h>

# include "private/qcore_symbian_p.h"

_LIT(qt_S60Filter, "Series60v?.*.sis");

_LIT(qt_S60SystemInstallDir, "z:\\system\\install\\");

#endif

QT_BEGIN_NAMESPACE

/*!

    \class QFlag

    \brief The QFlag class is a helper data type for QFlags.

    It is equivalent to a plain \c int, except with respect to

    function overloading and type conversions. You should never need

    to use this class in your applications.

    \sa QFlags

*/

/*!

    \fn QFlag::QFlag(int value)

    Constructs a QFlag object that stores the given \a value.

*/

/*!

    \fn QFlag::operator int() const

    Returns the value stored by the QFlag object.

*/

/*!

    \class QFlags

    \brief The QFlags class provides a type-safe way of storing

    OR-combinations of enum values.

    \ingroup tools

    The QFlags<Enum> class is a template class, where Enum is an enum

    type. QFlags is used throughout Qt for storing combinations of

    enum values.

    The traditional C++ approach for storing OR-combinations of enum

    values is to use an \c int or \c uint variable. The inconvenience

    with this approach is that there's no type checking at all; any

    enum value can be OR'd with any other enum value and passed on to

    a function that takes an \c int or \c uint.

    Qt uses QFlags to provide type safety. For example, the

    Qt::Alignment type is simply a typedef for

    QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() takes a

    Qt::Alignment parameter, which means that any combination of

    Qt::AlignmentFlag values,or 0, is legal:

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 0

    If you try to pass a value from another enum or just a plain

    integer other than 0, the compiler will report an error. If you

    need to cast integer values to flags in a untyped fashion, you can

    use the explicit QFlags constructor as cast operator.

    If you want to use QFlags for your own enum types, use

    the Q_DECLARE_FLAGS() and Q_DECLARE_OPERATORS_FOR_FLAGS().

    Example:

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 1

    You can then use the \c MyClass::Options type to store

    combinations of \c MyClass::Option values.

    \section1 Flags and the Meta-Object System

    The Q_DECLARE_FLAGS() macro does not expose the flags to the meta-object

    system, so they cannot be used by Qt Script or edited in Qt Designer.

    To make the flags available for these purposes, the Q_FLAGS() macro must

    be used:

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp meta-object flags

    \section1 Naming Convention

    A sensible naming convention for enum types and associated QFlags

    types is to give a singular name to the enum type (e.g., \c

    Option) and a plural name to the QFlags type (e.g., \c Options).

    When a singular name is desired for the QFlags type (e.g., \c

    Alignment), you can use \c Flag as the suffix for the enum type

    (e.g., \c AlignmentFlag).

    \sa QFlag

*/

/*!

    \typedef QFlags::enum_type

    Typedef for the Enum template type.

*/

/*!

    \fn QFlags::QFlags(const QFlags &other)

    Constructs a copy of \a other.

*/

/*!

    \fn QFlags::QFlags(Enum flag)

    Constructs a QFlags object storing the given \a flag.

*/

/*!

    \fn QFlags::QFlags(Zero zero)

    Constructs a QFlags object with no flags set. \a zero must be a

    literal 0 value.

*/

/*!

    \fn QFlags::QFlags(QFlag value)

    Constructs a QFlags object initialized with the given integer \a

    value.

    The QFlag type is a helper type. By using it here instead of \c

    int, we effectively ensure that arbitrary enum values cannot be

    cast to a QFlags, whereas untyped enum values (i.e., \c int

    values) can.

*/

/*!

    \fn QFlags &QFlags::operator=(const QFlags &other)

    Assigns \a other to this object and returns a reference to this

    object.

*/

/*!

    \fn QFlags &QFlags::operator&=(int mask)

    Performs a bitwise AND operation with \a mask and stores the

    result in this QFlags object. Returns a reference to this object.

    \sa operator&(), operator|=(), operator^=()

*/

/*!

    \fn QFlags &QFlags::operator&=(uint mask)

    \overload

*/

/*!

    \fn QFlags &QFlags::operator|=(QFlags other)

    Performs a bitwise OR operation with \a other and stores the

    result in this QFlags object. Returns a reference to this object.

    \sa operator|(), operator&=(), operator^=()

*/

/*!

    \fn QFlags &QFlags::operator|=(Enum other)

    \overload

*/

/*!

    \fn QFlags &QFlags::operator^=(QFlags other)

    Performs a bitwise XOR operation with \a other and stores the

    result in this QFlags object. Returns a reference to this object.

    \sa operator^(), operator&=(), operator|=()

*/

/*!

    \fn QFlags &QFlags::operator^=(Enum other)

    \overload

*/

/*!

    \fn QFlags::operator int() const

    Returns the value stored in the QFlags object as an integer.

*/

/*!

    \fn QFlags QFlags::operator|(QFlags other) const

    Returns a QFlags object containing the result of the bitwise OR

    operation on this object and \a other.

    \sa operator|=(), operator^(), operator&(), operator~()

*/

/*!

    \fn QFlags QFlags::operator|(Enum other) const

    \overload

*/

/*!

    \fn QFlags QFlags::operator^(QFlags other) const

    Returns a QFlags object containing the result of the bitwise XOR

    operation on this object and \a other.

    \sa operator^=(), operator&(), operator|(), operator~()

*/

/*!

    \fn QFlags QFlags::operator^(Enum other) const

    \overload

*/

/*!

    \fn QFlags QFlags::operator&(int mask) const

    Returns a QFlags object containing the result of the bitwise AND

    operation on this object and \a mask.

    \sa operator&=(), operator|(), operator^(), operator~()

*/

/*!

    \fn QFlags QFlags::operator&(uint mask) const

    \overload

*/

/*!

    \fn QFlags QFlags::operator&(Enum mask) const

    \overload

*/

/*!

    \fn QFlags QFlags::operator~() const

    Returns a QFlags object that contains the bitwise negation of

    this object.

    \sa operator&(), operator|(), operator^()

*/

/*!

    \fn bool QFlags::operator!() const

    Returns true if no flag is set (i.e., if the value stored by the

    QFlags object is 0); otherwise returns false.

*/

/*!

    \fn bool QFlags::testFlag(Enum flag) const

    \since 4.2

    Returns true if the \a flag is set, otherwise false.

*/

/*!

  \macro Q_DISABLE_COPY(Class)

  \relates QObject

  Disables the use of copy constructors and assignment operators

  for the given \a Class.

  Instances of subclasses of QObject should not be thought of as

  values that can be copied or assigned, but as unique identities.

  This means that when you create your own subclass of QObject

  (director or indirect), you should \e not give it a copy constructor

  or an assignment operator.  However, it may not enough to simply

  omit them from your class, because, if you mistakenly write some code

  that requires a copy constructor or an assignment operator (it's easy

  to do), your compiler will thoughtfully create it for you. You must

  do more.

  The curious user will have seen that the Qt classes derived

  from QObject typically include this macro in a private section:

  \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 43

  It declares a copy constructor and an assignment operator in the

  private section, so that if you use them by mistake, the compiler

  will report an error.

  \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 44

  But even this might not catch absolutely every case. You might be

  tempted to do something like this:

  \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 45

  First of all, don't do that. Most compilers will generate code that

  uses the copy constructor, so the privacy violation error will be

  reported, but your C++ compiler is not required to generate code for

  this statement in a specific way. It could generate code using

  \e{neither} the copy constructor \e{nor} the assignment operator we

  made private. In that case, no error would be reported, but your

  application would probably crash when you called a member function

  of \c{w}.

*/

/*!

    \macro Q_DECLARE_FLAGS(Flags, Enum)

    \relates QFlags

    The Q_DECLARE_FLAGS() macro expands to

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 2

    \a Enum is the name of an existing enum type, whereas \a Flags is

    the name of the QFlags<\e{Enum}> typedef.

    See the QFlags documentation for details.

    \sa Q_DECLARE_OPERATORS_FOR_FLAGS()

*/

/*!

    \macro Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)

    \relates QFlags

    The Q_DECLARE_OPERATORS_FOR_FLAGS() macro declares global \c

    operator|() functions for \a Flags, which is of type QFlags<T>.

    See the QFlags documentation for details.

    \sa Q_DECLARE_FLAGS()

*/

/*!

    \headerfile <QtGlobal>

    \title Global Qt Declarations

    \ingroup funclists

    \brief The <QtGlobal> header file includes the fundamental global

    declarations. It is included by most other Qt header files.

    The global declarations include \l{types}, \l{functions} and

    \l{macros}.

    The type definitions are partly convenience definitions for basic

    types (some of which guarantee certain bit-sizes on all platforms

    supported by Qt), partly types related to Qt message handling. The

    functions are related to generating messages, Qt version handling

    and comparing and adjusting object values. And finally, some of

    the declared macros enable programmers to add compiler or platform

    specific code to their applications, while others are convenience

    macros for larger operations.

    \section1 Types

    The header file declares several type definitions that guarantee a

    specified bit-size on all platforms supported by Qt for various

    basic types, for example \l qint8 which is a signed char

    guaranteed to be 8-bit on all platforms supported by Qt. The

    header file also declares the \l qlonglong type definition for \c

    {long long int } (\c __int64 on Windows).

    Several convenience type definitions are declared: \l qreal for \c

    double, \l uchar for \c unsigned char, \l uint for \c unsigned

    int, \l ulong for \c unsigned long and \l ushort for \c unsigned

    short.

    Finally, the QtMsgType definition identifies the various messages

    that can be generated and sent to a Qt message handler;

    QtMsgHandler is a type definition for a pointer to a function with

    the signature \c {void myMsgHandler(QtMsgType, const char *)}.

    \section1 Functions

    The <QtGlobal> header file contains several functions comparing

    and adjusting an object's value. These functions take a template

    type as argument: You can retrieve the absolute value of an object

    using the qAbs() function, and you can bound a given object's

    value by given minimum and maximum values using the qBound()

    function. You can retrieve the minimum and maximum of two given

    objects using qMin() and qMax() respectively. All these functions

    return a corresponding template type; the template types can be

    replaced by any other type.

    Example:

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 3

    <QtGlobal> also contains functions that generate messages from the

    given string argument: qCritical(), qDebug(), qFatal() and

    qWarning(). These functions call the message handler with the

    given message.

    Example:

    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 4

    The remaining functions are qRound() and qRound64(), which both

    accept a \l qreal value as their argument returning the value

    rounded up to the nearest integer and 64-bit integer respectively,

    the qInstallMsgHandler() function which installs the given

    QtMsgHandler, and the qVersion() function which returns the

    version number of Qt at run-time as a string.

    \section1 Macros

    The <QtGlobal> header file provides a range of macros (Q_CC_*)

    that are defined if the application is compiled using the

    specified platforms. For example, the Q_CC_SUN macro is defined if

    the application is compiled using Forte Developer, or Sun Studio

    C++.  The header file also declares a range of macros (Q_OS_*)

    that are defined for the specified platforms. For example,

    Q_OS_X11 which is defined for the X Window System.

    The purpose of these macros is to enable programmers to add

    compiler or platform specific code to their application.

    The remaining macros are convenience macros for larger operations:

    The QT_TRANSLATE_NOOP() and QT_TR_NOOP() macros provide the

    possibility of marking text for dynamic translation,

    i.e. translation without changing the stored source text. The

    Q_ASSERT() and Q_ASSERT_X() enables warning messages of various

    level of refinement. The Q_FOREACH() and foreach() macros

    implement Qt's foreach loop.

    The Q_INT64_C() and Q_UINT64_C() macros wrap signed and unsigned

    64-bit integer literals in a platform-independent way. The

    Q_CHECK_PTR() macro prints a warning containing the source code's

    file name and line number, saying that the program ran out of

    memory, if the pointer is 0. The qPrintable() macro represent an

    easy way of printing text.

    Finally, the QT_POINTER_SIZE macro expands to the size of a

    pointer in bytes, and the QT_VERSION and QT_VERSION_STR macros

    expand to a numeric value or a string, respectively, specifying

    Qt's version number, i.e the version the application is compiled

    against.

    \sa <QtAlgorithms>, QSysInfo

*/