source: trunk/src/corelib/tools/qstring.cpp @ 849

Last change on this file since 849 was 849, checked in by Dmitry A. Kuminov, 10 years ago

QString: Bump the checked Qt version to 4.7.3.

File size: 244.9 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file.  Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights.  These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file.  Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at qt-info@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "qstringlist.h"
43#include "qregexp.h"
44#include "qunicodetables_p.h"
45#ifndef QT_NO_TEXTCODEC
46#include <qtextcodec.h>
47#endif
48#include <private/qutfcodec_p.h>
49#include "qsimd_p.h"
50#include <qdatastream.h>
51#include <qlist.h>
52#include "qlocale.h"
53#include "qlocale_p.h"
54#include "qstringmatcher.h"
55#include "qvarlengtharray.h"
56#include "qtools_p.h"
57#include "qhash.h"
58#include "qdebug.h"
59#include "qendian.h"
60
61#ifdef Q_OS_MAC
62#include <private/qcore_mac_p.h>
63#endif
64
65#ifdef Q_OS_OS2
66#include "qatomic.h"
67#include <unidef.h>
68#endif
69
70#include <private/qfunctions_p.h>
71
72#if defined(Q_OS_WINCE)
73#include <windows.h>
74#include <winnls.h>
75#endif
76
77#ifdef Q_OS_SYMBIAN
78#include <e32cmn.h>
79#endif
80
81#include <limits.h>
82#include <string.h>
83#include <stdlib.h>
84#include <stdio.h>
85#include <stdarg.h>
86
87#ifdef truncate
88#undef truncate
89#endif
90
91#include "qchar.cpp"
92#include "qstringmatcher.cpp"
93
94#ifndef LLONG_MAX
95#define LLONG_MAX qint64_C(9223372036854775807)
96#endif
97#ifndef LLONG_MIN
98#define LLONG_MIN (-LLONG_MAX - qint64_C(1))
99#endif
100#ifndef ULLONG_MAX
101#define ULLONG_MAX quint64_C(18446744073709551615)
102#endif
103
104QT_BEGIN_NAMESPACE
105
106#ifndef QT_NO_TEXTCODEC
107QTextCodec *QString::codecForCStrings;
108#endif
109
110#ifdef QT3_SUPPORT
111static QHash<void *, QByteArray> *asciiCache = 0;
112#endif
113
114// internal
115int qFindString(const QChar *haystack, int haystackLen, int from,
116    const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
117int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from,
118    const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
119
120
121// Unicode case-insensitive comparison
122static int ucstricmp(const ushort *a, const ushort *ae, const ushort *b, const ushort *be)
123{
124    if (a == b)
125        return (ae - be);
126    if (a == 0)
127        return 1;
128    if (b == 0)
129        return -1;
130
131    const ushort *e = ae;
132    if (be - b < ae - a)
133        e = a + (be - b);
134
135    uint alast = 0;
136    uint blast = 0;
137    while (a < e) {
138//         qDebug() << hex << alast << blast;
139//         qDebug() << hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast);
140//         qDebug() << hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast);
141        int diff = foldCase(*a, alast) - foldCase(*b, blast);
142        if ((diff))
143            return diff;
144        ++a;
145        ++b;
146    }
147    if (a == ae) {
148        if (b == be)
149            return 0;
150        return -1;
151    }
152    return 1;
153}
154
155// Case-insensitive comparison between a Unicode string and a QLatin1String
156static int ucstricmp(const ushort *a, const ushort *ae, const uchar *b)
157{
158    if (a == 0) {
159        if (b == 0)
160            return 0;
161        return 1;
162    }
163    if (b == 0)
164        return -1;
165
166    while (a < ae && *b) {
167        int diff = foldCase(*a) - foldCase(*b);
168        if ((diff))
169            return diff;
170        ++a;
171        ++b;
172    }
173    if (a == ae) {
174        if (!*b)
175            return 0;
176        return -1;
177    }
178    return 1;
179}
180
181// Unicode case-sensitive compare two same-sized strings
182static int ucstrncmp(const QChar *a, const QChar *b, int l)
183{
184    while (l-- && *a == *b)
185        a++,b++;
186    if (l==-1)
187        return 0;
188    return a->unicode() - b->unicode();
189}
190
191// Unicode case-sensitive comparison
192static int ucstrcmp(const QChar *a, int alen, const QChar *b, int blen)
193{
194    if (a == b && alen == blen)
195        return 0;
196    int l = qMin(alen, blen);
197    int cmp = ucstrncmp(a, b, l);
198    return cmp ? cmp : (alen-blen);
199}
200
201// Unicode case-insensitive compare two same-sized strings
202static int ucstrnicmp(const ushort *a, const ushort *b, int l)
203{
204    return ucstricmp(a, a + l, b, b + l);
205}
206
207// Benchmarking indicates that doing memcmp is much slower than
208// executing the comparison ourselves.
209//
210// The profiling was done on a population of calls to qMemEquals, generated
211// during a run of the demo browser. The profile of the data (32-bit x86
212// Linux) was:
213//
214//  total number of comparisons: 21353
215//  longest string compared: 95
216//  average comparison length: 14.8786
217//  cache-line crosses: 5661 (13.3%)
218//  alignment histogram:
219//   0xXXX0 = 512 (1.2%) strings, 0 (0.0%) of which same-aligned
220//   0xXXX2 = 15087 (35.3%) strings, 5145 (34.1%) of which same-aligned
221//   0xXXX4 = 525 (1.2%) strings, 0 (0.0%) of which same-aligned
222//   0xXXX6 = 557 (1.3%) strings, 6 (1.1%) of which same-aligned
223//   0xXXX8 = 509 (1.2%) strings, 0 (0.0%) of which same-aligned
224//   0xXXXa = 24358 (57.0%) strings, 9901 (40.6%) of which same-aligned
225//   0xXXXc = 557 (1.3%) strings, 0 (0.0%) of which same-aligned
226//   0xXXXe = 601 (1.4%) strings, 15 (2.5%) of which same-aligned
227//   total  = 42706 (100%) strings, 15067 (35.3%) of which same-aligned
228//
229// 92% of the strings have alignment of 2 or 10, which is due to malloc on
230// 32-bit Linux returning values aligned to 8 bytes, and offsetof(array, QString::Data) == 18.
231//
232// The profile on 64-bit will be different since offsetof(array, QString::Data) == 26.
233//
234// The benchmark results were, for a Core-i7 @ 2.67 GHz 32-bit, compiled with -O3 -funroll-loops:
235//   16-bit loads only:           872,301 CPU ticks [Qt 4.5 / memcmp]
236//   32- and 16-bit loads:        773,362 CPU ticks [Qt 4.6]
237//   SSE2 "movdqu" 128-bit loads: 618,736 CPU ticks
238//   SSE3 "lddqu" 128-bit loads:  619,954 CPU ticks
239//   SSSE3 "palignr" corrections: 852,147 CPU ticks
240//   SSE4.2 "pcmpestrm":          738,702 CPU ticks
241//
242// The same benchmark on an Atom N450 @ 1.66 GHz, is:
243//  16-bit loads only:            2,185,882 CPU ticks
244//  32- and 16-bit loads:         1,805,060 CPU ticks
245//  SSE2 "movdqu" 128-bit loads:  2,529,843 CPU ticks
246//  SSE3 "lddqu" 128-bit loads:   2,514,858 CPU ticks
247//  SSSE3 "palignr" corrections:  2,160,325 CPU ticks
248//  SSE4.2 not available
249//
250// The conclusion we reach is that alignment the SSE2 unaligned code can gain
251// 20% improvement in performance in some systems, but suffers a penalty due
252// to the unaligned loads on others.
253
254static bool qMemEquals(const quint16 *a, const quint16 *b, int length)
255{
256    if (a == b || !length)
257        return true;
258
259    register union {
260        const quint16 *w;
261        const quint32 *d;
262        quintptr value;
263    } sa, sb;
264    sa.w = a;
265    sb.w = b;
266
267    // check alignment
268    if ((sa.value & 2) == (sb.value & 2)) {
269        // both addresses have the same alignment
270        if (sa.value & 2) {
271            // both addresses are not aligned to 4-bytes boundaries
272            // compare the first character
273            if (*sa.w != *sb.w)
274                return false;
275            --length;
276            ++sa.w;
277            ++sb.w;
278
279            // now both addresses are 4-bytes aligned
280        }
281
282        // both addresses are 4-bytes aligned
283        // do a fast 32-bit comparison
284        register const quint32 *e = sa.d + (length >> 1);
285        for ( ; sa.d != e; ++sa.d, ++sb.d) {
286            if (*sa.d != *sb.d)
287                return false;
288        }
289
290        // do we have a tail?
291        return (length & 1) ? *sa.w == *sb.w : true;
292    } else {
293        // one of the addresses isn't 4-byte aligned but the other is
294        register const quint16 *e = sa.w + length;
295        for ( ; sa.w != e; ++sa.w, ++sb.w) {
296            if (*sa.w != *sb.w)
297                return false;
298        }
299    }
300    return true;
301}
302
303/*!
304    \internal
305
306    Returns the index position of the first occurrence of the
307    character \a ch in the string given by \a str and \a len,
308    searching forward from index
309    position \a from. Returns -1 if \a ch could not be found.
310*/
311static int findChar(const QChar *str, int len, QChar ch, int from,
312    Qt::CaseSensitivity cs)
313{
314    const ushort *s = (const ushort *)str;
315    ushort c = ch.unicode();
316    if (from < 0)
317        from = qMax(from + len, 0);
318    if (from < len) {
319        const ushort *n = s + from - 1;
320        const ushort *e = s + len;
321        if (cs == Qt::CaseSensitive) {
322            while (++n != e)
323                if (*n == c)
324                    return  n - s;
325        } else {
326            c = foldCase(c);
327            while (++n != e)
328                if (foldCase(*n) == c)
329                    return  n - s;
330        }
331    }
332    return -1;
333}
334
335#define REHASH(a) \
336    if (sl_minus_1 < (int)sizeof(int) * CHAR_BIT)       \
337        hashHaystack -= (a) << sl_minus_1; \
338    hashHaystack <<= 1
339
340inline bool qIsUpper(char ch)
341{
342    return ch >= 'A' && ch <= 'Z';
343}
344
345inline bool qIsDigit(char ch)
346{
347    return ch >= '0' && ch <= '9';
348}
349
350inline char qToLower(char ch)
351{
352    if (ch >= 'A' && ch <= 'Z')
353        return ch - 'A' + 'a';
354    else
355        return ch;
356}
357
358#if defined(Q_CC_MSVC) && _MSC_VER <= 1300
359const QString::Null QString::null;
360#else
361const QString::Null QString::null = { };
362#endif
363
364/*!
365  \macro QT_NO_CAST_FROM_ASCII
366  \relates QString
367
368  Disables automatic conversions from 8-bit strings (char *) to unicode QStrings
369
370  \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_BYTEARRAY
371*/
372
373/*!
374  \macro QT_NO_CAST_TO_ASCII
375  \relates QString
376
377  disables automatic conversion from QString to 8-bit strings (char *)
378
379  \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
380*/
381
382/*!
383  \macro QT_ASCII_CAST_WARNINGS
384  \internal
385  \relates QString
386
387  This macro can be defined to force a warning whenever a function is
388  called that automatically converts between unicode and 8-bit encodings.
389
390  Note: This only works for compilers that support warnings for
391  deprecated API.
392
393  \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII
394*/
395
396/*!
397    \class QCharRef
398    \reentrant
399    \brief The QCharRef class is a helper class for QString.
400
401    \internal
402
403    \ingroup string-processing
404
405    When you get an object of type QCharRef, if you can assign to it,
406    the assignment will apply to the character in the string from
407    which you got the reference. That is its whole purpose in life.
408    The QCharRef becomes invalid once modifications are made to the
409    string: if you want to keep the character, copy it into a QChar.
410
411    Most of the QChar member functions also exist in QCharRef.
412    However, they are not explicitly documented here.
413
414    \sa QString::operator[]() QString::at() QChar
415*/
416
417/*!
418    \class QString
419    \reentrant
420
421    \brief The QString class provides a Unicode character string.
422
423    \ingroup tools
424    \ingroup shared
425    \ingroup string-processing
426
427
428    QString stores a string of 16-bit \l{QChar}s, where each QChar
429    corresponds one Unicode 4.0 character. (Unicode characters
430    with code values above 65535 are stored using surrogate pairs,
431    i.e., two consecutive \l{QChar}s.)
432
433    \l{Unicode} is an international standard that supports most of the
434    writing systems in use today. It is a superset of US-ASCII (ANSI
435    X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1
436    characters are available at the same code positions.
437
438    Behind the scenes, QString uses \l{implicit sharing}
439    (copy-on-write) to reduce memory usage and to avoid the needless
440    copying of data. This also helps reduce the inherent overhead of
441    storing 16-bit characters instead of 8-bit characters.
442
443    In addition to QString, Qt also provides the QByteArray class to
444    store raw bytes and traditional 8-bit '\\0'-terminated strings.
445    For most purposes, QString is the class you want to use. It is
446    used throughout the Qt API, and the Unicode support ensures that
447    your applications will be easy to translate if you want to expand
448    your application's market at some point. The two main cases where
449    QByteArray is appropriate are when you need to store raw binary
450    data, and when memory conservation is critical (e.g., with
451    \l{Qt for Embedded Linux}).
452
453    \tableofcontents
454
455    \section1 Initializing a String
456
457    One way to initialize a QString is simply to pass a \c{const char
458    *} to its constructor. For example, the following code creates a
459    QString of size 5 containing the data "Hello":
460
461    \snippet doc/src/snippets/qstring/main.cpp 0
462
463    QString converts the \c{const char *} data into Unicode using the
464    fromAscii() function. By default, fromAscii() treats character
465    above 128 as Latin-1 characters, but this can be changed by
466    calling QTextCodec::setCodecForCStrings().
467
468    In all of the QString functions that take \c{const char *}
469    parameters, the \c{const char *} is interpreted as a classic
470    C-style '\\0'-terminated string. It is legal for the \c{const char
471    *} parameter to be 0.
472
473    You can also provide string data as an array of \l{QChar}s:
474
475    \snippet doc/src/snippets/qstring/main.cpp 1
476
477    QString makes a deep copy of the QChar data, so you can modify it
478    later without experiencing side effects. (If for performance
479    reasons you don't want to take a deep copy of the character data,
480    use QString::fromRawData() instead.)
481
482    Another approach is to set the size of the string using resize()
483    and to initialize the data character per character. QString uses
484    0-based indexes, just like C++ arrays. To access the character at
485    a particular index position, you can use \l operator[](). On
486    non-const strings, \l operator[]() returns a reference to a
487    character that can be used on the left side of an assignment. For
488    example:
489
490    \snippet doc/src/snippets/qstring/main.cpp 2
491
492    For read-only access, an alternative syntax is to use the at()
493    function:
494
495    \snippet doc/src/snippets/qstring/main.cpp 3
496
497    The at() function can be faster than \l operator[](), because it
498    never causes a \l{deep copy} to occur. Alternatively, use the
499    left(), right(), or mid() functions to extract several characters
500    at a time.
501
502    A QString can embed '\\0' characters (QChar::Null). The size()
503    function always returns the size of the whole string, including
504    embedded '\\0' characters.
505
506    After a call to the resize() function, newly allocated characters
507    have undefined values. To set all the characters in the string to
508    a particular value, use the fill() function.
509
510    QString provides dozens of overloads designed to simplify string
511    usage. For example, if you want to compare a QString with a string
512    literal, you can write code like this and it will work as expected:
513
514    \snippet doc/src/snippets/qstring/main.cpp 4
515
516    You can also pass string literals to functions that take QStrings
517    as arguments, invoking the QString(const char *)
518    constructor. Similarly, you can pass a QString to a function that
519    takes a \c{const char *} argument using the \l qPrintable() macro
520    which returns the given QString as a \c{const char *}. This is
521    equivalent to calling <QString>.toLocal8Bit().constData().
522
523    \section1 Manipulating String Data
524
525    QString provides the following basic functions for modifying the
526    character data: append(), prepend(), insert(), replace(), and
527    remove(). For example:
528
529    \snippet doc/src/snippets/qstring/main.cpp 5
530
531    If you are building a QString gradually and know in advance
532    approximately how many characters the QString will contain, you
533    can call reserve(), asking QString to preallocate a certain amount
534    of memory. You can also call capacity() to find out how much
535    memory QString actually allocated.
536
537    The replace() and remove() functions' first two arguments are the
538    position from which to start erasing and the number of characters
539    that should be erased.  If you want to replace all occurrences of
540    a particular substring with another, use one of the two-parameter
541    replace() overloads.
542
543    A frequent requirement is to remove whitespace characters from a
544    string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace
545    from both ends of a QString, use the trimmed() function. If you
546    want to remove whitespace from both ends and replace multiple
547    consecutive whitespaces with a single space character within the
548    string, use simplified().
549
550    If you want to find all occurrences of a particular character or
551    substring in a QString, use the indexOf() or lastIndexOf()
552    functions. The former searches forward starting from a given index
553    position, the latter searches backward. Both return the index
554    position of the character or substring if they find it; otherwise,
555    they return -1.  For example, here's a typical loop that finds all
556    occurrences of a particular substring:
557
558    \snippet doc/src/snippets/qstring/main.cpp 6
559
560    QString provides many functions for converting numbers into
561    strings and strings into numbers. See the arg() functions, the
562    setNum() functions, the number() static functions, and the
563    toInt(), toDouble(), and similar functions.
564
565    To get an upper- or lowercase version of a string use toUpper() or
566    toLower().
567
568    Lists of strings are handled by the QStringList class. You can
569    split a string into a list of strings using the split() function,
570    and join a list of strings into a single string with an optional
571    separator using QStringList::join(). You can obtain a list of
572    strings from a string list that contain a particular substring or
573    that match a particular QRegExp using the QStringList::filter()
574    function.
575
576    \section1 Querying String Data
577
578    If you want to see if a QString starts or ends with a particular
579    substring use startsWith() or endsWith(). If you simply want to
580    check whether a QString contains a particular character or
581    substring, use the contains() function. If you want to find out
582    how many times a particular character or substring occurs in the
583    string, use count().
584
585    QStrings can be compared using overloaded operators such as \l
586    operator<(), \l operator<=(), \l operator==(), \l operator>=(),
587    and so on.  Note that the comparison is based exclusively on the
588    numeric Unicode values of the characters. It is very fast, but is
589    not what a human would expect; the QString::localeAwareCompare()
590    function is a better choice for sorting user-interface strings.
591
592    To obtain a pointer to the actual character data, call data() or
593    constData(). These functions return a pointer to the beginning of
594    the QChar data. The pointer is guaranteed to remain valid until a
595    non-const function is called on the QString.
596
597    \section1 Converting Between 8-Bit Strings and Unicode Strings
598
599    QString provides the following four functions that return a
600    \c{const char *} version of the string as QByteArray: toAscii(),
601    toLatin1(), toUtf8(), and toLocal8Bit().
602
603    \list
604    \o toAscii() returns an 8-bit string encoded using the codec
605       specified by QTextCodec::codecForCStrings (by default, that is
606       Latin 1).
607    \o toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
608    \o toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a
609       superset of US-ASCII (ANSI X3.4-1986) that supports the entire
610       Unicode character set through multibyte sequences.
611    \o toLocal8Bit() returns an 8-bit string using the system's local
612       encoding.
613    \endlist
614
615    To convert from one of these encodings, QString provides
616    fromAscii(), fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other
617    encodings are supported through the QTextCodec class.
618
619    As mentioned above, QString provides a lot of functions and
620    operators that make it easy to interoperate with \c{const char *}
621    strings. But this functionality is a double-edged sword: It makes
622    QString more convenient to use if all strings are US-ASCII or
623    Latin-1, but there is always the risk that an implicit conversion
624    from or to \c{const char *} is done using the wrong 8-bit
625    encoding. To minimize these risks, you can turn off these implicit
626    conversions by defining the following two preprocessor symbols:
627
628    \list
629    \o \c QT_NO_CAST_FROM_ASCII disables automatic conversions from
630       C string literals and pointers to Unicode.
631    \o \c QT_NO_CAST_TO_ASCII disables automatic conversion from QString
632       to C strings.
633    \endlist
634
635    One way to define these preprocessor symbols globally for your
636    application is to add the following entry to your
637    \l{qmake Project Files}{qmake project file}:
638
639    \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 0
640
641    You then need to explicitly call fromAscii(), fromLatin1(),
642    fromUtf8(), or fromLocal8Bit() to construct a QString from an
643    8-bit string, or use the lightweight QLatin1String class, for
644    example:
645
646    \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 1
647
648    Similarly, you must call toAscii(), toLatin1(), toUtf8(), or
649    toLocal8Bit() explicitly to convert the QString to an 8-bit
650    string.  (Other encodings are supported through the QTextCodec
651    class.)
652
653    \table 100 %
654    \row
655    \o
656    \section1 Note for C Programmers
657
658    Due to C++'s type system and the fact that QString is
659    \l{implicitly shared}, QStrings may be treated like \c{int}s or
660    other basic types. For example:
661
662    \snippet doc/src/snippets/qstring/main.cpp 7
663
664    The \c result variable, is a normal variable allocated on the
665    stack. When \c return is called, and because we're returning by
666    value, the copy constructor is called and a copy of the string is
667    returned. No actual copying takes place thanks to the implicit
668    sharing.
669
670    \endtable
671
672    \section1 Distinction Between Null and Empty Strings
673
674    For historical reasons, QString distinguishes between a null
675    string and an empty string. A \e null string is a string that is
676    initialized using QString's default constructor or by passing
677    (const char *)0 to the constructor. An \e empty string is any
678    string with size 0. A null string is always empty, but an empty
679    string isn't necessarily null:
680
681    \snippet doc/src/snippets/qstring/main.cpp 8
682
683    All functions except isNull() treat null strings the same as empty
684    strings. For example, toAscii().constData() returns a pointer to a
685    '\\0' character for a null string (\e not a null pointer), and
686    QString() compares equal to QString(""). We recommend that you
687    always use the isEmpty() function and avoid isNull().
688
689    \section1 Argument Formats
690
691    In member functions where an argument \e format can be specified
692    (e.g., arg(), number()), the argument \e format can be one of the
693    following:
694
695    \table
696    \header \o Format \o Meaning
697    \row \o \c e \o format as [-]9.9e[+|-]999
698    \row \o \c E \o format as [-]9.9E[+|-]999
699    \row \o \c f \o format as [-]9.9
700    \row \o \c g \o use \c e or \c f format, whichever is the most concise
701    \row \o \c G \o use \c E or \c f format, whichever is the most concise
702    \endtable
703
704    A \e precision is also specified with the argument \e format. For
705    the 'e', 'E', and 'f' formats, the \e precision represents the
706    number of digits \e after the decimal point. For the 'g' and 'G'
707    formats, the \e precision represents the maximum number of
708    significant digits (trailing zeroes are omitted).
709
710    \section1 More Efficient String Construction
711
712    Using the QString \c{'+'} operator, it is easy to construct a
713    complex string from multiple substrings. You will often write code
714    like this:
715
716    \snippet doc/src/snippets/qstring/stringbuilder.cpp 0
717
718    There is nothing wrong with either of these string constructions,
719    but there are a few hidden inefficiencies. Beginning with Qt 4.6,
720    you can eliminate them.
721
722    First, multiple uses of the \c{'+'} operator usually means
723    multiple memory allocations. When concatenating \e{n} substrings,
724    where \e{n > 2}, there can be as many as \e{n - 1} calls to the
725    memory allocator.
726
727    Second, QLatin1String does not store its length internally but
728    calls qstrlen() when it needs to know its length.
729
730    In 4.6, an internal template class \c{QStringBuilder} has been
731    added along with a few helper functions. This class is marked
732    internal and does not appear in the documentation, because you
733    aren't meant to instantiate it in your code. Its use will be
734    automatic, as described below. The class is found in
735    \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
736    look at it.
737
738    \c{QStringBuilder} uses expression templates and reimplements the
739    \c{'%'} operator so that when you use \c{'%'} for string
740    concatenation instead of \c{'+'}, multiple substring
741    concatenations will be postponed until the final result is about
742    to be assigned to a QString. At this point, the amount of memory
743    required for the final result is known. The memory allocator is
744    then called \e{once} to get the required space, and the substrings
745    are copied into it one by one.
746
747    \c{QLatin1Literal} is a second internal class that can replace
748    QLatin1String, which can't be changed for compatibility reasons.
749    \c{QLatin1Literal} stores its length, thereby saving time when
750    \c{QStringBuilder} computes the amount of memory required for the
751    final string.
752
753    Additional efficiency is gained by inlining and reduced reference
754    counting (the QString created from a \c{QStringBuilder} typically
755    has a ref count of 1, whereas QString::append() needs an extra
756    test).
757
758    There are three ways you can access this improved method of string
759    construction. The straightforward way is to include
760    \c{QStringBuilder} wherever you want to use it, and use the
761    \c{'%'} operator instead of \c{'+'} when concatenating strings:
762
763    \snippet doc/src/snippets/qstring/stringbuilder.cpp 5
764
765    A more global approach is to include this define:
766
767    \snippet doc/src/snippets/qstring/stringbuilder.cpp 3
768
769    and use \c{'%'} instead of \c{'+'} for string concatenation
770    everywhere. The third approach, which is the most convenient but
771    not entirely source compatible, is to include two defines:
772
773    \snippet doc/src/snippets/qstring/stringbuilder.cpp 4
774
775    and the \c{'+'} will automatically be performed as the
776    \c{QStringBuilder} \c{'%'} everywhere.
777
778    \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
779*/
780
781/*!
782    \enum QString::SplitBehavior
783
784    This enum specifies how the split() function should behave with
785    respect to empty strings.
786
787    \value KeepEmptyParts  If a field is empty, keep it in the result.
788    \value SkipEmptyParts  If a field is empty, don't include it in the result.
789
790    \sa split()
791*/
792
793QString::Data QString::shared_null = { Q_BASIC_ATOMIC_INITIALIZER(1),
794                                       0, 0, shared_null.array, 0, 0, 0, 0, 0, 0, {0} };
795QString::Data QString::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1),
796                                        0, 0, shared_empty.array, 0, 0, 0, 0, 0, 0, {0} };
797
798int QString::grow(int size)
799{
800    return qAllocMore(size * sizeof(QChar), sizeof(Data)) / sizeof(QChar);
801}
802
803/*! \typedef QString::ConstIterator
804
805    Qt-style synonym for QString::const_iterator.
806*/
807
808/*! \typedef QString::Iterator
809
810    Qt-style synonym for QString::iterator.
811*/
812
813/*! \typedef QString::const_iterator
814
815    The QString::const_iterator typedef provides an STL-style const
816    iterator for QString.
817
818    \sa QString::iterator
819*/
820
821/*! \typedef QString::iterator
822
823    The QString::iterator typedef provides an STL-style non-const
824    iterator for QString.
825
826    \sa QString::const_iterator
827*/
828
829/*! \fn QString::iterator QString::begin()
830
831    Returns an \l{STL-style iterator} pointing to the first character in
832    the string.
833
834    \sa constBegin(), end()
835*/
836
837/*! \fn QString::const_iterator QString::begin() const
838
839    \overload begin()
840*/
841
842/*! \fn QString::const_iterator QString::constBegin() const
843
844    Returns a const \l{STL-style iterator} pointing to the first character
845    in the string.
846
847    \sa begin(), constEnd()
848*/
849
850/*! \fn QString::iterator QString::end()
851
852    Returns an \l{STL-style iterator} pointing to the imaginary character
853    after the last character in the string.
854
855    \sa begin(), constEnd()
856*/
857
858/*! \fn QString::const_iterator QString::end() const
859
860    \overload end()
861*/
862
863/*! \fn QString::const_iterator QString::constEnd() const
864
865    Returns a const \l{STL-style iterator} pointing to the imaginary
866    item after the last item in the list.
867
868    \sa constBegin(), end()
869*/
870
871/*!
872    \fn QString::QString()
873
874    Constructs a null string. Null strings are also empty.
875
876    \sa isEmpty()
877*/
878
879/*! \fn QString::QString(const char *str)
880
881    Constructs a string initialized with the 8-bit string \a str. The
882    given const char pointer is converted to Unicode using the
883    fromAscii() function.
884
885    You can disable this constructor by defining \c
886    QT_NO_CAST_FROM_ASCII when you compile your applications. This
887    can be useful if you want to ensure that all user-visible strings
888    go through QObject::tr(), for example.
889
890    \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
891*/
892
893/*! \fn QString QString::fromStdString(const std::string &str)
894
895    Returns a copy of the \a str string. The given string is converted
896    to Unicode using the fromAscii() function.
897
898    This constructor is only available if Qt is configured with STL
899    compatibility enabled.
900
901    \sa  fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
902*/
903
904/*! \fn QString QString::fromStdWString(const std::wstring &str)
905
906    Returns a copy of the \a str string. The given string is assumed
907    to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on
908    windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix
909    systems).
910
911    This method is only available if Qt is configured with STL
912    compatibility enabled.
913
914    \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4()
915*/
916
917/*!
918    \since 4.2
919
920    Returns a copy of the \a string, where the encoding of \a string depends on
921    the size of wchar. If wchar is 4 bytes, the \a string is interpreted as ucs-4,
922    if wchar is 2 bytes it is interpreted as ucs-2.
923
924    If \a size is -1 (default), the \a string has to be 0 terminated.
925
926    \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
927*/
928QString QString::fromWCharArray(const wchar_t *string, int size)
929{
930    if (sizeof(wchar_t) == sizeof(QChar)) {
931        return fromUtf16((const ushort *)string, size);
932    } else {
933        return fromUcs4((uint *)string, size);
934    }
935}
936
937/*! \fn std::wstring QString::toStdWString() const
938
939    Returns a std::wstring object with the data contained in this
940    QString. The std::wstring is encoded in utf16 on platforms where
941    wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
942    where wchar_t is 4 bytes wide (most Unix systems).
943
944    This operator is mostly useful to pass a QString to a function
945    that accepts a std::wstring object.
946
947    This operator is only available if Qt is configured with STL
948    compatibility enabled.
949
950    \sa utf16(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
951*/
952
953/*!
954  \since 4.2
955
956  Fills the \a array with the data contained in this QString object.
957  The array is encoded in utf16 on platforms where
958  wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
959  where wchar_t is 4 bytes wide (most Unix systems).
960
961  \a array has to be allocated by the caller and contain enough space to
962  hold the complete string (allocating the array with the same length as the
963  string is always sufficient).
964
965  returns the actual length of the string in \a array.
966
967  \note This function does not append a null character to the array.
968
969  \sa utf16(), toUcs4(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString()
970*/
971int QString::toWCharArray(wchar_t *array) const
972{
973    if (sizeof(wchar_t) == sizeof(QChar)) {
974        memcpy(array, utf16(), sizeof(wchar_t)*length());
975        return length();
976    } else {
977        wchar_t *a = array;
978        const unsigned short *uc = utf16();
979        for (int i = 0; i < length(); ++i) {
980            uint u = uc[i];
981            if (QChar::isHighSurrogate(u) && i + 1 < length()) {
982                ushort low = uc[i+1];
983                if (QChar::isLowSurrogate(low)) {
984                    u = QChar::surrogateToUcs4(u, low);
985                    ++i;
986                }
987            }
988            *a = wchar_t(u);
989            ++a;
990        }
991        return a - array;
992    }
993}
994
995/*! \fn QString::QString(const QString &other)
996
997    Constructs a copy of \a other.
998
999    This operation takes \l{constant time}, because QString is
1000    \l{implicitly shared}. This makes returning a QString from a
1001    function very fast. If a shared instance is modified, it will be
1002    copied (copy-on-write), and that takes \l{linear time}.
1003
1004    \sa operator=()
1005*/
1006
1007/*!
1008    Constructs a string initialized with the first \a size characters
1009    of the QChar array \a unicode.
1010
1011    QString makes a deep copy of the string data. The unicode data is copied as
1012    is and the Byte Order Mark is preserved if present.
1013*/
1014QString::QString(const QChar *unicode, int size)
1015{
1016   if (!unicode) {
1017        d = &shared_null;
1018        d->ref.ref();
1019    } else if (size <= 0) {
1020        d = &shared_empty;
1021        d->ref.ref();
1022    } else {
1023        d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
1024        Q_CHECK_PTR(d);
1025        d->ref = 1;
1026        d->alloc = d->size = size;
1027        d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
1028        d->data = d->array;
1029        memcpy(d->array, unicode, size * sizeof(QChar));
1030        d->array[size] = '\0';
1031    }
1032}
1033
1034/*!
1035    \since 4.7
1036
1037    Constructs a string initialized with the characters of the QChar array
1038    \a unicode, which must be terminated with a 0.
1039
1040    QString makes a deep copy of the string data. The unicode data is copied as
1041    is and the Byte Order Mark is preserved if present.
1042*/
1043QString::QString(const QChar *unicode)
1044{
1045     if (!unicode) {
1046         d = &shared_null;
1047         d->ref.ref();
1048     } else {
1049         int size = 0;
1050         while (unicode[size] != 0)
1051             ++size;
1052         if (!size) {
1053             d = &shared_empty;
1054             d->ref.ref();
1055         } else {
1056             d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
1057             Q_CHECK_PTR(d);
1058             d->ref = 1;
1059             d->alloc = d->size = size;
1060             d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
1061             d->data = d->array;
1062             memcpy(d->array, unicode, size * sizeof(QChar));
1063             d->array[size] = '\0';
1064         }
1065     }
1066}
1067
1068
1069/*!
1070    Constructs a string of the given \a size with every character set
1071    to \a ch.
1072
1073    \sa fill()
1074*/
1075QString::QString(int size, QChar ch)
1076{
1077   if (size <= 0) {
1078        d = &shared_empty;
1079        d->ref.ref();
1080    } else {
1081        d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
1082        Q_CHECK_PTR(d);
1083        d->ref = 1;
1084        d->alloc = d->size = size;
1085        d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
1086        d->data = d->array;
1087        d->array[size] = '\0';
1088        ushort *i = d->array + size;
1089        ushort *b = d->array;
1090        const ushort value = ch.unicode();
1091        while (i != b)
1092           *--i = value;
1093    }
1094}
1095
1096/*! \fn QString::QString(int size, Qt::Initialization)
1097  \internal
1098
1099  Constructs a string of the given \a size without initializing the
1100  characters. This is only used in \c QStringBuilder::toString().
1101*/
1102QString::QString(int size, Qt::Initialization)
1103{
1104    d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar));
1105    Q_CHECK_PTR(d);
1106    d->ref = 1;
1107    d->alloc = d->size = size;
1108    d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
1109    d->data = d->array;
1110    d->array[size] = '\0';
1111}
1112
1113/*! \fn QString::QString(const QLatin1String &str)
1114
1115    Constructs a copy of the Latin-1 string \a str.
1116
1117    \sa fromLatin1()
1118*/
1119
1120/*!
1121    Constructs a string of size 1 containing the character \a ch.
1122*/
1123QString::QString(QChar ch)
1124{
1125    void *buf = qMalloc(sizeof(Data) + sizeof(QChar));
1126    Q_CHECK_PTR(buf);
1127    d = reinterpret_cast<Data *>(buf);
1128    d->ref = 1;
1129    d->alloc = d->size = 1;
1130    d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
1131    d->data = d->array;
1132    d->array[0] = ch.unicode();
1133    d->array[1] = '\0';
1134}
1135
1136/*! \fn QString::QString(const QByteArray &ba)
1137
1138    Constructs a string initialized with the byte array \a ba. The
1139    given byte array is converted to Unicode using fromAscii(). Stops
1140    copying at the first 0 character, otherwise copies the entire byte
1141    array.
1142
1143    You can disable this constructor by defining \c
1144    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1145    can be useful if you want to ensure that all user-visible strings
1146    go through QObject::tr(), for example.
1147
1148    \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
1149*/
1150
1151/*! \fn QString::QString(const Null &)
1152    \internal
1153*/
1154
1155/*! \fn QString &QString::operator=(const Null &)
1156    \internal
1157*/
1158
1159/*!
1160  \fn QString::~QString()
1161
1162    Destroys the string.
1163*/
1164
1165
1166/*! \fn void QString::detach()
1167
1168    \internal
1169*/
1170
1171/*! \fn bool QString::isDetached() const
1172
1173    \internal
1174*/
1175
1176/*! \fn bool QString::isSharedWith(const QString &other) const
1177
1178    \internal
1179*/
1180
1181// ### Qt 5: rename freeData() to avoid confusion. See task 197625.
1182void QString::free(Data *d)
1183{
1184#ifdef QT3_SUPPORT
1185    if (d->asciiCache) {
1186        Q_ASSERT(asciiCache);
1187        asciiCache->remove(d);
1188    }
1189#endif
1190    qFree(d);
1191}
1192
1193/*!
1194    Sets the size of the string to \a size characters.
1195
1196    If \a size is greater than the current size, the string is
1197    extended to make it \a size characters long with the extra
1198    characters added to the end. The new characters are uninitialized.
1199
1200    If \a size is less than the current size, characters are removed
1201    from the end.
1202
1203    Example:
1204
1205    \snippet doc/src/snippets/qstring/main.cpp 45
1206
1207    If you want to append a certain number of identical characters to
1208    the string, use \l operator+=() as follows rather than resize():
1209
1210    \snippet doc/src/snippets/qstring/main.cpp 46
1211
1212    If you want to expand the string so that it reaches a certain
1213    width and fill the new positions with a particular character, use
1214    the leftJustified() function:
1215
1216    If \a size is negative, it is equivalent to passing zero.
1217
1218    \snippet doc/src/snippets/qstring/main.cpp 47
1219
1220    \sa truncate(), reserve()
1221*/
1222
1223void QString::resize(int size)
1224{
1225    if (size < 0)
1226        size = 0;
1227
1228    if (size == 0 && !d->capacity) {
1229        Data *x = &shared_empty;
1230        x->ref.ref();
1231        if (!d->ref.deref())
1232            QString::free(d);
1233        d = x;
1234    } else {
1235        if (d->ref != 1 || size > d->alloc ||
1236            (!d->capacity && size < d->size && size < d->alloc >> 1))
1237            realloc(grow(size));
1238        if (d->alloc >= size) {
1239            d->size = size;
1240            if (d->data == d->array) {
1241                d->array[size] = '\0';
1242            }
1243        }
1244    }
1245}
1246
1247/*! \fn int QString::capacity() const
1248
1249    Returns the maximum number of characters that can be stored in
1250    the string without forcing a reallocation.
1251
1252    The sole purpose of this function is to provide a means of fine
1253    tuning QString's memory usage. In general, you will rarely ever
1254    need to call this function. If you want to know how many
1255    characters are in the string, call size().
1256
1257    \sa reserve(), squeeze()
1258*/
1259
1260/*!
1261    \fn void QString::reserve(int size)
1262
1263    Attempts to allocate memory for at least \a size characters. If
1264    you know in advance how large the string will be, you can call
1265    this function, and if you resize the string often you are likely
1266    to get better performance. If \a size is an underestimate, the
1267    worst that will happen is that the QString will be a bit slower.
1268
1269    The sole purpose of this function is to provide a means of fine
1270    tuning QString's memory usage. In general, you will rarely ever
1271    need to call this function. If you want to change the size of the
1272    string, call resize().
1273
1274    This function is useful for code that needs to build up a long
1275    string and wants to avoid repeated reallocation. In this example,
1276    we want to add to the string until some condition is true, and
1277    we're fairly sure that size is large enough to make a call to
1278    reserve() worthwhile:
1279
1280    \snippet doc/src/snippets/qstring/main.cpp 44
1281
1282    \sa squeeze(), capacity()
1283*/
1284
1285/*!
1286    \fn void QString::squeeze()
1287
1288    Releases any memory not required to store the character data.
1289
1290    The sole purpose of this function is to provide a means of fine
1291    tuning QString's memory usage. In general, you will rarely ever
1292    need to call this function.
1293
1294    \sa reserve(), capacity()
1295*/
1296
1297// ### Qt 5: rename reallocData() to avoid confusion. 197625
1298void QString::realloc(int alloc)
1299{
1300    if (d->ref != 1 || d->data != d->array) {
1301        Data *x = static_cast<Data *>(qMalloc(sizeof(Data) + alloc * sizeof(QChar)));
1302        Q_CHECK_PTR(x);
1303        x->size = qMin(alloc, d->size);
1304        ::memcpy(x->array, d->data, x->size * sizeof(QChar));
1305        x->array[x->size] = 0;
1306        x->asciiCache = 0;
1307        x->ref = 1;
1308        x->alloc = alloc;
1309        x->clean = d->clean;
1310        x->simpletext = d->simpletext;
1311        x->righttoleft = d->righttoleft;
1312        x->capacity = d->capacity;
1313        x->data = x->array;
1314        if (!d->ref.deref())
1315            QString::free(d);
1316        d = x;
1317    } else {
1318#ifdef QT3_SUPPORT
1319        if (d->asciiCache) {
1320            Q_ASSERT(asciiCache);
1321            asciiCache->remove(d);
1322        }
1323#endif
1324        d = static_cast<Data *>(q_check_ptr(qRealloc(d, sizeof(Data) + alloc * sizeof(QChar))));
1325        d->alloc = alloc;
1326        d->data = d->array;
1327    }
1328}
1329
1330void QString::realloc()
1331{
1332    realloc(d->size);
1333}
1334
1335void QString::expand(int i)
1336{
1337    int sz = d->size;
1338    resize(qMax(i + 1, sz));
1339    if (d->size - 1 > sz) {
1340        ushort *n = d->data + d->size - 1;
1341        ushort *e = d->data + sz;
1342        while (n != e)
1343           * --n = ' ';
1344    }
1345}
1346
1347/*! \fn void QString::clear()
1348
1349    Clears the contents of the string and makes it empty.
1350
1351    \sa resize(), isEmpty()
1352*/
1353
1354/*! \fn QString &QString::operator=(const QString &other)
1355
1356    Assigns \a other to this string and returns a reference to this
1357    string.
1358*/
1359
1360QString &QString::operator=(const QString &other)
1361{
1362    other.d->ref.ref();
1363    if (!d->ref.deref())
1364        QString::free(d);
1365    d = other.d;
1366    return *this;
1367}
1368
1369
1370/*! \fn QString &QString::operator=(const QLatin1String &str)
1371
1372    \overload operator=()
1373
1374    Assigns the Latin-1 string \a str to this string.
1375*/
1376
1377/*! \fn QString &QString::operator=(const QByteArray &ba)
1378
1379    \overload operator=()
1380
1381    Assigns \a ba to this string. The byte array is converted to Unicode
1382    using the fromAscii() function. This function stops conversion at the
1383    first NUL character found, or the end of the \a ba byte array.
1384
1385    You can disable this operator by defining \c
1386    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1387    can be useful if you want to ensure that all user-visible strings
1388    go through QObject::tr(), for example.
1389*/
1390
1391/*! \fn QString &QString::operator=(const char *str)
1392
1393    \overload operator=()
1394
1395    Assigns \a str to this string. The const char pointer is converted
1396    to Unicode using the fromAscii() function.
1397
1398    You can disable this operator by defining \c
1399    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1400    can be useful if you want to ensure that all user-visible strings
1401    go through QObject::tr(), for example.
1402*/
1403
1404/*! \fn QString &QString::operator=(char ch)
1405
1406    \overload operator=()
1407
1408    Assigns character \a ch to this string. The character is converted
1409    to Unicode using the fromAscii() function.
1410
1411    You can disable this operator by defining \c
1412    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1413    can be useful if you want to ensure that all user-visible strings
1414    go through QObject::tr(), for example.
1415*/
1416
1417/*!
1418    \overload operator=()
1419
1420    Sets the string to contain the single character \a ch.
1421*/
1422QString &QString::operator=(QChar ch)
1423{
1424    return operator=(QString(ch));
1425}
1426
1427/*!
1428     \fn QString& QString::insert(int position, const QString &str)
1429
1430    Inserts the string \a str at the given index \a position and
1431    returns a reference to this string.
1432
1433    Example:
1434
1435    \snippet doc/src/snippets/qstring/main.cpp 26
1436
1437    If the given \a position is greater than size(), the array is
1438    first extended using resize().
1439
1440    \sa append(), prepend(), replace(), remove()
1441*/
1442
1443
1444/*!
1445    \fn QString &QString::insert(int position, const QLatin1String &str)
1446    \overload insert()
1447
1448    Inserts the Latin-1 string \a str at the given index \a position.
1449*/
1450QString &QString::insert(int i, const QLatin1String &str)
1451{
1452    const uchar *s = (const uchar *)str.latin1();
1453    if (i < 0 || !s || !(*s))
1454        return *this;
1455
1456    int len = qstrlen(str.latin1());
1457    expand(qMax(d->size, i) + len - 1);
1458
1459    ::memmove(d->data + i + len, d->data + i, (d->size - i - len) * sizeof(QChar));
1460    for (int j = 0; j < len; ++j)
1461        d->data[i + j] = s[j];
1462    return *this;
1463}
1464
1465/*!
1466    \fn QString& QString::insert(int position, const QChar *unicode, int size)
1467    \overload insert()
1468
1469    Inserts the first \a size characters of the QChar array \a unicode
1470    at the given index \a position in the string.
1471*/
1472QString& QString::insert(int i, const QChar *unicode, int size)
1473{
1474    if (i < 0 || size <= 0)
1475        return *this;
1476
1477    const ushort *s = (const ushort *)unicode;
1478    if (s >= d->data && s < d->data + d->alloc) {
1479        // Part of me - take a copy
1480        ushort *tmp = static_cast<ushort *>(qMalloc(size * sizeof(QChar)));
1481        Q_CHECK_PTR(tmp);
1482        memcpy(tmp, s, size * sizeof(QChar));
1483        insert(i, reinterpret_cast<const QChar *>(tmp), size);
1484        qFree(tmp);
1485        return *this;
1486    }
1487
1488    expand(qMax(d->size, i) + size - 1);
1489
1490    ::memmove(d->data + i + size, d->data + i, (d->size - i - size) * sizeof(QChar));
1491    memcpy(d->data + i, s, size * sizeof(QChar));
1492    return *this;
1493}
1494
1495/*!
1496    \fn QString& QString::insert(int position, QChar ch)
1497    \overload insert()
1498
1499    Inserts \a ch at the given index \a position in the string.
1500*/
1501
1502QString& QString::insert(int i, QChar ch)
1503{
1504    if (i < 0)
1505        i += d->size;
1506    if (i < 0)
1507        return *this;
1508    expand(qMax(i, d->size));
1509    ::memmove(d->data + i + 1, d->data + i, (d->size - i) * sizeof(QChar));
1510    d->data[i] = ch.unicode();
1511    return *this;
1512}
1513
1514/*!
1515    Appends the string \a str onto the end of this string.
1516
1517    Example:
1518
1519    \snippet doc/src/snippets/qstring/main.cpp 9
1520
1521    This is the same as using the insert() function:
1522
1523    \snippet doc/src/snippets/qstring/main.cpp 10
1524
1525    The append() function is typically very fast (\l{constant time}),
1526    because QString preallocates extra space at the end of the string
1527    data so it can grow without reallocating the entire string each
1528    time.
1529
1530    \sa operator+=(), prepend(), insert()
1531*/
1532QString &QString::append(const QString &str)
1533{
1534    if (str.d != &shared_null) {
1535        if (d == &shared_null) {
1536            operator=(str);
1537        } else {
1538            if (d->ref != 1 || d->size + str.d->size > d->alloc)
1539                realloc(grow(d->size + str.d->size));
1540            memcpy(d->data + d->size, str.d->data, str.d->size * sizeof(QChar));
1541            d->size += str.d->size;
1542            d->data[d->size] = '\0';
1543        }
1544    }
1545    return *this;
1546}
1547
1548/*!
1549  \overload append()
1550
1551  Appends the Latin-1 string \a str to this string.
1552*/
1553QString &QString::append(const QLatin1String &str)
1554{
1555    const uchar *s = (const uchar *)str.latin1();
1556    if (s) {
1557        int len = qstrlen((char *)s);
1558        if (d->ref != 1 || d->size + len > d->alloc)
1559            realloc(grow(d->size + len));
1560        ushort *i = d->data + d->size;
1561        while ((*i++ = *s++))
1562            ;
1563        d->size += len;
1564    }
1565    return *this;
1566}
1567
1568/*! \fn QString &QString::append(const QByteArray &ba)
1569
1570    \overload append()
1571
1572    Appends the byte array \a ba to this string. The given byte array
1573    is converted to Unicode using the fromAscii() function.
1574
1575    You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1576    when you compile your applications. This can be useful if you want
1577    to ensure that all user-visible strings go through QObject::tr(),
1578    for example.
1579*/
1580
1581/*! \fn QString &QString::append(const char *str)
1582
1583    \overload append()
1584
1585    Appends the string \a str to this string. The given const char
1586    pointer is converted to Unicode using the fromAscii() function.
1587
1588    You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1589    when you compile your applications. This can be useful if you want
1590    to ensure that all user-visible strings go through QObject::tr(),
1591    for example.
1592*/
1593
1594/*!
1595    \overload append()
1596
1597    Appends the character \a ch to this string.
1598*/
1599QString &QString::append(QChar ch)
1600{
1601    if (d->ref != 1 || d->size + 1 > d->alloc)
1602        realloc(grow(d->size + 1));
1603    d->data[d->size++] = ch.unicode();
1604    d->data[d->size] = '\0';
1605    return *this;
1606}
1607
1608/*! \fn QString &QString::prepend(const QString &str)
1609
1610    Prepends the string \a str to the beginning of this string and
1611    returns a reference to this string.
1612
1613    Example:
1614
1615    \snippet doc/src/snippets/qstring/main.cpp 36
1616
1617    \sa append(), insert()
1618*/
1619
1620/*! \fn QString &QString::prepend(const QLatin1String &str)
1621
1622    \overload prepend()
1623
1624    Prepends the Latin-1 string \a str to this string.
1625*/
1626
1627/*! \fn QString &QString::prepend(const QByteArray &ba)
1628
1629    \overload prepend()
1630
1631    Prepends the byte array \a ba to this string. The byte array is
1632    converted to Unicode using the fromAscii() function.
1633
1634    You can disable this function by defining \c
1635    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1636    can be useful if you want to ensure that all user-visible strings
1637    go through QObject::tr(), for example.
1638*/
1639
1640/*! \fn QString &QString::prepend(const char *str)
1641
1642    \overload prepend()
1643
1644    Prepends the string \a str to this string. The const char pointer
1645    is converted to Unicode using the fromAscii() function.
1646
1647    You can disable this function by defining \c
1648    QT_NO_CAST_FROM_ASCII when you compile your applications. This
1649    can be useful if you want to ensure that all user-visible strings
1650    go through QObject::tr(), for example.
1651*/
1652
1653/*! \fn QString &QString::prepend(QChar ch)
1654
1655    \overload prepend()
1656
1657    Prepends the character \a ch to this string.
1658*/
1659
1660/*!
1661  \fn QString &QString::remove(int position, int n)
1662
1663  Removes \a n characters from the string, starting at the given \a
1664  position index, and returns a reference to the string.
1665
1666  If the specified \a position index is within the string, but \a
1667  position + \a n is beyond the end of the string, the string is
1668  truncated at the specified \a position.
1669
1670  \snippet doc/src/snippets/qstring/main.cpp 37
1671
1672  \sa insert(), replace()
1673*/
1674QString &QString::remove(int pos, int len)
1675{
1676    if (pos < 0)  // count from end of string
1677        pos += d->size;
1678    if (pos < 0 || pos >= d->size) {
1679        // range problems
1680    } else if (len >= d->size - pos) {
1681        resize(pos); // truncate
1682    } else if (len > 0) {
1683        detach();
1684        memmove(d->data + pos, d->data + pos + len,
1685                (d->size - pos - len + 1) * sizeof(ushort));
1686        d->size -= len;
1687    }
1688    return *this;
1689}
1690
1691/*!
1692  Removes every occurrence of the given \a str string in this
1693  string, and returns a reference to this string.
1694
1695  If \a cs is Qt::CaseSensitive (default), the search is
1696  case sensitive; otherwise the search is case insensitive.
1697
1698  This is the same as \c replace(str, "", cs).
1699
1700  \sa replace()
1701*/
1702QString &QString::remove(const QString &str, Qt::CaseSensitivity cs)
1703{
1704    if (str.d->size) {
1705        int i = 0;
1706        while ((i = indexOf(str, i, cs)) != -1)
1707            remove(i, str.d->size);
1708    }
1709    return *this;
1710}
1711
1712/*!
1713  Removes every occurrence of the character \a ch in this string, and
1714  returns a reference to this string.
1715
1716  If \a cs is Qt::CaseSensitive (default), the search is case
1717  sensitive; otherwise the search is case insensitive.
1718
1719  Example:
1720
1721  \snippet doc/src/snippets/qstring/main.cpp 38
1722
1723  This is the same as \c replace(ch, "", cs).
1724
1725  \sa replace()
1726*/
1727QString &QString::remove(QChar ch, Qt::CaseSensitivity cs)
1728{
1729    int i = 0;
1730    ushort c = ch.unicode();
1731    if (cs == Qt::CaseSensitive) {
1732        while (i < d->size)
1733            if (d->data[i] == ch)
1734                remove(i, 1);
1735            else
1736                i++;
1737    } else {
1738        c = foldCase(c);
1739        while (i < d->size)
1740            if (foldCase(d->data[i]) == c)
1741                remove(i, 1);
1742            else
1743                i++;
1744    }
1745    return *this;
1746}
1747
1748/*!
1749  \fn QString &QString::remove(const QRegExp &rx)
1750
1751  Removes every occurrence of the regular expression \a rx in the
1752  string, and returns a reference to the string. For example:
1753
1754  \snippet doc/src/snippets/qstring/main.cpp 39
1755
1756  \sa indexOf(), lastIndexOf(), replace()
1757*/
1758
1759/*!
1760  \fn QString &QString::replace(int position, int n, const QString &after)
1761
1762  Replaces \a n characters beginning at index \a position with
1763  the string \a after and returns a reference to this string.
1764
1765  Example:
1766
1767  \snippet doc/src/snippets/qstring/main.cpp 40
1768
1769  \sa insert(), remove()
1770*/
1771QString &QString::replace(int pos, int len, const QString &after)
1772{
1773    QString copy = after;
1774    return replace(pos, len, copy.constData(), copy.length());
1775}
1776
1777/*!
1778  \fn QString &QString::replace(int position, int n, const QChar *unicode, int size)
1779  \overload replace()
1780  Replaces \a n characters beginning at index \a position with the
1781  first \a size characters of the QChar array \a unicode and returns a
1782  reference to this string.
1783*/
1784QString &QString::replace(int pos, int len, const QChar *unicode, int size)
1785{
1786    if (pos < 0 || pos > d->size)
1787        return *this;
1788    if (pos + len > d->size)
1789        len = d->size - pos;
1790
1791    uint index = pos;
1792    replace_helper(&index, 1, len, unicode, size);
1793    return *this;
1794}
1795
1796/*!
1797  \fn QString &QString::replace(int position, int n, QChar after)
1798  \overload replace()
1799
1800  Replaces \a n characters beginning at index \a position with the
1801  character \a after and returns a reference to this string.
1802*/
1803QString &QString::replace(int pos, int len, QChar after)
1804{
1805    return replace(pos, len, &after, 1);
1806}
1807
1808/*!
1809  \overload replace()
1810  Replaces every occurrence of the string \a before with the string \a
1811  after and returns a reference to this string.
1812
1813  If \a cs is Qt::CaseSensitive (default), the search is case
1814  sensitive; otherwise the search is case insensitive.
1815
1816  Example:
1817
1818  \snippet doc/src/snippets/qstring/main.cpp 41
1819
1820  \note The replacement text is not rescanned after it is inserted.
1821
1822  Example:
1823
1824  \snippet doc/src/snippets/qstring/main.cpp 86
1825*/
1826QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs)
1827{
1828    return replace(before.constData(), before.size(), after.constData(), after.size(), cs);
1829}
1830
1831/*!
1832  \internal
1833 */
1834void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen)
1835{
1836    // copy *after in case it lies inside our own d->data area
1837    // (which we could possibly invalidate via a realloc or corrupt via memcpy operations.)
1838    QChar *afterBuffer = const_cast<QChar *>(after);
1839    if (after >= reinterpret_cast<QChar *>(d->data) && after < reinterpret_cast<QChar *>(d->data) + d->size) {
1840        afterBuffer = static_cast<QChar *>(qMalloc(alen*sizeof(QChar)));
1841        Q_CHECK_PTR(afterBuffer);
1842        ::memcpy(afterBuffer, after, alen*sizeof(QChar));
1843    }
1844
1845    QT_TRY {
1846        if (blen == alen) {
1847            // replace in place
1848            detach();
1849            for (int i = 0; i < nIndices; ++i)
1850                memcpy(d->data + indices[i], afterBuffer, alen * sizeof(QChar));
1851        } else if (alen < blen) {
1852            // replace from front
1853            detach();
1854            uint to = indices[0];
1855            if (alen)
1856                memcpy(d->data+to, after, alen*sizeof(QChar));
1857            to += alen;
1858            uint movestart = indices[0] + blen;
1859            for (int i = 1; i < nIndices; ++i) {
1860                int msize = indices[i] - movestart;
1861                if (msize > 0) {
1862                    memmove(d->data + to, d->data + movestart, msize * sizeof(QChar));
1863                    to += msize;
1864                }
1865                if (alen) {
1866                    memcpy(d->data + to, afterBuffer, alen*sizeof(QChar));
1867                    to += alen;
1868                }
1869                movestart = indices[i] + blen;
1870            }
1871            int msize = d->size - movestart;
1872            if (msize > 0)
1873                memmove(d->data + to, d->data + movestart, msize * sizeof(QChar));
1874            resize(d->size - nIndices*(blen-alen));
1875        } else {
1876            // replace from back
1877            int adjust = nIndices*(alen-blen);
1878            int newLen = d->size + adjust;
1879            int moveend = d->size;
1880            resize(newLen);
1881
1882            while (nIndices) {
1883                --nIndices;
1884                int movestart = indices[nIndices] + blen;
1885                int insertstart = indices[nIndices] + nIndices*(alen-blen);
1886                int moveto = insertstart + alen;
1887                memmove(d->data + moveto, d->data + movestart,
1888                        (moveend - movestart)*sizeof(QChar));
1889                memcpy(d->data + insertstart, afterBuffer, alen*sizeof(QChar));
1890                moveend = movestart-blen;
1891            }
1892        }
1893    } QT_CATCH(const std::bad_alloc &) {
1894        if (afterBuffer != after)
1895            qFree(afterBuffer);
1896        QT_RETHROW;
1897    }
1898    if (afterBuffer != after)
1899        qFree(afterBuffer);
1900}
1901
1902/*!
1903  \since 4.5
1904  \overload replace()
1905
1906  Replaces each occurrence in this string of the first \a blen
1907  characters of \a before with the first \a alen characters of \a
1908  after and returns a reference to this string.
1909
1910  If \a cs is Qt::CaseSensitive (default), the search is case
1911  sensitive; otherwise the search is case insensitive.
1912*/
1913QString &QString::replace(const QChar *before, int blen,
1914                          const QChar *after, int alen,
1915                          Qt::CaseSensitivity cs)
1916{
1917    if (d->size == 0) {
1918        if (blen)
1919            return *this;
1920    } else {
1921        if (cs == Qt::CaseSensitive && before == after && blen == alen)
1922            return *this;
1923    }
1924    if (alen == 0 && blen == 0)
1925        return *this;
1926
1927    QStringMatcher matcher(before, blen, cs);
1928
1929    int index = 0;
1930    while (1) {
1931        uint indices[1024];
1932        uint pos = 0;
1933        while (pos < 1023) {
1934            index = matcher.indexIn(*this, index);
1935            if (index == -1)
1936                break;
1937            indices[pos++] = index;
1938            index += blen;
1939            // avoid infinite loop
1940            if (!blen)
1941                index++;
1942        }
1943        if (!pos)
1944            break;
1945
1946        replace_helper(indices, pos, blen, after, alen);
1947
1948        if (index == -1)
1949            break;
1950        // index has to be adjusted in case we get back into the loop above.
1951        index += pos*(alen-blen);
1952    }
1953
1954    return *this;
1955}
1956
1957/*!
1958  \overload replace()
1959  Replaces every occurrence of the character \a ch in the string with
1960  \a after and returns a reference to this string.
1961
1962  If \a cs is Qt::CaseSensitive (default), the search is case
1963  sensitive; otherwise the search is case insensitive.
1964*/
1965QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs)
1966{
1967    if (after.d->size == 0)
1968        return remove(ch, cs);
1969
1970    if (after.d->size == 1)
1971        return replace(ch, after.d->data[0], cs);
1972
1973    if (d->size == 0)
1974        return *this;
1975
1976    ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode());
1977
1978    int index = 0;
1979    while (1) {
1980        uint indices[1024];
1981        uint pos = 0;
1982        if (cs == Qt::CaseSensitive) {
1983            while (pos < 1023 && index < d->size) {
1984                if (d->data[index] == cc)
1985                    indices[pos++] = index;
1986                index++;
1987            }
1988        } else {
1989            while (pos < 1023 && index < d->size) {
1990                if (QChar::toCaseFolded(d->data[index]) == cc)
1991                    indices[pos++] = index;
1992                index++;
1993            }
1994        }
1995        if (!pos)
1996            break;
1997
1998        replace_helper(indices, pos, 1, after.constData(), after.d->size);
1999
2000        if (index == -1)
2001            break;
2002        // index has to be adjusted in case we get back into the loop above.
2003        index += pos*(after.d->size - 1);
2004    }
2005    return *this;
2006}
2007
2008/*!
2009  \overload replace()
2010  Replaces every occurrence of the character \a before with the
2011  character \a after and returns a reference to this string.
2012
2013  If \a cs is Qt::CaseSensitive (default), the search is case
2014  sensitive; otherwise the search is case insensitive.
2015*/
2016QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs)
2017{
2018    ushort a = after.unicode();
2019    ushort b = before.unicode();
2020    if (d->size) {
2021        detach();
2022        ushort *i = d->data;
2023        const ushort *e = i + d->size;
2024        if (cs == Qt::CaseSensitive) {
2025            for (; i != e; ++i)
2026                if (*i == b)
2027                    *i = a;
2028        } else {
2029            b = foldCase(b);
2030            for (; i != e; ++i)
2031                if (foldCase(*i) == b)
2032                    *i = a;
2033        }
2034    }
2035    return *this;
2036}
2037
2038/*!
2039  \since 4.5
2040  \overload replace()
2041
2042  Replaces every occurrence of the string \a before with the string \a
2043  after and returns a reference to this string.
2044
2045  If \a cs is Qt::CaseSensitive (default), the search is case
2046  sensitive; otherwise the search is case insensitive.
2047
2048  \note The text is not rescanned after a replacement.
2049*/
2050QString &QString::replace(const QLatin1String &before,
2051                          const QLatin1String &after,
2052                          Qt::CaseSensitivity cs)
2053{
2054    int alen = qstrlen(after.latin1());
2055    QVarLengthArray<ushort> a(alen);
2056    for (int i = 0; i < alen; ++i)
2057        a[i] = (uchar)after.latin1()[i];
2058    int blen = qstrlen(before.latin1());
2059    QVarLengthArray<ushort> b(blen);
2060    for (int i = 0; i < blen; ++i)
2061        b[i] = (uchar)before.latin1()[i];
2062    return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs);
2063}
2064
2065/*!
2066  \since 4.5
2067  \overload replace()
2068
2069  Replaces every occurrence of the string \a before with the string \a
2070  after and returns a reference to this string.
2071
2072  If \a cs is Qt::CaseSensitive (default), the search is case
2073  sensitive; otherwise the search is case insensitive.
2074
2075  \note The text is not rescanned after a replacement.
2076*/
2077QString &QString::replace(const QLatin1String &before,
2078                          const QString &after,
2079                          Qt::CaseSensitivity cs)
2080{
2081    int blen = qstrlen(before.latin1());
2082    QVarLengthArray<ushort> b(blen);
2083    for (int i = 0; i < blen; ++i)
2084        b[i] = (uchar)before.latin1()[i];
2085    return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs);
2086}
2087
2088/*!
2089  \since 4.5
2090  \overload replace()
2091
2092  Replaces every occurrence of the string \a before with the string \a
2093  after and returns a reference to this string.
2094
2095  If \a cs is Qt::CaseSensitive (default), the search is case
2096  sensitive; otherwise the search is case insensitive.
2097
2098  \note The text is not rescanned after a replacement.
2099*/
2100QString &QString::replace(const QString &before,
2101                          const QLatin1String &after,
2102                          Qt::CaseSensitivity cs)
2103{
2104    int alen = qstrlen(after.latin1());
2105    QVarLengthArray<ushort> a(alen);
2106    for (int i = 0; i < alen; ++i)
2107        a[i] = (uchar)after.latin1()[i];
2108    return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs);
2109}
2110
2111/*!
2112  \since 4.5
2113  \overload replace()
2114
2115  Replaces every occurrence of the character \a c with the string \a
2116  after and returns a reference to this string.
2117
2118  If \a cs is Qt::CaseSensitive (default), the search is case
2119  sensitive; otherwise the search is case insensitive.
2120
2121  \note The text is not rescanned after a replacement.
2122*/
2123QString &QString::replace(QChar c, const QLatin1String &after, Qt::CaseSensitivity cs)
2124{
2125    int alen = qstrlen(after.latin1());
2126    QVarLengthArray<ushort> a(alen);
2127    for (int i = 0; i < alen; ++i)
2128        a[i] = (uchar)after.latin1()[i];
2129    return replace(&c, 1, (const QChar *)a.data(), alen, cs);
2130}
2131
2132
2133/*!
2134  Returns true if string \a other is equal to this string; otherwise
2135  returns false.
2136
2137  The comparison is based exclusively on the numeric Unicode values of
2138  the characters and is very fast, but is not what a human would
2139  expect. Consider sorting user-interface strings with
2140  localeAwareCompare().
2141*/
2142bool QString::operator==(const QString &other) const
2143{
2144    if (d->size != other.d->size)
2145        return false;
2146
2147    return qMemEquals(d->data, other.d->data, d->size);
2148}
2149
2150/*!
2151    \overload operator==()
2152*/
2153bool QString::operator==(const QLatin1String &other) const
2154{
2155    const ushort *uc = d->data;
2156    const ushort *e = uc + d->size;
2157    const uchar *c = (uchar *)other.latin1();
2158
2159    if (!c)
2160        return isEmpty();
2161
2162    while (*c) {
2163        if (uc == e || *uc != *c)
2164            return false;
2165        ++uc;
2166        ++c;
2167    }
2168    return (uc == e);
2169}
2170
2171/*! \fn bool QString::operator==(const QByteArray &other) const
2172
2173    \overload operator==()
2174
2175    The \a other byte array is converted to a QString using the
2176    fromAscii() function. This function stops conversion at the
2177    first NUL character found, or the end of the byte array.
2178
2179    You can disable this operator by defining \c
2180    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2181    can be useful if you want to ensure that all user-visible strings
2182    go through QObject::tr(), for example.
2183*/
2184
2185/*! \fn bool QString::operator==(const char *other) const
2186
2187    \overload operator==()
2188
2189    The \a other const char pointer is converted to a QString using
2190    the fromAscii() function.
2191
2192    You can disable this operator by defining \c
2193    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2194    can be useful if you want to ensure that all user-visible strings
2195    go through QObject::tr(), for example.
2196*/
2197
2198/*!
2199    Returns true if this string is lexically less than string \a
2200    other; otherwise returns false.
2201
2202    The comparison is based exclusively on the numeric Unicode values
2203    of the characters and is very fast, but is not what a human would
2204    expect. Consider sorting user-interface strings using the
2205    QString::localeAwareCompare() function.
2206*/
2207bool QString::operator<(const QString &other) const
2208{
2209    return ucstrcmp(constData(), length(), other.constData(), other.length()) < 0;
2210}
2211
2212/*!
2213    \overload operator<()
2214*/
2215bool QString::operator<(const QLatin1String &other) const
2216{
2217    const ushort *uc = d->data;
2218    const ushort *e = uc + d->size;
2219    const uchar *c = (uchar *) other.latin1();
2220
2221    if (!c || *c == 0)
2222        return false;
2223
2224    while (*c) {
2225        if (uc == e || *uc != *c)
2226            break;
2227        ++uc;
2228        ++c;
2229    }
2230    return (uc == e ? *c : *uc < *c);
2231}
2232
2233/*! \fn bool QString::operator<(const QByteArray &other) const
2234
2235    \overload operator<()
2236
2237    The \a other byte array is converted to a QString using the
2238    fromAscii() function. If any NUL characters ('\0') are embedded
2239    in the byte array, they will be included in the transformation.
2240
2241    You can disable this operator by defining \c
2242    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2243    can be useful if you want to ensure that all user-visible strings
2244    go through QObject::tr(), for example.
2245*/
2246
2247/*! \fn bool QString::operator<(const char *other) const
2248
2249    \overload operator<()
2250
2251    The \a other const char pointer is converted to a QString using
2252    the fromAscii() function.
2253
2254    You can disable this operator by defining \c
2255    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2256    can be useful if you want to ensure that all user-visible strings
2257    go through QObject::tr(), for example.
2258*/
2259
2260/*! \fn bool QString::operator<=(const QString &other) const
2261
2262    Returns true if this string is lexically less than or equal to
2263    string \a other; otherwise returns false.
2264
2265    The comparison is based exclusively on the numeric Unicode values
2266    of the characters and is very fast, but is not what a human would
2267    expect. Consider sorting user-interface strings with
2268    localeAwareCompare().
2269*/
2270
2271/*! \fn bool QString::operator<=(const QLatin1String &other) const
2272
2273    \overload operator<=()
2274*/
2275
2276/*! \fn bool QString::operator<=(const QByteArray &other) const
2277
2278    \overload operator<=()
2279
2280    The \a other byte array is converted to a QString using the
2281    fromAscii() function. If any NUL characters ('\0') are embedded
2282    in the byte array, they will be included in the transformation.
2283
2284    You can disable this operator by defining \c
2285    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2286    can be useful if you want to ensure that all user-visible strings
2287    go through QObject::tr(), for example.
2288*/
2289
2290/*! \fn bool QString::operator<=(const char *other) const
2291
2292    \overload operator<=()
2293
2294    The \a other const char pointer is converted to a QString using
2295    the fromAscii() function.
2296
2297    You can disable this operator by defining \c
2298    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2299    can be useful if you want to ensure that all user-visible strings
2300    go through QObject::tr(), for example.
2301*/
2302
2303/*! \fn bool QString::operator>(const QString &other) const
2304
2305    Returns true if this string is lexically greater than string \a
2306    other; otherwise returns false.
2307
2308    The comparison is based exclusively on the numeric Unicode values
2309    of the characters and is very fast, but is not what a human would
2310    expect. Consider sorting user-interface strings with
2311    localeAwareCompare().
2312*/
2313
2314/*!
2315    \overload operator>()
2316*/
2317bool QString::operator>(const QLatin1String &other) const
2318{
2319    const ushort *uc = d->data;;
2320    const ushort *e = uc + d->size;
2321    const uchar *c = (uchar *) other.latin1();
2322
2323    if (!c || *c == '\0')
2324        return !isEmpty();
2325
2326    while (*c) {
2327        if (uc == e || *uc != *c)
2328            break;
2329        ++uc;
2330        ++c;
2331    }
2332    return (uc == e ? false : *uc > *c);
2333}
2334
2335/*! \fn bool QString::operator>(const QByteArray &other) const
2336
2337    \overload operator>()
2338
2339    The \a other byte array is converted to a QString using the
2340    fromAscii() function. If any NUL characters ('\0') are embedded
2341    in the byte array, they will be included in the transformation.
2342
2343    You can disable this operator by defining \c
2344    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2345    can be useful if you want to ensure that all user-visible strings
2346    go through QObject::tr(), for example.
2347*/
2348
2349/*! \fn bool QString::operator>(const char *other) const
2350
2351    \overload operator>()
2352
2353    The \a other const char pointer is converted to a QString using
2354    the fromAscii() function.
2355
2356    You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2357    when you compile your applications. This can be useful if you want
2358    to ensure that all user-visible strings go through QObject::tr(),
2359    for example.
2360*/
2361
2362/*! \fn bool QString::operator>=(const QString &other) const
2363
2364    Returns true if this string is lexically greater than or equal to
2365    string \a other; otherwise returns false.
2366
2367    The comparison is based exclusively on the numeric Unicode values
2368    of the characters and is very fast, but is not what a human would
2369    expect. Consider sorting user-interface strings with
2370    localeAwareCompare().
2371*/
2372
2373/*! \fn bool QString::operator>=(const QLatin1String &other) const
2374
2375    \overload operator>=()
2376*/
2377
2378/*! \fn bool QString::operator>=(const QByteArray &other) const
2379
2380    \overload operator>=()
2381
2382    The \a other byte array is converted to a QString using the
2383    fromAscii() function. If any NUL characters ('\0') are embedded in
2384    the byte array, they will be included in the transformation.
2385
2386    You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2387    when you compile your applications. This can be useful if you want
2388    to ensure that all user-visible strings go through QObject::tr(),
2389    for example.
2390*/
2391
2392/*! \fn bool QString::operator>=(const char *other) const
2393
2394    \overload operator>=()
2395
2396    The \a other const char pointer is converted to a QString using
2397    the fromAscii() function.
2398
2399    You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2400    when you compile your applications. This can be useful if you want
2401    to ensure that all user-visible strings go through QObject::tr(),
2402    for example.
2403*/
2404
2405/*! \fn bool QString::operator!=(const QString &other) const
2406
2407    Returns true if this string is not equal to string \a other;
2408    otherwise returns false.
2409
2410    The comparison is based exclusively on the numeric Unicode values
2411    of the characters and is very fast, but is not what a human would
2412    expect. Consider sorting user-interface strings with
2413    localeAwareCompare().
2414*/
2415
2416/*! \fn bool QString::operator!=(const QLatin1String &other) const
2417
2418    \overload operator!=()
2419*/
2420
2421/*! \fn bool QString::operator!=(const QByteArray &other) const
2422
2423    \overload operator!=()
2424
2425    The \a other byte array is converted to a QString using the
2426    fromAscii() function. If any NUL characters ('\0') are embedded
2427    in the byte array, they will be included in the transformation.
2428
2429    You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2430    when you compile your applications. This can be useful if you want
2431    to ensure that all user-visible strings go through QObject::tr(),
2432    for example.
2433*/
2434
2435/*! \fn bool QString::operator!=(const char *other) const
2436
2437    \overload operator!=()
2438
2439    The \a other const char pointer is converted to a QString using
2440    the fromAscii() function.
2441
2442    You can disable this operator by defining \c
2443    QT_NO_CAST_FROM_ASCII when you compile your applications. This
2444    can be useful if you want to ensure that all user-visible strings
2445    go through QObject::tr(), for example.
2446*/
2447
2448/*!
2449  Returns the index position of the first occurrence of the string \a
2450  str in this string, searching forward from index position \a
2451  from. Returns -1 if \a str is not found.
2452
2453  If \a cs is Qt::CaseSensitive (default), the search is case
2454  sensitive; otherwise the search is case insensitive.
2455
2456  Example:
2457
2458  \snippet doc/src/snippets/qstring/main.cpp 24
2459
2460  If \a from is -1, the search starts at the last character; if it is
2461  -2, at the next to last character and so on.
2462
2463  \sa lastIndexOf(), contains(), count()
2464*/
2465int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2466{
2467    return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2468}
2469
2470/*!
2471  \since 4.5
2472  Returns the index position of the first occurrence of the string \a
2473  str in this string, searching forward from index position \a
2474  from. Returns -1 if \a str is not found.
2475
2476  If \a cs is Qt::CaseSensitive (default), the search is case
2477  sensitive; otherwise the search is case insensitive.
2478
2479  Example:
2480
2481  \snippet doc/src/snippets/qstring/main.cpp 24
2482
2483  If \a from is -1, the search starts at the last character; if it is
2484  -2, at the next to last character and so on.
2485
2486  \sa lastIndexOf(), contains(), count()
2487*/
2488int QString::indexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2489{
2490    int len = qstrlen(str.latin1());
2491    QVarLengthArray<ushort> s(len);
2492    for (int i = 0; i < len; ++i)
2493        s[i] = str.latin1()[i];
2494
2495    return qFindString(unicode(), length(), from, (const QChar *)s.data(), len, cs);
2496}
2497
2498int qFindString(
2499    const QChar *haystack0, int haystackLen, int from,
2500    const QChar *needle0, int needleLen, Qt::CaseSensitivity cs)
2501{
2502    const int l = haystackLen;
2503    const int sl = needleLen;
2504    if (from < 0)
2505        from += l;
2506    if (uint(sl + from) > (uint)l)
2507        return -1;
2508    if (!sl)
2509        return from;
2510    if (!l)
2511        return -1;
2512
2513    if (sl == 1)
2514        return findChar(haystack0, haystackLen, needle0[0], from, cs);
2515
2516    /*
2517        We use the Boyer-Moore algorithm in cases where the overhead
2518        for the skip table should pay off, otherwise we use a simple
2519        hash function.
2520    */
2521    if (l > 500 && sl > 5)
2522        return qFindStringBoyerMoore(haystack0, haystackLen, from,
2523            needle0, needleLen, cs);
2524
2525    /*
2526        We use some hashing for efficiency's sake. Instead of
2527        comparing strings, we compare the hash value of str with that
2528        of a part of this QString. Only if that matches, we call
2529        ucstrncmp() or ucstrnicmp().
2530    */
2531    const ushort *needle = (const ushort *)needle0;
2532    const ushort *haystack = (const ushort *)haystack0 + from;
2533    const ushort *end = (const ushort *)haystack0 + (l-sl);
2534    const int sl_minus_1 = sl-1;
2535    int hashNeedle = 0, hashHaystack = 0, idx;
2536
2537    if (cs == Qt::CaseSensitive) {
2538        for (idx = 0; idx < sl; ++idx) {
2539            hashNeedle = ((hashNeedle<<1) + needle[idx]);
2540            hashHaystack = ((hashHaystack<<1) + haystack[idx]);
2541        }
2542        hashHaystack -= haystack[sl_minus_1];
2543
2544        while (haystack <= end) {
2545            hashHaystack += haystack[sl_minus_1];
2546            if (hashHaystack == hashNeedle
2547                 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2548                return haystack - (const ushort *)haystack0;
2549
2550            REHASH(*haystack);
2551            ++haystack;
2552        }
2553    } else {
2554        const ushort *haystack_start = (const ushort *)haystack0;
2555        for (idx = 0; idx < sl; ++idx) {
2556            hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle);
2557            hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start);
2558        }
2559        hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start);
2560
2561        while (haystack <= end) {
2562            hashHaystack += foldCase(haystack + sl_minus_1, haystack_start);
2563            if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2564                return haystack - (const ushort *)haystack0;
2565
2566            REHASH(foldCase(haystack, haystack_start));
2567            ++haystack;
2568        }
2569    }
2570    return -1;
2571}
2572
2573/*!
2574    \overload indexOf()
2575
2576    Returns the index position of the first occurrence of the
2577    character \a ch in the string, searching forward from index
2578    position \a from. Returns -1 if \a ch could not be found.
2579*/
2580int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2581{
2582    return findChar(unicode(), length(), ch, from, cs);
2583}
2584
2585static int lastIndexOfHelper(const ushort *haystack, int from, const ushort *needle, int sl, Qt::CaseSensitivity cs)
2586{
2587    /*
2588        See indexOf() for explanations.
2589    */
2590
2591    const ushort *end = haystack;
2592    haystack += from;
2593    const int sl_minus_1 = sl-1;
2594    const ushort *n = needle+sl_minus_1;
2595    const ushort *h = haystack+sl_minus_1;
2596    int hashNeedle = 0, hashHaystack = 0, idx;
2597
2598    if (cs == Qt::CaseSensitive) {
2599        for (idx = 0; idx < sl; ++idx) {
2600            hashNeedle = ((hashNeedle<<1) + *(n-idx));
2601            hashHaystack = ((hashHaystack<<1) + *(h-idx));
2602        }
2603        hashHaystack -= *haystack;
2604
2605        while (haystack >= end) {
2606            hashHaystack += *haystack;
2607            if (hashHaystack == hashNeedle
2608                 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2609                return haystack - end;
2610            --haystack;
2611            REHASH(haystack[sl]);
2612        }
2613    } else {
2614        for (idx = 0; idx < sl; ++idx) {
2615            hashNeedle = ((hashNeedle<<1) + foldCase(n-idx, needle));
2616            hashHaystack = ((hashHaystack<<1) + foldCase(h-idx, end));
2617        }
2618        hashHaystack -= foldCase(haystack, end);
2619
2620        while (haystack >= end) {
2621            hashHaystack += foldCase(haystack, end);
2622            if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2623                return haystack - end;
2624            --haystack;
2625            REHASH(foldCase(haystack + sl, end));
2626        }
2627    }
2628    return -1;
2629}
2630
2631/*!
2632  Returns the index position of the last occurrence of the string \a
2633  str in this string, searching backward from index position \a
2634  from. If \a from is -1 (default), the search starts at the last
2635  character; if \a from is -2, at the next to last character and so
2636  on. Returns -1 if \a str is not found.
2637
2638  If \a cs is Qt::CaseSensitive (default), the search is case
2639  sensitive; otherwise the search is case insensitive.
2640
2641  Example:
2642
2643  \snippet doc/src/snippets/qstring/main.cpp 29
2644
2645  \sa indexOf(), contains(), count()
2646*/
2647int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2648{
2649    const int sl = str.d->size;
2650    if (sl == 1)
2651        return lastIndexOf(QChar(str.d->data[0]), from, cs);
2652
2653    const int l = d->size;
2654    if (from < 0)
2655        from += l;
2656    int delta = l-sl;
2657    if (from == l && sl == 0)
2658        return from;
2659    if (from < 0 || from >= l || delta < 0)
2660        return -1;
2661    if (from > delta)
2662        from = delta;
2663
2664
2665    return lastIndexOfHelper(d->data, from, str.d->data, str.d->size, cs);
2666}
2667
2668/*!
2669  \since 4.5
2670  Returns the index position of the last occurrence of the string \a
2671  str in this string, searching backward from index position \a
2672  from. If \a from is -1 (default), the search starts at the last
2673  character; if \a from is -2, at the next to last character and so
2674  on. Returns -1 if \a str is not found.
2675
2676  If \a cs is Qt::CaseSensitive (default), the search is case
2677  sensitive; otherwise the search is case insensitive.
2678
2679  Example:
2680
2681  \snippet doc/src/snippets/qstring/main.cpp 29
2682
2683  \sa indexOf(), contains(), count()
2684*/
2685int QString::lastIndexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2686{
2687    const int sl = qstrlen(str.latin1());
2688    if (sl == 1)
2689        return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
2690
2691    const int l = d->size;
2692    if (from < 0)
2693        from += l;
2694    int delta = l-sl;
2695    if (from == l && sl == 0)
2696        return from;
2697    if (from < 0 || from >= l || delta < 0)
2698        return -1;
2699    if (from > delta)
2700        from = delta;
2701
2702    QVarLengthArray<ushort> s(sl);
2703    for (int i = 0; i < sl; ++i)
2704        s[i] = str.latin1()[i];
2705
2706    return lastIndexOfHelper(d->data, from, s.data(), sl, cs);
2707}
2708
2709/*!
2710  \overload lastIndexOf()
2711
2712  Returns the index position of the last occurrence of the character
2713  \a ch, searching backward from position \a from.
2714*/
2715int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2716{
2717    ushort c = ch.unicode();
2718    if (from < 0)
2719        from += d->size;
2720    if (from < 0 || from >= d->size)
2721        return -1;
2722    if (from >= 0) {
2723        const ushort *n = d->data + from;
2724        const ushort *b = d->data;
2725        if (cs == Qt::CaseSensitive) {
2726            for (; n >= b; --n)
2727                if (*n == c)
2728                    return n - b;
2729        } else {
2730            c = foldCase(c);
2731            for (; n >= b; --n)
2732                if (foldCase(*n) == c)
2733                    return n - b;
2734        }
2735    }
2736    return -1;
2737}
2738
2739#ifndef QT_NO_REGEXP
2740struct QStringCapture
2741{
2742    int pos;
2743    int len;
2744    int no;
2745};
2746
2747/*!
2748  \overload replace()
2749
2750  Replaces every occurrence of the regular expression \a rx in the
2751  string with \a after. Returns a reference to the string. For
2752  example:
2753
2754  \snippet doc/src/snippets/qstring/main.cpp 42
2755
2756  For regular expressions containing \l{capturing parentheses},
2757  occurrences of \bold{\\1}, \bold{\\2}, ..., in \a after are replaced
2758  with \a{rx}.cap(1), cap(2), ...
2759
2760  \snippet doc/src/snippets/qstring/main.cpp 43
2761
2762  \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap()
2763*/
2764QString& QString::replace(const QRegExp &rx, const QString &after)
2765{
2766    QRegExp rx2(rx);
2767
2768    if (isEmpty() && rx2.indexIn(*this) == -1)
2769        return *this;
2770
2771    realloc();
2772
2773    int index = 0;
2774    int numCaptures = rx2.captureCount();
2775    int al = after.length();
2776    QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
2777
2778    if (numCaptures > 0) {
2779        const QChar *uc = after.unicode();
2780        int numBackRefs = 0;
2781
2782        for (int i = 0; i < al - 1; i++) {
2783            if (uc[i] == QLatin1Char('\\')) {
2784                int no = uc[i + 1].digitValue();
2785                if (no > 0 && no <= numCaptures)
2786                    numBackRefs++;
2787            }
2788        }
2789
2790        /*
2791            This is the harder case where we have back-references.
2792        */
2793        if (numBackRefs > 0) {
2794            QVarLengthArray<QStringCapture, 16> captures(numBackRefs);
2795            int j = 0;
2796
2797            for (int i = 0; i < al - 1; i++) {
2798                if (uc[i] == QLatin1Char('\\')) {
2799                    int no = uc[i + 1].digitValue();
2800                    if (no > 0 && no <= numCaptures) {
2801                        QStringCapture capture;
2802                        capture.pos = i;
2803                        capture.len = 2;
2804
2805                        if (i < al - 2) {
2806                            int secondDigit = uc[i + 2].digitValue();
2807                            if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
2808                                no = (no * 10) + secondDigit;
2809                                ++capture.len;
2810                            }
2811                        }
2812
2813                        capture.no = no;
2814                        captures[j++] = capture;
2815                    }
2816                }
2817            }
2818
2819            while (index <= length()) {
2820                index = rx2.indexIn(*this, index, caretMode);
2821                if (index == -1)
2822                    break;
2823
2824                QString after2(after);
2825                for (j = numBackRefs - 1; j >= 0; j--) {
2826                    const QStringCapture &capture = captures[j];
2827                    after2.replace(capture.pos, capture.len, rx2.cap(capture.no));
2828                }
2829
2830                replace(index, rx2.matchedLength(), after2);
2831                index += after2.length();
2832
2833                // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*"))
2834                if (rx2.matchedLength() == 0)
2835                    ++index;
2836
2837                caretMode = QRegExp::CaretWontMatch;
2838            }
2839            return *this;
2840        }
2841    }
2842
2843    /*
2844        This is the simple and optimized case where we don't have
2845        back-references.
2846    */
2847    while (index != -1) {
2848        struct {
2849            int pos;
2850            int length;
2851        } replacements[2048];
2852
2853        int pos = 0;
2854        int adjust = 0;
2855        while (pos < 2047) {
2856            index = rx2.indexIn(*this, index, caretMode);
2857            if (index == -1)
2858                break;
2859            int ml = rx2.matchedLength();
2860            replacements[pos].pos = index;
2861            replacements[pos++].length = ml;
2862            index += ml;
2863            adjust += al - ml;
2864            // avoid infinite loop
2865            if (!ml)
2866                index++;
2867        }
2868        if (!pos)
2869            break;
2870        replacements[pos].pos = d->size;
2871        int newlen = d->size + adjust;
2872
2873        // to continue searching at the right position after we did
2874        // the first round of replacements
2875        if (index != -1)
2876            index += adjust;
2877        QString newstring;
2878        newstring.reserve(newlen + 1);
2879        QChar *newuc = newstring.data();
2880        QChar *uc = newuc;
2881        int copystart = 0;
2882        int i = 0;
2883        while (i < pos) {
2884            int copyend = replacements[i].pos;
2885            int size = copyend - copystart;
2886            memcpy(uc, d->data + copystart, size * sizeof(QChar));
2887            uc += size;
2888            memcpy(uc, after.d->data, al * sizeof(QChar));
2889            uc += al;
2890            copystart = copyend + replacements[i].length;
2891            i++;
2892        }
2893        memcpy(uc, d->data + copystart, (d->size - copystart) * sizeof(QChar));
2894        newstring.resize(newlen);
2895        *this = newstring;
2896        caretMode = QRegExp::CaretWontMatch;
2897    }
2898    return *this;
2899}
2900#endif
2901
2902/*!
2903    Returns the number of (potentially overlapping) occurrences of
2904    the string \a str in this string.
2905
2906    If \a cs is Qt::CaseSensitive (default), the search is
2907    case sensitive; otherwise the search is case insensitive.
2908
2909    \sa contains(), indexOf()
2910*/
2911int QString::count(const QString &str, Qt::CaseSensitivity cs) const
2912{
2913    int num = 0;
2914    int i = -1;
2915    if (d->size > 500 && str.d->size > 5) {
2916        QStringMatcher matcher(str, cs);
2917        while ((i = matcher.indexIn(*this, i + 1)) != -1)
2918            ++num;
2919    } else {
2920        while ((i = indexOf(str, i + 1, cs)) != -1)
2921            ++num;
2922    }
2923    return num;
2924}
2925
2926/*!
2927  \overload count()
2928
2929  Returns the number of occurrences of character \a ch in the string.
2930*/
2931int QString::count(QChar ch, Qt::CaseSensitivity cs) const
2932{
2933    ushort c = ch.unicode();
2934    int num = 0;
2935    const ushort *i = d->data + d->size;
2936    const ushort *b = d->data;
2937    if (cs == Qt::CaseSensitive) {
2938        while (i != b)
2939            if (*--i == c)
2940                ++num;
2941    } else {
2942        c = foldCase(c);
2943        while (i != b)
2944            if (foldCase(*(--i)) == c)
2945                ++num;
2946    }
2947    return num;
2948}
2949
2950/*! \fn bool QString::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
2951
2952    Returns true if this string contains an occurrence of the string
2953    \a str; otherwise returns false.
2954
2955    If \a cs is Qt::CaseSensitive (default), the search is
2956    case sensitive; otherwise the search is case insensitive.
2957
2958    Example:
2959    \snippet doc/src/snippets/qstring/main.cpp 17
2960
2961    \sa indexOf(), count()
2962*/
2963
2964/*! \fn bool QString::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
2965
2966    \overload contains()
2967
2968    Returns true if this string contains an occurrence of the
2969    character \a ch; otherwise returns false.
2970*/
2971
2972/*! \fn bool QString::contains(const QRegExp &rx) const
2973
2974    \overload contains()
2975
2976    Returns true if the regular expression \a rx matches somewhere in
2977    this string; otherwise returns false.
2978*/
2979
2980/*! \fn bool QString::contains(QRegExp &rx) const
2981    \overload contains()
2982    \since 4.5
2983
2984    Returns true if the regular expression \a rx matches somewhere in
2985    this string; otherwise returns false.
2986
2987    If there is a match, the \a rx regular expression will contain the
2988    matched captures (see QRegExp::matchedLength, QRegExp::cap).
2989*/
2990
2991#ifndef QT_NO_REGEXP
2992/*!
2993    \overload indexOf()
2994
2995    Returns the index position of the first match of the regular
2996    expression \a rx in the string, searching forward from index
2997    position \a from. Returns -1 if \a rx didn't match anywhere.
2998
2999    Example:
3000
3001    \snippet doc/src/snippets/qstring/main.cpp 25
3002*/
3003int QString::indexOf(const QRegExp& rx, int from) const
3004{
3005    QRegExp rx2(rx);
3006    return rx2.indexIn(*this, from);
3007}
3008
3009/*!
3010    \overload indexOf()
3011    \since 4.5
3012
3013    Returns the index position of the first match of the regular
3014    expression \a rx in the string, searching forward from index
3015    position \a from. Returns -1 if \a rx didn't match anywhere.
3016
3017    If there is a match, the \a rx regular expression will contain the
3018    matched captures (see QRegExp::matchedLength, QRegExp::cap).
3019
3020    Example:
3021
3022    \snippet doc/src/snippets/qstring/main.cpp 25
3023*/
3024int QString::indexOf(QRegExp& rx, int from) const
3025{
3026    return rx.indexIn(*this, from);
3027}
3028
3029/*!
3030    \overload lastIndexOf()
3031
3032    Returns the index position of the last match of the regular
3033    expression \a rx in the string, searching backward from index
3034    position \a from. Returns -1 if \a rx didn't match anywhere.
3035
3036    Example:
3037
3038    \snippet doc/src/snippets/qstring/main.cpp 30
3039*/
3040int QString::lastIndexOf(const QRegExp& rx, int from) const
3041{
3042    QRegExp rx2(rx);
3043    return rx2.lastIndexIn(*this, from);
3044}
3045
3046/*!
3047    \overload lastIndexOf()
3048    \since 4.5
3049
3050    Returns the index position of the last match of the regular
3051    expression \a rx in the string, searching backward from index
3052    position \a from. Returns -1 if \a rx didn't match anywhere.
3053
3054    If there is a match, the \a rx regular expression will contain the
3055    matched captures (see QRegExp::matchedLength, QRegExp::cap).
3056
3057    Example:
3058
3059    \snippet doc/src/snippets/qstring/main.cpp 30
3060*/
3061int QString::lastIndexOf(QRegExp& rx, int from) const
3062{
3063    return rx.lastIndexIn(*this, from);
3064}
3065
3066/*!
3067    \overload count()
3068
3069    Returns the number of times the regular expression \a rx matches
3070    in the string.
3071
3072    This function counts overlapping matches, so in the example
3073    below, there are four instances of "ana" or "ama":
3074
3075    \snippet doc/src/snippets/qstring/main.cpp 18
3076
3077*/
3078int QString::count(const QRegExp& rx) const
3079{
3080    QRegExp rx2(rx);
3081    int count = 0;
3082    int index = -1;
3083    int len = length();
3084    while (index < len - 1) {                 // count overlapping matches
3085        index = rx2.indexIn(*this, index + 1);
3086        if (index == -1)
3087            break;
3088        count++;
3089    }
3090    return count;
3091}
3092#endif // QT_NO_REGEXP
3093
3094/*! \fn int QString::count() const
3095
3096    \overload count()
3097
3098    Same as size().
3099*/
3100
3101
3102/*!
3103    \enum QString::SectionFlag
3104
3105    This enum specifies flags that can be used to affect various
3106    aspects of the section() function's behavior with respect to
3107    separators and empty fields.
3108
3109    \value SectionDefault Empty fields are counted, leading and
3110    trailing separators are not included, and the separator is
3111    compared case sensitively.
3112
3113    \value SectionSkipEmpty Treat empty fields as if they don't exist,
3114    i.e. they are not considered as far as \e start and \e end are
3115    concerned.
3116
3117    \value SectionIncludeLeadingSep Include the leading separator (if
3118    any) in the result string.
3119
3120    \value SectionIncludeTrailingSep Include the trailing separator
3121    (if any) in the result string.
3122
3123    \value SectionCaseInsensitiveSeps Compare the separator
3124    case-insensitively.
3125
3126    \sa section()
3127*/
3128
3129/*!
3130    \fn QString QString::section(QChar sep, int start, int end = -1, SectionFlags flags) const
3131
3132    This function returns a section of the string.
3133
3134    This string is treated as a sequence of fields separated by the
3135    character, \a sep. The returned string consists of the fields from
3136    position \a start to position \a end inclusive. If \a end is not
3137    specified, all fields from position \a start to the end of the
3138    string are included. Fields are numbered 0, 1, 2, etc., counting
3139    from the left, and -1, -2, etc., counting from right to left.
3140
3141    The \a flags argument can be used to affect some aspects of the
3142    function's behavior, e.g. whether to be case sensitive, whether
3143    to skip empty fields and how to deal with leading and trailing
3144    separators; see \l{SectionFlags}.
3145
3146    \snippet doc/src/snippets/qstring/main.cpp 52
3147
3148    If \a start or \a end is negative, we count fields from the right
3149    of the string, the right-most field being -1, the one from
3150    right-most field being -2, and so on.
3151
3152    \snippet doc/src/snippets/qstring/main.cpp 53
3153
3154    \sa split()
3155*/
3156
3157/*!
3158    \overload section()
3159
3160    \snippet doc/src/snippets/qstring/main.cpp 51
3161    \snippet doc/src/snippets/qstring/main.cpp 54
3162
3163    \sa split()
3164*/
3165
3166QString QString::section(const QString &sep, int start, int end, SectionFlags flags) const
3167{
3168    QStringList sections = split(sep, KeepEmptyParts,
3169                                 (flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive : Qt::CaseSensitive);
3170    if (sections.isEmpty())
3171        return QString();
3172    if (!(flags & SectionSkipEmpty)) {
3173        if (start < 0)
3174            start += sections.count();
3175        if (end < 0)
3176            end += sections.count();
3177    } else {
3178        int skip = 0;
3179        for (int k=0; k<sections.size(); ++k) {
3180            if (sections.at(k).isEmpty())
3181                skip++;
3182        }
3183        if (start < 0)
3184            start += sections.count() - skip;
3185        if (end < 0)
3186            end += sections.count() - skip;
3187    }
3188    int x = 0;
3189    QString ret;
3190    int first_i = start, last_i = end;
3191    for (int i = 0; x <= end && i < sections.size(); ++i) {
3192        QString section = sections.at(i);
3193        const bool empty = section.isEmpty();
3194        if (x >= start) {
3195            if(x == start)
3196                first_i = i;
3197            if(x == end)
3198                last_i = i;
3199            if(x > start)
3200                ret += sep;
3201            ret += section;
3202        }
3203        if (!empty || !(flags & SectionSkipEmpty))
3204            x++;
3205    }
3206    if((flags & SectionIncludeLeadingSep) && first_i)
3207        ret.prepend(sep);
3208    if((flags & SectionIncludeTrailingSep) && last_i < sections.size()-1)
3209        ret += sep;
3210    return ret;
3211}
3212
3213#ifndef QT_NO_REGEXP
3214class qt_section_chunk {
3215public:
3216    qt_section_chunk(int l, QString s) { length = l; string = s; }
3217    int length;
3218    QString string;
3219};
3220
3221/*!
3222    \overload section()
3223
3224    This string is treated as a sequence of fields separated by the
3225    regular expression, \a reg.
3226
3227    \snippet doc/src/snippets/qstring/main.cpp 55
3228
3229    \warning Using this QRegExp version is much more expensive than
3230    the overloaded string and character versions.
3231
3232    \sa split() simplified()
3233*/
3234QString QString::section(const QRegExp &reg, int start, int end, SectionFlags flags) const
3235{
3236    const QChar *uc = unicode();
3237    if(!uc)
3238        return QString();
3239
3240    QRegExp sep(reg);
3241    sep.setCaseSensitivity((flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive
3242                                                                : Qt::CaseSensitive);
3243
3244    QList<qt_section_chunk> sections;
3245    int n = length(), m = 0, last_m = 0, last_len = 0;
3246    while ((m = sep.indexIn(*this, m)) != -1) {
3247        sections.append(qt_section_chunk(last_len, QString(uc + last_m, m - last_m)));
3248        last_m = m;
3249        last_len = sep.matchedLength();
3250        m += qMax(sep.matchedLength(), 1);
3251    }
3252    sections.append(qt_section_chunk(last_len, QString(uc + last_m, n - last_m)));
3253
3254    if(start < 0)
3255        start += sections.count();
3256    if(end < 0)
3257        end += sections.count();
3258
3259    QString ret;
3260    int x = 0;
3261    int first_i = start, last_i = end;
3262    for (int i = 0; x <= end && i < sections.size(); ++i) {
3263        const qt_section_chunk &section = sections.at(i);
3264        const bool empty = (section.length == section.string.length());
3265        if (x >= start) {
3266            if(x == start)
3267                first_i = i;
3268            if(x == end)
3269                last_i = i;
3270            if(x != start)
3271                ret += section.string;
3272            else
3273                ret += section.string.mid(section.length);
3274        }
3275        if (!empty || !(flags & SectionSkipEmpty))
3276            x++;
3277    }
3278    if((flags & SectionIncludeLeadingSep) && first_i < sections.size()) {
3279        const qt_section_chunk &section = sections.at(first_i);
3280        ret.prepend(section.string.left(section.length));
3281    }
3282    if((flags & SectionIncludeTrailingSep) && last_i+1 <= sections.size()-1) {
3283        const qt_section_chunk &section = sections.at(last_i+1);
3284        ret += section.string.left(section.length);
3285    }
3286    return ret;
3287}
3288#endif
3289
3290/*!
3291    Returns a substring that contains the \a n leftmost characters
3292    of the string.
3293
3294    The entire string is returned if \a n is greater than size() or
3295    less than zero.
3296
3297    \snippet doc/src/snippets/qstring/main.cpp 31
3298
3299    \sa right(), mid(), startsWith()
3300*/
3301QString QString::left(int n)  const
3302{
3303    if (n >= d->size || n < 0)
3304        return *this;
3305    return QString((const QChar*) d->data, n);
3306}
3307
3308/*!
3309    Returns a substring that contains the \a n rightmost characters
3310    of the string.
3311
3312    The entire string is returned if \a n is greater than size() or
3313    less than zero.
3314
3315    \snippet doc/src/snippets/qstring/main.cpp 48
3316
3317    \sa left(), mid(), endsWith()
3318*/
3319QString QString::right(int n) const
3320{
3321    if (n >= d->size || n < 0)
3322        return *this;
3323    return QString((const QChar*) d->data + d->size - n, n);
3324}
3325
3326/*!
3327    Returns a string that contains \a n characters of this string,
3328    starting at the specified \a position index.
3329
3330    Returns a null string if the \a position index exceeds the
3331    length of the string. If there are less than \a n characters
3332    available in the string starting at the given \a position, or if
3333    \a n is -1 (default), the function returns all characters that
3334    are available from the specified \a position.
3335
3336    Example:
3337
3338    \snippet doc/src/snippets/qstring/main.cpp 34
3339
3340    \sa left(), right()
3341*/
3342
3343QString QString::mid(int position, int n) const
3344{
3345    if (d == &shared_null || position >= d->size)
3346        return QString();
3347    if (n < 0)
3348        n = d->size - position;
3349    if (position < 0) {
3350        n += position;
3351        position = 0;
3352    }
3353    if (n + position > d->size)
3354        n = d->size - position;
3355    if (position == 0 && n == d->size)
3356        return *this;
3357    return QString((const QChar*) d->data + position, n);
3358}
3359
3360/*!
3361    Returns true if the string starts with \a s; otherwise returns
3362    false.
3363
3364    If \a cs is Qt::CaseSensitive (default), the search is
3365    case sensitive; otherwise the search is case insensitive.
3366
3367    \snippet doc/src/snippets/qstring/main.cpp 65
3368
3369    \sa endsWith()
3370*/
3371bool QString::startsWith(const QString& s, Qt::CaseSensitivity cs) const
3372{
3373    if (d == &shared_null)
3374        return (s.d == &shared_null);
3375    if (d->size == 0)
3376        return s.d->size == 0;
3377    if (s.d->size > d->size)
3378        return false;
3379    if (cs == Qt::CaseSensitive) {
3380        return qMemEquals(d->data, s.d->data, s.d->size);
3381    } else {
3382        uint last = 0;
3383        uint olast = 0;
3384        for (int i = 0; i < s.d->size; ++i)
3385            if (foldCase(d->data[i], last) != foldCase(s.d->data[i], olast))
3386                return false;
3387    }
3388    return true;
3389}
3390
3391/*!
3392  \overload startsWith()
3393 */
3394bool QString::startsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const
3395{
3396    if (d == &shared_null)
3397        return (s.latin1() == 0);
3398    if (d->size == 0)
3399        return !s.latin1() || *s.latin1() == 0;
3400    int slen = qstrlen(s.latin1());
3401    if (slen > d->size)
3402        return false;
3403    const uchar *latin = (const uchar *)s.latin1();
3404    if (cs == Qt::CaseSensitive) {
3405        for (int i = 0; i < slen; ++i)
3406            if (d->data[i] != latin[i])
3407                return false;
3408    } else {
3409        for (int i = 0; i < slen; ++i)
3410            if (foldCase(d->data[i]) != foldCase((ushort)latin[i]))
3411                return false;
3412    }
3413    return true;
3414}
3415
3416/*!
3417  \overload startsWith()
3418
3419  Returns true if the string starts with \a c; otherwise returns
3420  false.
3421*/
3422bool QString::startsWith(const QChar &c, Qt::CaseSensitivity cs) const
3423{
3424    return d->size
3425           && (cs == Qt::CaseSensitive
3426               ? d->data[0] == c
3427               : foldCase(d->data[0]) == foldCase(c.unicode()));
3428}
3429
3430/*!
3431    Returns true if the string ends with \a s; otherwise returns
3432    false.
3433
3434    If \a cs is Qt::CaseSensitive (default), the search is case
3435    sensitive; otherwise the search is case insensitive.
3436
3437    \snippet doc/src/snippets/qstring/main.cpp 20
3438
3439    \sa startsWith()
3440*/
3441bool QString::endsWith(const QString& s, Qt::CaseSensitivity cs) const
3442{
3443    if (d == &shared_null)
3444        return (s.d == &shared_null);
3445    if (d->size == 0)
3446        return s.d->size == 0;
3447    int pos = d->size - s.d->size;
3448    if (pos < 0)
3449        return false;
3450    if (cs == Qt::CaseSensitive) {
3451        return qMemEquals(d->data + pos, s.d->data, s.d->size);
3452    } else {
3453        uint last = 0;
3454        uint olast = 0;
3455        for (int i = 0; i < s.length(); i++)
3456            if (foldCase(d->data[pos+i], last) != foldCase(s.d->data[i], olast))
3457                return false;
3458    }
3459    return true;
3460}
3461
3462/*!
3463    \overload endsWith()
3464*/
3465bool QString::endsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const
3466{
3467    if (d == &shared_null)
3468        return (s.latin1() == 0);
3469    if (d->size == 0)
3470        return !s.latin1() || *s.latin1() == 0;
3471    int slen = qstrlen(s.latin1());
3472    int pos = d->size - slen;
3473    const uchar *latin = (const uchar *)s.latin1();
3474    if (pos < 0)
3475        return false;
3476    if (cs == Qt::CaseSensitive) {
3477        for (int i = 0; i < slen; i++)
3478            if (d->data[pos+i] != latin[i])
3479                return false;
3480    } else {
3481        for (int i = 0; i < slen; i++)
3482            if (foldCase(d->data[pos+i]) != foldCase((ushort)latin[i]))
3483                return false;
3484    }
3485    return true;
3486}
3487
3488/*!
3489  Returns true if the string ends with \a c; otherwise returns
3490  false.
3491
3492  \overload endsWith()
3493 */
3494bool QString::endsWith(const QChar &c, Qt::CaseSensitivity cs) const
3495{
3496    return d->size
3497           && (cs == Qt::CaseSensitive
3498               ? d->data[d->size - 1] == c
3499               : foldCase(d->data[d->size - 1]) == foldCase(c.unicode()));
3500}
3501
3502/*! \fn const char *QString::ascii() const
3503    \nonreentrant
3504
3505    Use toAscii() instead.
3506*/
3507
3508/*! \fn const char *QString::latin1() const
3509    \nonreentrant
3510
3511    Use toLatin1() instead.
3512*/
3513
3514/*! \fn const char *QString::utf8() const
3515    \nonreentrant
3516
3517    Use toUtf8() instead.
3518*/
3519
3520/*! \fn const char *QString::local8Bit() const
3521    \nonreentrant
3522
3523    Use toLocal8Bit() instead.
3524*/
3525
3526static QByteArray toLatin1_helper(const QChar *data, int length)
3527{
3528    QByteArray ba;
3529    if (length) {
3530        ba.resize(length);
3531        const ushort *src = reinterpret_cast<const ushort *>(data);
3532        uchar *dst = (uchar*) ba.data();
3533#if defined(QT_ALWAYS_HAVE_SSE2)
3534        if (length >= 16) {
3535            const int chunkCount = length >> 4; // divided by 16
3536            const __m128i questionMark = _mm_set1_epi16('?');
3537            // SSE has no compare instruction for unsigned comparison.
3538            // The variables must be shiffted + 0x8000 to be compared
3539            const __m128i signedBitOffset = _mm_set1_epi16(0x8000);
3540            const __m128i thresholdMask = _mm_set1_epi16(0xff + 0x8000);
3541            for (int i = 0; i < chunkCount; ++i) {
3542                __m128i chunk1 = _mm_loadu_si128((__m128i*)src); // load
3543                src += 8;
3544                {
3545                    // each 16 bit is equal to 0xFF if the source is outside latin 1 (>0xff)
3546                    const __m128i signedChunk = _mm_add_epi16(chunk1, signedBitOffset);
3547                    const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask);
3548
3549                    // offLimitQuestionMark contains '?' for each 16 bits that was off-limit
3550                    // the 16 bits that were correct contains zeros
3551                    const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark);
3552
3553                    // correctBytes contains the bytes that were in limit
3554                    // the 16 bits that were off limits contains zeros
3555                    const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk1);
3556
3557                    // merge offLimitQuestionMark and correctBytes to have the result
3558                    chunk1 = _mm_or_si128(correctBytes, offLimitQuestionMark);
3559                }
3560
3561                __m128i chunk2 = _mm_loadu_si128((__m128i*)src); // load
3562                src += 8;
3563                {
3564                    // exactly the same operations as for the previous chunk of data
3565                    const __m128i signedChunk = _mm_add_epi16(chunk2, signedBitOffset);
3566                    const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask);
3567                    const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark);
3568                    const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk2);
3569                    chunk2 = _mm_or_si128(correctBytes, offLimitQuestionMark);
3570                }
3571
3572                // pack the two vector to 16 x 8bits elements
3573                const __m128i result = _mm_packus_epi16(chunk1, chunk2);
3574
3575                _mm_storeu_si128((__m128i*)dst, result); // store
3576                dst += 16;
3577            }
3578            length = length % 16;
3579        }
3580#elif defined(QT_ALWAYS_HAVE_NEON)
3581        // Refer to the documentation of the SSE2 implementation
3582        // this use eactly the same method as for SSE except:
3583        // 1) neon has unsigned comparison
3584        // 2) packing is done to 64 bits (8 x 8bits component).
3585        if (length >= 16) {
3586            const int chunkCount = length >> 3; // divided by 8
3587            const uint16x8_t questionMark = vdupq_n_u16('?'); // set
3588            const uint16x8_t thresholdMask = vdupq_n_u16(0xff); // set
3589            for (int i = 0; i < chunkCount; ++i) {
3590                uint16x8_t chunk = vld1q_u16((uint16_t *)src); // load
3591                src += 8;
3592
3593                const uint16x8_t offLimitMask = vcgtq_u16(chunk, thresholdMask); // chunk > thresholdMask
3594                const uint16x8_t offLimitQuestionMark = vandq_u16(offLimitMask, questionMark); // offLimitMask & questionMark
3595                const uint16x8_t correctBytes = vbicq_u16(chunk, offLimitMask); // !offLimitMask & chunk
3596                chunk = vorrq_u16(correctBytes, offLimitQuestionMark); // correctBytes | offLimitQuestionMark
3597                const uint8x8_t result = vmovn_u16(chunk); // narrowing move->packing
3598                vst1_u8(dst, result); // store
3599                dst += 8;
3600            }
3601            length = length % 8;
3602        }
3603#endif
3604        while (length--) {
3605            *dst++ = (*src>0xff) ? '?' : (uchar) *src;
3606            ++src;
3607        }
3608    }
3609    return ba;
3610}
3611
3612/*!
3613    Returns a Latin-1 representation of the string as a QByteArray.
3614
3615    The returned byte array is undefined if the string contains non-Latin1
3616    characters. Those characters may be suppressed or replaced with a
3617    question mark.
3618
3619    \sa fromLatin1(), toAscii(), toUtf8(), toLocal8Bit(), QTextCodec
3620*/
3621QByteArray QString::toLatin1() const
3622{
3623    return toLatin1_helper(unicode(), length());
3624}
3625
3626// ### Qt 5: Change the return type of at least toAscii(),
3627// toLatin1() and unicode() such that the use of Q_COMPILER_MANGLES_RETURN_TYPE
3628// isn't necessary in the header. See task 177402.
3629
3630/*!
3631    Returns an 8-bit representation of the string as a QByteArray.
3632
3633    If a codec has been set using QTextCodec::setCodecForCStrings(),
3634    it is used to convert Unicode to 8-bit char; otherwise this
3635    function does the same as toLatin1().
3636
3637    Note that, despite the name, this function does not necessarily return an US-ASCII
3638    (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
3639
3640    \sa fromAscii(), toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
3641*/
3642QByteArray QString::toAscii() const
3643{
3644#ifndef QT_NO_TEXTCODEC
3645    if (codecForCStrings)
3646        return codecForCStrings->fromUnicode(*this);
3647#endif // QT_NO_TEXTCODEC
3648    return toLatin1();
3649}
3650
3651#if !defined(Q_WS_MAC) && defined(Q_OS_UNIX) && !defined(Q_OS_OS2)
3652static QByteArray toLocal8Bit_helper(const QChar *data, int length)
3653{
3654#ifndef QT_NO_TEXTCODEC
3655    if (QTextCodec::codecForLocale())
3656        return QTextCodec::codecForLocale()->fromUnicode(data, length);
3657#endif // QT_NO_TEXTCODEC
3658    return toLatin1_helper(data, length);
3659}
3660#endif
3661
3662/*!
3663    Returns the local 8-bit representation of the string as a
3664    QByteArray. The returned byte array is undefined if the string
3665    contains characters not supported by the local 8-bit encoding.
3666
3667    QTextCodec::codecForLocale() is used to perform the conversion from
3668    Unicode. If the locale encoding could not be determined, this function
3669    does the same as toLatin1().
3670
3671    If this string contains any characters that cannot be encoded in the
3672    locale, the returned byte array is undefined. Those characters may be
3673    suppressed or replaced by another.
3674
3675    \sa fromLocal8Bit(), toAscii(), toLatin1(), toUtf8(), QTextCodec
3676*/
3677QByteArray QString::toLocal8Bit() const
3678{
3679#ifndef QT_NO_TEXTCODEC
3680    if (QTextCodec::codecForLocale())
3681        return QTextCodec::codecForLocale()->fromUnicode(*this);
3682#endif // QT_NO_TEXTCODEC
3683    return toLatin1();
3684}
3685
3686/*!
3687    Returns a UTF-8 representation of the string as a QByteArray.
3688
3689    UTF-8 is a Unicode codec and can represent all characters in a Unicode
3690    string like QString.
3691
3692    However, in the Unicode range, there are certain codepoints that are not
3693    considered characters. The Unicode standard reserves the last two
3694    codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
3695    U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF,
3696    inclusive, as non-characters. If any of those appear in the string, they
3697    may be discarded and will not appear in the UTF-8 representation, or they
3698    may be replaced by one or more replacement characters.
3699
3700    \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
3701*/
3702QByteArray QString::toUtf8() const
3703{
3704    if (isNull())
3705        return QByteArray();
3706
3707    return QUtf8::convertFromUnicode(constData(), length(), 0);
3708}
3709
3710/*!
3711    \since 4.2
3712
3713    Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
3714
3715    UCS-4 is a Unicode codec and is lossless. All characters from this string
3716    can be encoded in UCS-4. The vector is not null terminated.
3717
3718    \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
3719*/
3720QVector<uint> QString::toUcs4() const
3721{
3722    QVector<uint> v(length());
3723    uint *a = v.data();
3724    const unsigned short *uc = utf16();
3725    for (int i = 0; i < length(); ++i) {
3726        uint u = uc[i];
3727        if (QChar(u).isHighSurrogate() && i < length()-1) {
3728            ushort low = uc[i+1];
3729            if (QChar(low).isLowSurrogate()) {
3730                ++i;
3731                u = QChar::surrogateToUcs4(u, low);
3732            }
3733        }
3734        *a = u;
3735        ++a;
3736    }
3737    v.resize(a - v.data());
3738    return v;
3739}
3740
3741QString::Data *QString::fromLatin1_helper(const char *str, int size)
3742{
3743    Data *d;
3744    if (!str) {
3745        d = &shared_null;
3746        d->ref.ref();
3747    } else if (size == 0 || (!*str && size < 0)) {
3748        d = &shared_empty;
3749        d->ref.ref();
3750    } else {
3751        if (size < 0)
3752            size = qstrlen(str);
3753        d = static_cast<Data *>(qMalloc(sizeof(Data) + size * sizeof(QChar)));
3754        Q_CHECK_PTR(d);
3755        d->ref = 1;
3756        d->alloc = d->size = size;
3757        d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
3758        d->data = d->array;
3759        d->array[size] = '\0';
3760        ushort *dst = d->data;
3761        /* SIMD:
3762         * Unpacking with SSE has been shown to improve performance on recent CPUs
3763         * The same method gives no improvement with NEON.
3764         */
3765#if defined(QT_ALWAYS_HAVE_SSE2)
3766        if (size >= 16) {
3767            int chunkCount = size >> 4; // divided by 16
3768            const __m128i nullMask = _mm_set1_epi32(0);
3769            for (int i = 0; i < chunkCount; ++i) {
3770                const __m128i chunk = _mm_loadu_si128((__m128i*)str); // load
3771                str += 16;
3772
3773                // unpack the first 8 bytes, padding with zeros
3774                const __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullMask);
3775                _mm_storeu_si128((__m128i*)dst, firstHalf); // store
3776                dst += 8;
3777
3778                // unpack the last 8 bytes, padding with zeros
3779                const __m128i secondHalf = _mm_unpackhi_epi8 (chunk, nullMask);
3780                _mm_storeu_si128((__m128i*)dst, secondHalf); // store
3781                dst += 8;
3782            }
3783            size = size % 16;
3784        }
3785#endif
3786        while (size--)
3787            *dst++ = (uchar)*str++;
3788    }
3789    return d;
3790}
3791
3792QString::Data *QString::fromAscii_helper(const char *str, int size)
3793{
3794#ifndef QT_NO_TEXTCODEC
3795    if (codecForCStrings) {
3796        Data *d;
3797        if (!str) {
3798            d = &shared_null;
3799            d->ref.ref();
3800        } else if (size == 0 || (!*str && size < 0)) {
3801            d = &shared_empty;
3802            d->ref.ref();
3803        } else {
3804            if (size < 0)
3805                size = qstrlen(str);
3806            QString s = codecForCStrings->toUnicode(str, size);
3807            d = s.d;
3808            d->ref.ref();
3809        }
3810        return d;
3811    }
3812#endif
3813    return fromLatin1_helper(str, size);
3814}
3815
3816/*!
3817    Returns a QString initialized with the first \a size characters
3818    of the Latin-1 string \a str.
3819
3820    If \a size is -1 (default), it is taken to be qstrlen(\a
3821    str).
3822
3823    \sa toLatin1(), fromAscii(), fromUtf8(), fromLocal8Bit()
3824*/
3825QString QString::fromLatin1(const char *str, int size)
3826{
3827    return QString(fromLatin1_helper(str, size), 0);
3828}
3829
3830
3831#ifdef QT3_SUPPORT
3832
3833/*!
3834  \internal
3835*/
3836const char *QString::ascii_helper() const
3837{
3838    if (!asciiCache)
3839        asciiCache = new QHash<void *, QByteArray>();
3840
3841    d->asciiCache = true;
3842    QByteArray ascii = toAscii();
3843    QByteArray old = asciiCache->value(d);
3844    if (old == ascii)
3845        return old.constData();
3846    asciiCache->insert(d, ascii);
3847    return ascii.constData();
3848}
3849
3850/*!
3851  \internal
3852*/
3853const char *QString::latin1_helper() const
3854{
3855    if (!asciiCache)
3856        asciiCache = new QHash<void *, QByteArray>();
3857
3858    d->asciiCache = true;
3859    QByteArray ascii = toLatin1();
3860    QByteArray old = asciiCache->value(d);
3861    if (old == ascii)
3862        return old.constData();
3863    asciiCache->insert(d, ascii);
3864    return ascii.constData();
3865}
3866
3867#endif
3868
3869/*!
3870    Returns a QString initialized with the first \a size characters
3871    of the 8-bit string \a str.
3872
3873    If \a size is -1 (default), it is taken to be qstrlen(\a
3874    str).
3875
3876    QTextCodec::codecForLocale() is used to perform the conversion
3877    from Unicode.
3878
3879    \sa toLocal8Bit(), fromAscii(), fromLatin1(), fromUtf8()
3880*/
3881QString QString::fromLocal8Bit(const char *str, int size)
3882{
3883    if (!str)
3884        return QString();
3885    if (size == 0 || (!*str && size < 0))
3886        return QLatin1String("");
3887#if !defined(QT_NO_TEXTCODEC)
3888    if (size < 0)
3889        size = qstrlen(str);
3890    QTextCodec *codec = QTextCodec::codecForLocale();
3891    if (codec)
3892        return codec->toUnicode(str, size);
3893#endif // !QT_NO_TEXTCODEC
3894    return fromLatin1(str, size);
3895}
3896
3897/*!
3898    Returns a QString initialized with the first \a size characters
3899    from the string \a str.
3900
3901    If \a size is -1 (default), it is taken to be qstrlen(\a
3902    str).
3903
3904    Note that, despite the name, this function actually uses the codec
3905    defined by QTextCodec::setCodecForCStrings() to convert \a str to
3906    Unicode. Depending on the codec, it may not accept valid US-ASCII (ANSI
3907    X3.4-1986) input. If no codec has been set, this function does the same
3908    as fromLatin1().
3909
3910    \sa toAscii(), fromLatin1(), fromUtf8(), fromLocal8Bit()
3911*/
3912QString QString::fromAscii(const char *str, int size)
3913{
3914    return QString(fromAscii_helper(str, size), 0);
3915}
3916
3917/*!
3918    Returns a QString initialized with the first \a size bytes
3919    of the UTF-8 string \a str.
3920
3921    If \a size is -1 (default), it is taken to be qstrlen(\a
3922    str).
3923
3924    UTF-8 is a Unicode codec and can represent all characters in a Unicode
3925    string like QString. However, invalid sequences are possible with UTF-8
3926    and, if any such are found, they will be replaced with one or more
3927    "replacement characters", or suppressed. These include non-Unicode
3928    sequences, non-characters, overlong sequences or surrogate codepoints
3929    encoded into UTF-8.
3930
3931    Non-characters are codepoints that the Unicode standard reserves and must
3932    not be used in text interchange. They are the last two codepoints in each
3933    Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well
3934    as 16 codepoints in the range U+FDD0..U+FDDF, inclusive.
3935
3936    \sa toUtf8(), fromAscii(), fromLatin1(), fromLocal8Bit()
3937*/
3938QString QString::fromUtf8(const char *str, int size)
3939{
3940    if (!str)
3941        return QString();
3942    if (size < 0)
3943        size = qstrlen(str);
3944
3945    return QUtf8::convertToUnicode(str, size, 0);
3946}
3947
3948/*!
3949    Returns a QString initialized with the first \a size characters
3950    of the Unicode string \a unicode (ISO-10646-UTF-16 encoded).
3951
3952    If \a size is -1 (default), \a unicode must be terminated
3953    with a 0.
3954
3955    This function checks for a Byte Order Mark (BOM). If it is missing,
3956    host byte order is assumed.
3957
3958    This function is slow compared to the other Unicode conversions.
3959    Use QString(const QChar *, int) or QString(const QChar *) if possible.
3960
3961    QString makes a deep copy of the Unicode data.
3962
3963    \sa utf16(), setUtf16()
3964*/
3965QString QString::fromUtf16(const ushort *unicode, int size)
3966{
3967    if (!unicode)
3968        return QString();
3969    if (size < 0) {
3970        size = 0;
3971        while (unicode[size] != 0)
3972            ++size;
3973    }
3974    return QUtf16::convertToUnicode((const char *)unicode, size*2, 0);
3975}
3976
3977
3978/*!
3979    \since 4.2
3980
3981    Returns a QString initialized with the first \a size characters
3982    of the Unicode string \a unicode (ISO-10646-UCS-4 encoded).
3983
3984    If \a size is -1 (default), \a unicode must be terminated
3985    with a 0.
3986
3987    \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray()
3988*/
3989QString QString::fromUcs4(const uint *unicode, int size)
3990{
3991    if (!unicode)
3992        return QString();
3993    if (size < 0) {
3994        size = 0;
3995        while (unicode[size] != 0)
3996            ++size;
3997    }
3998    return QUtf32::convertToUnicode((const char *)unicode, size*4, 0);
3999}
4000
4001/*!
4002    Resizes the string to \a size characters and copies \a unicode
4003    into the string.
4004
4005    If \a unicode is 0, nothing is copied, but the string is still
4006    resized to \a size.
4007
4008    \sa unicode(), setUtf16()
4009*/
4010QString& QString::setUnicode(const QChar *unicode, int size)
4011{
4012     resize(size);
4013     if (unicode && size)
4014         memcpy(d->data, unicode, size * sizeof(QChar));
4015     return *this;
4016}
4017
4018/*!
4019    \fn QString &QString::setUtf16(const ushort *unicode, int size)
4020
4021    Resizes the string to \a size characters and copies \a unicode
4022    into the string.
4023
4024    If \a unicode is 0, nothing is copied, but the string is still
4025    resized to \a size.
4026
4027    Note that unlike fromUtf16(), this function does not consider BOMs and
4028    possibly differing byte ordering.
4029
4030    \sa utf16(), setUnicode()
4031*/
4032
4033/*!
4034    Returns a string that has whitespace removed from the start
4035    and the end, and that has each sequence of internal whitespace
4036    replaced with a single space.
4037
4038    Whitespace means any character for which QChar::isSpace() returns
4039    true. This includes the ASCII characters '\\t', '\\n', '\\v',
4040    '\\f', '\\r', and ' '.
4041
4042    Example:
4043
4044    \snippet doc/src/snippets/qstring/main.cpp 57
4045
4046    \sa trimmed()
4047*/
4048QString QString::simplified() const
4049{
4050    if (d->size == 0)
4051        return *this;
4052
4053    const QChar * const start = reinterpret_cast<QChar *>(d->data);
4054    const QChar *from = start;
4055    const QChar *fromEnd = start + d->size;
4056    forever {
4057        QChar ch = *from;
4058        if (!ch.isSpace())
4059            break;
4060        if (++from == fromEnd) {
4061            // All-whitespace string
4062            shared_empty.ref.ref();
4063            return QString(&shared_empty, 0);
4064        }
4065    }
4066    // This loop needs no underflow check, as we already determined that
4067    // the string contains non-whitespace. If the string has exactly one
4068    // non-whitespace, it will be checked twice - we can live with that.
4069    while (fromEnd[-1].isSpace())
4070        fromEnd--;
4071    // The rest of the function depends on the fact that we already know
4072    // that the last character in the source is no whitespace.
4073    const QChar *copyFrom = from;
4074    int copyCount;
4075    forever {
4076        if (++from == fromEnd) {
4077            // Only leading and/or trailing whitespace, if any at all
4078            return mid(copyFrom - start, from - copyFrom);
4079        }
4080        QChar ch = *from;
4081        if (!ch.isSpace())
4082            continue;
4083        if (ch != QLatin1Char(' ')) {
4084            copyCount = from - copyFrom;
4085            break;
4086        }
4087        ch = *++from;
4088        if (ch.isSpace()) {
4089            copyCount = from - copyFrom - 1;
4090            break;
4091        }
4092    }
4093    // 'from' now points at the non-trailing whitespace which made the
4094    // string not simplified in the first place. 'copyCount' is the number
4095    // of already simplified characters - at least one, obviously -
4096    // without a trailing space.
4097    QString result((fromEnd - from) + copyCount, Qt::Uninitialized);
4098    QChar *to = reinterpret_cast<QChar *>(result.d->data);
4099    ::memcpy(to, copyFrom, copyCount * 2);
4100    to += copyCount;
4101    fromEnd--;
4102    QChar ch;
4103    forever {
4104        *to++ = QLatin1Char(' ');
4105        do {
4106            ch = *++from;
4107        } while (ch.isSpace());
4108        if (from == fromEnd)
4109            break;
4110        do {
4111            *to++ = ch;
4112            ch = *++from;
4113            if (from == fromEnd)
4114                goto done;
4115        } while (!ch.isSpace());
4116    }
4117  done:
4118    *to++ = ch;
4119    result.truncate(to - reinterpret_cast<QChar *>(result.d->data));
4120    return result;
4121}
4122
4123/*!
4124    Returns a string that has whitespace removed from the start and
4125    the end.
4126
4127    Whitespace means any character for which QChar::isSpace() returns
4128    true. This includes the ASCII characters '\\t', '\\n', '\\v',
4129    '\\f', '\\r', and ' '.
4130
4131    Example:
4132
4133    \snippet doc/src/snippets/qstring/main.cpp 82
4134
4135    Unlike simplified(), trimmed() leaves internal whitespace alone.
4136
4137    \sa simplified()
4138*/
4139QString QString::trimmed() const
4140{
4141    if (d->size == 0)
4142        return *this;
4143    const QChar *s = (const QChar*)d->data;
4144    if (!s->isSpace() && !s[d->size-1].isSpace())
4145        return *this;
4146    int start = 0;
4147    int end = d->size - 1;
4148    while (start<=end && s[start].isSpace())  // skip white space from start
4149        start++;
4150    if (start <= end) {                          // only white space
4151        while (end && s[end].isSpace())           // skip white space from end
4152            end--;
4153    }
4154    int l = end - start + 1;
4155    if (l <= 0) {
4156        shared_empty.ref.ref();
4157        return QString(&shared_empty, 0);
4158    }
4159    return QString(s + start, l);
4160}
4161
4162/*! \fn const QChar QString::at(int position) const
4163
4164    Returns the character at the given index \a position in the
4165    string.
4166
4167    The \a position must be a valid index position in the string
4168    (i.e., 0 <= \a position < size()).
4169
4170    \sa operator[]()
4171*/
4172
4173/*!
4174    \fn QCharRef QString::operator[](int position)
4175
4176    Returns the character at the specified \a position in the string as a
4177    modifiable reference.
4178
4179    Example:
4180
4181    \snippet doc/src/snippets/qstring/main.cpp 85
4182
4183    The return value is of type QCharRef, a helper class for QString.
4184    When you get an object of type QCharRef, you can use it as if it
4185    were a QChar &. If you assign to it, the assignment will apply to
4186    the character in the QString from which you got the reference.
4187
4188    \sa at()
4189*/
4190
4191/*!
4192    \fn const QChar QString::operator[](int position) const
4193
4194    \overload operator[]()
4195*/
4196
4197/*! \fn QCharRef QString::operator[](uint position)
4198
4199\overload operator[]()
4200
4201Returns the character at the specified \a position in the string as a
4202modifiable reference. Equivalent to \c at(position).
4203*/
4204
4205/*! \fn const QChar QString::operator[](uint position) const
4206
4207\overload operator[]()
4208*/
4209
4210/*!
4211    \fn void QString::truncate(int position)
4212
4213    Truncates the string at the given \a position index.
4214
4215    If the specified \a position index is beyond the end of the
4216    string, nothing happens.
4217
4218    Example:
4219
4220    \snippet doc/src/snippets/qstring/main.cpp 83
4221
4222    If \a position is negative, it is equivalent to passing zero.
4223
4224    \sa chop(), resize(), left()
4225*/
4226
4227void QString::truncate(int pos)
4228{
4229    if (pos < d->size)
4230        resize(pos);
4231}
4232
4233
4234/*!
4235    Removes \a n characters from the end of the string.
4236
4237    If \a n is greater than size(), the result is an empty string.
4238
4239    Example:
4240    \snippet doc/src/snippets/qstring/main.cpp 15
4241
4242    If you want to remove characters from the \e beginning of the
4243    string, use remove() instead.
4244
4245    \sa truncate(), resize(), remove()
4246*/
4247void QString::chop(int n)
4248{
4249    if (n > 0)
4250        resize(d->size - n);
4251}
4252
4253/*!
4254    Sets every character in the string to character \a ch. If \a size
4255    is different from -1 (default), the string is resized to \a
4256    size beforehand.
4257
4258    Example:
4259
4260    \snippet doc/src/snippets/qstring/main.cpp 21
4261
4262    \sa resize()
4263*/
4264
4265QString& QString::fill(QChar ch, int size)
4266{
4267    resize(size < 0 ? d->size : size);
4268    if (d->size) {
4269        QChar *i = (QChar*)d->data + d->size;
4270        QChar *b = (QChar*)d->data;
4271        while (i != b)
4272           *--i = ch;
4273    }
4274    return *this;
4275}
4276
4277/*!
4278    \fn int QString::length() const
4279
4280    Returns the number of characters in this string.  Equivalent to
4281    size().
4282
4283    \sa resize()
4284*/
4285
4286/*!
4287    \fn int QString::size() const
4288
4289    Returns the number of characters in this string.
4290
4291    The last character in the string is at position size() - 1. In
4292    addition, QString ensures that the character at position size()
4293    is always '\\0', so that you can use the return value of data()
4294    and constData() as arguments to functions that expect
4295    '\\0'-terminated strings.
4296
4297    Example:
4298
4299    \snippet doc/src/snippets/qstring/main.cpp 58
4300
4301    \sa isEmpty(), resize()
4302*/
4303
4304/*! \fn bool QString::isNull() const
4305
4306    Returns true if this string is null; otherwise returns false.
4307
4308    Example:
4309
4310    \snippet doc/src/snippets/qstring/main.cpp 28
4311
4312    Qt makes a distinction between null strings and empty strings for
4313    historical reasons. For most applications, what matters is
4314    whether or not a string contains any data, and this can be
4315    determined using the isEmpty() function.
4316
4317    \sa isEmpty()
4318*/
4319
4320/*! \fn bool QString::isEmpty() const
4321
4322    Returns true if the string has no characters; otherwise returns
4323    false.
4324
4325    Example:
4326
4327    \snippet doc/src/snippets/qstring/main.cpp 27
4328
4329    \sa size()
4330*/
4331
4332/*! \fn QString &QString::operator+=(const QString &other)
4333
4334    Appends the string \a other onto the end of this string and
4335    returns a reference to this string.
4336
4337    Example:
4338
4339    \snippet doc/src/snippets/qstring/main.cpp 84
4340
4341    This operation is typically very fast (\l{constant time}),
4342    because QString preallocates extra space at the end of the string
4343    data so it can grow without reallocating the entire string each
4344    time.
4345
4346    \sa append(), prepend()
4347*/
4348
4349/*! \fn QString &QString::operator+=(const QLatin1String &str)
4350
4351    \overload operator+=()
4352
4353    Appends the Latin-1 string \a str to this string.
4354*/
4355
4356/*! \fn QString &QString::operator+=(const QByteArray &ba)
4357
4358    \overload operator+=()
4359
4360    Appends the byte array \a ba to this string. The byte array is converted
4361    to Unicode using the fromAscii() function. If any NUL characters ('\0')
4362    are embedded in the \a ba byte array, they will be included in the
4363    transformation.
4364
4365    You can disable this function by defining \c
4366    QT_NO_CAST_FROM_ASCII when you compile your applications. This
4367    can be useful if you want to ensure that all user-visible strings
4368    go through QObject::tr(), for example.
4369*/
4370
4371/*! \fn QString &QString::operator+=(const char *str)
4372
4373    \overload operator+=()
4374
4375    Appends the string \a str to this string. The const char pointer
4376    is converted to Unicode using the fromAscii() function.
4377
4378    You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4379    when you compile your applications. This can be useful if you want
4380    to ensure that all user-visible strings go through QObject::tr(),
4381    for example.
4382*/
4383
4384/*! \fn QString &QString::operator+=(const QStringRef &str)
4385
4386    \overload operator+=()
4387
4388    Appends the string section referenced by \a str to this string.
4389*/
4390
4391/*! \fn QString &QString::operator+=(char ch)
4392
4393    \overload operator+=()
4394
4395    Appends the character \a ch to this string. The character is
4396    converted to Unicode using the fromAscii() function.
4397
4398    You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4399    when you compile your applications. This can be useful if you want
4400    to ensure that all user-visible strings go through QObject::tr(),
4401    for example.
4402*/
4403
4404/*! \fn QString &QString::operator+=(QChar ch)
4405
4406    \overload operator+=()
4407
4408    Appends the character \a ch to the string.
4409*/
4410
4411/*! \fn QString &QString::operator+=(QChar::SpecialCharacter c)
4412
4413    \overload operator+=()
4414
4415    \internal
4416*/
4417
4418/*!
4419    \fn bool operator==(const char *s1, const QString &s2)
4420
4421    \overload  operator==()
4422    \relates QString
4423
4424    Returns true if \a s1 is equal to \a s2; otherwise returns false.
4425    Note that no string is equal to \a s1 being 0.
4426
4427    Equivalent to \c {s1 != 0 && compare(s1, s2) == 0}.
4428
4429    \sa QString::compare()
4430*/
4431
4432/*!
4433    \fn bool operator!=(const char *s1, const QString &s2)
4434    \relates QString
4435
4436    Returns true if \a s1 is not equal to \a s2; otherwise returns
4437    false.
4438
4439    For \a s1 != 0, this is equivalent to \c {compare(} \a s1, \a s2
4440    \c {) != 0}. Note that no string is equal to \a s1 being 0.
4441
4442    \sa QString::compare()
4443*/
4444
4445/*!
4446    \fn bool operator<(const char *s1, const QString &s2)
4447    \relates QString
4448
4449    Returns true if \a s1 is lexically less than \a s2; otherwise
4450    returns false.  For \a s1 != 0, this is equivalent to \c
4451    {compare(s1, s2) < 0}.
4452
4453    The comparison is based exclusively on the numeric Unicode values
4454    of the characters and is very fast, but is not what a human would
4455    expect. Consider sorting user-interface strings using the
4456    QString::localeAwareCompare() function.
4457
4458    \sa QString::compare()
4459*/
4460
4461/*!
4462    \fn bool operator<=(const char *s1, const QString &s2)
4463    \relates QString
4464
4465    Returns true if \a s1 is lexically less than or equal to \a s2;
4466    otherwise returns false.  For \a s1 != 0, this is equivalent to \c
4467    {compare(s1, s2) <= 0}.
4468
4469    The comparison is based exclusively on the numeric Unicode values
4470    of the characters and is very fast, but is not what a human would
4471    expect. Consider sorting user-interface strings with
4472    QString::localeAwareCompare().
4473
4474    \sa QString::compare()
4475*/
4476
4477/*!
4478    \fn bool operator>(const char *s1, const QString &s2)
4479    \relates QString
4480
4481    Returns true if \a s1 is lexically greater than \a s2; otherwise
4482    returns false.  Equivalent to \c {compare(s1, s2) > 0}.
4483
4484    The comparison is based exclusively on the numeric Unicode values
4485    of the characters and is very fast, but is not what a human would
4486    expect. Consider sorting user-interface strings using the
4487    QString::localeAwareCompare() function.
4488
4489    \sa QString::compare()
4490*/
4491
4492/*!
4493    \fn bool operator>=(const char *s1, const QString &s2)
4494    \relates QString
4495
4496    Returns true if \a s1 is lexically greater than or equal to \a s2;
4497    otherwise returns false.  For \a s1 != 0, this is equivalent to \c
4498    {compare(s1, s2) >= 0}.
4499
4500    The comparison is based exclusively on the numeric Unicode values
4501    of the characters and is very fast, but is not what a human would
4502    expect. Consider sorting user-interface strings using the
4503    QString::localeAwareCompare() function.
4504*/
4505
4506/*!
4507    \fn const QString operator+(const QString &s1, const QString &s2)
4508    \relates QString
4509
4510    Returns a string which is the result of concatenating \a s1 and \a
4511    s2.
4512*/
4513
4514/*!
4515    \fn const QString operator+(const QString &s1, const char *s2)
4516    \relates QString
4517
4518    Returns a string which is the result of concatenating \a s1 and \a
4519    s2 (\a s2 is converted to Unicode using the QString::fromAscii()
4520    function).
4521
4522    \sa QString::fromAscii()
4523*/
4524
4525/*!
4526    \fn const QString operator+(const char *s1, const QString &s2)
4527    \relates QString
4528
4529    Returns a string which is the result of concatenating \a s1 and \a
4530    s2 (\a s1 is converted to Unicode using the QString::fromAscii()
4531    function).
4532
4533    \sa QString::fromAscii()
4534*/
4535
4536/*!
4537    \fn const QString operator+(const QString &s, char ch)
4538    \relates QString
4539
4540    Returns a string which is the result of concatenating the string
4541    \a s and the character \a ch.
4542*/
4543
4544/*!
4545    \fn const QString operator+(char ch, const QString &s)
4546    \relates QString
4547
4548    Returns a string which is the result of concatenating the
4549    character \a ch and the string \a s.
4550*/
4551
4552/*!
4553    \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs)
4554    \since 4.2
4555
4556    Compares \a s1 with \a s2 and returns an integer less than, equal
4557    to, or greater than zero if \a s1 is less than, equal to, or
4558    greater than \a s2.
4559
4560    If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
4561    otherwise the comparison is case insensitive.
4562
4563    Case sensitive comparison is based exclusively on the numeric
4564    Unicode values of the characters and is very fast, but is not what
4565    a human would expect.  Consider sorting user-visible strings with
4566    localeAwareCompare().
4567
4568    \snippet doc/src/snippets/qstring/main.cpp 16
4569
4570    \sa operator==(), operator<(), operator>()
4571*/
4572
4573/*!
4574    \fn int QString::compare(const QString & s1, const QString & s2)
4575
4576    \overload compare()
4577
4578    Performs a case sensitive compare of \a s1 and \a s2.
4579*/
4580
4581/*!
4582    \fn int QString::compare(const QString &s1, const QLatin1String &s2, Qt::CaseSensitivity cs)
4583    \since 4.2
4584    \overload compare()
4585
4586    Performs a comparison of \a s1 and \a s2, using the case
4587    sensitivity setting \a cs.
4588*/
4589
4590/*!
4591    \fn int QString::compare(const QLatin1String &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4592
4593    \since 4.2
4594    \overload compare()
4595
4596    Performs a comparison of \a s1 and \a s2, using the case
4597    sensitivity setting \a cs.
4598*/
4599
4600/*!
4601    \overload compare()
4602
4603    Lexically compares this string with the \a other string and
4604    returns an integer less than, equal to, or greater than zero if
4605    this string is less than, equal to, or greater than the other
4606    string.
4607
4608    Equivalent to \c {compare(*this, other)}.
4609*/
4610int QString::compare(const QString &other) const
4611{
4612    return ucstrcmp(constData(), length(), other.constData(), other.length());
4613}
4614
4615/*!
4616    \overload compare()
4617    \since 4.2
4618
4619    Same as compare(*this, \a other, \a cs).
4620*/
4621int QString::compare(const QString &other, Qt::CaseSensitivity cs) const
4622{
4623    if (cs == Qt::CaseSensitive)
4624        return ucstrcmp(constData(), length(), other.constData(), other.length());
4625    return ucstricmp(d->data, d->data + d->size, other.d->data, other.d->data + other.d->size);
4626}
4627
4628/*!
4629    \internal
4630    \since 4.5
4631*/
4632int QString::compare_helper(const QChar *data1, int length1, const QChar *data2, int length2,
4633                            Qt::CaseSensitivity cs)
4634{
4635    if (cs == Qt::CaseSensitive)
4636        return ucstrcmp(data1, length1, data2, length2);
4637    register const ushort *s1 = reinterpret_cast<const ushort *>(data1);
4638    register const ushort *s2 = reinterpret_cast<const ushort *>(data2);
4639    return ucstricmp(s1, s1 + length1, s2, s2 + length2);
4640}
4641
4642/*!
4643    \overload compare()
4644    \since 4.2
4645
4646    Same as compare(*this, \a other, \a cs).
4647*/
4648int QString::compare(const QLatin1String &other, Qt::CaseSensitivity cs) const
4649{
4650    return compare_helper(unicode(), length(), other, cs);
4651}
4652
4653/*!
4654  \fn int QString::compare(const QStringRef &ref, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4655  \overload compare()
4656
4657  Compares the string reference, \a ref, with the string and returns
4658  an integer less than, equal to, or greater than zero if the string
4659  is less than, equal to, or greater than \a ref.
4660*/
4661
4662/*!
4663  \fn int QString::compare(const QString &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4664  \overload compare()
4665*/
4666
4667/*!
4668    \internal
4669    \since 4.5
4670*/
4671int QString::compare_helper(const QChar *data1, int length1, QLatin1String s2,
4672                            Qt::CaseSensitivity cs)
4673{
4674    const ushort *uc = reinterpret_cast<const ushort *>(data1);
4675    const ushort *e = uc + length1;
4676    const uchar *c = (uchar *)s2.latin1();
4677
4678    if (!c)
4679        return length1;
4680
4681    if (cs == Qt::CaseSensitive) {
4682        while (uc < e && *c && *uc == *c)
4683            uc++, c++;
4684
4685        if (uc == e)
4686            return -*c;
4687
4688        return *uc - *c;
4689    } else {
4690        return ucstricmp(uc, e, c);
4691    }
4692}
4693
4694/*!
4695    \fn int QString::localeAwareCompare(const QString & s1, const QString & s2)
4696
4697    Compares \a s1 with \a s2 and returns an integer less than, equal
4698    to, or greater than zero if \a s1 is less than, equal to, or
4699    greater than \a s2.
4700
4701    The comparison is performed in a locale- and also
4702    platform-dependent manner. Use this function to present sorted
4703    lists of strings to the user.
4704
4705    On Mac OS X since Qt 4.3, this function compares according the
4706    "Order for sorted lists" setting in the International prefereces panel.
4707
4708    \sa compare(), QTextCodec::locale()
4709*/
4710
4711/*!
4712    \fn int QString::localeAwareCompare(const QStringRef &other) const
4713    \since 4.5
4714    \overload localeAwareCompare()
4715
4716    Compares this string with the \a other string and returns an
4717    integer less than, equal to, or greater than zero if this string
4718    is less than, equal to, or greater than the \a other string.
4719
4720    The comparison is performed in a locale- and also
4721    platform-dependent manner. Use this function to present sorted
4722    lists of strings to the user.
4723
4724    Same as \c {localeAwareCompare(*this, other)}.
4725*/
4726
4727/*!
4728    \fn int QString::localeAwareCompare(const QString &s1, const QStringRef &s2)
4729    \since 4.5
4730    \overload localeAwareCompare()
4731
4732    Compares \a s1 with \a s2 and returns an integer less than, equal
4733    to, or greater than zero if \a s1 is less than, equal to, or
4734    greater than \a s2.
4735
4736    The comparison is performed in a locale- and also
4737    platform-dependent manner. Use this function to present sorted
4738    lists of strings to the user.
4739*/
4740
4741
4742#if !defined(CSTR_LESS_THAN)
4743#define CSTR_LESS_THAN    1
4744#define CSTR_EQUAL        2
4745#define CSTR_GREATER_THAN 3
4746#endif
4747
4748/*!
4749    \overload localeAwareCompare()
4750
4751    Compares this string with the \a other string and returns an
4752    integer less than, equal to, or greater than zero if this string
4753    is less than, equal to, or greater than the \a other string.
4754
4755    The comparison is performed in a locale- and also
4756    platform-dependent manner. Use this function to present sorted
4757    lists of strings to the user.
4758
4759    Same as \c {localeAwareCompare(*this, other)}.
4760*/
4761int QString::localeAwareCompare(const QString &other) const
4762{
4763    return localeAwareCompare_helper(constData(), length(), other.constData(), other.length());
4764}
4765
4766#if defined(Q_OS_WIN32) || defined(Q_OS_WINCE)
4767QT_END_NAMESPACE
4768#include "qt_windows.h"
4769QT_BEGIN_NAMESPACE
4770#endif
4771
4772/*!
4773    \internal
4774    \since 4.5
4775*/
4776int QString::localeAwareCompare_helper(const QChar *data1, int length1,
4777                                       const QChar *data2, int length2)
4778{
4779    // do the right thing for null and empty
4780    if (length1 == 0 || length2 == 0)
4781        return ucstrcmp(data1, length1, data2, length2);
4782
4783#if defined(Q_OS_WIN32) || defined(Q_OS_WINCE)
4784    int res = CompareString(GetUserDefaultLCID(), 0, (wchar_t*)data1, length1, (wchar_t*)data2, length2);
4785
4786    switch (res) {
4787    case CSTR_LESS_THAN:
4788        return -1;
4789    case CSTR_GREATER_THAN:
4790        return 1;
4791    default:
4792        return 0;
4793    }
4794#elif defined(Q_OS_OS2)
4795    extern Q_CORE_EXPORT QString qt_system_locale_name(); // qlocale.cpp
4796    // UniCreateLocaleObject("") creates an "en_US" locale when LANG is not set
4797    // but we want to get the system locale so always use the exact name as
4798    // returned by qt_system_locale_name() (it also takes LANG into account)
4799#if !defined(QT_NO_THREAD)
4800    static QAtomicPointer<void> localeObj;
4801    if (!localeObj) {
4802        LocaleObject lo = 0;
4803        UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
4804                              qt_system_locale_name().utf16(), &lo);
4805        if (!localeObj.testAndSetRelaxed(0, lo))
4806            UniFreeLocaleObject(lo); // we are too late
4807    }
4808#else
4809    static LocaleObject localeObj = 0;
4810    if (!localeObj)
4811        UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
4812                              qt_system_locale_name().utf16(), &localeObj);
4813#endif
4814    if (localeObj) {
4815        // note: we assume that data1 and data2 are zero-terminated (to avoid
4816        // creation of dumb deep copies) which is at least true for <= 4.7.x.
4817#if QT_VERSION < 0x040703
4818        return UniStrcoll(localeObj, (UniChar*)data1, (UniChar *)data2);
4819#else
4820# error "Check me!"
4821#endif
4822    } else {
4823        return ucstrcmp(data1, length1, data2, length2);
4824    }
4825#elif defined (Q_OS_MAC)
4826    // Use CFStringCompare for comparing strings on Mac. This makes Qt order
4827    // strings the same way as native applications do, and also respects
4828    // the "Order for sorted lists" setting in the International preferences
4829    // panel.
4830    const CFStringRef thisString =
4831        CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
4832            reinterpret_cast<const UniChar *>(data1), length1, kCFAllocatorNull);
4833    const CFStringRef otherString =
4834        CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
4835            reinterpret_cast<const UniChar *>(data2), length2, kCFAllocatorNull);
4836
4837    const int result = CFStringCompare(thisString, otherString, kCFCompareLocalized);
4838    CFRelease(thisString);
4839    CFRelease(otherString);
4840    return result;
4841#elif defined(Q_OS_SYMBIAN)
4842    TPtrC p1 = TPtrC16(reinterpret_cast<const TUint16 *>(data1), length1);
4843    TPtrC p2 = TPtrC16(reinterpret_cast<const TUint16 *>(data2), length2);
4844    return p1.CompareC(p2);
4845#elif defined(Q_OS_UNIX)
4846    // declared in <string.h>
4847    int delta = strcoll(toLocal8Bit_helper(data1, length1), toLocal8Bit_helper(data2, length2));
4848    if (delta == 0)
4849        delta = ucstrcmp(data1, length1, data2, length2);
4850    return delta;
4851#else
4852    return ucstrcmp(data1, length1, data2, length2);
4853#endif
4854}
4855
4856
4857/*!
4858    \fn const QChar *QString::unicode() const
4859
4860    Returns a '\\0'-terminated Unicode representation of the string.
4861    The result remains valid until the string is modified.
4862
4863    \sa utf16()
4864*/
4865
4866/*!
4867    \fn const ushort *QString::utf16() const
4868
4869    Returns the QString as a '\\0\'-terminated array of unsigned
4870    shorts. The result remains valid until the string is modified.
4871
4872    The returned string is in host byte order.
4873
4874    \sa unicode()
4875*/
4876
4877const ushort *QString::utf16() const
4878{
4879    if (d->data != d->array) {
4880        QString *that = const_cast<QString*>(this);
4881        that->realloc();   // ensure '\\0'-termination for ::fromRawData strings
4882        return that->d->data;
4883    }
4884    return d->array;
4885}
4886
4887/*!
4888    Returns a string of size \a width that contains this string
4889    padded by the \a fill character.
4890
4891    If \a truncate is false and the size() of the string is more than
4892    \a width, then the returned string is a copy of the string.
4893
4894    \snippet doc/src/snippets/qstring/main.cpp 32
4895
4896    If \a truncate is true and the size() of the string is more than
4897    \a width, then any characters in a copy of the string after
4898    position \a width are removed, and the copy is returned.
4899
4900    \snippet doc/src/snippets/qstring/main.cpp 33
4901
4902    \sa rightJustified()
4903*/
4904
4905QString QString::leftJustified(int width, QChar fill, bool truncate) const
4906{
4907    QString result;
4908    int len = length();
4909    int padlen = width - len;
4910    if (padlen > 0) {
4911        result.resize(len+padlen);
4912        if (len)
4913            memcpy(result.d->data, d->data, sizeof(QChar)*len);
4914        QChar *uc = (QChar*)result.d->data + len;
4915        while (padlen--)
4916           * uc++ = fill;
4917    } else {
4918        if (truncate)
4919            result = left(width);
4920        else
4921            result = *this;
4922    }
4923    return result;
4924}
4925
4926/*!
4927    Returns a string of size() \a width that contains the \a fill
4928    character followed by the string. For example:
4929
4930    \snippet doc/src/snippets/qstring/main.cpp 49
4931
4932    If \a truncate is false and the size() of the string is more than
4933    \a width, then the returned string is a copy of the string.
4934
4935    If \a truncate is true and the size() of the string is more than
4936    \a width, then the resulting string is truncated at position \a
4937    width.
4938
4939    \snippet doc/src/snippets/qstring/main.cpp 50
4940
4941    \sa leftJustified()
4942*/
4943
4944QString QString::rightJustified(int width, QChar fill, bool truncate) const
4945{
4946    QString result;
4947    int len = length();
4948    int padlen = width - len;
4949    if (padlen > 0) {
4950        result.resize(len+padlen);
4951        QChar *uc = (QChar*)result.d->data;
4952        while (padlen--)
4953           * uc++ = fill;
4954        if (len)
4955            memcpy(uc, d->data, sizeof(QChar)*len);
4956    } else {
4957        if (truncate)
4958            result = left(width);
4959        else
4960            result = *this;
4961    }
4962    return result;
4963}
4964
4965/*!
4966    Returns a lowercase copy of the string.
4967
4968    \snippet doc/src/snippets/qstring/main.cpp 75
4969
4970    \sa toUpper()
4971*/
4972
4973QString QString::toLower() const
4974{
4975    const ushort *p = d->data;
4976    if (!p)
4977        return *this;
4978    if (!d->size)
4979        return *this;
4980
4981    const ushort *e = d->data + d->size;
4982
4983    // this avoids one out of bounds check in the loop
4984    if (QChar(*p).isLowSurrogate())
4985        ++p;
4986
4987    while (p != e) {
4988        uint c = *p;
4989        if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4990            c = QChar::surrogateToUcs4(*(p - 1), c);
4991        const QUnicodeTables::Properties *prop = qGetProp(c);
4992        if (prop->lowerCaseDiff || prop->lowerCaseSpecial) {
4993            QString s(d->size, Qt::Uninitialized);
4994            memcpy(s.d->data, d->data, (p - d->data)*sizeof(ushort));
4995            ushort *pp = s.d->data + (p - d->data);
4996            while (p < e) {
4997                uint c = *p;
4998                if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4999                    c = QChar::surrogateToUcs4(*(p - 1), c);
5000                prop = qGetProp(c);
5001                if (prop->lowerCaseSpecial) {
5002                    int pos = pp - s.d->data;
5003                    s.resize(s.d->size + SPECIAL_CASE_MAX_LEN);
5004                    pp = s.d->data + pos;
5005                    const ushort *specialCase = specialCaseMap + prop->lowerCaseDiff;
5006                    while (*specialCase)
5007                        *pp++ = *specialCase++;
5008                } else {
5009                    *pp++ = *p + prop->lowerCaseDiff;
5010                }
5011                ++p;
5012            }
5013            s.truncate(pp - s.d->data);
5014            return s;
5015        }
5016        ++p;
5017    }
5018    return *this;
5019}
5020
5021/*!
5022    Returns the case folded equivalent of the string. For most Unicode
5023    characters this is the same as toLower().
5024*/
5025QString QString::toCaseFolded() const
5026{
5027    if (!d->size)
5028        return *this;
5029
5030    const ushort *p = d->data;
5031    if (!p)
5032        return *this;
5033
5034    const ushort *e = d->data + d->size;
5035
5036    uint last = 0;
5037    while (p < e) {
5038        ushort folded = foldCase(*p, last);
5039        if (folded != *p) {
5040            QString s(*this);
5041            s.detach();
5042            ushort *pp = s.d->data + (p - d->data);
5043            const ushort *ppe = s.d->data + s.d->size;
5044            last = pp > s.d->data ? *(pp - 1) : 0;
5045            while (pp < ppe) {
5046                *pp = foldCase(*pp, last);
5047                ++pp;
5048            }
5049            return s;
5050        }
5051        p++;
5052    }
5053    return *this;
5054}
5055
5056/*!
5057    Returns an uppercase copy of the string.
5058
5059    \snippet doc/src/snippets/qstring/main.cpp 81
5060
5061    \sa toLower()
5062*/
5063
5064QString QString::toUpper() const
5065{
5066    const ushort *p = d->data;
5067    if (!p)
5068        return *this;
5069    if (!d->size)
5070        return *this;
5071
5072    const ushort *e = d->data + d->size;
5073
5074    // this avoids one out of bounds check in the loop
5075    if (QChar(*p).isLowSurrogate())
5076        ++p;
5077
5078    while (p != e) {
5079        uint c = *p;
5080        if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
5081            c = QChar::surrogateToUcs4(*(p - 1), c);
5082        const QUnicodeTables::Properties *prop = qGetProp(c);
5083        if (prop->upperCaseDiff || prop->upperCaseSpecial) {
5084            QString s(d->size, Qt::Uninitialized);
5085            memcpy(s.d->data, d->data, (p - d->data)*sizeof(ushort));
5086            ushort *pp = s.d->data + (p - d->data);
5087            while (p < e) {
5088                uint c = *p;
5089                if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
5090                    c = QChar::surrogateToUcs4(*(p - 1), c);
5091                prop = qGetProp(c);
5092                if (prop->upperCaseSpecial) {
5093                    int pos = pp - s.d->data;
5094                    s.resize(s.d->size + SPECIAL_CASE_MAX_LEN);
5095                    pp = s.d->data + pos;
5096                    const ushort *specialCase = specialCaseMap + prop->upperCaseDiff;
5097                    while (*specialCase)
5098                        *pp++ = *specialCase++;
5099                } else {
5100                    *pp++ = *p + prop->upperCaseDiff;
5101                }
5102                ++p;
5103            }
5104            s.truncate(pp - s.d->data);
5105            return s;
5106        }
5107        ++p;
5108    }
5109    return *this;
5110}
5111
5112// ### Qt 5: Consider whether this function shouldn't be removed See task 202871.
5113/*!
5114    Safely builds a formatted string from the format string \a cformat
5115    and an arbitrary list of arguments.
5116
5117    The %lc escape sequence expects a unicode character of type ushort
5118    (as returned by QChar::unicode()). The %ls escape sequence expects
5119    a pointer to a zero-terminated array of unicode characters of type
5120    ushort (as returned by QString::utf16()).
5121
5122    \note This function expects a UTF-8 string for %s and Latin-1 for
5123    the format string.
5124
5125    The format string supports most of the conversion specifiers
5126    provided by printf() in the standard C++ library. It doesn't
5127    honor the length modifiers (e.g. \c h for \c short, \c ll for
5128    \c{long long}). If you need those, use the standard snprintf()
5129    function instead:
5130
5131    \snippet doc/src/snippets/qstring/main.cpp 63
5132
5133    \warning We do not recommend using QString::sprintf() in new Qt
5134    code. Instead, consider using QTextStream or arg(), both of
5135    which support Unicode strings seamlessly and are type-safe.
5136    Here's an example that uses QTextStream:
5137
5138    \snippet doc/src/snippets/qstring/main.cpp 64
5139
5140    For \l {QObject::tr()}{translations}, especially if the strings
5141    contains more than one escape sequence, you should consider using
5142    the arg() function instead. This allows the order of the
5143    replacements to be controlled by the translator.
5144
5145    \sa arg()
5146*/
5147
5148QString &QString::sprintf(const char *cformat, ...)
5149{
5150    va_list ap;
5151    va_start(ap, cformat);
5152    QString &s = vsprintf(cformat, ap);
5153    va_end(ap);
5154    return s;
5155}
5156
5157/*!
5158    Equivalent method to sprintf(), but takes a va_list \a ap
5159    instead a list of variable arguments. See the sprintf()
5160    documentation for an explanation of \a cformat.
5161
5162    This method does not call the va_end macro, the caller
5163    is responsible to call va_end on \a ap.
5164
5165    \sa sprintf()
5166*/
5167
5168QString &QString::vsprintf(const char* cformat, va_list ap)
5169{
5170    QLocale locale(QLocale::C);
5171
5172    if (!cformat || !*cformat) {
5173        // Qt 1.x compat
5174        *this = fromLatin1("");
5175        return *this;
5176    }
5177
5178    // Parse cformat
5179
5180    QString result;
5181    const char *c = cformat;
5182    for (;;) {
5183        // Copy non-escape chars to result
5184#ifndef QT_NO_TEXTCODEC
5185        int i = 0;
5186        while (*(c + i) != '\0' && *(c + i) != '%')
5187            ++i;
5188        if (codecForCStrings)
5189            result.append(codecForCStrings->toUnicode(c, i));
5190        else
5191            result.append(fromLatin1(c, i));
5192        c += i;
5193#else
5194        while (*c != '\0' && *c != '%')
5195            result.append(QLatin1Char(*c++));
5196#endif
5197
5198        if (*c == '\0')
5199            break;
5200
5201        // Found '%'
5202        const char *escape_start = c;
5203        ++c;
5204
5205        if (*c == '\0') {
5206            result.append(QLatin1Char('%')); // a % at the end of the string - treat as non-escape text
5207            break;
5208        }
5209        if (*c == '%') {
5210            result.append(QLatin1Char('%')); // %%
5211            ++c;
5212            continue;
5213        }
5214
5215        // Parse flag characters
5216        uint flags = 0;
5217        bool no_more_flags = false;
5218        do {
5219            switch (*c) {
5220                case '#': flags |= QLocalePrivate::Alternate; break;
5221                case '0': flags |= QLocalePrivate::ZeroPadded; break;
5222                case '-': flags |= QLocalePrivate::LeftAdjusted; break;
5223                case ' ': flags |= QLocalePrivate::BlankBeforePositive; break;
5224                case '+': flags |= QLocalePrivate::AlwaysShowSign; break;
5225                case '\'': flags |= QLocalePrivate::ThousandsGroup; break;
5226                default: no_more_flags = true; break;
5227            }
5228
5229            if (!no_more_flags)
5230                ++c;
5231        } while (!no_more_flags);
5232
5233        if (*c == '\0') {
5234            result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5235            break;
5236        }
5237
5238        // Parse field width
5239        int width = -1; // -1 means unspecified
5240        if (qIsDigit(*c)) {
5241            QString width_str;
5242            while (*c != '\0' && qIsDigit(*c))
5243                width_str.append(QLatin1Char(*c++));
5244
5245            // can't be negative - started with a digit
5246            // contains at least one digit
5247            width = width_str.toInt();
5248        }
5249        else if (*c == '*') {
5250            width = va_arg(ap, int);
5251            if (width < 0)
5252                width = -1; // treat all negative numbers as unspecified
5253            ++c;
5254        }
5255
5256        if (*c == '\0') {
5257            result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5258            break;
5259        }
5260
5261        // Parse precision
5262        int precision = -1; // -1 means unspecified
5263        if (*c == '.') {
5264            ++c;
5265            if (qIsDigit(*c)) {
5266                QString precision_str;
5267                while (*c != '\0' && qIsDigit(*c))
5268                    precision_str.append(QLatin1Char(*c++));
5269
5270                // can't be negative - started with a digit
5271                // contains at least one digit
5272                precision = precision_str.toInt();
5273            }
5274            else if (*c == '*') {
5275                precision = va_arg(ap, int);
5276                if (precision < 0)
5277                    precision = -1; // treat all negative numbers as unspecified
5278                ++c;
5279            }
5280        }
5281
5282        if (*c == '\0') {
5283            result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5284            break;
5285        }
5286
5287        // Parse the length modifier
5288        enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t };
5289        LengthMod length_mod = lm_none;
5290        switch (*c) {
5291            case 'h':
5292                ++c;
5293                if (*c == 'h') {
5294                    length_mod = lm_hh;
5295                    ++c;
5296                }
5297                else
5298                    length_mod = lm_h;
5299                break;
5300
5301            case 'l':
5302                ++c;
5303                if (*c == 'l') {
5304                    length_mod = lm_ll;
5305                    ++c;
5306                }
5307                else
5308                    length_mod = lm_l;
5309                break;
5310
5311            case 'L':
5312                ++c;
5313                length_mod = lm_L;
5314                break;
5315
5316            case 'j':
5317                ++c;
5318                length_mod = lm_j;
5319                break;
5320
5321            case 'z':
5322            case 'Z':
5323                ++c;
5324                length_mod = lm_z;
5325                break;
5326
5327            case 't':
5328                ++c;
5329                length_mod = lm_t;
5330                break;
5331
5332            default: break;
5333        }
5334
5335        if (*c == '\0') {
5336            result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5337            break;
5338        }
5339
5340        // Parse the conversion specifier and do the conversion
5341        QString subst;
5342        switch (*c) {
5343            case 'd':
5344            case 'i': {
5345                qint64 i;
5346                switch (length_mod) {
5347                    case lm_none: i = va_arg(ap, int); break;
5348                    case lm_hh: i = va_arg(ap, int); break;
5349                    case lm_h: i = va_arg(ap, int); break;
5350                    case lm_l: i = va_arg(ap, long int); break;
5351                    case lm_ll: i = va_arg(ap, qint64); break;
5352                    case lm_j: i = va_arg(ap, long int); break;
5353                    case lm_z: i = va_arg(ap, size_t); break;
5354                    case lm_t: i = va_arg(ap, int); break;
5355                    default: i = 0; break;
5356                }
5357                subst = locale.d()->longLongToString(i, precision, 10, width, flags);
5358                ++c;
5359                break;
5360            }
5361            case 'o':
5362            case 'u':
5363            case 'x':
5364            case 'X': {
5365                quint64 u;
5366                switch (length_mod) {
5367                    case lm_none: u = va_arg(ap, uint); break;
5368                    case lm_hh: u = va_arg(ap, uint); break;
5369                    case lm_h: u = va_arg(ap, uint); break;
5370                    case lm_l: u = va_arg(ap, ulong); break;
5371                    case lm_ll: u = va_arg(ap, quint64); break;
5372                    case lm_z: u = va_arg(ap, size_t); break;
5373                    default: u = 0; break;
5374                }
5375
5376                if (qIsUpper(*c))
5377                    flags |= QLocalePrivate::CapitalEorX;
5378
5379                int base = 10;
5380                switch (qToLower(*c)) {
5381                    case 'o':
5382                        base = 8; break;
5383                    case 'u':
5384                        base = 10; break;
5385                    case 'x':
5386                        base = 16; break;
5387                    default: break;
5388                }
5389                subst = locale.d()->unsLongLongToString(u, precision, base, width, flags);
5390                ++c;
5391                break;
5392            }
5393            case 'E':
5394            case 'e':
5395            case 'F':
5396            case 'f':
5397            case 'G':
5398            case 'g':
5399            case 'A':
5400            case 'a': {
5401                double d;
5402                if (length_mod == lm_L)
5403                    d = va_arg(ap, long double); // not supported - converted to a double
5404                else
5405                    d = va_arg(ap, double);
5406
5407                if (qIsUpper(*c))
5408                    flags |= QLocalePrivate::CapitalEorX;
5409
5410                QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5411                switch (qToLower(*c)) {
5412                    case 'e': form = QLocalePrivate::DFExponent; break;
5413                    case 'a':                             // not supported - decimal form used instead
5414                    case 'f': form = QLocalePrivate::DFDecimal; break;
5415                    case 'g': form = QLocalePrivate::DFSignificantDigits; break;
5416                    default: break;
5417                }
5418                subst = locale.d()->doubleToString(d, precision, form, width, flags);
5419                ++c;
5420                break;
5421            }
5422            case 'c': {
5423                if (length_mod == lm_l)
5424                    subst = QChar((ushort) va_arg(ap, int));
5425                else
5426                    subst = QLatin1Char((uchar) va_arg(ap, int));
5427                ++c;
5428                break;
5429            }
5430            case 's': {
5431                if (length_mod == lm_l) {
5432                    const ushort *buff = va_arg(ap, const ushort*);
5433                    const ushort *ch = buff;
5434                    while (*ch != 0)
5435                        ++ch;
5436                    subst.setUtf16(buff, ch - buff);
5437                } else
5438                    subst = QString::fromUtf8(va_arg(ap, const char*));
5439                if (precision != -1)
5440                    subst.truncate(precision);
5441                ++c;
5442                break;
5443            }
5444            case 'p': {
5445                void *arg = va_arg(ap, void*);
5446#ifdef Q_OS_WIN64
5447                quint64 i = reinterpret_cast<quint64>(arg);
5448#else
5449                quint64 i = reinterpret_cast<unsigned long>(arg);
5450#endif
5451                flags |= QLocalePrivate::Alternate;
5452                subst = locale.d()->unsLongLongToString(i, precision, 16, width, flags);
5453                ++c;
5454                break;
5455            }
5456            case 'n':
5457                switch (length_mod) {
5458                    case lm_hh: {
5459                        signed char *n = va_arg(ap, signed char*);
5460                        *n = result.length();
5461                        break;
5462                    }
5463                    case lm_h: {
5464                        short int *n = va_arg(ap, short int*);
5465                        *n = result.length();
5466                            break;
5467                    }
5468                    case lm_l: {
5469                        long int *n = va_arg(ap, long int*);
5470                        *n = result.length();
5471                        break;
5472                    }
5473                    case lm_ll: {
5474                        qint64 *n = va_arg(ap, qint64*);
5475                        volatile uint tmp = result.length(); // egcs-2.91.66 gets internal
5476                        *n = tmp;                             // compiler error without volatile
5477                        break;
5478                    }
5479                    default: {
5480                        int *n = va_arg(ap, int*);
5481                        *n = result.length();
5482                        break;
5483                    }
5484                }
5485                ++c;
5486                break;
5487
5488            default: // bad escape, treat as non-escape text
5489                for (const char *cc = escape_start; cc != c; ++cc)
5490                    result.append(QLatin1Char(*cc));
5491                continue;
5492        }
5493
5494        if (flags & QLocalePrivate::LeftAdjusted)
5495            result.append(subst.leftJustified(width));
5496        else
5497            result.append(subst.rightJustified(width));
5498    }
5499
5500    *this = result;
5501
5502    return *this;
5503}
5504
5505/*!
5506    Returns the string converted to a \c{long long} using base \a
5507    base, which is 10 by default and must be between 2 and 36, or 0.
5508    Returns 0 if the conversion fails.
5509
5510    If a conversion error occurs, *\a{ok} is set to false; otherwise
5511    *\a{ok} is set to true.
5512
5513    If \a base is 0, the C language convention is used: If the string
5514    begins with "0x", base 16 is used; if the string begins with "0",
5515    base 8 is used; otherwise, base 10 is used.
5516
5517    Example:
5518
5519    \snippet doc/src/snippets/qstring/main.cpp 74
5520
5521    \sa number(), toULongLong(), toInt()
5522*/
5523
5524qint64 QString::toLongLong(bool *ok, int base) const
5525{
5526#if defined(QT_CHECK_RANGE)
5527    if (base != 0 && (base < 2 || base > 36)) {
5528        qWarning("QString::toLongLong: Invalid base (%d)", base);
5529        base = 10;
5530    }
5531#endif
5532
5533    bool my_ok;
5534    QLocale def_locale;
5535    qint64 result = def_locale.d()->stringToLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5536    if (my_ok) {
5537        if (ok != 0)
5538            *ok = true;
5539        return result;
5540    }
5541
5542    QLocale c_locale(QLocale::C);
5543    return c_locale.d()->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5544}
5545
5546/*!
5547    Returns the string converted to an \c{unsigned long long} using base \a
5548    base, which is 10 by default and must be between 2 and 36, or 0.
5549    Returns 0 if the conversion fails.
5550
5551    If a conversion error occurs, *\a{ok} is set to false; otherwise
5552    *\a{ok} is set to true.
5553
5554    If \a base is 0, the C language convention is used: If the string
5555    begins with "0x", base 16 is used; if the string begins with "0",
5556    base 8 is used; otherwise, base 10 is used.
5557
5558    Example:
5559
5560    \snippet doc/src/snippets/qstring/main.cpp 79
5561
5562    \sa number(), toLongLong()
5563*/
5564
5565quint64 QString::toULongLong(bool *ok, int base) const
5566{
5567#if defined(QT_CHECK_RANGE)
5568    if (base != 0 && (base < 2 || base > 36)) {
5569        qWarning("QString::toULongLong: Invalid base (%d)", base);
5570        base = 10;
5571    }
5572#endif
5573
5574    bool my_ok;
5575    QLocale def_locale;
5576    quint64 result = def_locale.d()->stringToUnsLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5577    if (my_ok) {
5578        if (ok != 0)
5579            *ok = true;
5580        return result;
5581    }
5582
5583    QLocale c_locale(QLocale::C);
5584    return c_locale.d()->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5585}
5586
5587/*!
5588    \fn long QString::toLong(bool *ok, int base) const
5589
5590    Returns the string converted to a \c long using base \a
5591    base, which is 10 by default and must be between 2 and 36, or 0.
5592    Returns 0 if the conversion fails.
5593
5594    If a conversion error occurs, *\a{ok} is set to false; otherwise
5595    *\a{ok} is set to true.
5596
5597    If \a base is 0, the C language convention is used: If the string
5598    begins with "0x", base 16 is used; if the string begins with "0",
5599    base 8 is used; otherwise, base 10 is used.
5600
5601    Example:
5602
5603    \snippet doc/src/snippets/qstring/main.cpp 73
5604
5605    \sa number(), toULong(), toInt()
5606*/
5607
5608long QString::toLong(bool *ok, int base) const
5609{
5610    qint64 v = toLongLong(ok, base);
5611    if (v < LONG_MIN || v > LONG_MAX) {
5612        if (ok)
5613            *ok = false;
5614        v = 0;
5615    }
5616    return (long)v;
5617}
5618
5619/*!
5620    \fn ulong QString::toULong(bool *ok, int base) const
5621
5622    Returns the string converted to an \c{unsigned long} using base \a
5623    base, which is 10 by default and must be between 2 and 36, or 0.
5624    Returns 0 if the conversion fails.
5625
5626    If a conversion error occurs, *\a{ok} is set to false; otherwise
5627    *\a{ok} is set to true.
5628
5629    If \a base is 0, the C language convention is used: If the string
5630    begins with "0x", base 16 is used; if the string begins with "0",
5631    base 8 is used; otherwise, base 10 is used.
5632
5633    Example:
5634
5635    \snippet doc/src/snippets/qstring/main.cpp 78
5636
5637    \sa number()
5638*/
5639
5640ulong QString::toULong(bool *ok, int base) const
5641{
5642    quint64 v = toULongLong(ok, base);
5643    if (v > ULONG_MAX) {
5644        if (ok)
5645            *ok = false;
5646        v = 0;
5647    }
5648    return (ulong)v;
5649}
5650
5651
5652/*!
5653    Returns the string converted to an \c int using base \a
5654    base, which is 10 by default and must be between 2 and 36, or 0.
5655    Returns 0 if the conversion fails.
5656
5657    If a conversion error occurs, *\a{ok} is set to false; otherwise
5658    *\a{ok} is set to true.
5659
5660    If \a base is 0, the C language convention is used: If the string
5661    begins with "0x", base 16 is used; if the string begins with "0",
5662    base 8 is used; otherwise, base 10 is used.
5663
5664    Example:
5665
5666    \snippet doc/src/snippets/qstring/main.cpp 72
5667
5668    \sa number(), toUInt(), toDouble()
5669*/
5670
5671int QString::toInt(bool *ok, int base) const
5672{
5673    qint64 v = toLongLong(ok, base);
5674    if (v < INT_MIN || v > INT_MAX) {
5675        if (ok)
5676            *ok = false;
5677        v = 0;
5678    }
5679    return v;
5680}
5681
5682/*!
5683    Returns the string converted to an \c{unsigned int} using base \a
5684    base, which is 10 by default and must be between 2 and 36, or 0.
5685    Returns 0 if the conversion fails.
5686
5687    If a conversion error occurs, *\a{ok} is set to false; otherwise
5688    *\a{ok} is set to true.
5689
5690    If \a base is 0, the C language convention is used: If the string
5691    begins with "0x", base 16 is used; if the string begins with "0",
5692    base 8 is used; otherwise, base 10 is used.
5693
5694    Example:
5695
5696    \snippet doc/src/snippets/qstring/main.cpp 77
5697
5698    \sa number(), toInt()
5699*/
5700
5701uint QString::toUInt(bool *ok, int base) const
5702{
5703    quint64 v = toULongLong(ok, base);
5704    if (v > UINT_MAX) {
5705        if (ok)
5706            *ok = false;
5707        v = 0;
5708    }
5709    return (uint)v;
5710}
5711
5712/*!
5713    Returns the string converted to a \c short using base \a
5714    base, which is 10 by default and must be between 2 and 36, or 0.
5715    Returns 0 if the conversion fails.
5716
5717    If a conversion error occurs, *\a{ok} is set to false; otherwise
5718    *\a{ok} is set to true.
5719
5720    If \a base is 0, the C language convention is used: If the string
5721    begins with "0x", base 16 is used; if the string begins with "0",
5722    base 8 is used; otherwise, base 10 is used.
5723
5724    Example:
5725
5726    \snippet doc/src/snippets/qstring/main.cpp 76
5727
5728    \sa number(), toUShort(), toInt()
5729*/
5730
5731short QString::toShort(bool *ok, int base) const
5732{
5733    long v = toLongLong(ok, base);
5734    if (v < SHRT_MIN || v > SHRT_MAX) {
5735        if (ok)
5736            *ok = false;
5737        v = 0;
5738    }
5739    return (short)v;
5740}
5741
5742/*!
5743    Returns the string converted to an \c{unsigned short} using base \a
5744    base, which is 10 by default and must be between 2 and 36, or 0.
5745    Returns 0 if the conversion fails.
5746
5747    If a conversion error occurs, *\a{ok} is set to false; otherwise
5748    *\a{ok} is set to true.
5749
5750    If \a base is 0, the C language convention is used: If the string
5751    begins with "0x", base 16 is used; if the string begins with "0",
5752    base 8 is used; otherwise, base 10 is used.
5753
5754    Example:
5755
5756    \snippet doc/src/snippets/qstring/main.cpp 80
5757
5758    \sa number(), toShort()
5759*/
5760
5761ushort QString::toUShort(bool *ok, int base) const
5762{
5763    ulong v = toULongLong(ok, base);
5764    if (v > USHRT_MAX) {
5765        if (ok)
5766            *ok = false;
5767        v = 0;
5768    }
5769    return (ushort)v;
5770}
5771
5772
5773/*!
5774    Returns the string converted to a \c double value.
5775
5776    Returns 0.0 if the conversion fails.
5777
5778    If a conversion error occurs, \c{*}\a{ok} is set to false;
5779    otherwise \c{*}\a{ok} is set to true.
5780
5781    \snippet doc/src/snippets/qstring/main.cpp 66
5782
5783    Various string formats for floating point numbers can be converted
5784    to double values:
5785
5786    \snippet doc/src/snippets/qstring/main.cpp 67
5787
5788    This function tries to interpret the string according to the
5789    current locale. The current locale is determined from the
5790    system at application startup and can be changed by calling
5791    QLocale::setDefault(). If the string cannot be interpreted
5792    according to the current locale, this function falls back
5793    on the "C" locale.
5794
5795    \snippet doc/src/snippets/qstring/main.cpp 69
5796    \snippet doc/src/snippets/qstring/main.cpp 70
5797
5798    Due to the ambiguity between the decimal point and thousands group
5799    separator in various locales, this function does not handle
5800    thousands group separators. If you need to convert such numbers,
5801    see QLocale::toDouble().
5802
5803    \snippet doc/src/snippets/qstring/main.cpp 68
5804
5805    \sa number() QLocale::setDefault() QLocale::toDouble() trimmed()
5806*/
5807
5808double QString::toDouble(bool *ok) const
5809{
5810    bool my_ok;
5811    QLocale def_locale;
5812    double result = def_locale.d()->stringToDouble(*this, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5813    if (my_ok) {
5814        if (ok != 0)
5815            *ok = true;
5816        return result;
5817    }
5818
5819    QLocale c_locale(QLocale::C);
5820    return c_locale.d()->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators);
5821}
5822
5823/*!
5824    Returns the string converted to a \c float value.
5825
5826    If a conversion error occurs, *\a{ok} is set to false; otherwise
5827    *\a{ok} is set to true. Returns 0.0 if the conversion fails.
5828
5829    Example:
5830
5831    \snippet doc/src/snippets/qstring/main.cpp 71
5832
5833    \sa number(), toDouble(), toInt()
5834*/
5835
5836#define QT_MAX_FLOAT 3.4028234663852886e+38
5837
5838float QString::toFloat(bool *ok) const
5839{
5840    bool myOk;
5841    double d = toDouble(&myOk);
5842    if (!myOk || d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) {
5843        if (ok != 0)
5844            *ok = false;
5845        return 0.0;
5846    }
5847    if (ok != 0)
5848        *ok = true;
5849    return (float) d;
5850}
5851
5852/*! \fn QString &QString::setNum(int n, int base)
5853
5854    Sets the string to the printed value of \a n in the specified \a
5855    base, and returns a reference to the string.
5856
5857    The base is 10 by default and must be between 2 and 36. For bases
5858    other than 10, \a n is treated as an unsigned integer.
5859
5860    \snippet doc/src/snippets/qstring/main.cpp 56
5861
5862   The formatting always uses QLocale::C, i.e., English/UnitedStates.
5863   To get a localized string representation of a number, use
5864   QLocale::toString() with the appropriate locale.
5865*/
5866
5867/*! \fn QString &QString::setNum(uint n, int base)
5868
5869    \overload
5870*/
5871
5872/*! \fn QString &QString::setNum(long n, int base)
5873
5874    \overload
5875*/
5876
5877/*! \fn QString &QString::setNum(ulong n, int base)
5878
5879    \overload
5880*/
5881
5882/*!
5883    \overload
5884*/
5885QString &QString::setNum(qlonglong n, int base)
5886{
5887#if defined(QT_CHECK_RANGE)
5888    if (base < 2 || base > 36) {
5889        qWarning("QString::setNum: Invalid base (%d)", base);
5890        base = 10;
5891    }
5892#endif
5893    QLocale locale(QLocale::C);
5894    *this = locale.d()->longLongToString(n, -1, base);
5895    return *this;
5896}
5897
5898/*!
5899    \overload
5900*/
5901QString &QString::setNum(qulonglong n, int base)
5902{
5903#if defined(QT_CHECK_RANGE)
5904    if (base < 2 || base > 36) {
5905        qWarning("QString::setNum: Invalid base (%d)", base);
5906        base = 10;
5907    }
5908#endif
5909    QLocale locale(QLocale::C);
5910    *this = locale.d()->unsLongLongToString(n, -1, base);
5911    return *this;
5912}
5913
5914/*! \fn QString &QString::setNum(short n, int base)
5915
5916    \overload
5917*/
5918
5919/*! \fn QString &QString::setNum(ushort n, int base)
5920
5921    \overload
5922*/
5923
5924/*!
5925    \fn QString &QString::setNum(double n, char format, int precision)
5926    \overload
5927
5928    Sets the string to the printed value of \a n, formatted according
5929    to the given \a format and \a precision, and returns a reference
5930    to the string.
5931
5932    The \a format can be 'f', 'F', 'e', 'E', 'g' or 'G' (see the
5933    arg() function documentation for an explanation of the formats).
5934
5935    Unlike QLocale::toString(), this function doesn't honor the
5936    user's locale settings.
5937*/
5938
5939QString &QString::setNum(double n, char f, int prec)
5940{
5941    QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5942    uint flags = 0;
5943
5944    if (qIsUpper(f))
5945        flags = QLocalePrivate::CapitalEorX;
5946    f = qToLower(f);
5947
5948    switch (f) {
5949        case 'f':
5950            form = QLocalePrivate::DFDecimal;
5951            break;
5952        case 'e':
5953            form = QLocalePrivate::DFExponent;
5954            break;
5955        case 'g':
5956            form = QLocalePrivate::DFSignificantDigits;
5957            break;
5958        default:
5959#if defined(QT_CHECK_RANGE)
5960            qWarning("QString::setNum: Invalid format char '%c'", f);
5961#endif
5962            break;
5963    }
5964
5965    QLocale locale(QLocale::C);
5966    *this = locale.d()->doubleToString(n, prec, form, -1, flags);
5967    return *this;
5968}
5969
5970/*!
5971    \fn QString &QString::setNum(float n, char format, int precision)
5972    \overload
5973
5974    Sets the string to the printed value of \a n, formatted according
5975    to the given \a format and \a precision, and returns a reference
5976    to the string.
5977*/
5978
5979
5980/*!
5981    \fn QString QString::number(long n, int base)
5982
5983    Returns a string equivalent of the number \a n according to the
5984    specified \a base.
5985
5986    The base is 10 by default and must be between 2
5987    and 36. For bases other than 10, \a n is treated as an
5988    unsigned integer.
5989
5990    \snippet doc/src/snippets/qstring/main.cpp 35
5991
5992    \sa setNum()
5993*/
5994
5995QString QString::number(long n, int base)
5996{
5997    QString s;
5998    s.setNum(n, base);
5999    return s;
6000}
6001
6002/*!
6003  \fn QString QString::number(ulong n, int base)
6004
6005    \overload
6006*/
6007QString QString::number(ulong n, int base)
6008{
6009    QString s;
6010    s.setNum(n, base);
6011    return s;
6012}
6013
6014/*!
6015    \overload
6016*/
6017QString QString::number(int n, int base)
6018{
6019    QString s;
6020    s.setNum(n, base);
6021    return s;
6022}
6023
6024/*!
6025    \overload
6026*/
6027QString QString::number(uint n, int base)
6028{
6029    QString s;
6030    s.setNum(n, base);
6031    return s;
6032}
6033
6034/*!
6035    \overload
6036*/
6037QString QString::number(qlonglong n, int base)
6038{
6039    QString s;
6040    s.setNum(n, base);
6041    return s;
6042}
6043
6044/*!
6045    \overload
6046*/
6047QString QString::number(qulonglong n, int base)
6048{
6049    QString s;
6050    s.setNum(n, base);
6051    return s;
6052}
6053
6054
6055/*!
6056    \fn QString QString::number(double n, char format, int precision)
6057
6058    Returns a string equivalent of the number \a n, formatted
6059    according to the specified \a format and \a precision. See
6060    \l{Argument Formats} for details.
6061
6062    Unlike QLocale::toString(), this function does not honor the
6063    user's locale settings.
6064
6065    \sa setNum(), QLocale::toString()
6066*/
6067QString QString::number(double n, char f, int prec)
6068{
6069    QString s;
6070    s.setNum(n, f, prec);
6071    return s;
6072}
6073
6074/*!
6075    Splits the string into substrings wherever \a sep occurs, and
6076    returns the list of those strings. If \a sep does not match
6077    anywhere in the string, split() returns a single-element list
6078    containing this string.
6079
6080    \a cs specifies whether \a sep should be matched case
6081    sensitively or case insensitively.
6082
6083    If \a behavior is QString::SkipEmptyParts, empty entries don't
6084    appear in the result. By default, empty entries are kept.
6085
6086    Example:
6087
6088    \snippet doc/src/snippets/qstring/main.cpp 62
6089
6090    \sa QStringList::join(), section()
6091*/
6092QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6093{
6094    QStringList list;
6095    int start = 0;
6096    int extra = 0;
6097    int end;
6098    while ((end = indexOf(sep, start + extra, cs)) != -1) {
6099        if (start != end || behavior == KeepEmptyParts)
6100            list.append(mid(start, end - start));
6101        start = end + sep.size();
6102        extra = (sep.size() == 0 ? 1 : 0);
6103    }
6104    if (start != size() || behavior == KeepEmptyParts)
6105        list.append(mid(start));
6106    return list;
6107}
6108
6109/*!
6110    \overload
6111*/
6112QStringList QString::split(const QChar &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6113{
6114    QStringList list;
6115    int start = 0;
6116    int end;
6117    while ((end = indexOf(sep, start, cs)) != -1) {
6118        if (start != end || behavior == KeepEmptyParts)
6119            list.append(mid(start, end - start));
6120        start = end + 1;
6121    }
6122    if (start != size() || behavior == KeepEmptyParts)
6123        list.append(mid(start));
6124    return list;
6125}
6126
6127#ifndef QT_NO_REGEXP
6128/*!
6129    \overload
6130
6131    Splits the string into substrings wherever the regular expression
6132    \a rx matches, and returns the list of those strings. If \a rx
6133    does not match anywhere in the string, split() returns a
6134    single-element list containing this string.
6135
6136    Here's an example where we extract the words in a sentence
6137    using one or more whitespace characters as the separator:
6138
6139    \snippet doc/src/snippets/qstring/main.cpp 59
6140
6141    Here's a similar example, but this time we use any sequence of
6142    non-word characters as the separator:
6143
6144    \snippet doc/src/snippets/qstring/main.cpp 60
6145
6146    Here's a third example where we use a zero-length assertion,
6147    \bold{\\b} (word boundary), to split the string into an
6148    alternating sequence of non-word and word tokens:
6149
6150    \snippet doc/src/snippets/qstring/main.cpp 61
6151
6152    \sa QStringList::join(), section()
6153*/
6154QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const
6155{
6156    QRegExp rx2(rx);
6157    QStringList list;
6158    int start = 0;
6159    int extra = 0;
6160    int end;
6161    while ((end = rx2.indexIn(*this, start + extra)) != -1) {
6162        int matchedLen = rx2.matchedLength();
6163        if (start != end || behavior == KeepEmptyParts)
6164            list.append(mid(start, end - start));
6165        start = end + matchedLen;
6166        extra = (matchedLen == 0) ? 1 : 0;
6167    }
6168    if (start != size() || behavior == KeepEmptyParts)
6169        list.append(mid(start));
6170    return list;
6171}
6172#endif
6173
6174/*!
6175    \enum QString::NormalizationForm
6176
6177    This enum describes the various normalized forms of Unicode text.
6178
6179    \value NormalizationForm_D  Canonical Decomposition
6180    \value NormalizationForm_C  Canonical Decomposition followed by Canonical Composition
6181    \value NormalizationForm_KD  Compatibility Decomposition
6182    \value NormalizationForm_KC  Compatibility Decomposition followed by Canonical Composition
6183
6184    \sa normalized(),
6185        {http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15}
6186*/
6187
6188/*!
6189    \fn QString QString::normalized(NormalizationForm mode) const
6190    Returns the string in the given Unicode normalization \a mode.
6191*/
6192QString QString::normalized(QString::NormalizationForm mode) const
6193{
6194    return normalized(mode, UNICODE_DATA_VERSION);
6195}
6196
6197/*!
6198    \since 4.5
6199
6200    Returns a copy of this string repeated the specified number of \a times.
6201
6202    If \a times is less than 1, an empty string is returned.
6203
6204    Example:
6205
6206    \code
6207        QString str("ab");
6208        str.repeated(4);            // returns "abababab"
6209    \endcode
6210*/
6211QString QString::repeated(int times) const
6212{
6213    if (d->size == 0)
6214        return *this;
6215
6216    if (times <= 1) {
6217        if (times == 1)
6218            return *this;
6219        return QString();
6220    }
6221
6222    const int resultSize = times * d->size;
6223
6224    QString result;
6225    result.reserve(resultSize);
6226    if (result.d->alloc != resultSize)
6227        return QString(); // not enough memory
6228
6229    memcpy(result.d->data, d->data, d->size * sizeof(ushort));
6230
6231    int sizeSoFar = d->size;
6232    ushort *end = result.d->data + sizeSoFar;
6233
6234    const int halfResultSize = resultSize >> 1;
6235    while (sizeSoFar <= halfResultSize) {
6236        memcpy(end, result.d->data, sizeSoFar * sizeof(ushort));
6237        end += sizeSoFar;
6238        sizeSoFar <<= 1;
6239    }
6240    memcpy(end, result.d->data, (resultSize - sizeSoFar) * sizeof(ushort));
6241    result.d->data[resultSize] = '\0';
6242    result.d->size = resultSize;
6243    return result;
6244}
6245
6246void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from);
6247/*!
6248    \overload
6249    \fn QString QString::normalized(NormalizationForm mode, QChar::UnicodeVersion version) const
6250
6251    Returns the string in the given Unicode normalization \a mode,
6252    according to the given \a version of the Unicode standard.
6253*/
6254QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const
6255{
6256    QString copy = *this;
6257    qt_string_normalize(&copy, mode, version, 0);
6258    return copy;
6259}
6260
6261void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from)
6262{
6263    bool simple = true;
6264    const QChar *p = data->constData();
6265    int len = data->length();
6266    for (int i = from; i < len; ++i) {
6267        if (p[i].unicode() >= 0x80) {
6268            simple = false;
6269            break;
6270        }
6271    }
6272    if (simple)
6273        return;
6274
6275    if (version == QChar::Unicode_Unassigned) {
6276        version = UNICODE_DATA_VERSION;
6277    } else if (version != UNICODE_DATA_VERSION) {
6278        QString &s = *data;
6279        for (int i = 0; i < NumNormalizationCorrections; ++i) {
6280            const NormalizationCorrection &n = uc_normalization_corrections[i];
6281            if (n.version > version) {
6282                int pos = from;
6283                if (n.ucs4 > 0xffff) {
6284                    ushort ucs4High = QChar::highSurrogate(n.ucs4);
6285                    ushort ucs4Low = QChar::lowSurrogate(n.ucs4);
6286                    ushort oldHigh = QChar::highSurrogate(n.old_mapping);
6287                    ushort oldLow = QChar::lowSurrogate(n.old_mapping);
6288                    while (pos < s.length() - 1) {
6289                        if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) {
6290                            s[pos] = oldHigh;
6291                            s[pos + 1] = oldLow;
6292                            ++pos;
6293                        }
6294                        ++pos;
6295                    }
6296                } else {
6297                    while (pos < s.length()) {
6298                        if (s.at(pos).unicode() == n.ucs4) {
6299                            s[pos] = n.old_mapping;
6300                        }
6301                        ++pos;
6302                    }
6303                }
6304            }
6305        }
6306    }
6307    decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from);
6308
6309    canonicalOrderHelper(data, version, from);
6310
6311    if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD)
6312        return;
6313
6314    composeHelper(data, from);
6315}
6316
6317
6318struct ArgEscapeData
6319{
6320    int min_escape;            // lowest escape sequence number
6321    int occurrences;           // number of occurrences of the lowest escape sequence number
6322    int locale_occurrences;    // number of occurrences of the lowest escape sequence number that
6323                               // contain 'L'
6324    int escape_len;            // total length of escape sequences which will be replaced
6325};
6326
6327static ArgEscapeData findArgEscapes(const QString &s)
6328{
6329    const QChar *uc_begin = s.unicode();
6330    const QChar *uc_end = uc_begin + s.length();
6331
6332    ArgEscapeData d;
6333
6334    d.min_escape = INT_MAX;
6335    d.occurrences = 0;
6336    d.escape_len = 0;
6337    d.locale_occurrences = 0;
6338
6339    const QChar *c = uc_begin;
6340    while (c != uc_end) {
6341        while (c != uc_end && c->unicode() != '%')
6342            ++c;
6343
6344        if (c == uc_end)
6345            break;
6346        const QChar *escape_start = c;
6347        if (++c == uc_end)
6348            break;
6349
6350        bool locale_arg = false;
6351        if (c->unicode() == 'L') {
6352            locale_arg = true;
6353            if (++c == uc_end)
6354                break;
6355        }
6356
6357        if (c->digitValue() == -1)
6358            continue;
6359
6360        int escape = c->digitValue();
6361        ++c;
6362
6363        if (c != uc_end && c->digitValue() != -1) {
6364            escape = (10 * escape) + c->digitValue();
6365            ++c;
6366        }
6367
6368        if (escape > d.min_escape)
6369            continue;
6370
6371        if (escape < d.min_escape) {
6372            d.min_escape = escape;
6373            d.occurrences = 0;
6374            d.escape_len = 0;
6375            d.locale_occurrences = 0;
6376        }
6377
6378        ++d.occurrences;
6379        if (locale_arg)
6380            ++d.locale_occurrences;
6381        d.escape_len += c - escape_start;
6382    }
6383    return d;
6384}
6385
6386static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width,
6387                                 const QString &arg, const QString &larg, const QChar &fillChar = QLatin1Char(' '))
6388{
6389    const QChar *uc_begin = s.unicode();
6390    const QChar *uc_end = uc_begin + s.length();
6391
6392    int abs_field_width = qAbs(field_width);
6393    int result_len = s.length()
6394                     - d.escape_len
6395                     + (d.occurrences - d.locale_occurrences)
6396                     *qMax(abs_field_width, arg.length())
6397                     + d.locale_occurrences
6398                     *qMax(abs_field_width, larg.length());
6399
6400    QString result(result_len, Qt::Uninitialized);
6401    QChar *result_buff = (QChar*) result.unicode();
6402
6403    QChar *rc = result_buff;
6404    const QChar *c = uc_begin;
6405    int repl_cnt = 0;
6406    while (c != uc_end) {
6407        /* We don't have to check if we run off the end of the string with c,
6408           because as long as d.occurrences > 0 we KNOW there are valid escape
6409           sequences. */
6410
6411        const QChar *text_start = c;
6412
6413        while (c->unicode() != '%')
6414            ++c;
6415
6416        const QChar *escape_start = c++;
6417
6418        bool locale_arg = false;
6419        if (c->unicode() == 'L') {
6420            locale_arg = true;
6421            ++c;
6422        }
6423
6424        int escape = c->digitValue();
6425        if (escape != -1) {
6426            if (c + 1 != uc_end && (c + 1)->digitValue() != -1) {
6427                escape = (10 * escape) + (c + 1)->digitValue();
6428                ++c;
6429            }
6430        }
6431
6432        if (escape != d.min_escape) {
6433            memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
6434            rc += c - text_start;
6435        }
6436        else {
6437            ++c;
6438
6439            memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
6440            rc += escape_start - text_start;
6441
6442            uint pad_chars;
6443            if (locale_arg)
6444                pad_chars = qMax(abs_field_width, larg.length()) - larg.length();
6445            else
6446                pad_chars = qMax(abs_field_width, arg.length()) - arg.length();
6447
6448            if (field_width > 0) { // left padded
6449                for (uint i = 0; i < pad_chars; ++i)
6450                    (rc++)->unicode() = fillChar.unicode();
6451            }
6452
6453            if (locale_arg) {
6454                memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar));
6455                rc += larg.length();
6456            }
6457            else {
6458                memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar));
6459                rc += arg.length();
6460            }
6461
6462            if (field_width < 0) { // right padded
6463                for (uint i = 0; i < pad_chars; ++i)
6464                    (rc++)->unicode() = fillChar.unicode();
6465            }
6466
6467            if (++repl_cnt == d.occurrences) {
6468                memcpy(rc, c, (uc_end - c)*sizeof(QChar));
6469                rc += uc_end - c;
6470                Q_ASSERT(rc - result_buff == result_len);
6471                c = uc_end;
6472            }
6473        }
6474    }
6475    Q_ASSERT(rc == result_buff + result_len);
6476
6477    return result;
6478}
6479
6480/*!
6481  Returns a copy of this string with the lowest numbered place marker
6482  replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
6483
6484  \a fieldWidth specifies the minimum amount of space that argument \a
6485  a shall occupy. If \a a requires less space than \a fieldWidth, it
6486  is padded to \a fieldWidth with character \a fillChar.  A positive
6487  \a fieldWidth produces right-aligned text. A negative \a fieldWidth
6488  produces left-aligned text.
6489
6490  This example shows how we might create a \c status string for
6491  reporting progress while processing a list of files:
6492
6493  \snippet doc/src/snippets/qstring/main.cpp 11
6494
6495  First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
6496  %2. Finally, \c arg(fileName) replaces \c %3.
6497
6498  One advantage of using arg() over sprintf() is that the order of the
6499  numbered place markers can change, if the application's strings are
6500  translated into other languages, but each arg() will still replace
6501  the lowest numbered unreplaced place marker, no matter where it
6502  appears. Also, if place marker \c %i appears more than once in the
6503  string, the arg() replaces all of them.
6504
6505  If there is no unreplaced place marker remaining, a warning message
6506  is output and the result is undefined. Place marker numbers must be
6507  in the range 1 to 99.
6508*/
6509QString QString::arg(const QString &a, int fieldWidth, const QChar &fillChar) const
6510{
6511    ArgEscapeData d = findArgEscapes(*this);
6512
6513    if (d.occurrences == 0) {
6514        qWarning("QString::arg: Argument missing: %s, %s", toLocal8Bit().data(),
6515                  a.toLocal8Bit().data());
6516        return *this;
6517    }
6518    return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar);
6519}
6520
6521/*!
6522  \fn QString QString::arg(const QString& a1, const QString& a2) const
6523  \overload arg()
6524
6525  This is the same as \c {str.arg(a1).arg(a2)}, except that the
6526  strings \a a1 and \a a2 are replaced in one pass. This can make a
6527  difference if \a a1 contains e.g. \c{%1}:
6528
6529  \snippet doc/src/snippets/qstring/main.cpp 13
6530*/
6531
6532/*!
6533  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const
6534  \overload arg()
6535
6536  This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except
6537  that the strings \a a1, \a a2 and \a a3 are replaced in one pass.
6538*/
6539
6540/*!
6541  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const
6542  \overload arg()
6543
6544  This is the same as calling \c
6545  {str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a
6546  a1, \a a2, \a a3 and \a a4 are replaced in one pass.
6547*/
6548
6549/*!
6550  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const
6551  \overload arg()
6552
6553  This is the same as calling \c
6554  {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings
6555  \a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass.
6556*/
6557
6558/*!
6559  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const
6560  \overload arg()
6561
6562  This is the same as calling \c
6563  {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that
6564  the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are
6565  replaced in one pass.
6566*/
6567
6568/*!
6569  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7) const
6570  \overload arg()
6571
6572  This is the same as calling \c
6573  {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)},
6574  except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6,
6575  and \a a7 are replaced in one pass.
6576*/
6577
6578/*!
6579  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8) const
6580  \overload arg()
6581
6582  This is the same as calling \c
6583  {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)},
6584  except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6585  a7, and \a a8 are replaced in one pass.
6586*/
6587
6588/*!
6589  \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8, const QString& a9) const
6590  \overload arg()
6591
6592  This is the same as calling \c
6593  {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)},
6594  except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6595  a7, \a a8, and \a a9 are replaced in one pass.
6596*/
6597
6598/*! \fn QString QString::arg(int a, int fieldWidth, int base, const QChar &fillChar) const
6599  \overload arg()
6600
6601  The \a a argument is expressed in base \a base, which is 10 by
6602  default and must be between 2 and 36. For bases other than 10, \a a
6603  is treated as an unsigned integer.
6604
6605  \a fieldWidth specifies the minimum amount of space that \a a is
6606  padded to and filled with the character \a fillChar. A positive
6607  value produces right-aligned text; a negative value produces
6608  left-aligned text.
6609
6610  The '%' can be followed by an 'L', in which case the sequence is
6611  replaced with a localized representation of \a a. The conversion
6612  uses the default locale, set by QLocale::setDefault(). If no default
6613  locale was specified, the "C" locale is used. The 'L' flag is
6614  ignored if \a base is not 10.
6615
6616  \snippet doc/src/snippets/qstring/main.cpp 12
6617  \snippet doc/src/snippets/qstring/main.cpp 14
6618
6619  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6620  used. For negative numbers, zero padding might appear before the
6621  minus sign.
6622*/
6623
6624/*! \fn QString QString::arg(uint a, int fieldWidth, int base, const QChar &fillChar) const
6625  \overload arg()
6626
6627  The \a base argument specifies the base to use when converting the
6628  integer \a a into a string. The base must be between 2 and 36.
6629
6630  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6631  used. For negative numbers, zero padding might appear before the
6632  minus sign.
6633*/
6634
6635/*! \fn QString QString::arg(long a, int fieldWidth, int base, const QChar &fillChar) const
6636  \overload arg()
6637
6638  \a fieldWidth specifies the minimum amount of space that \a a is
6639  padded to and filled with the character \a fillChar. A positive
6640  value produces right-aligned text; a negative value produces
6641  left-aligned text.
6642
6643  The \a a argument is expressed in the given \a base, which is 10 by
6644  default and must be between 2 and 36.
6645
6646  The '%' can be followed by an 'L', in which case the sequence is
6647  replaced with a localized representation of \a a. The conversion
6648  uses the default locale. The default locale is determined from the
6649  system's locale settings at application startup. It can be changed
6650  using QLocale::setDefault(). The 'L' flag is ignored if \a base is
6651  not 10.
6652
6653  \snippet doc/src/snippets/qstring/main.cpp 12
6654  \snippet doc/src/snippets/qstring/main.cpp 14
6655
6656  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6657  used. For negative numbers, zero padding might appear before the
6658  minus sign.
6659*/
6660
6661/*! \fn QString QString::arg(ulong a, int fieldWidth, int base, const QChar &fillChar) const
6662  \overload arg()
6663
6664  \a fieldWidth specifies the minimum amount of space that \a a is
6665  padded to and filled with the character \a fillChar. A positive
6666  value produces right-aligned text; a negative value produces
6667  left-aligned text.
6668
6669  The \a base argument specifies the base to use when converting the
6670  integer \a a to a string. The base must be between 2 and 36, with 8
6671  giving octal, 10 decimal, and 16 hexadecimal numbers.
6672
6673  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6674  used. For negative numbers, zero padding might appear before the
6675  minus sign.
6676*/
6677
6678/*!
6679  \overload arg()
6680
6681  \a fieldWidth specifies the minimum amount of space that \a a is
6682  padded to and filled with the character \a fillChar. A positive
6683  value produces right-aligned text; a negative value produces
6684  left-aligned text.
6685
6686  The \a base argument specifies the base to use when converting the
6687  integer \a a into a string. The base must be between 2 and 36, with
6688  8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6689
6690  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6691  used. For negative numbers, zero padding might appear before the
6692  minus sign.
6693*/
6694QString QString::arg(qlonglong a, int fieldWidth, int base, const QChar &fillChar) const
6695{
6696    ArgEscapeData d = findArgEscapes(*this);
6697
6698    if (d.occurrences == 0) {
6699        qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6700        return *this;
6701    }
6702
6703    unsigned flags = QLocalePrivate::NoFlags;
6704    if (fillChar == QLatin1Char('0'))
6705        flags = QLocalePrivate::ZeroPadded;
6706
6707    QString arg;
6708    if (d.occurrences > d.locale_occurrences)
6709        arg = QLocale::c().d()->longLongToString(a, -1, base, fieldWidth, flags);
6710
6711    QString locale_arg;
6712    if (d.locale_occurrences > 0) {
6713        QLocale locale;
6714        if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6715            flags |= QLocalePrivate::ThousandsGroup;
6716        locale_arg = locale.d()->longLongToString(a, -1, base, fieldWidth, flags);
6717    }
6718
6719    return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6720}
6721
6722/*!
6723  \overload arg()
6724
6725  \a fieldWidth specifies the minimum amount of space that \a a is
6726  padded to and filled with the character \a fillChar. A positive
6727  value produces right-aligned text; a negative value produces
6728  left-aligned text.
6729
6730  The \a base argument specifies the base to use when converting the
6731  integer \a a into a string. \a base must be between 2 and 36, with 8
6732  giving octal, 10 decimal, and 16 hexadecimal numbers.
6733
6734  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6735  used. For negative numbers, zero padding might appear before the
6736  minus sign.
6737*/
6738QString QString::arg(qulonglong a, int fieldWidth, int base, const QChar &fillChar) const
6739{
6740    ArgEscapeData d = findArgEscapes(*this);
6741
6742    if (d.occurrences == 0) {
6743        qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6744        return *this;
6745    }
6746
6747    unsigned flags = QLocalePrivate::NoFlags;
6748    if (fillChar == QLatin1Char('0'))
6749        flags = QLocalePrivate::ZeroPadded;
6750
6751    QString arg;
6752    if (d.occurrences > d.locale_occurrences)
6753        arg = QLocale::c().d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6754
6755    QString locale_arg;
6756    if (d.locale_occurrences > 0) {
6757        QLocale locale;
6758        if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6759            flags |= QLocalePrivate::ThousandsGroup;
6760        locale_arg = locale.d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6761    }
6762
6763    return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6764}
6765
6766/*!
6767  \overload arg()
6768
6769  \fn QString QString::arg(short a, int fieldWidth, int base, const QChar &fillChar) const
6770
6771  \a fieldWidth specifies the minimum amount of space that \a a is
6772  padded to and filled with the character \a fillChar. A positive
6773  value produces right-aligned text; a negative value produces
6774  left-aligned text.
6775
6776  The \a base argument specifies the base to use when converting the
6777  integer \a a into a string. The base must be between 2 and 36, with
6778  8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6779
6780  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6781  used. For negative numbers, zero padding might appear before the
6782  minus sign.
6783*/
6784
6785/*!
6786  \fn QString QString::arg(ushort a, int fieldWidth, int base, const QChar &fillChar) const
6787  \overload arg()
6788
6789  \a fieldWidth specifies the minimum amount of space that \a a is
6790  padded to and filled with the character \a fillChar. A positive
6791  value produces right-aligned text; a negative value produces
6792  left-aligned text.
6793
6794  The \a base argument specifies the base to use when converting the
6795  integer \a a into a string. The base must be between 2 and 36, with
6796  8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6797
6798  If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6799  used. For negative numbers, zero padding might appear before the
6800  minus sign.
6801*/
6802
6803/*!
6804    \overload arg()
6805*/
6806QString QString::arg(QChar a, int fieldWidth, const QChar &fillChar) const
6807{
6808    QString c;
6809    c += a;
6810    return arg(c, fieldWidth, fillChar);
6811}
6812
6813/*!
6814  \overload arg()
6815
6816  The \a a argument is interpreted as a Latin-1 character.
6817*/
6818QString QString::arg(char a, int fieldWidth, const QChar &fillChar) const
6819{
6820    QString c;
6821    c += QLatin1Char(a);
6822    return arg(c, fieldWidth, fillChar);
6823}
6824
6825/*!
6826  \fn QString QString::arg(double a, int fieldWidth, char format, int precision, const QChar &fillChar) const
6827  \overload arg()
6828
6829  Argument \a a is formatted according to the specified \a format and
6830  \a precision. See \l{Argument Formats} for details.
6831
6832  \a fieldWidth specifies the minimum amount of space that \a a is
6833  padded to and filled with the character \a fillChar.  A positive
6834  value produces right-aligned text; a negative value produces
6835  left-aligned text.
6836
6837  \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 2
6838
6839  The '%' can be followed by an 'L', in which case the sequence is
6840  replaced with a localized representation of \a a. The conversion
6841  uses the default locale, set by QLocale::setDefaultLocale(). If no
6842  default locale was specified, the "C" locale is used.
6843
6844  If \a fillChar is '0' (the number 0, ASCII 48), this function will
6845  use the locale's zero to pad. For negative numbers, the zero padding
6846  will probably appear before the minus sign.
6847
6848  \sa QLocale::toString()
6849*/
6850QString QString::arg(double a, int fieldWidth, char fmt, int prec, const QChar &fillChar) const
6851{
6852    ArgEscapeData d = findArgEscapes(*this);
6853
6854    if (d.occurrences == 0) {
6855        qWarning("QString::arg: Argument missing: %s, %g", toLocal8Bit().data(), a);
6856        return *this;
6857    }
6858
6859    unsigned flags = QLocalePrivate::NoFlags;
6860    if (fillChar == QLatin1Char('0'))
6861        flags = QLocalePrivate::ZeroPadded;
6862
6863    if (qIsUpper(fmt))
6864        flags |= QLocalePrivate::CapitalEorX;
6865    fmt = qToLower(fmt);
6866
6867    QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
6868    switch (fmt) {
6869    case 'f':
6870        form = QLocalePrivate::DFDecimal;
6871        break;
6872    case 'e':
6873        form = QLocalePrivate::DFExponent;
6874        break;
6875    case 'g':
6876        form = QLocalePrivate::DFSignificantDigits;
6877        break;
6878    default:
6879#if defined(QT_CHECK_RANGE)
6880        qWarning("QString::arg: Invalid format char '%c'", fmt);