make fromWCharArray() and toWCharArray() inlined
[qt:ritts-qtbase.git] / src / corelib / tools / qstring.cpp
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 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 **
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 **
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
29 **
30 ** Other Usage
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
33 **
34 **
35 **
36 **
37 **
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 #include <private/qfunctions_p.h>
66
67 #if defined(Q_OS_WINCE)
68 #include <windows.h>
69 #include <winnls.h>
70 #endif
71
72 #ifdef Q_OS_SYMBIAN
73 #include <e32cmn.h>
74 #endif
75
76 #include <limits.h>
77 #include <string.h>
78 #include <stdlib.h>
79 #include <stdio.h>
80 #include <stdarg.h>
81
82 #ifdef truncate
83 #undef truncate
84 #endif
85
86 #include "qchar.cpp"
87 #include "qstringmatcher.cpp"
88
89 #ifndef LLONG_MAX
90 #define LLONG_MAX qint64_C(9223372036854775807)
91 #endif
92 #ifndef LLONG_MIN
93 #define LLONG_MIN (-LLONG_MAX - qint64_C(1))
94 #endif
95 #ifndef ULLONG_MAX
96 #define ULLONG_MAX quint64_C(18446744073709551615)
97 #endif
98
99 QT_BEGIN_NAMESPACE
100
101 #ifndef QT_NO_TEXTCODEC
102 QTextCodec *QString::codecForCStrings;
103 #endif
104
105 #ifdef QT_USE_ICU
106 // qlocale_icu.cpp
107 extern bool qt_ucol_strcoll(const QChar *source, int sourceLength, const QChar *target, int targetLength, int *result);
108 #endif
109
110
111 // internal
112 int qFindString(const QChar *haystack, int haystackLen, int from,
113     const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
114 int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from,
115     const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
116 static inline int qt_last_index_of(const QChar *haystack, int haystackLen, const QChar &needle,
117                                    int from, Qt::CaseSensitivity cs);
118 static inline int qt_string_count(const QChar *haystack, int haystackLen,
119                                   const QChar *needle, int needleLen,
120                                   Qt::CaseSensitivity cs);
121 static inline int qt_string_count(const QChar *haystack, int haystackLen,
122                                   const QChar &needle, Qt::CaseSensitivity cs);
123 static inline int qt_find_latin1_string(const QChar *hay, int size, const QLatin1String &needle,
124                                         int from, Qt::CaseSensitivity cs);
125 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
126                                   const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
127 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
128                                   const QLatin1String &needle, Qt::CaseSensitivity cs);
129 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
130                                 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
131 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
132                                 const QLatin1String &needle, Qt::CaseSensitivity cs);
133
134 // Unicode case-insensitive comparison
135 static int ucstricmp(const ushort *a, const ushort *ae, const ushort *b, const ushort *be)
136 {
137     if (a == b)
138         return (ae - be);
139     if (a == 0)
140         return 1;
141     if (b == 0)
142         return -1;
143
144     const ushort *e = ae;
145     if (be - b < ae - a)
146         e = a + (be - b);
147
148     uint alast = 0;
149     uint blast = 0;
150     while (a < e) {
151 //         qDebug() << hex << alast << blast;
152 //         qDebug() << hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast);
153 //         qDebug() << hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast);
154         int diff = foldCase(*a, alast) - foldCase(*b, blast);
155         if ((diff))
156             return diff;
157         ++a;
158         ++b;
159     }
160     if (a == ae) {
161         if (b == be)
162             return 0;
163         return -1;
164     }
165     return 1;
166 }
167
168 // Case-insensitive comparison between a Unicode string and a QLatin1String
169 static int ucstricmp(const ushort *a, const ushort *ae, const uchar *b)
170 {
171     if (a == 0) {
172         if (b == 0)
173             return 0;
174         return 1;
175     }
176     if (b == 0)
177         return -1;
178
179     while (a < ae && *b) {
180         int diff = foldCase(*a) - foldCase(*b);
181         if ((diff))
182             return diff;
183         ++a;
184         ++b;
185     }
186     if (a == ae) {
187         if (!*b)
188             return 0;
189         return -1;
190     }
191     return 1;
192 }
193
194 // Unicode case-sensitive compare two same-sized strings
195 static int ucstrncmp(const QChar *a, const QChar *b, int l)
196 {
197     while (l-- && *a == *b)
198         a++,b++;
199     if (l==-1)
200         return 0;
201     return a->unicode() - b->unicode();
202 }
203
204 // Unicode case-sensitive comparison
205 static int ucstrcmp(const QChar *a, int alen, const QChar *b, int blen)
206 {
207     if (a == b && alen == blen)
208         return 0;
209     int l = qMin(alen, blen);
210     int cmp = ucstrncmp(a, b, l);
211     return cmp ? cmp : (alen-blen);
212 }
213
214 // Unicode case-insensitive compare two same-sized strings
215 static int ucstrnicmp(const ushort *a, const ushort *b, int l)
216 {
217     return ucstricmp(a, a + l, b, b + l);
218 }
219
220 // Benchmarking indicates that doing memcmp is much slower than
221 // executing the comparison ourselves.
222 //
223 // The profiling was done on a population of calls to qMemEquals, generated
224 // during a run of the demo browser. The profile of the data (32-bit x86
225 // Linux) was:
226 //
227 //  total number of comparisons: 21353
228 //  longest string compared: 95
229 //  average comparison length: 14.8786
230 //  cache-line crosses: 5661 (13.3%)
231 //  alignment histogram:
232 //   0xXXX0 = 512 (1.2%) strings, 0 (0.0%) of which same-aligned
233 //   0xXXX2 = 15087 (35.3%) strings, 5145 (34.1%) of which same-aligned
234 //   0xXXX4 = 525 (1.2%) strings, 0 (0.0%) of which same-aligned
235 //   0xXXX6 = 557 (1.3%) strings, 6 (1.1%) of which same-aligned
236 //   0xXXX8 = 509 (1.2%) strings, 0 (0.0%) of which same-aligned
237 //   0xXXXa = 24358 (57.0%) strings, 9901 (40.6%) of which same-aligned
238 //   0xXXXc = 557 (1.3%) strings, 0 (0.0%) of which same-aligned
239 //   0xXXXe = 601 (1.4%) strings, 15 (2.5%) of which same-aligned
240 //   total  = 42706 (100%) strings, 15067 (35.3%) of which same-aligned
241 //
242 // 92% of the strings have alignment of 2 or 10, which is due to malloc on
243 // 32-bit Linux returning values aligned to 8 bytes, and offsetof(array, QString::Data) == 18.
244 //
245 // The profile on 64-bit will be different since offsetof(array, QString::Data) == 26.
246 //
247 // The benchmark results were, for a Core-i7 @ 2.67 GHz 32-bit, compiled with -O3 -funroll-loops:
248 //   16-bit loads only:           872,301 CPU ticks [Qt 4.5 / memcmp]
249 //   32- and 16-bit loads:        773,362 CPU ticks [Qt 4.6]
250 //   SSE2 "movdqu" 128-bit loads: 618,736 CPU ticks
251 //   SSE3 "lddqu" 128-bit loads:  619,954 CPU ticks
252 //   SSSE3 "palignr" corrections: 852,147 CPU ticks
253 //   SSE4.2 "pcmpestrm":          738,702 CPU ticks
254 //
255 // The same benchmark on an Atom N450 @ 1.66 GHz, is:
256 //  16-bit loads only:            2,185,882 CPU ticks
257 //  32- and 16-bit loads:         1,805,060 CPU ticks
258 //  SSE2 "movdqu" 128-bit loads:  2,529,843 CPU ticks
259 //  SSE3 "lddqu" 128-bit loads:   2,514,858 CPU ticks
260 //  SSSE3 "palignr" corrections:  2,160,325 CPU ticks
261 //  SSE4.2 not available
262 //
263 // The conclusion we reach is that alignment the SSE2 unaligned code can gain
264 // 20% improvement in performance in some systems, but suffers a penalty due
265 // to the unaligned loads on others.
266
267 static bool qMemEquals(const quint16 *a, const quint16 *b, int length)
268 {
269     if (a == b || !length)
270         return true;
271
272     register union {
273         const quint16 *w;
274         const quint32 *d;
275         quintptr value;
276     } sa, sb;
277     sa.w = a;
278     sb.w = b;
279
280     // check alignment
281     if ((sa.value & 2) == (sb.value & 2)) {
282         // both addresses have the same alignment
283         if (sa.value & 2) {
284             // both addresses are not aligned to 4-bytes boundaries
285             // compare the first character
286             if (*sa.w != *sb.w)
287                 return false;
288             --length;
289             ++sa.w;
290             ++sb.w;
291
292             // now both addresses are 4-bytes aligned
293         }
294
295         // both addresses are 4-bytes aligned
296         // do a fast 32-bit comparison
297         register const quint32 *e = sa.d + (length >> 1);
298         for ( ; sa.d != e; ++sa.d, ++sb.d) {
299             if (*sa.d != *sb.d)
300                 return false;
301         }
302
303         // do we have a tail?
304         return (length & 1) ? *sa.w == *sb.w : true;
305     } else {
306         // one of the addresses isn't 4-byte aligned but the other is
307         register const quint16 *e = sa.w + length;
308         for ( ; sa.w != e; ++sa.w, ++sb.w) {
309             if (*sa.w != *sb.w)
310                 return false;
311         }
312     }
313     return true;
314 }
315
316 /*!
317     \internal
318
319     Returns the index position of the first occurrence of the
320     character \a ch in the string given by \a str and \a len,
321     searching forward from index
322     position \a from. Returns -1 if \a ch could not be found.
323 */
324 static int findChar(const QChar *str, int len, QChar ch, int from,
325     Qt::CaseSensitivity cs)
326 {
327     const ushort *s = (const ushort *)str;
328     ushort c = ch.unicode();
329     if (from < 0)
330         from = qMax(from + len, 0);
331     if (from < len) {
332         const ushort *n = s + from - 1;
333         const ushort *e = s + len;
334         if (cs == Qt::CaseSensitive) {
335             while (++n != e)
336                 if (*n == c)
337                     return  n - s;
338         } else {
339             c = foldCase(c);
340             while (++n != e)
341                 if (foldCase(*n) == c)
342                     return  n - s;
343         }
344     }
345     return -1;
346 }
347
348 #define REHASH(a) \
349     if (sl_minus_1 < (int)sizeof(int) * CHAR_BIT)       \
350         hashHaystack -= (a) << sl_minus_1; \
351     hashHaystack <<= 1
352
353 inline bool qIsUpper(char ch)
354 {
355     return ch >= 'A' && ch <= 'Z';
356 }
357
358 inline bool qIsDigit(char ch)
359 {
360     return ch >= '0' && ch <= '9';
361 }
362
363 inline char qToLower(char ch)
364 {
365     if (ch >= 'A' && ch <= 'Z')
366         return ch - 'A' + 'a';
367     else
368         return ch;
369 }
370
371 const QString::Null QString::null = { };
372
373 /*!
374   \macro QT_NO_CAST_FROM_ASCII
375   \relates QString
376
377   Disables automatic conversions from 8-bit strings (char *) to unicode QStrings
378
379   \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_BYTEARRAY
380 */
381
382 /*!
383   \macro QT_NO_CAST_TO_ASCII
384   \relates QString
385
386   disables automatic conversion from QString to 8-bit strings (char *)
387
388   \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
389 */
390
391 /*!
392   \macro QT_ASCII_CAST_WARNINGS
393   \internal
394   \relates QString
395
396   This macro can be defined to force a warning whenever a function is
397   called that automatically converts between unicode and 8-bit encodings.
398
399   Note: This only works for compilers that support warnings for
400   deprecated API.
401
402   \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII
403 */
404
405 /*!
406     \class QCharRef
407     \reentrant
408     \brief The QCharRef class is a helper class for QString.
409
410     \internal
411
412     \ingroup string-processing
413
414     When you get an object of type QCharRef, if you can assign to it,
415     the assignment will apply to the character in the string from
416     which you got the reference. That is its whole purpose in life.
417     The QCharRef becomes invalid once modifications are made to the
418     string: if you want to keep the character, copy it into a QChar.
419
420     Most of the QChar member functions also exist in QCharRef.
421     However, they are not explicitly documented here.
422
423     \sa QString::operator[]() QString::at() QChar
424 */
425
426 /*!
427     \class QString
428     \reentrant
429
430     \brief The QString class provides a Unicode character string.
431
432     \ingroup tools
433     \ingroup shared
434     \ingroup string-processing
435
436     QString stores a string of 16-bit \l{QChar}s, where each QChar
437     corresponds one Unicode 4.0 character. (Unicode characters
438     with code values above 65535 are stored using surrogate pairs,
439     i.e., two consecutive \l{QChar}s.)
440
441     \l{Unicode} is an international standard that supports most of the
442     writing systems in use today. It is a superset of US-ASCII (ANSI
443     X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1
444     characters are available at the same code positions.
445
446     Behind the scenes, QString uses \l{implicit sharing}
447     (copy-on-write) to reduce memory usage and to avoid the needless
448     copying of data. This also helps reduce the inherent overhead of
449     storing 16-bit characters instead of 8-bit characters.
450
451     In addition to QString, Qt also provides the QByteArray class to
452     store raw bytes and traditional 8-bit '\\0'-terminated strings.
453     For most purposes, QString is the class you want to use. It is
454     used throughout the Qt API, and the Unicode support ensures that
455     your applications will be easy to translate if you want to expand
456     your application's market at some point. The two main cases where
457     QByteArray is appropriate are when you need to store raw binary
458     data, and when memory conservation is critical (e.g., with
459     \l{Qt for Embedded Linux}).
460
461     \tableofcontents
462
463     \section1 Initializing a String
464
465     One way to initialize a QString is simply to pass a \c{const char
466     *} to its constructor. For example, the following code creates a
467     QString of size 5 containing the data "Hello":
468
469     \snippet doc/src/snippets/qstring/main.cpp 0
470
471     QString converts the \c{const char *} data into Unicode using the
472     fromAscii() function. By default, fromAscii() treats character
473     above 128 as Latin-1 characters, but this can be changed by
474     calling QTextCodec::setCodecForCStrings().
475
476     In all of the QString functions that take \c{const char *}
477     parameters, the \c{const char *} is interpreted as a classic
478     C-style '\\0'-terminated string. It is legal for the \c{const char
479     *} parameter to be 0.
480
481     You can also provide string data as an array of \l{QChar}s:
482
483     \snippet doc/src/snippets/qstring/main.cpp 1
484
485     QString makes a deep copy of the QChar data, so you can modify it
486     later without experiencing side effects. (If for performance
487     reasons you don't want to take a deep copy of the character data,
488     use QString::fromRawData() instead.)
489
490     Another approach is to set the size of the string using resize()
491     and to initialize the data character per character. QString uses
492     0-based indexes, just like C++ arrays. To access the character at
493     a particular index position, you can use \l operator[](). On
494     non-const strings, \l operator[]() returns a reference to a
495     character that can be used on the left side of an assignment. For
496     example:
497
498     \snippet doc/src/snippets/qstring/main.cpp 2
499
500     For read-only access, an alternative syntax is to use the at()
501     function:
502
503     \snippet doc/src/snippets/qstring/main.cpp 3
504
505     The at() function can be faster than \l operator[](), because it
506     never causes a \l{deep copy} to occur. Alternatively, use the
507     left(), right(), or mid() functions to extract several characters
508     at a time.
509
510     A QString can embed '\\0' characters (QChar::Null). The size()
511     function always returns the size of the whole string, including
512     embedded '\\0' characters.
513
514     After a call to the resize() function, newly allocated characters
515     have undefined values. To set all the characters in the string to
516     a particular value, use the fill() function.
517
518     QString provides dozens of overloads designed to simplify string
519     usage. For example, if you want to compare a QString with a string
520     literal, you can write code like this and it will work as expected:
521
522     \snippet doc/src/snippets/qstring/main.cpp 4
523
524     You can also pass string literals to functions that take QStrings
525     as arguments, invoking the QString(const char *)
526     constructor. Similarly, you can pass a QString to a function that
527     takes a \c{const char *} argument using the \l qPrintable() macro
528     which returns the given QString as a \c{const char *}. This is
529     equivalent to calling <QString>.toLocal8Bit().constData().
530
531     \section1 Manipulating String Data
532
533     QString provides the following basic functions for modifying the
534     character data: append(), prepend(), insert(), replace(), and
535     remove(). For example:
536
537     \snippet doc/src/snippets/qstring/main.cpp 5
538
539     If you are building a QString gradually and know in advance
540     approximately how many characters the QString will contain, you
541     can call reserve(), asking QString to preallocate a certain amount
542     of memory. You can also call capacity() to find out how much
543     memory QString actually allocated.
544
545     The replace() and remove() functions' first two arguments are the
546     position from which to start erasing and the number of characters
547     that should be erased.  If you want to replace all occurrences of
548     a particular substring with another, use one of the two-parameter
549     replace() overloads.
550
551     A frequent requirement is to remove whitespace characters from a
552     string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace
553     from both ends of a QString, use the trimmed() function. If you
554     want to remove whitespace from both ends and replace multiple
555     consecutive whitespaces with a single space character within the
556     string, use simplified().
557
558     If you want to find all occurrences of a particular character or
559     substring in a QString, use the indexOf() or lastIndexOf()
560     functions. The former searches forward starting from a given index
561     position, the latter searches backward. Both return the index
562     position of the character or substring if they find it; otherwise,
563     they return -1.  For example, here's a typical loop that finds all
564     occurrences of a particular substring:
565
566     \snippet doc/src/snippets/qstring/main.cpp 6
567
568     QString provides many functions for converting numbers into
569     strings and strings into numbers. See the arg() functions, the
570     setNum() functions, the number() static functions, and the
571     toInt(), toDouble(), and similar functions.
572
573     To get an upper- or lowercase version of a string use toUpper() or
574     toLower().
575
576     Lists of strings are handled by the QStringList class. You can
577     split a string into a list of strings using the split() function,
578     and join a list of strings into a single string with an optional
579     separator using QStringList::join(). You can obtain a list of
580     strings from a string list that contain a particular substring or
581     that match a particular QRegExp using the QStringList::filter()
582     function.
583
584     \section1 Querying String Data
585
586     If you want to see if a QString starts or ends with a particular
587     substring use startsWith() or endsWith(). If you simply want to
588     check whether a QString contains a particular character or
589     substring, use the contains() function. If you want to find out
590     how many times a particular character or substring occurs in the
591     string, use count().
592
593     QStrings can be compared using overloaded operators such as \l
594     operator<(), \l operator<=(), \l operator==(), \l operator>=(),
595     and so on.  Note that the comparison is based exclusively on the
596     numeric Unicode values of the characters. It is very fast, but is
597     not what a human would expect; the QString::localeAwareCompare()
598     function is a better choice for sorting user-interface strings.
599
600     To obtain a pointer to the actual character data, call data() or
601     constData(). These functions return a pointer to the beginning of
602     the QChar data. The pointer is guaranteed to remain valid until a
603     non-const function is called on the QString.
604
605     \section1 Converting Between 8-Bit Strings and Unicode Strings
606
607     QString provides the following four functions that return a
608     \c{const char *} version of the string as QByteArray: toAscii(),
609     toLatin1(), toUtf8(), and toLocal8Bit().
610
611     \list
612     \o toAscii() returns an 8-bit string encoded using the codec
613        specified by QTextCodec::codecForCStrings (by default, that is
614        Latin 1).
615     \o toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
616     \o toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a
617        superset of US-ASCII (ANSI X3.4-1986) that supports the entire
618        Unicode character set through multibyte sequences.
619     \o toLocal8Bit() returns an 8-bit string using the system's local
620        encoding.
621     \endlist
622
623     To convert from one of these encodings, QString provides
624     fromAscii(), fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other
625     encodings are supported through the QTextCodec class.
626
627     As mentioned above, QString provides a lot of functions and
628     operators that make it easy to interoperate with \c{const char *}
629     strings. But this functionality is a double-edged sword: It makes
630     QString more convenient to use if all strings are US-ASCII or
631     Latin-1, but there is always the risk that an implicit conversion
632     from or to \c{const char *} is done using the wrong 8-bit
633     encoding. To minimize these risks, you can turn off these implicit
634     conversions by defining the following two preprocessor symbols:
635
636     \list
637     \o \c QT_NO_CAST_FROM_ASCII disables automatic conversions from
638        C string literals and pointers to Unicode.
639     \o \c QT_NO_CAST_TO_ASCII disables automatic conversion from QString
640        to C strings.
641     \endlist
642
643     One way to define these preprocessor symbols globally for your
644     application is to add the following entry to your
645     \l{qmake Project Files}{qmake project file}:
646
647     \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 0
648
649     You then need to explicitly call fromAscii(), fromLatin1(),
650     fromUtf8(), or fromLocal8Bit() to construct a QString from an
651     8-bit string, or use the lightweight QLatin1String class, for
652     example:
653
654     \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 1
655
656     Similarly, you must call toAscii(), toLatin1(), toUtf8(), or
657     toLocal8Bit() explicitly to convert the QString to an 8-bit
658     string.  (Other encodings are supported through the QTextCodec
659     class.)
660
661     \table 100 %
662     \header
663     \o Note for C Programmers
664
665     \row
666     \o
667     Due to C++'s type system and the fact that QString is
668     \l{implicitly shared}, QStrings may be treated like \c{int}s or
669     other basic types. For example:
670
671     \snippet doc/src/snippets/qstring/main.cpp 7
672
673     The \c result variable, is a normal variable allocated on the
674     stack. When \c return is called, and because we're returning by
675     value, the copy constructor is called and a copy of the string is
676     returned. No actual copying takes place thanks to the implicit
677     sharing.
678
679     \endtable
680
681     \section1 Distinction Between Null and Empty Strings
682
683     For historical reasons, QString distinguishes between a null
684     string and an empty string. A \e null string is a string that is
685     initialized using QString's default constructor or by passing
686     (const char *)0 to the constructor. An \e empty string is any
687     string with size 0. A null string is always empty, but an empty
688     string isn't necessarily null:
689
690     \snippet doc/src/snippets/qstring/main.cpp 8
691
692     All functions except isNull() treat null strings the same as empty
693     strings. For example, toAscii().constData() returns a pointer to a
694     '\\0' character for a null string (\e not a null pointer), and
695     QString() compares equal to QString(""). We recommend that you
696     always use the isEmpty() function and avoid isNull().
697
698     \section1 Argument Formats
699
700     In member functions where an argument \e format can be specified
701     (e.g., arg(), number()), the argument \e format can be one of the
702     following:
703
704     \table
705     \header \o Format \o Meaning
706     \row \o \c e \o format as [-]9.9e[+|-]999
707     \row \o \c E \o format as [-]9.9E[+|-]999
708     \row \o \c f \o format as [-]9.9
709     \row \o \c g \o use \c e or \c f format, whichever is the most concise
710     \row \o \c G \o use \c E or \c f format, whichever is the most concise
711     \endtable
712
713     A \e precision is also specified with the argument \e format. For
714     the 'e', 'E', and 'f' formats, the \e precision represents the
715     number of digits \e after the decimal point. For the 'g' and 'G'
716     formats, the \e precision represents the maximum number of
717     significant digits (trailing zeroes are omitted).
718
719     \section1 More Efficient String Construction
720
721     Many strings are known at compile time. But the trivial
722     constructor QString("Hello"), will convert the string literal
723     to a QString using the codecForCStrings(). To avoid this one
724     can use the QStringLiteral macro to directly create the required
725     data at compile time. Constructing a QString out of the literal
726     does then not cause any overhead at runtime.
727
728     A slightly less efficient way is to use QLatin1String. This class wraps
729     a C string literal, precalculates it length at compile time and can
730     then be used for faster comparison with QStrings and conversion to
731     QStrings than a regular C string literal.
732
733     Using the QString \c{'+'} operator, it is easy to construct a
734     complex string from multiple substrings. You will often write code
735     like this:
736
737     \snippet doc/src/snippets/qstring/stringbuilder.cpp 0
738
739     There is nothing wrong with either of these string constructions,
740     but there are a few hidden inefficiencies. Beginning with Qt 4.6,
741     you can eliminate them.
742
743     First, multiple uses of the \c{'+'} operator usually means
744     multiple memory allocations. When concatenating \e{n} substrings,
745     where \e{n > 2}, there can be as many as \e{n - 1} calls to the
746     memory allocator.
747
748     In 4.6, an internal template class \c{QStringBuilder} has been
749     added along with a few helper functions. This class is marked
750     internal and does not appear in the documentation, because you
751     aren't meant to instantiate it in your code. Its use will be
752     automatic, as described below. The class is found in
753     \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
754     look at it.
755
756     \c{QStringBuilder} uses expression templates and reimplements the
757     \c{'%'} operator so that when you use \c{'%'} for string
758     concatenation instead of \c{'+'}, multiple substring
759     concatenations will be postponed until the final result is about
760     to be assigned to a QString. At this point, the amount of memory
761     required for the final result is known. The memory allocator is
762     then called \e{once} to get the required space, and the substrings
763     are copied into it one by one.
764
765     Additional efficiency is gained by inlining and reduced reference
766     counting (the QString created from a \c{QStringBuilder} typically
767     has a ref count of 1, whereas QString::append() needs an extra
768     test).
769
770     There are three ways you can access this improved method of string
771     construction. The straightforward way is to include
772     \c{QStringBuilder} wherever you want to use it, and use the
773     \c{'%'} operator instead of \c{'+'} when concatenating strings:
774
775     \snippet doc/src/snippets/qstring/stringbuilder.cpp 5
776
777     A more global approach which is the most convenient but
778     not entirely source compatible, is to this define in your
779     .pro file:
780
781     \snippet doc/src/snippets/qstring/stringbuilder.cpp 3
782
783     and the \c{'+'} will automatically be performed as the
784     \c{QStringBuilder} \c{'%'} everywhere.
785
786     \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
787 */
788
789 /*!
790     \enum QString::SplitBehavior
791
792     This enum specifies how the split() function should behave with
793     respect to empty strings.
794
795     \value KeepEmptyParts  If a field is empty, keep it in the result.
796     \value SkipEmptyParts  If a field is empty, don't include it in the result.
797
798     \sa split()
799 */
800
801 const QConstStringData<1> QString::shared_null = { { Q_REFCOUNT_INITIALIZER(-1), 0, 0, false, { 0 } }, { 0 } };
802 const QConstStringData<1> QString::shared_empty = { { Q_REFCOUNT_INITIALIZER(-1), 0, 0, false, { 0 } }, { 0 } };
803
804 int QString::grow(int size)
805 {
806     return qAllocMore(size * sizeof(QChar), sizeof(Data)) / sizeof(QChar);
807 }
808
809 /*! \typedef QString::ConstIterator
810
811     Qt-style synonym for QString::const_iterator.
812 */
813
814 /*! \typedef QString::Iterator
815
816     Qt-style synonym for QString::iterator.
817 */
818
819 /*! \typedef QString::const_iterator
820
821     The QString::const_iterator typedef provides an STL-style const
822     iterator for QString.
823
824     \sa QString::iterator
825 */
826
827 /*! \typedef QString::iterator
828
829     The QString::iterator typedef provides an STL-style non-const
830     iterator for QString.
831
832     \sa QString::const_iterator
833 */
834
835 /*!
836     \typedef QString::const_reference
837
838     The QString::const_reference typedef provides an STL-style
839     const reference for QString.
840 */
841 /*!
842     \typedef QString::reference
843
844     The QString::const_reference typedef provides an STL-style
845     reference for QString.
846 */
847 /*!
848     \typedef QString::value_type
849
850     The QString::const_reference typedef provides an STL-style
851     value type for QString.
852 */
853
854 /*! \fn QString::iterator QString::begin()
855
856     Returns an \l{STL-style iterator} pointing to the first character in
857     the string.
858
859     \sa constBegin(), end()
860 */
861
862 /*! \fn QString::const_iterator QString::begin() const
863
864     \overload begin()
865 */
866
867 /*! \fn QString::const_iterator QString::constBegin() const
868
869     Returns a const \l{STL-style iterator} pointing to the first character
870     in the string.
871
872     \sa begin(), constEnd()
873 */
874
875 /*! \fn QString::iterator QString::end()
876
877     Returns an \l{STL-style iterator} pointing to the imaginary character
878     after the last character in the string.
879
880     \sa begin(), constEnd()
881 */
882
883 /*! \fn QString::const_iterator QString::end() const
884
885     \overload end()
886 */
887
888 /*! \fn QString::const_iterator QString::constEnd() const
889
890     Returns a const \l{STL-style iterator} pointing to the imaginary
891     item after the last item in the list.
892
893     \sa constBegin(), end()
894 */
895
896 /*!
897     \fn QString::QString()
898
899     Constructs a null string. Null strings are also empty.
900
901     \sa isEmpty()
902 */
903
904 /*! \fn QString::QString(const char *str)
905
906     Constructs a string initialized with the 8-bit string \a str. The
907     given const char pointer is converted to Unicode using the
908     fromAscii() function.
909
910     You can disable this constructor by defining \c
911     QT_NO_CAST_FROM_ASCII when you compile your applications. This
912     can be useful if you want to ensure that all user-visible strings
913     go through QObject::tr(), for example.
914
915     \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
916 */
917
918 /*! \fn QString QString::fromStdString(const std::string &str)
919
920     Returns a copy of the \a str string. The given string is converted
921     to Unicode using the fromAscii() function.
922
923     This constructor is only available if Qt is configured with STL
924     compatibility enabled.
925
926     \sa  fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
927 */
928
929 /*! \fn QString QString::fromStdWString(const std::wstring &str)
930
931     Returns a copy of the \a str string. The given string is assumed
932     to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on
933     windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix
934     systems).
935
936     This method is only available if Qt is configured with STL
937     compatibility enabled.
938
939     \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4()
940 */
941
942 /*! \fn QString QString::fromWCharArray(const wchar_t *string, int size)
943     \since 4.2
944
945     Returns a copy of the \a string, where the encoding of \a string depends on
946     the size of wchar. If wchar is 4 bytes, the \a string is interpreted as ucs-4,
947     if wchar is 2 bytes it is interpreted as ucs-2.
948
949     If \a size is -1 (default), the \a string has to be 0 terminated.
950
951     \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
952 */
953
954 /*! \fn std::wstring QString::toStdWString() const
955
956     Returns a std::wstring object with the data contained in this
957     QString. The std::wstring 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     This operator is mostly useful to pass a QString to a function
962     that accepts a std::wstring object.
963
964     This operator is only available if Qt is configured with STL
965     compatibility enabled.
966
967     \sa utf16(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
968 */
969
970 // ### replace with QCharIterator
971 int QString::toUcs4_helper(const ushort *uc, int length, uint *out)
972 {
973     int i = 0;
974     for (; i < length; ++i) {
975         uint u = uc[i];
976         if (QChar::isHighSurrogate(u) && i + 1 < length) {
977             ushort low = uc[i+1];
978             if (QChar::isLowSurrogate(low)) {
979                 ++i;
980                 u = QChar::surrogateToUcs4(u, low);
981             }
982         }
983         *out++ = u;
984     }
985     return i;
986 }
987
988 /*! \fn int QString::toWCharArray(wchar_t *array) const
989   \since 4.2
990
991   Fills the \a array with the data contained in this QString object.
992   The array is encoded in utf16 on platforms where
993   wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
994   where wchar_t is 4 bytes wide (most Unix systems).
995
996   \a array has to be allocated by the caller and contain enough space to
997   hold the complete string (allocating the array with the same length as the
998   string is always sufficient).
999
1000   returns the actual length of the string in \a array.
1001
1002   \note This function does not append a null character to the array.
1003
1004   \sa utf16(), toUcs4(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString()
1005 */
1006
1007 /*! \fn QString::QString(const QString &other)
1008
1009     Constructs a copy of \a other.
1010
1011     This operation takes \l{constant time}, because QString is
1012     \l{implicitly shared}. This makes returning a QString from a
1013     function very fast. If a shared instance is modified, it will be
1014     copied (copy-on-write), and that takes \l{linear time}.
1015
1016     \sa operator=()
1017 */
1018
1019 /*!
1020     Constructs a string initialized with the first \a size characters
1021     of the QChar array \a unicode.
1022
1023     QString makes a deep copy of the string data. The unicode data is copied as
1024     is and the Byte Order Mark is preserved if present.
1025 */
1026 QString::QString(const QChar *unicode, int size)
1027 {
1028    if (!unicode) {
1029         d = const_cast<Data *>(&shared_null.str);
1030     } else if (size <= 0) {
1031         d = const_cast<Data *>(&shared_empty.str);
1032     } else {
1033         d = (Data*) qMalloc(sizeof(Data)+(size+1)*sizeof(QChar));
1034         Q_CHECK_PTR(d);
1035         d->ref = 1;
1036         d->size = size;
1037         d->alloc = (uint) size;
1038         d->capacityReserved = false;
1039         d->offset = 0;
1040         memcpy(d->data(), unicode, size * sizeof(QChar));
1041         d->data()[size] = '\0';
1042     }
1043 }
1044
1045 /*!
1046     \since 4.7
1047
1048     Constructs a string initialized with the characters of the QChar array
1049     \a unicode, which must be terminated with a 0.
1050
1051     QString makes a deep copy of the string data. The unicode data is copied as
1052     is and the Byte Order Mark is preserved if present.
1053 */
1054 QString::QString(const QChar *unicode)
1055 {
1056      if (!unicode) {
1057          d = const_cast<Data *>(&shared_null.str);
1058      } else {
1059          int size = 0;
1060          while (unicode[size] != 0)
1061              ++size;
1062          if (!size) {
1063              d = const_cast<Data *>(&shared_empty.str);
1064          } else {
1065              d = (Data*) qMalloc(sizeof(Data)+(size+1)*sizeof(QChar));
1066              Q_CHECK_PTR(d);
1067              d->ref = 1;
1068              d->size = size;
1069              d->alloc = (uint) size;
1070              d->capacityReserved = false;
1071              d->offset = 0;
1072              memcpy(d->data(), unicode, size * sizeof(QChar));
1073              d->data()[size] = '\0';
1074          }
1075      }
1076 }
1077
1078
1079 /*!
1080     Constructs a string of the given \a size with every character set
1081     to \a ch.
1082
1083     \sa fill()
1084 */
1085 QString::QString(int size, QChar ch)
1086 {
1087    if (size <= 0) {
1088         d = const_cast<Data *>(&shared_empty.str);
1089     } else {
1090         d = (Data*) qMalloc(sizeof(Data)+(size+1)*sizeof(QChar));
1091         Q_CHECK_PTR(d);
1092         d->ref = 1;
1093         d->size = size;
1094         d->alloc = (uint) size;
1095         d->capacityReserved = false;
1096         d->offset = 0;
1097         d->data()[size] = '\0';
1098         ushort *i = d->data() + size;
1099         ushort *b = d->data();
1100         const ushort value = ch.unicode();
1101         while (i != b)
1102            *--i = value;
1103     }
1104 }
1105
1106 /*! \fn QString::QString(int size, Qt::Initialization)
1107   \internal
1108
1109   Constructs a string of the given \a size without initializing the
1110   characters. This is only used in \c QStringBuilder::toString().
1111 */
1112 QString::QString(int size, Qt::Initialization)
1113 {
1114     d = (Data*) qMalloc(sizeof(Data)+(size+1)*sizeof(QChar));
1115     Q_CHECK_PTR(d);
1116     d->ref = 1;
1117     d->size = size;
1118     d->alloc = (uint) size;
1119     d->capacityReserved = false;
1120     d->offset = 0;
1121     d->data()[size] = '\0';
1122 }
1123
1124 /*! \fn QString::QString(const QLatin1String &str)
1125
1126     Constructs a copy of the Latin-1 string \a str.
1127
1128     \sa fromLatin1()
1129 */
1130
1131 /*!
1132     Constructs a string of size 1 containing the character \a ch.
1133 */
1134 QString::QString(QChar ch)
1135 {
1136     d = (Data *) qMalloc(sizeof(Data) + 2*sizeof(QChar));
1137     Q_CHECK_PTR(d);
1138     d->ref = 1;
1139     d->size = 1;
1140     d->alloc = 1;
1141     d->capacityReserved = false;
1142     d->offset = 0;
1143     d->data()[0] = ch.unicode();
1144     d->data()[1] = '\0';
1145 }
1146
1147 /*! \fn QString::QString(const QByteArray &ba)
1148
1149     Constructs a string initialized with the byte array \a ba. The
1150     given byte array is converted to Unicode using fromAscii(). Stops
1151     copying at the first 0 character, otherwise copies the entire byte
1152     array.
1153
1154     You can disable this constructor by defining \c
1155     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1156     can be useful if you want to ensure that all user-visible strings
1157     go through QObject::tr(), for example.
1158
1159     \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
1160 */
1161
1162 /*! \fn QString::QString(const Null &)
1163     \internal
1164 */
1165
1166 /*! \fn QString &QString::operator=(const Null &)
1167     \internal
1168 */
1169
1170 /*!
1171   \fn QString::~QString()
1172
1173     Destroys the string.
1174 */
1175
1176
1177 /*! \fn void QString::swap(QString &other)
1178     \since 4.8
1179
1180     Swaps string \a other with this string. This operation is very fast and
1181     never fails.
1182 */
1183
1184 /*! \fn void QString::detach()
1185
1186     \internal
1187 */
1188
1189 /*! \fn bool QString::isDetached() const
1190
1191     \internal
1192 */
1193
1194 /*! \fn bool QString::isSharedWith(const QString &other) const
1195
1196     \internal
1197 */
1198
1199 // ### Qt 5: rename freeData() to avoid confusion. See task 197625.
1200 void QString::free(Data *d)
1201 {
1202     qFree(d);
1203 }
1204
1205 /*!
1206     Sets the size of the string to \a size characters.
1207
1208     If \a size is greater than the current size, the string is
1209     extended to make it \a size characters long with the extra
1210     characters added to the end. The new characters are uninitialized.
1211
1212     If \a size is less than the current size, characters are removed
1213     from the end.
1214
1215     Example:
1216
1217     \snippet doc/src/snippets/qstring/main.cpp 45
1218
1219     If you want to append a certain number of identical characters to
1220     the string, use \l operator+=() as follows rather than resize():
1221
1222     \snippet doc/src/snippets/qstring/main.cpp 46
1223
1224     If you want to expand the string so that it reaches a certain
1225     width and fill the new positions with a particular character, use
1226     the leftJustified() function:
1227
1228     If \a size is negative, it is equivalent to passing zero.
1229
1230     \snippet doc/src/snippets/qstring/main.cpp 47
1231
1232     \sa truncate(), reserve()
1233 */
1234
1235 void QString::resize(int size)
1236 {
1237     if (size < 0)
1238         size = 0;
1239
1240     if (d->offset && d->ref == 1 && size < d->size) {
1241         d->size = size;
1242         return;
1243     }
1244
1245     if (size == 0 && !d->capacityReserved) {
1246         Data *x = const_cast<Data *>(&shared_empty.str);
1247         if (!d->ref.deref())
1248             QString::free(d);
1249         d = x;
1250     } else {
1251         if (d->ref != 1 || size > int(d->alloc) ||
1252             (!d->capacityReserved && size < d->size && size < int(d->alloc) >> 1))
1253             realloc(grow(size));
1254         if (int(d->alloc) >= size) {
1255             d->size = size;
1256             d->data()[size] = '\0';
1257         }
1258     }
1259 }
1260
1261 /*! \fn int QString::capacity() const
1262
1263     Returns the maximum number of characters that can be stored in
1264     the string without forcing a reallocation.
1265
1266     The sole purpose of this function is to provide a means of fine
1267     tuning QString's memory usage. In general, you will rarely ever
1268     need to call this function. If you want to know how many
1269     characters are in the string, call size().
1270
1271     \sa reserve(), squeeze()
1272 */
1273
1274 /*!
1275     \fn void QString::reserve(int size)
1276
1277     Attempts to allocate memory for at least \a size characters. If
1278     you know in advance how large the string will be, you can call
1279     this function, and if you resize the string often you are likely
1280     to get better performance. If \a size is an underestimate, the
1281     worst that will happen is that the QString will be a bit slower.
1282
1283     The sole purpose of this function is to provide a means of fine
1284     tuning QString's memory usage. In general, you will rarely ever
1285     need to call this function. If you want to change the size of the
1286     string, call resize().
1287
1288     This function is useful for code that needs to build up a long
1289     string and wants to avoid repeated reallocation. In this example,
1290     we want to add to the string until some condition is true, and
1291     we're fairly sure that size is large enough to make a call to
1292     reserve() worthwhile:
1293
1294     \snippet doc/src/snippets/qstring/main.cpp 44
1295
1296     \sa squeeze(), capacity()
1297 */
1298
1299 /*!
1300     \fn void QString::squeeze()
1301
1302     Releases any memory not required to store the character data.
1303
1304     The sole purpose of this function is to provide a means of fine
1305     tuning QString's memory usage. In general, you will rarely ever
1306     need to call this function.
1307
1308     \sa reserve(), capacity()
1309 */
1310
1311 // ### Qt 5: rename reallocData() to avoid confusion. 197625
1312 void QString::realloc(int alloc)
1313 {
1314     if (d->ref != 1 || d->offset) {
1315         Data *x = static_cast<Data *>(qMalloc(sizeof(Data) + (alloc+1) * sizeof(QChar)));
1316         Q_CHECK_PTR(x);
1317         x->ref = 1;
1318         x->size = qMin(alloc, d->size);
1319         x->alloc = (uint) alloc;
1320         x->capacityReserved = d->capacityReserved;
1321         x->offset =0;
1322         ::memcpy(x->data(), d->data(), x->size * sizeof(QChar));
1323         x->data()[x->size] = 0;
1324         if (!d->ref.deref())
1325             QString::free(d);
1326         d = x;
1327     } else {
1328         Data *p = static_cast<Data *>(qRealloc(d, sizeof(Data) + (alloc+1) * sizeof(QChar)));
1329         Q_CHECK_PTR(p);
1330         d = p;
1331         d->alloc = alloc;
1332         d->offset = 0;
1333     }
1334 }
1335
1336 void QString::realloc()
1337 {
1338     realloc(d->size);
1339 }
1340
1341 void QString::expand(int i)
1342 {
1343     int sz = d->size;
1344     resize(qMax(i + 1, sz));
1345     if (d->size - 1 > sz) {
1346         ushort *n = d->data() + d->size - 1;
1347         ushort *e = d->data() + sz;
1348         while (n != e)
1349            * --n = ' ';
1350     }
1351 }
1352
1353 /*! \fn void QString::clear()
1354
1355     Clears the contents of the string and makes it empty.
1356
1357     \sa resize(), isEmpty()
1358 */
1359
1360 /*! \fn QString &QString::operator=(const QString &other)
1361
1362     Assigns \a other to this string and returns a reference to this
1363     string.
1364 */
1365
1366 QString &QString::operator=(const QString &other)
1367 {
1368     other.d->ref.ref();
1369     if (!d->ref.deref())
1370         QString::free(d);
1371     d = other.d;
1372     return *this;
1373 }
1374
1375
1376 /*! \fn QString &QString::operator=(const QLatin1String &str)
1377
1378     \overload operator=()
1379
1380     Assigns the Latin-1 string \a str to this string.
1381 */
1382
1383 /*! \fn QString &QString::operator=(const QByteArray &ba)
1384
1385     \overload operator=()
1386
1387     Assigns \a ba to this string. The byte array is converted to Unicode
1388     using the fromAscii() function. This function stops conversion at the
1389     first NUL character found, or the end of the \a ba byte array.
1390
1391     You can disable this operator by defining \c
1392     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1393     can be useful if you want to ensure that all user-visible strings
1394     go through QObject::tr(), for example.
1395 */
1396
1397 /*! \fn QString &QString::operator=(const char *str)
1398
1399     \overload operator=()
1400
1401     Assigns \a str to this string. The const char pointer is converted
1402     to Unicode using the fromAscii() function.
1403
1404     You can disable this operator by defining \c
1405     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1406     can be useful if you want to ensure that all user-visible strings
1407     go through QObject::tr(), for example.
1408 */
1409
1410 /*! \fn QString &QString::operator=(char ch)
1411
1412     \overload operator=()
1413
1414     Assigns character \a ch to this string. The character is converted
1415     to Unicode using the fromAscii() function.
1416
1417     You can disable this operator by defining \c
1418     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1419     can be useful if you want to ensure that all user-visible strings
1420     go through QObject::tr(), for example.
1421 */
1422
1423 /*!
1424     \overload operator=()
1425
1426     Sets the string to contain the single character \a ch.
1427 */
1428 QString &QString::operator=(QChar ch)
1429 {
1430     return operator=(QString(ch));
1431 }
1432
1433 /*!
1434      \fn QString& QString::insert(int position, const QString &str)
1435
1436     Inserts the string \a str at the given index \a position and
1437     returns a reference to this string.
1438
1439     Example:
1440
1441     \snippet doc/src/snippets/qstring/main.cpp 26
1442
1443     If the given \a position is greater than size(), the array is
1444     first extended using resize().
1445
1446     \sa append(), prepend(), replace(), remove()
1447 */
1448
1449
1450 /*!
1451     \fn QString &QString::insert(int position, const QLatin1String &str)
1452     \overload insert()
1453
1454     Inserts the Latin-1 string \a str at the given index \a position.
1455 */
1456 QString &QString::insert(int i, const QLatin1String &str)
1457 {
1458     const uchar *s = (const uchar *)str.latin1();
1459     if (i < 0 || !s || !(*s))
1460         return *this;
1461
1462     int len = qstrlen(str.latin1());
1463     expand(qMax(d->size, i) + len - 1);
1464
1465     ::memmove(d->data() + i + len, d->data() + i, (d->size - i - len) * sizeof(QChar));
1466     for (int j = 0; j < len; ++j)
1467         d->data()[i + j] = s[j];
1468     return *this;
1469 }
1470
1471 /*!
1472     \fn QString& QString::insert(int position, const QChar *unicode, int size)
1473     \overload insert()
1474
1475     Inserts the first \a size characters of the QChar array \a unicode
1476     at the given index \a position in the string.
1477 */
1478 QString& QString::insert(int i, const QChar *unicode, int size)
1479 {
1480     if (i < 0 || size <= 0)
1481         return *this;
1482
1483     const ushort *s = (const ushort *)unicode;
1484     if (s >= d->data() && s < d->data() + d->alloc) {
1485         // Part of me - take a copy
1486         ushort *tmp = static_cast<ushort *>(qMalloc(size * sizeof(QChar)));
1487         Q_CHECK_PTR(tmp);
1488         memcpy(tmp, s, size * sizeof(QChar));
1489         insert(i, reinterpret_cast<const QChar *>(tmp), size);
1490         qFree(tmp);
1491         return *this;
1492     }
1493
1494     expand(qMax(d->size, i) + size - 1);
1495
1496     ::memmove(d->data() + i + size, d->data() + i, (d->size - i - size) * sizeof(QChar));
1497     memcpy(d->data() + i, s, size * sizeof(QChar));
1498     return *this;
1499 }
1500
1501 /*!
1502     \fn QString& QString::insert(int position, QChar ch)
1503     \overload insert()
1504
1505     Inserts \a ch at the given index \a position in the string.
1506 */
1507
1508 QString& QString::insert(int i, QChar ch)
1509 {
1510     if (i < 0)
1511         i += d->size;
1512     if (i < 0)
1513         return *this;
1514     expand(qMax(i, d->size));
1515     ::memmove(d->data() + i + 1, d->data() + i, (d->size - i) * sizeof(QChar));
1516     d->data()[i] = ch.unicode();
1517     return *this;
1518 }
1519
1520 /*!
1521     Appends the string \a str onto the end of this string.
1522
1523     Example:
1524
1525     \snippet doc/src/snippets/qstring/main.cpp 9
1526
1527     This is the same as using the insert() function:
1528
1529     \snippet doc/src/snippets/qstring/main.cpp 10
1530
1531     The append() function is typically very fast (\l{constant time}),
1532     because QString preallocates extra space at the end of the string
1533     data so it can grow without reallocating the entire string each
1534     time.
1535
1536     \sa operator+=(), prepend(), insert()
1537 */
1538 QString &QString::append(const QString &str)
1539 {
1540     if (str.d != &shared_null.str) {
1541         if (d == &shared_null.str) {
1542             operator=(str);
1543         } else {
1544             if (d->ref != 1 || d->size + str.d->size > int(d->alloc))
1545                 realloc(grow(d->size + str.d->size));
1546             memcpy(d->data() + d->size, str.d->data(), str.d->size * sizeof(QChar));
1547             d->size += str.d->size;
1548             d->data()[d->size] = '\0';
1549         }
1550     }
1551     return *this;
1552 }
1553
1554 /*!
1555   \overload append()
1556
1557   Appends the Latin-1 string \a str to this string.
1558 */
1559 QString &QString::append(const QLatin1String &str)
1560 {
1561     const uchar *s = (const uchar *)str.latin1();
1562     if (s) {
1563         int len = qstrlen((char *)s);
1564         if (d->ref != 1 || d->size + len > int(d->alloc))
1565             realloc(grow(d->size + len));
1566         ushort *i = d->data() + d->size;
1567         while ((*i++ = *s++))
1568             ;
1569         d->size += len;
1570     }
1571     return *this;
1572 }
1573
1574 /*! \fn QString &QString::append(const QByteArray &ba)
1575
1576     \overload append()
1577
1578     Appends the byte array \a ba to this string. The given byte array
1579     is converted to Unicode using the fromAscii() function.
1580
1581     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1582     when you compile your applications. This can be useful if you want
1583     to ensure that all user-visible strings go through QObject::tr(),
1584     for example.
1585 */
1586
1587 /*! \fn QString &QString::append(const char *str)
1588
1589     \overload append()
1590
1591     Appends the string \a str to this string. The given const char
1592     pointer is converted to Unicode using the fromAscii() function.
1593
1594     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1595     when you compile your applications. This can be useful if you want
1596     to ensure that all user-visible strings go through QObject::tr(),
1597     for example.
1598 */
1599
1600 /*!
1601     \overload append()
1602
1603     Appends the character \a ch to this string.
1604 */
1605 QString &QString::append(QChar ch)
1606 {
1607     if (d->ref != 1 || d->size + 1 > int(d->alloc))
1608         realloc(grow(d->size + 1));
1609     d->data()[d->size++] = ch.unicode();
1610     d->data()[d->size] = '\0';
1611     return *this;
1612 }
1613
1614 /*! \fn QString &QString::prepend(const QString &str)
1615
1616     Prepends the string \a str to the beginning of this string and
1617     returns a reference to this string.
1618
1619     Example:
1620
1621     \snippet doc/src/snippets/qstring/main.cpp 36
1622
1623     \sa append(), insert()
1624 */
1625
1626 /*! \fn QString &QString::prepend(const QLatin1String &str)
1627
1628     \overload prepend()
1629
1630     Prepends the Latin-1 string \a str to this string.
1631 */
1632
1633 /*! \fn QString &QString::prepend(const QByteArray &ba)
1634
1635     \overload prepend()
1636
1637     Prepends the byte array \a ba to this string. The byte array is
1638     converted to Unicode using the fromAscii() function.
1639
1640     You can disable this function by defining \c
1641     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1642     can be useful if you want to ensure that all user-visible strings
1643     go through QObject::tr(), for example.
1644 */
1645
1646 /*! \fn QString &QString::prepend(const char *str)
1647
1648     \overload prepend()
1649
1650     Prepends the string \a str to this string. The const char pointer
1651     is converted to Unicode using the fromAscii() function.
1652
1653     You can disable this function by defining \c
1654     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1655     can be useful if you want to ensure that all user-visible strings
1656     go through QObject::tr(), for example.
1657 */
1658
1659 /*! \fn QString &QString::prepend(QChar ch)
1660
1661     \overload prepend()
1662
1663     Prepends the character \a ch to this string.
1664 */
1665
1666 /*!
1667   \fn QString &QString::remove(int position, int n)
1668
1669   Removes \a n characters from the string, starting at the given \a
1670   position index, and returns a reference to the string.
1671
1672   If the specified \a position index is within the string, but \a
1673   position + \a n is beyond the end of the string, the string is
1674   truncated at the specified \a position.
1675
1676   \snippet doc/src/snippets/qstring/main.cpp 37
1677
1678   \sa insert(), replace()
1679 */
1680 QString &QString::remove(int pos, int len)
1681 {
1682     if (pos < 0)  // count from end of string
1683         pos += d->size;
1684     if (pos < 0 || pos >= d->size) {
1685         // range problems
1686     } else if (len >= d->size - pos) {
1687         resize(pos); // truncate
1688     } else if (len > 0) {
1689         detach();
1690         memmove(d->data() + pos, d->data() + pos + len,
1691                 (d->size - pos - len + 1) * sizeof(ushort));
1692         d->size -= len;
1693     }
1694     return *this;
1695 }
1696
1697 /*!
1698   Removes every occurrence of the given \a str string in this
1699   string, and returns a reference to this string.
1700
1701   If \a cs is Qt::CaseSensitive (default), the search is
1702   case sensitive; otherwise the search is case insensitive.
1703
1704   This is the same as \c replace(str, "", cs).
1705
1706   \sa replace()
1707 */
1708 QString &QString::remove(const QString &str, Qt::CaseSensitivity cs)
1709 {
1710     if (str.d->size) {
1711         int i = 0;
1712         while ((i = indexOf(str, i, cs)) != -1)
1713             remove(i, str.d->size);
1714     }
1715     return *this;
1716 }
1717
1718 /*!
1719   Removes every occurrence of the character \a ch in this string, and
1720   returns a reference to this string.
1721
1722   If \a cs is Qt::CaseSensitive (default), the search is case
1723   sensitive; otherwise the search is case insensitive.
1724
1725   Example:
1726
1727   \snippet doc/src/snippets/qstring/main.cpp 38
1728
1729   This is the same as \c replace(ch, "", cs).
1730
1731   \sa replace()
1732 */
1733 QString &QString::remove(QChar ch, Qt::CaseSensitivity cs)
1734 {
1735     int i = 0;
1736     ushort c = ch.unicode();
1737     if (cs == Qt::CaseSensitive) {
1738         while (i < d->size)
1739             if (d->data()[i] == ch)
1740                 remove(i, 1);
1741             else
1742                 i++;
1743     } else {
1744         c = foldCase(c);
1745         while (i < d->size)
1746             if (foldCase(d->data()[i]) == c)
1747                 remove(i, 1);
1748             else
1749                 i++;
1750     }
1751     return *this;
1752 }
1753
1754 /*!
1755   \fn QString &QString::remove(const QRegExp &rx)
1756
1757   Removes every occurrence of the regular expression \a rx in the
1758   string, and returns a reference to the string. For example:
1759
1760   \snippet doc/src/snippets/qstring/main.cpp 39
1761
1762   \sa indexOf(), lastIndexOf(), replace()
1763 */
1764
1765 /*!
1766   \fn QString &QString::replace(int position, int n, const QString &after)
1767
1768   Replaces \a n characters beginning at index \a position with
1769   the string \a after and returns a reference to this string.
1770
1771   Example:
1772
1773   \snippet doc/src/snippets/qstring/main.cpp 40
1774
1775   \sa insert(), remove()
1776 */
1777 QString &QString::replace(int pos, int len, const QString &after)
1778 {
1779     QString copy = after;
1780     return replace(pos, len, copy.constData(), copy.length());
1781 }
1782
1783 /*!
1784   \fn QString &QString::replace(int position, int n, const QChar *unicode, int size)
1785   \overload replace()
1786   Replaces \a n characters beginning at index \a position with the
1787   first \a size characters of the QChar array \a unicode and returns a
1788   reference to this string.
1789 */
1790 QString &QString::replace(int pos, int len, const QChar *unicode, int size)
1791 {
1792     if (pos < 0 || pos > d->size)
1793         return *this;
1794     if (pos + len > d->size)
1795         len = d->size - pos;
1796
1797     uint index = pos;
1798     replace_helper(&index, 1, len, unicode, size);
1799     return *this;
1800 }
1801
1802 /*!
1803   \fn QString &QString::replace(int position, int n, QChar after)
1804   \overload replace()
1805
1806   Replaces \a n characters beginning at index \a position with the
1807   character \a after and returns a reference to this string.
1808 */
1809 QString &QString::replace(int pos, int len, QChar after)
1810 {
1811     return replace(pos, len, &after, 1);
1812 }
1813
1814 /*!
1815   \overload replace()
1816   Replaces every occurrence of the string \a before with the string \a
1817   after and returns a reference to this string.
1818
1819   If \a cs is Qt::CaseSensitive (default), the search is case
1820   sensitive; otherwise the search is case insensitive.
1821
1822   Example:
1823
1824   \snippet doc/src/snippets/qstring/main.cpp 41
1825
1826   \note The replacement text is not rescanned after it is inserted.
1827
1828   Example:
1829
1830   \snippet doc/src/snippets/qstring/main.cpp 86
1831 */
1832 QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs)
1833 {
1834     return replace(before.constData(), before.size(), after.constData(), after.size(), cs);
1835 }
1836
1837 /*!
1838   \internal
1839  */
1840 void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen)
1841 {
1842     // copy *after in case it lies inside our own d->data() area
1843     // (which we could possibly invalidate via a realloc or corrupt via memcpy operations.)
1844     QChar *afterBuffer = const_cast<QChar *>(after);
1845     if (after >= reinterpret_cast<QChar *>(d->data()) && after < reinterpret_cast<QChar *>(d->data()) + d->size) {
1846         afterBuffer = static_cast<QChar *>(qMalloc(alen*sizeof(QChar)));
1847         Q_CHECK_PTR(afterBuffer);
1848         ::memcpy(afterBuffer, after, alen*sizeof(QChar));
1849     }
1850
1851     QT_TRY {
1852         if (blen == alen) {
1853             // replace in place
1854             detach();
1855             for (int i = 0; i < nIndices; ++i)
1856                 memcpy(d->data() + indices[i], afterBuffer, alen * sizeof(QChar));
1857         } else if (alen < blen) {
1858             // replace from front
1859             detach();
1860             uint to = indices[0];
1861             if (alen)
1862                 memcpy(d->data()+to, after, alen*sizeof(QChar));
1863             to += alen;
1864             uint movestart = indices[0] + blen;
1865             for (int i = 1; i < nIndices; ++i) {
1866                 int msize = indices[i] - movestart;
1867                 if (msize > 0) {
1868                     memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1869                     to += msize;
1870                 }
1871                 if (alen) {
1872                     memcpy(d->data() + to, afterBuffer, alen*sizeof(QChar));
1873                     to += alen;
1874                 }
1875                 movestart = indices[i] + blen;
1876             }
1877             int msize = d->size - movestart;
1878             if (msize > 0)
1879                 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1880             resize(d->size - nIndices*(blen-alen));
1881         } else {
1882             // replace from back
1883             int adjust = nIndices*(alen-blen);
1884             int newLen = d->size + adjust;
1885             int moveend = d->size;
1886             resize(newLen);
1887
1888             while (nIndices) {
1889                 --nIndices;
1890                 int movestart = indices[nIndices] + blen;
1891                 int insertstart = indices[nIndices] + nIndices*(alen-blen);
1892                 int moveto = insertstart + alen;
1893                 memmove(d->data() + moveto, d->data() + movestart,
1894                         (moveend - movestart)*sizeof(QChar));
1895                 memcpy(d->data() + insertstart, afterBuffer, alen*sizeof(QChar));
1896                 moveend = movestart-blen;
1897             }
1898         }
1899     } QT_CATCH(const std::bad_alloc &) {
1900         if (afterBuffer != after)
1901             qFree(afterBuffer);
1902         QT_RETHROW;
1903     }
1904     if (afterBuffer != after)
1905         qFree(afterBuffer);
1906 }
1907
1908 /*!
1909   \since 4.5
1910   \overload replace()
1911
1912   Replaces each occurrence in this string of the first \a blen
1913   characters of \a before with the first \a alen characters of \a
1914   after and returns a reference to this string.
1915
1916   If \a cs is Qt::CaseSensitive (default), the search is case
1917   sensitive; otherwise the search is case insensitive.
1918 */
1919 QString &QString::replace(const QChar *before, int blen,
1920                           const QChar *after, int alen,
1921                           Qt::CaseSensitivity cs)
1922 {
1923     if (d->size == 0) {
1924         if (blen)
1925             return *this;
1926     } else {
1927         if (cs == Qt::CaseSensitive && before == after && blen == alen)
1928             return *this;
1929     }
1930     if (alen == 0 && blen == 0)
1931         return *this;
1932
1933     QStringMatcher matcher(before, blen, cs);
1934
1935     int index = 0;
1936     while (1) {
1937         uint indices[1024];
1938         uint pos = 0;
1939         while (pos < 1023) {
1940             index = matcher.indexIn(*this, index);
1941             if (index == -1)
1942                 break;
1943             indices[pos++] = index;
1944             index += blen;
1945             // avoid infinite loop
1946             if (!blen)
1947                 index++;
1948         }
1949         if (!pos)
1950             break;
1951
1952         replace_helper(indices, pos, blen, after, alen);
1953
1954         if (index == -1)
1955             break;
1956         // index has to be adjusted in case we get back into the loop above.
1957         index += pos*(alen-blen);
1958     }
1959
1960     return *this;
1961 }
1962
1963 /*!
1964   \overload replace()
1965   Replaces every occurrence of the character \a ch in the string with
1966   \a after and returns a reference to this string.
1967
1968   If \a cs is Qt::CaseSensitive (default), the search is case
1969   sensitive; otherwise the search is case insensitive.
1970 */
1971 QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs)
1972 {
1973     if (after.d->size == 0)
1974         return remove(ch, cs);
1975
1976     if (after.d->size == 1)
1977         return replace(ch, after.d->data()[0], cs);
1978
1979     if (d->size == 0)
1980         return *this;
1981
1982     ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode());
1983
1984     int index = 0;
1985     while (1) {
1986         uint indices[1024];
1987         uint pos = 0;
1988         if (cs == Qt::CaseSensitive) {
1989             while (pos < 1023 && index < d->size) {
1990                 if (d->data()[index] == cc)
1991                     indices[pos++] = index;
1992                 index++;
1993             }
1994         } else {
1995             while (pos < 1023 && index < d->size) {
1996                 if (QChar::toCaseFolded(d->data()[index]) == cc)
1997                     indices[pos++] = index;
1998                 index++;
1999             }
2000         }
2001         if (!pos)
2002             break;
2003
2004         replace_helper(indices, pos, 1, after.constData(), after.d->size);
2005
2006         if (index == -1)
2007             break;
2008         // index has to be adjusted in case we get back into the loop above.
2009         index += pos*(after.d->size - 1);
2010     }
2011     return *this;
2012 }
2013
2014 /*!
2015   \overload replace()
2016   Replaces every occurrence of the character \a before with the
2017   character \a after and returns a reference to this string.
2018
2019   If \a cs is Qt::CaseSensitive (default), the search is case
2020   sensitive; otherwise the search is case insensitive.
2021 */
2022 QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs)
2023 {
2024     ushort a = after.unicode();
2025     ushort b = before.unicode();
2026     if (d->size) {
2027         detach();
2028         ushort *i = d->data();
2029         const ushort *e = i + d->size;
2030         if (cs == Qt::CaseSensitive) {
2031             for (; i != e; ++i)
2032                 if (*i == b)
2033                     *i = a;
2034         } else {
2035             b = foldCase(b);
2036             for (; i != e; ++i)
2037                 if (foldCase(*i) == b)
2038                     *i = a;
2039         }
2040     }
2041     return *this;
2042 }
2043
2044 /*!
2045   \since 4.5
2046   \overload replace()
2047
2048   Replaces every occurrence of the string \a before with the string \a
2049   after and returns a reference to this string.
2050
2051   If \a cs is Qt::CaseSensitive (default), the search is case
2052   sensitive; otherwise the search is case insensitive.
2053
2054   \note The text is not rescanned after a replacement.
2055 */
2056 QString &QString::replace(const QLatin1String &before,
2057                           const QLatin1String &after,
2058                           Qt::CaseSensitivity cs)
2059 {
2060     int alen = qstrlen(after.latin1());
2061     QVarLengthArray<ushort> a(alen);
2062     for (int i = 0; i < alen; ++i)
2063         a[i] = (uchar)after.latin1()[i];
2064     int blen = qstrlen(before.latin1());
2065     QVarLengthArray<ushort> b(blen);
2066     for (int i = 0; i < blen; ++i)
2067         b[i] = (uchar)before.latin1()[i];
2068     return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs);
2069 }
2070
2071 /*!
2072   \since 4.5
2073   \overload replace()
2074
2075   Replaces every occurrence of the string \a before with the string \a
2076   after and returns a reference to this string.
2077
2078   If \a cs is Qt::CaseSensitive (default), the search is case
2079   sensitive; otherwise the search is case insensitive.
2080
2081   \note The text is not rescanned after a replacement.
2082 */
2083 QString &QString::replace(const QLatin1String &before,
2084                           const QString &after,
2085                           Qt::CaseSensitivity cs)
2086 {
2087     int blen = before.size();
2088     QVarLengthArray<ushort> b(blen);
2089     for (int i = 0; i < blen; ++i)
2090         b[i] = (uchar)before.latin1()[i];
2091     return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs);
2092 }
2093
2094 /*!
2095   \since 4.5
2096   \overload replace()
2097
2098   Replaces every occurrence of the string \a before with the string \a
2099   after and returns a reference to this string.
2100
2101   If \a cs is Qt::CaseSensitive (default), the search is case
2102   sensitive; otherwise the search is case insensitive.
2103
2104   \note The text is not rescanned after a replacement.
2105 */
2106 QString &QString::replace(const QString &before,
2107                           const QLatin1String &after,
2108                           Qt::CaseSensitivity cs)
2109 {
2110     int alen = after.size();
2111     QVarLengthArray<ushort> a(alen);
2112     for (int i = 0; i < alen; ++i)
2113         a[i] = (uchar)after.latin1()[i];
2114     return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs);
2115 }
2116
2117 /*!
2118   \since 4.5
2119   \overload replace()
2120
2121   Replaces every occurrence of the character \a c with the string \a
2122   after and returns a reference to this string.
2123
2124   If \a cs is Qt::CaseSensitive (default), the search is case
2125   sensitive; otherwise the search is case insensitive.
2126
2127   \note The text is not rescanned after a replacement.
2128 */
2129 QString &QString::replace(QChar c, const QLatin1String &after, Qt::CaseSensitivity cs)
2130 {
2131     int alen = after.size();
2132     QVarLengthArray<ushort> a(alen);
2133     for (int i = 0; i < alen; ++i)
2134         a[i] = (uchar)after.latin1()[i];
2135     return replace(&c, 1, (const QChar *)a.data(), alen, cs);
2136 }
2137
2138
2139 /*!
2140   Returns true if string \a other is equal to this string; otherwise
2141   returns false.
2142
2143   The comparison is based exclusively on the numeric Unicode values of
2144   the characters and is very fast, but is not what a human would
2145   expect. Consider sorting user-interface strings with
2146   localeAwareCompare().
2147 */
2148 bool QString::operator==(const QString &other) const
2149 {
2150     if (d->size != other.d->size)
2151         return false;
2152
2153     return qMemEquals(d->data(), other.d->data(), d->size);
2154 }
2155
2156 /*!
2157     \overload operator==()
2158 */
2159 bool QString::operator==(const QLatin1String &other) const
2160 {
2161     if (d->size != other.size())
2162         return false;
2163
2164     if (!other.size())
2165         return isEmpty();
2166
2167     const ushort *uc = d->data();
2168     const ushort *e = uc + d->size;
2169     const uchar *c = (uchar *)other.latin1();
2170
2171     while (uc < e) {
2172         if (*uc != *c)
2173             return false;
2174         ++uc;
2175         ++c;
2176     }
2177     return true;
2178 }
2179
2180 /*! \fn bool QString::operator==(const QByteArray &other) const
2181
2182     \overload operator==()
2183
2184     The \a other byte array is converted to a QString using the
2185     fromAscii() function. This function stops conversion at the
2186     first NUL character found, or the end of the byte array.
2187
2188     You can disable this operator by defining \c
2189     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2190     can be useful if you want to ensure that all user-visible strings
2191     go through QObject::tr(), for example.
2192 */
2193
2194 /*! \fn bool QString::operator==(const char *other) const
2195
2196     \overload operator==()
2197
2198     The \a other const char pointer is converted to a QString using
2199     the fromAscii() function.
2200
2201     You can disable this operator by defining \c
2202     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2203     can be useful if you want to ensure that all user-visible strings
2204     go through QObject::tr(), for example.
2205 */
2206
2207 /*!
2208     Returns true if this string is lexically less than string \a
2209     other; otherwise returns false.
2210
2211     The comparison is based exclusively on the numeric Unicode values
2212     of the characters and is very fast, but is not what a human would
2213     expect. Consider sorting user-interface strings using the
2214     QString::localeAwareCompare() function.
2215 */
2216 bool QString::operator<(const QString &other) const
2217 {
2218     return ucstrcmp(constData(), length(), other.constData(), other.length()) < 0;
2219 }
2220
2221 /*!
2222     \overload operator<()
2223 */
2224 bool QString::operator<(const QLatin1String &other) const
2225 {
2226     const uchar *c = (uchar *) other.latin1();
2227     if (!c || *c == 0)
2228         return false;
2229
2230     const ushort *uc = d->data();
2231     const ushort *e = uc + qMin(d->size, other.size());
2232
2233     while (uc < e) {
2234         if (*uc != *c)
2235             break;
2236         ++uc;
2237         ++c;
2238     }
2239     return (uc == (d->data() + d->size) ? *c : *uc < *c);
2240 }
2241
2242 /*! \fn bool QString::operator<(const QByteArray &other) const
2243
2244     \overload operator<()
2245
2246     The \a other byte array is converted to a QString using the
2247     fromAscii() function. If any NUL characters ('\0') are embedded
2248     in the byte array, they will be included in the transformation.
2249
2250     You can disable this operator by defining \c
2251     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2252     can be useful if you want to ensure that all user-visible strings
2253     go through QObject::tr(), for example.
2254 */
2255
2256 /*! \fn bool QString::operator<(const char *other) const
2257
2258     \overload operator<()
2259
2260     The \a other const char pointer is converted to a QString using
2261     the fromAscii() function.
2262
2263     You can disable this operator by defining \c
2264     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2265     can be useful if you want to ensure that all user-visible strings
2266     go through QObject::tr(), for example.
2267 */
2268
2269 /*! \fn bool QString::operator<=(const QString &other) const
2270
2271     Returns true if this string is lexically less than or equal to
2272     string \a other; otherwise returns false.
2273
2274     The comparison is based exclusively on the numeric Unicode values
2275     of the characters and is very fast, but is not what a human would
2276     expect. Consider sorting user-interface strings with
2277     localeAwareCompare().
2278 */
2279
2280 /*! \fn bool QString::operator<=(const QLatin1String &other) const
2281
2282     \overload operator<=()
2283 */
2284
2285 /*! \fn bool QString::operator<=(const QByteArray &other) const
2286
2287     \overload operator<=()
2288
2289     The \a other byte array is converted to a QString using the
2290     fromAscii() function. If any NUL characters ('\0') are embedded
2291     in the byte array, they will be included in the transformation.
2292
2293     You can disable this operator by defining \c
2294     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2295     can be useful if you want to ensure that all user-visible strings
2296     go through QObject::tr(), for example.
2297 */
2298
2299 /*! \fn bool QString::operator<=(const char *other) const
2300
2301     \overload operator<=()
2302
2303     The \a other const char pointer is converted to a QString using
2304     the fromAscii() function.
2305
2306     You can disable this operator by defining \c
2307     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2308     can be useful if you want to ensure that all user-visible strings
2309     go through QObject::tr(), for example.
2310 */
2311
2312 /*! \fn bool QString::operator>(const QString &other) const
2313
2314     Returns true if this string is lexically greater than string \a
2315     other; otherwise returns false.
2316
2317     The comparison is based exclusively on the numeric Unicode values
2318     of the characters and is very fast, but is not what a human would
2319     expect. Consider sorting user-interface strings with
2320     localeAwareCompare().
2321 */
2322
2323 /*!
2324     \overload operator>()
2325 */
2326 bool QString::operator>(const QLatin1String &other) const
2327 {
2328     const uchar *c = (uchar *) other.latin1();
2329     if (!c || *c == '\0')
2330         return !isEmpty();
2331
2332     const ushort *uc = d->data();;
2333     const ushort *e = uc + qMin(d->size, other.size());
2334
2335     while (uc < e) {
2336         if (*uc != *c)
2337             break;
2338         ++uc;
2339         ++c;
2340     }
2341     return (uc == (d->data() + d->size) ? false : *uc > *c);
2342 }
2343
2344 /*! \fn bool QString::operator>(const QByteArray &other) const
2345
2346     \overload operator>()
2347
2348     The \a other byte array is converted to a QString using the
2349     fromAscii() function. If any NUL characters ('\0') are embedded
2350     in the byte array, they will be included in the transformation.
2351
2352     You can disable this operator by defining \c
2353     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2354     can be useful if you want to ensure that all user-visible strings
2355     go through QObject::tr(), for example.
2356 */
2357
2358 /*! \fn bool QString::operator>(const char *other) const
2359
2360     \overload operator>()
2361
2362     The \a other const char pointer is converted to a QString using
2363     the fromAscii() function.
2364
2365     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2366     when you compile your applications. This can be useful if you want
2367     to ensure that all user-visible strings go through QObject::tr(),
2368     for example.
2369 */
2370
2371 /*! \fn bool QString::operator>=(const QString &other) const
2372
2373     Returns true if this string is lexically greater than or equal to
2374     string \a other; otherwise returns false.
2375
2376     The comparison is based exclusively on the numeric Unicode values
2377     of the characters and is very fast, but is not what a human would
2378     expect. Consider sorting user-interface strings with
2379     localeAwareCompare().
2380 */
2381
2382 /*! \fn bool QString::operator>=(const QLatin1String &other) const
2383
2384     \overload operator>=()
2385 */
2386
2387 /*! \fn bool QString::operator>=(const QByteArray &other) const
2388
2389     \overload operator>=()
2390
2391     The \a other byte array is converted to a QString using the
2392     fromAscii() function. If any NUL characters ('\0') are embedded in
2393     the byte array, they will be included in the transformation.
2394
2395     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2396     when you compile your applications. This can be useful if you want
2397     to ensure that all user-visible strings go through QObject::tr(),
2398     for example.
2399 */
2400
2401 /*! \fn bool QString::operator>=(const char *other) const
2402
2403     \overload operator>=()
2404
2405     The \a other const char pointer is converted to a QString using
2406     the fromAscii() function.
2407
2408     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2409     when you compile your applications. This can be useful if you want
2410     to ensure that all user-visible strings go through QObject::tr(),
2411     for example.
2412 */
2413
2414 /*! \fn bool QString::operator!=(const QString &other) const
2415
2416     Returns true if this string is not equal to string \a other;
2417     otherwise returns false.
2418
2419     The comparison is based exclusively on the numeric Unicode values
2420     of the characters and is very fast, but is not what a human would
2421     expect. Consider sorting user-interface strings with
2422     localeAwareCompare().
2423 */
2424
2425 /*! \fn bool QString::operator!=(const QLatin1String &other) const
2426
2427     \overload operator!=()
2428 */
2429
2430 /*! \fn bool QString::operator!=(const QByteArray &other) const
2431
2432     \overload operator!=()
2433
2434     The \a other byte array is converted to a QString using the
2435     fromAscii() function. If any NUL characters ('\0') are embedded
2436     in the byte array, they will be included in the transformation.
2437
2438     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2439     when you compile your applications. This can be useful if you want
2440     to ensure that all user-visible strings go through QObject::tr(),
2441     for example.
2442 */
2443
2444 /*! \fn bool QString::operator!=(const char *other) const
2445
2446     \overload operator!=()
2447
2448     The \a other const char pointer is converted to a QString using
2449     the fromAscii() function.
2450
2451     You can disable this operator by defining \c
2452     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2453     can be useful if you want to ensure that all user-visible strings
2454     go through QObject::tr(), for example.
2455 */
2456
2457 /*!
2458   Returns the index position of the first occurrence of the string \a
2459   str in this string, searching forward from index position \a
2460   from. Returns -1 if \a str is not found.
2461
2462   If \a cs is Qt::CaseSensitive (default), the search is case
2463   sensitive; otherwise the search is case insensitive.
2464
2465   Example:
2466
2467   \snippet doc/src/snippets/qstring/main.cpp 24
2468
2469   If \a from is -1, the search starts at the last character; if it is
2470   -2, at the next to last character and so on.
2471
2472   \sa lastIndexOf(), contains(), count()
2473 */
2474 int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2475 {
2476     return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2477 }
2478
2479 /*!
2480   \since 4.5
2481   Returns the index position of the first occurrence of the string \a
2482   str in this string, searching forward from index position \a
2483   from. Returns -1 if \a str is not found.
2484
2485   If \a cs is Qt::CaseSensitive (default), the search is case
2486   sensitive; otherwise the search is case insensitive.
2487
2488   Example:
2489
2490   \snippet doc/src/snippets/qstring/main.cpp 24
2491
2492   If \a from is -1, the search starts at the last character; if it is
2493   -2, at the next to last character and so on.
2494
2495   \sa lastIndexOf(), contains(), count()
2496 */
2497
2498 int QString::indexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2499 {
2500     return qt_find_latin1_string(unicode(), size(), str, from, cs);
2501 }
2502
2503 int qFindString(
2504     const QChar *haystack0, int haystackLen, int from,
2505     const QChar *needle0, int needleLen, Qt::CaseSensitivity cs)
2506 {
2507     const int l = haystackLen;
2508     const int sl = needleLen;
2509     if (from < 0)
2510         from += l;
2511     if (uint(sl + from) > (uint)l)
2512         return -1;
2513     if (!sl)
2514         return from;
2515     if (!l)
2516         return -1;
2517
2518     if (sl == 1)
2519         return findChar(haystack0, haystackLen, needle0[0], from, cs);
2520
2521     /*
2522         We use the Boyer-Moore algorithm in cases where the overhead
2523         for the skip table should pay off, otherwise we use a simple
2524         hash function.
2525     */
2526     if (l > 500 && sl > 5)
2527         return qFindStringBoyerMoore(haystack0, haystackLen, from,
2528             needle0, needleLen, cs);
2529
2530     /*
2531         We use some hashing for efficiency's sake. Instead of
2532         comparing strings, we compare the hash value of str with that
2533         of a part of this QString. Only if that matches, we call
2534         ucstrncmp() or ucstrnicmp().
2535     */
2536     const ushort *needle = (const ushort *)needle0;
2537     const ushort *haystack = (const ushort *)haystack0 + from;
2538     const ushort *end = (const ushort *)haystack0 + (l-sl);
2539     const int sl_minus_1 = sl-1;
2540     int hashNeedle = 0, hashHaystack = 0, idx;
2541
2542     if (cs == Qt::CaseSensitive) {
2543         for (idx = 0; idx < sl; ++idx) {
2544             hashNeedle = ((hashNeedle<<1) + needle[idx]);
2545             hashHaystack = ((hashHaystack<<1) + haystack[idx]);
2546         }
2547         hashHaystack -= haystack[sl_minus_1];
2548
2549         while (haystack <= end) {
2550             hashHaystack += haystack[sl_minus_1];
2551             if (hashHaystack == hashNeedle
2552                  && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2553                 return haystack - (const ushort *)haystack0;
2554
2555             REHASH(*haystack);
2556             ++haystack;
2557         }
2558     } else {
2559         const ushort *haystack_start = (const ushort *)haystack0;
2560         for (idx = 0; idx < sl; ++idx) {
2561             hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle);
2562             hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start);
2563         }
2564         hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start);
2565
2566         while (haystack <= end) {
2567             hashHaystack += foldCase(haystack + sl_minus_1, haystack_start);
2568             if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2569                 return haystack - (const ushort *)haystack0;
2570
2571             REHASH(foldCase(haystack, haystack_start));
2572             ++haystack;
2573         }
2574     }
2575     return -1;
2576 }
2577
2578 /*!
2579     \overload indexOf()
2580
2581     Returns the index position of the first occurrence of the
2582     character \a ch in the string, searching forward from index
2583     position \a from. Returns -1 if \a ch could not be found.
2584 */
2585 int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2586 {
2587     return findChar(unicode(), length(), ch, from, cs);
2588 }
2589
2590 /*!
2591     \since 4.8
2592
2593     \overload indexOf()
2594
2595     Returns the index position of the first occurrence of the string
2596     reference \a str in this string, searching forward from index
2597     position \a from. Returns -1 if \a str is not found.
2598
2599     If \a cs is Qt::CaseSensitive (default), the search is case
2600     sensitive; otherwise the search is case insensitive.
2601 */
2602 int QString::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2603 {
2604     return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2605 }
2606
2607 static int lastIndexOfHelper(const ushort *haystack, int from, const ushort *needle, int sl, Qt::CaseSensitivity cs)
2608 {
2609     /*
2610         See indexOf() for explanations.
2611     */
2612
2613     const ushort *end = haystack;
2614     haystack += from;
2615     const int sl_minus_1 = sl-1;
2616     const ushort *n = needle+sl_minus_1;
2617     const ushort *h = haystack+sl_minus_1;
2618     int hashNeedle = 0, hashHaystack = 0, idx;
2619
2620     if (cs == Qt::CaseSensitive) {
2621         for (idx = 0; idx < sl; ++idx) {
2622             hashNeedle = ((hashNeedle<<1) + *(n-idx));
2623             hashHaystack = ((hashHaystack<<1) + *(h-idx));
2624         }
2625         hashHaystack -= *haystack;
2626
2627         while (haystack >= end) {
2628             hashHaystack += *haystack;
2629             if (hashHaystack == hashNeedle
2630                  && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2631                 return haystack - end;
2632             --haystack;
2633             REHASH(haystack[sl]);
2634         }
2635     } else {
2636         for (idx = 0; idx < sl; ++idx) {
2637             hashNeedle = ((hashNeedle<<1) + foldCase(n-idx, needle));
2638             hashHaystack = ((hashHaystack<<1) + foldCase(h-idx, end));
2639         }
2640         hashHaystack -= foldCase(haystack, end);
2641
2642         while (haystack >= end) {
2643             hashHaystack += foldCase(haystack, end);
2644             if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2645                 return haystack - end;
2646             --haystack;
2647             REHASH(foldCase(haystack + sl, end));
2648         }
2649     }
2650     return -1;
2651 }
2652
2653 /*!
2654   Returns the index position of the last occurrence of the string \a
2655   str in this string, searching backward from index position \a
2656   from. If \a from is -1 (default), the search starts at the last
2657   character; if \a from is -2, at the next to last character and so
2658   on. Returns -1 if \a str is not found.
2659
2660   If \a cs is Qt::CaseSensitive (default), the search is case
2661   sensitive; otherwise the search is case insensitive.
2662
2663   Example:
2664
2665   \snippet doc/src/snippets/qstring/main.cpp 29
2666
2667   \sa indexOf(), contains(), count()
2668 */
2669 int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2670 {
2671     const int sl = str.d->size;
2672     if (sl == 1)
2673         return lastIndexOf(QChar(str.d->data()[0]), from, cs);
2674
2675     const int l = d->size;
2676     if (from < 0)
2677         from += l;
2678     int delta = l-sl;
2679     if (from == l && sl == 0)
2680         return from;
2681     if (from < 0 || from >= l || delta < 0)
2682         return -1;
2683     if (from > delta)
2684         from = delta;
2685
2686     return lastIndexOfHelper(d->data(), from, str.d->data(), str.d->size, cs);
2687 }
2688
2689 /*!
2690   \since 4.5
2691   \overload lastIndexOf()
2692
2693   Returns the index position of the last occurrence of the string \a
2694   str in this string, searching backward from index position \a
2695   from. If \a from is -1 (default), the search starts at the last
2696   character; if \a from is -2, at the next to last character and so
2697   on. Returns -1 if \a str is not found.
2698
2699   If \a cs is Qt::CaseSensitive (default), the search is case
2700   sensitive; otherwise the search is case insensitive.
2701
2702   Example:
2703
2704   \snippet doc/src/snippets/qstring/main.cpp 29
2705
2706   \sa indexOf(), contains(), count()
2707 */
2708 int QString::lastIndexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2709 {
2710     const int sl = str.size();
2711     if (sl == 1)
2712         return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
2713
2714     const int l = d->size;
2715     if (from < 0)
2716         from += l;
2717     int delta = l-sl;
2718     if (from == l && sl == 0)
2719         return from;
2720     if (from < 0 || from >= l || delta < 0)
2721         return -1;
2722     if (from > delta)
2723         from = delta;
2724
2725     QVarLengthArray<ushort> s(sl);
2726     for (int i = 0; i < sl; ++i)
2727         s[i] = str.latin1()[i];
2728
2729     return lastIndexOfHelper(d->data(), from, s.data(), sl, cs);
2730 }
2731
2732 /*!
2733   \overload lastIndexOf()
2734
2735   Returns the index position of the last occurrence of the character
2736   \a ch, searching backward from position \a from.
2737 */
2738 int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2739 {
2740     return qt_last_index_of(unicode(), size(), ch, from, cs);
2741     }
2742
2743 /*!
2744   \since 4.8
2745   \overload lastIndexOf()
2746
2747   Returns the index position of the last occurrence of the string
2748   reference \a str in this string, searching backward from index
2749   position \a from. If \a from is -1 (default), the search starts at
2750   the last character; if \a from is -2, at the next to last character
2751   and so on. Returns -1 if \a str is not found.
2752
2753   If \a cs is Qt::CaseSensitive (default), the search is case
2754   sensitive; otherwise the search is case insensitive.
2755
2756   \sa indexOf(), contains(), count()
2757 */
2758 int QString::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2759 {
2760     const int sl = str.size();
2761     if (sl == 1)
2762         return lastIndexOf(str.at(0), from, cs);
2763
2764     const int l = d->size;
2765     if (from < 0)
2766         from += l;
2767     int delta = l - sl;
2768     if (from == l && sl == 0)
2769         return from;
2770     if (from < 0 || from >= l || delta < 0)
2771     return -1;
2772     if (from > delta)
2773         from = delta;
2774
2775     return lastIndexOfHelper(d->data(), from, reinterpret_cast<const ushort*>(str.unicode()),
2776                              str.size(), cs);
2777 }
2778
2779 #ifndef QT_NO_REGEXP
2780 struct QStringCapture
2781 {
2782     int pos;
2783     int len;
2784     int no;
2785 };
2786
2787 /*!
2788   \overload replace()
2789
2790   Replaces every occurrence of the regular expression \a rx in the
2791   string with \a after. Returns a reference to the string. For
2792   example:
2793
2794   \snippet doc/src/snippets/qstring/main.cpp 42
2795
2796   For regular expressions containing \l{capturing parentheses},
2797   occurrences of \bold{\\1}, \bold{\\2}, ..., in \a after are replaced
2798   with \a{rx}.cap(1), cap(2), ...
2799
2800   \snippet doc/src/snippets/qstring/main.cpp 43
2801
2802   \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap()
2803 */
2804 QString& QString::replace(const QRegExp &rx, const QString &after)
2805 {
2806     QRegExp rx2(rx);
2807
2808     if (isEmpty() && rx2.indexIn(*this) == -1)
2809         return *this;
2810
2811     realloc();
2812
2813     int index = 0;
2814     int numCaptures = rx2.captureCount();
2815     int al = after.length();
2816     QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
2817
2818     if (numCaptures > 0) {
2819         const QChar *uc = after.unicode();
2820         int numBackRefs = 0;
2821
2822         for (int i = 0; i < al - 1; i++) {
2823             if (uc[i] == QLatin1Char('\\')) {
2824                 int no = uc[i + 1].digitValue();
2825                 if (no > 0 && no <= numCaptures)
2826                     numBackRefs++;
2827             }
2828         }
2829
2830         /*
2831             This is the harder case where we have back-references.
2832         */
2833         if (numBackRefs > 0) {
2834             QVarLengthArray<QStringCapture, 16> captures(numBackRefs);
2835             int j = 0;
2836
2837             for (int i = 0; i < al - 1; i++) {
2838                 if (uc[i] == QLatin1Char('\\')) {
2839                     int no = uc[i + 1].digitValue();
2840                     if (no > 0 && no <= numCaptures) {
2841                         QStringCapture capture;
2842                         capture.pos = i;
2843                         capture.len = 2;
2844
2845                         if (i < al - 2) {
2846                             int secondDigit = uc[i + 2].digitValue();
2847                             if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
2848                                 no = (no * 10) + secondDigit;
2849                                 ++capture.len;
2850                             }
2851                         }
2852
2853                         capture.no = no;
2854                         captures[j++] = capture;
2855                     }
2856                 }
2857             }
2858
2859             while (index <= length()) {
2860                 index = rx2.indexIn(*this, index, caretMode);
2861                 if (index == -1)
2862                     break;
2863
2864                 QString after2(after);
2865                 for (j = numBackRefs - 1; j >= 0; j--) {
2866                     const QStringCapture &capture = captures[j];
2867                     after2.replace(capture.pos, capture.len, rx2.cap(capture.no));
2868                 }
2869
2870                 replace(index, rx2.matchedLength(), after2);
2871                 index += after2.length();
2872
2873                 // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*"))
2874                 if (rx2.matchedLength() == 0)
2875                     ++index;
2876
2877                 caretMode = QRegExp::CaretWontMatch;
2878             }
2879             return *this;
2880         }
2881     }
2882
2883     /*
2884         This is the simple and optimized case where we don't have
2885         back-references.
2886     */
2887     while (index != -1) {
2888         struct {
2889             int pos;
2890             int length;
2891         } replacements[2048];
2892
2893         int pos = 0;
2894         int adjust = 0;
2895         while (pos < 2047) {
2896             index = rx2.indexIn(*this, index, caretMode);
2897             if (index == -1)
2898                 break;
2899             int ml = rx2.matchedLength();
2900             replacements[pos].pos = index;
2901             replacements[pos++].length = ml;
2902             index += ml;
2903             adjust += al - ml;
2904             // avoid infinite loop
2905             if (!ml)
2906                 index++;
2907         }
2908         if (!pos)
2909             break;
2910         replacements[pos].pos = d->size;
2911         int newlen = d->size + adjust;
2912
2913         // to continue searching at the right position after we did
2914         // the first round of replacements
2915         if (index != -1)
2916             index += adjust;
2917         QString newstring;
2918         newstring.reserve(newlen + 1);
2919         QChar *newuc = newstring.data();
2920         QChar *uc = newuc;
2921         int copystart = 0;
2922         int i = 0;
2923         while (i < pos) {
2924             int copyend = replacements[i].pos;
2925             int size = copyend - copystart;
2926             memcpy(uc, d->data() + copystart, size * sizeof(QChar));
2927             uc += size;
2928             memcpy(uc, after.d->data(), al * sizeof(QChar));
2929             uc += al;
2930             copystart = copyend + replacements[i].length;
2931             i++;
2932         }