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