qstring.cpp

QT 开发环境里面一个很重要的文件

    toLocal8Bit() explicitly to convert the QString to an 8-bit
    string.  (Other encodings are supported through the QTextCodec
    class.)

    \table 100 %
    \row
    \o
    \section1 Note for C Programmers

    Due to C++'s type system and the fact that QString is
    \l{implicitly shared}, QStrings may be treated like \c{int}s or
    other basic types. For example:

    \skipto boolToString(bool b)
    \printuntil }

    The \c result variable, is a normal variable allocated on the
    stack. When \c return is called, and because we're returning by
    value, the copy constructor is called and a copy of the string is
    returned. No actual copying takes place thanks to the implicit
    sharing.

    \endtable

    \section1 Distinction Between Null and Empty Strings

    For historical reasons, QString distinguishes between a null
    string and an empty string. A \e null string is a string that is
    initialized using QString's default constructor or by passing
    (const char *)0 to the constructor. An \e empty string is any
    string with size 0. A null string is always empty, but an empty
    string isn't necessarily null:

    \quotefromfile snippets/qstring/main.cpp
    \skipto QString().isNull()
    \printuntil QString("abc").isEmpty()

    All functions except isNull() treat null strings the same as empty
    strings. For example, toAscii().constData() returns a pointer to a
    '\\0' character for a null string (\e not a null pointer), and
    QString() compares equal to QString(""). We recommend that you
    always use the isEmpty() function and avoid isNull().

    \sa fromRawData(), QChar, QLatin1String, QByteArray
*/

/*!
    \enum QString::SplitBehavior

    This enum specifies how the split() function should behave with
    respect to empty strings.

    \value KeepEmptyParts  If a field is empty, keep it in the result.
    \value SkipEmptyParts  If a field is empty, don't include it in the result.

    \sa split()
*/

QString::Data QString::shared_null = { Q_ATOMIC_INIT(1), 0, 0, shared_null.array, 0, 0, 0, 0, 0, {0} };
QString::Data QString::shared_empty = { Q_ATOMIC_INIT(1), 0, 0, shared_empty.array, 0, 0, 0, 0, 0, {0} };

inline int QString::grow(int size)
{
    return qAllocMore(size * sizeof(QChar), sizeof(Data)) / sizeof(QChar);
}

/*! \typedef QString::ConstIterator

    \internal

    Qt-style synonym for QString::const_iterator.
*/

/*! \typedef QString::Iterator

    \internal

    Qt-style synonym for QString::iterator.
*/

/*! \typedef QString::const_iterator

    \internal

    The QString::const_iterator typedef provides an STL-style const
    iterator for QString.

    \sa QString::iterator
*/

/*! \typedef QString::iterator

    \internal

    The QString::iterator typedef provides an STL-style non-const
    iterator for QString.

    \sa QString::const_iterator
*/

/*! \fn QString::iterator QString::begin()

    \internal
*/

/*! \fn QString::const_iterator QString::begin() const

    \internal
*/

/*! \fn QString::const_iterator QString::constBegin() const

    \internal
*/

/*! \fn QString::iterator QString::end()

    \internal
*/

/*! \fn QString::const_iterator QString::end() const

    \internal
*/

/*! \fn QString::const_iterator QString::constEnd() const

    \internal
*/

/*!
    \fn QString::QString()

    Constructs a null string. Null strings are also empty.

    \sa isEmpty()
*/

/*! \fn QString::QString(const char *str)

    Constructs a string initialized with the ASCII string \a str. The
    given const char pointer is converted to Unicode using the
    fromAscii() function.

    You can disable this constructor by defining \c
    QT_NO_CAST_FROM_ASCII when you compile your applications. This
    can be useful if you want to ensure that all user-visible strings
    go through QObject::tr(), for example.

    \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
*/

/*! \fn QString QString::fromStdString(const std::string &str)

    Returns a copy of the \a str string. The given string is converted
    to Unicode using the fromAscii() function.

    This constructor is only available if Qt is configured with STL
    compatibility enabled.

    \sa  fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
*/

/*! \fn QString QString::fromStdWString(const std::wstring &str)

    Returns a copy of the \a str string. The given string is assumed
    to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on
    windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix
    systems).

    This method is only available if Qt is configured with STL
    compatibility enabled.

    \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4()
*/

/*!
    \since 4.2

    Returns a copy of the \a string string encoded in ucs4.

    If \a size is -1 (the default), the \a string has to be 0 terminated.

    \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
*/
QString QString::fromWCharArray(const wchar_t *string, int size)
{
    if (sizeof(wchar_t) == sizeof(QChar)) {
        return fromUtf16((ushort *)string, size);
    } else {
        return fromUcs4((uint *)string, size);
    }
}

/*! \fn std::wstring QString::toStdWString() const

    Returns a std::wstring object with the data contained in this
    QString. The std::wstring is encoded in utf16 on platforms where
    wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
    where wchar_t is 4 bytes wide (most Unix systems).

    This operator is mostly useful to pass a QString to a function
    that accepts a std::wstring object.

    This operator is only available if Qt is configured with STL
    compatibility enabled.

    \sa utf16(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
*/

/*!
  \since 4.2

  Fills the \a array with the data contained in this QString object.
  The array is encoded in utf16 on platforms where
  wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
  where wchar_t is 4 bytes wide (most Unix systems).

  \a array has to be allocated by the caller and contain enough space to
  hold the complete string (allocating the array with the same length as the
  string is always sufficient).

  returns the actual length of the string in \a array.

  \sa utf16(), toUcs4(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString()
*/
int QString::toWCharArray(wchar_t *array) const
{
    if (sizeof(wchar_t) == sizeof(QChar)) {
        memcpy(array, utf16(), sizeof(wchar_t)*length());
        return length();
    } else {
        wchar_t *a = array;
        const unsigned short *uc = utf16();
        for (int i = 0; i < length(); ++i) {
            uint u = uc[i];
            if (u >= 0xd800 && u < 0xdc00 && i < length()-1) {
                ushort low = uc[i+1];
                if (low >= 0xdc00 && low < 0xe000) {
                    ++i;
                    u = (u - 0xd800)*0x400 + (low - 0xdc00) + 0x10000;
                }
            }
            *a = wchar_t(u);
            ++a;
        }
        return a - array;
    }
}

/*! \fn QString::QString(const QString &other)

    Constructs a copy of \a other.

    This operation takes \l{constant time}, because QString is
    \l{implicitly shared}. This makes returning a QString from a
    function very fast. If a shared instance is modified, it will be
    copied (copy-on-write), and that takes \l{linear time}.

    \sa operator=()
*/

/*!
    Constructs a string initialized with the first \a size characters
    of the QChar array \a unicode.

    QString makes a deep copy of the string data.
*/
QString::QString(const QChar *unicode, int size)
{
   if (!unicode) {
        d = &shared_null;
        d->ref.ref();
    } else if (size <= 0) {
        d = &shared_empty;
        d->ref.ref();
    } else {
        d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
        d->ref.init(1);
        d->alloc = d->size = size;
        d->clean = d->asciiCache = d->simpletext = d->righttoleft = 0;
        d->data = d->array;
        memcpy(d->array, unicode, size * sizeof(QChar));
        d->array[size] = '\0';
    }
}


/*!
    Constructs a string of the given \a size with every character set
    to \a ch.

    \sa fill()
*/
QString::QString(int size, QChar ch)
{
   if (size <= 0) {
        d = &shared_empty;
        d->ref.ref();
    } else {
        d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
        d->ref.init(1);
        d->alloc = d->size = size;
        d->clean = d->asciiCache = d->simpletext = d->righttoleft = 0;
        d->data = d->array;
        d->array[size] = '\0';
        ushort *i = d->array + size;
        ushort *b = d->array;
        const ushort value = ch.unicode();
        while (i != b)
           *--i = value;
    }
}

/*! \fn QString::QString(const QLatin1String &str)

    Constructs a copy of the Latin-1 string \a str.

    \sa fromLatin1()
*/

/*!
    Constructs a string of size 1 containing the character \a ch.
*/
QString::QString(QChar ch)
{
    d = (Data *)qMalloc(sizeof(Data) + sizeof(QChar));
    d->ref.init(1);
    d->alloc = d->size = 1;
    d->clean = d->asciiCache = d->simpletext = d->righttoleft = 0;
    d->data = d->array;
    d->array[0] = ch.unicode();
    d->array[1] = '\0';
}

/*! \fn QString::QString(const QByteArray &ba)

    Constructs a string initialized with the byte array \a ba. The
    given byte array is converted to Unicode using fromAscii(). Stops
    copying at the first 0 character, otherwise copies the entire byte
    array.

    You can disable this constructor by defining \c
    QT_NO_CAST_FROM_ASCII when you compile your applications. This
    can be useful if you want to ensure that all user-visible strings
    go through QObject::tr(), for example.

    \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
*/

/*! \fn QString::QString(const Null &)
    \internal
*/

/*! \fn QString &QString::operator=(const Null &)
    \internal
*/

/*!
  \fn QString::~QString()

    Destroys the string.
*/


/*! \fn void QString::detach()

    \internal
*/

/*! \fn void QString::isDetached() const

    \internal
*/

void QString::free(Data *d)
{
#ifdef QT3_SUPPORT
    if (d->asciiCache) {
        Q_ASSERT(asciiCache);
        asciiCache->remove(d);
    }
#endif
    qFree(d);
}

/*!
    Sets the size of the string to \a size characters.

    If \a size is greater than the current size, the string is
    extended to make it \a size characters long with the extra
    characters added to the end. The new characters are uninitialized.

    If \a size is less than the current size, characters are removed
    from the end.

    Example:

    \quotefromfile snippets/qstring/main.cpp
    \skipto Widget::resizeFunction()
    \skipto QString s
    \printuntil // s == "Hello???"

    If you want to append a certain number of identical characters to
    the string, use \l operator+=() as follows rather than resize():

    \quotefromfile snippets/qstring/main.cpp
    \skipto Widget::resizeFunction()
    \skipto QString t
    \printuntil // t == "HelloXXXXXXXXXX"

    If you want to expand the string so that it reaches a certain
    width and fill the new positions with a particular character, use
    the leftJustified() function:

    \quotefromfile snippets/qstring/main.cpp
    \skipto Widget::resizeFunction()
    \skipto QString r
    \printuntil // r == "Hello     "

    \sa truncate(), reserve()
*/

void QString::resize(int size)
{
    if (size <= 0) {
        Data *x = &shared_empty;
        x->ref.ref();
        x = qAtomicSetPtr(&d, x);
        if (!x->ref.deref())
            free(x);
    } else {
        if (d->ref != 1 || size > d->alloc || (size < d->size && size < d->alloc >> 1))
            realloc(grow(size));
        if (d->alloc >= size) {
            d->size = size;
            if (d->data == d->array) {
                d->array[size] = '\0';
            }
        }
    }
}