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
100	QT_BEGIN_NAMESPACE
101
102	#ifndef QT_NO_TEXTCODEC
103	QTextCodec *QString::codecForCStrings;
104	#endif
105
106	#ifdef QT3_SUPPORT
107	static QHash<void *, QByteArray> *asciiCache = 0;
108	Q_GLOBAL_STATIC(QMutex, asciiCacheMutex)
109
110	#endif
111
112	#ifdef QT_USE_ICU
113	// qlocale_icu.cpp
114	extern bool qt_ucol_strcoll(const QChar *source, int sourceLength, const QChar *target, int targetLength, int *result);
115	#endif
116
117	// internal
118	int qFindString(const QChar *haystack, int haystackLen, int from,
119	const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
120	int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from,
121	const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
122	static inline int qt_last_index_of(const QChar *haystack, int haystackLen, const QChar &needle,
123	int from, Qt::CaseSensitivity cs);
124	static inline int qt_string_count(const QChar *haystack, int haystackLen,
125	const QChar *needle, int needleLen,
126	Qt::CaseSensitivity cs);
127	static inline int qt_string_count(const QChar *haystack, int haystackLen,
128	const QChar &needle, Qt::CaseSensitivity cs);
129	static inline int qt_find_latin1_string(const QChar *hay, int size, const QLatin1String &needle,
130	int from, Qt::CaseSensitivity cs);
131	static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
132	const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
133	static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
134	const QLatin1String &needle, Qt::CaseSensitivity cs);
135	static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
136	const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
137	static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
138	const QLatin1String &needle, Qt::CaseSensitivity cs);
139
140	// Unicode case-insensitive comparison
141	static 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
175	static 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
201	static 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
211	static 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
221	static 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
273	static 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	*/
330	static 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
359	inline bool qIsUpper(char ch)
360	{
361	return ch >= 'A' && ch <= 'Z';
362	}
363
364	inline bool qIsDigit(char ch)
365	{
366	return ch >= '0' && ch <= '9';
367	}
368
369	inline char qToLower(char ch)
370	{
371	if (ch >= 'A' && ch <= 'Z')
372	return ch - 'A' + 'a';
373	else
374	return ch;
375	}
376
377	const 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
804	QString::Data QString::shared_null = { Q_BASIC_ATOMIC_INITIALIZER(1),
805	0, 0, shared_null.array, 0, 0, 0, 0, 0, 0, {0} };
806	QString::Data QString::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1),
807	0, 0, shared_empty.array, 0, 0, 0, 0, 0, 0, {0} };
808
809	int 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	*/
961	QString 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
986	template<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	*/
1022	int 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	*/
1051	QString::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	*/
1080	QString::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	*/
1112	QString::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	*/
1139	QString::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	*/
1160	QString::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.
1226	void 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
1268	void 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
1343	void 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
1378	void QString::realloc()
1379	{
1380	realloc(d->size);
1381	}
1382
1383	void 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
1408	QString &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	*/
1470	QString &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	*/
1498	QString &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	*/
1520	QString& 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
1550	QString& 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	*/
1580	QString &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	*/
1601	QString &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	*/
1647	QString &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	*/
1722	QString &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	*/
1750	QString &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	*/
1775	QString &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	*/
1819	QString &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	*/
1832	QString &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	*/
1851	QString &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	*/
1874	QString &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	*/
1882	void 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	*/
1961	QString &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	*/
2013	QString& 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	*/
2064	QString& 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	*/
2098	QString &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	*/
2125	QString &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	*/
2148	QString &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	*/
2171	QString &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	*/
2190	bool 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	*/
2201	bool 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	*/
2255	bool QString::operator<(const QString &other) const
2256	{
2257	return ucstrcmp(constData(), length(), other.constData(), other.length()) < 0;
2258	}
2259
2260	/*!
2261	\overload operator<()
2262	*/
2263	bool 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	*/
2365	bool 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	*/
2513	int 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
2537	int 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
2542	int 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	*/
2624	int 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	*/
2641	int 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
2646	static 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	*/
2708	int 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	*/
2747	int 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	*/
2777	int 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	*/
2797	int 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
2819	struct 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	*/
2843	QString& 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
2991	int 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
3002	int 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	*/
3018	int 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	*/
3089	int 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	*/
3110	int 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	*/
3126	int 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	*/
3147	int 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	*/
3164	int 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
3252	QString 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
3300	class qt_section_chunk {
3301	public:
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	*/
3320	QString 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	*/
3387	QString 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	*/
3405	QString 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
3429	QString 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	*/
3457	bool 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	*/
3466	bool 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	*/
3477	bool 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	*/
3496	bool 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	*/
3513	bool 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	*/
3530	bool 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	*/
3540	bool 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	*/
3551	bool 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)
3584	static 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
3638	static 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	*/
3707	QByteArray 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	*/
3728	QByteArray 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)
3738	static 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	*/
3763	QByteArray 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	*/
3788	QByteArray 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	*/
3806	QVector<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
3815	QString::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
3866	QString::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	*/
3899	QString 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	*/
3910	const 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	*/
3928	const 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	*/
3956	QString 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	*/
3987	QString 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	*/
4013	QString 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	*/
4040	QString 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	*/
4064	QString 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	*/
4085	QString& 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	*/
4123	QString 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	*/
4214	QString 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
4276	Returns the character at the specified \a position in the string as a
4277	modifiable 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
4302	void 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	*/
4322	void 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
4340	QString& 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	*/
4685	int 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	*/
4696	int 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	*/
4707	int 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	*/
4723	int 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	*/
4746	int 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	*/
4836	int 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)
4842	QT_END_NAMESPACE
4843	#include "qt_windows.h"
4844	QT_BEGIN_NAMESPACE
4845	#endif
4846
4847	/*!
4848	\internal
4849	\since 4.5
4850	*/
4851	int 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
4929	const 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
4957	QString 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
4996	QString 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
5028	QString 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	*/
5080	QString 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
5122	QString 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
5206	QString &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
5226	QString &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
5579	\sa number(), toULongLong(), toInt()
5580	*/
5581
5582	qint64 QString::toLongLong(bool *ok, int base) const
5583	{
5584	#if defined(QT_CHECK_RANGE)
5585	if (base != 0 && (base < 2 || base > 36)) {
5586	qWarning("QString::toLongLong: Invalid base (%d)", base);
5587	base = 10;
5588	}
5589	#endif
5590
5591	bool my_ok;
5592	QLocale def_locale;
5593	qint64 result = def_locale.d()->stringToLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5594	if (my_ok) {
5595	if (ok != 0)
5596	*ok = true;
5597	return result;
5598	}
5599
5600	QLocale c_locale(QLocale::C);
5601	return c_locale.d()->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5602	}
5603
5604	/*!
5605	Returns the string converted to an \c{unsigned long long} using base \a
5606	base, which is 10 by default and must be between 2 and 36, or 0.
5607	Returns 0 if the conversion fails.
5608
5609	If a conversion error occurs, *\a{ok} is set to false; otherwise
5610	*\a{ok} is set to true.
5611
5612	If \a base is 0, the C language convention is used: If the string
5613	begins with "0x", base 16 is used; if the string begins with "0",
5614	base 8 is used; otherwise, base 10 is used.
5615
5616	Example:
5617
5618	\snippet doc/src/snippets/qstring/main.cpp 79
5619
5620	\sa number(), toLongLong()
5621	*/
5622
5623	quint64 QString::toULongLong(bool *ok, int base) const
5624	{
5625	#if defined(QT_CHECK_RANGE)
5626	if (base != 0 && (base < 2 || base > 36)) {
5627	qWarning("QString::toULongLong: Invalid base (%d)", base);
5628	base = 10;
5629	}
5630	#endif
5631
5632	bool my_ok;
5633	QLocale def_locale;
5634	quint64 result = def_locale.d()->stringToUnsLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5635	if (my_ok) {
5636	if (ok != 0)
5637	*ok = true;
5638	return result;
5639	}
5640
5641	QLocale c_locale(QLocale::C);
5642	return c_locale.d()->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5643	}
5644
5645	/*!
5646	\fn long QString::toLong(bool *ok, int base) const
5647
5648	Returns the string converted to a \c long using base \a
5649	base, which is 10 by default and must be between 2 and 36, or 0.
5650	Returns 0 if the conversion fails.
5651
5652	If a conversion error occurs, *\a{ok} is set to false; otherwise
5653	*\a{ok} is set to true.
5654
5655	If \a base is 0, the C language convention is used: If the string
5656	begins with "0x", base 16 is used; if the string begins with "0",
5657	base 8 is used; otherwise, base 10 is used.
5658
5659	Example:
5660
5661	\snippet doc/src/snippets/qstring/main.cpp 73
5662
5663	\sa number(), toULong(), toInt()
5664	*/
5665
5666	long QString::toLong(bool *ok, int base) const
5667	{
5668	qint64 v = toLongLong(ok, base);
5669	if (v < LONG_MIN || v > LONG_MAX) {
5670	if (ok)
5671	*ok = false;
5672	v = 0;
5673	}
5674	return (long)v;
5675	}
5676
5677	/*!
5678	\fn ulong QString::toULong(bool *ok, int base) const
5679
5680	Returns the string converted to an \c{unsigned long} using base \a
5681	base, which is 10 by default and must be between 2 and 36, or 0.
5682	Returns 0 if the conversion fails.
5683
5684	If a conversion error occurs, *\a{ok} is set to false; otherwise
5685	*\a{ok} is set to true.
5686
5687	If \a base is 0, the C language convention is used: If the string
5688	begins with "0x", base 16 is used; if the string begins with "0",
5689	base 8 is used; otherwise, base 10 is used.
5690
5691	Example:
5692
5693	\snippet doc/src/snippets/qstring/main.cpp 78
5694
5695	\sa number()
5696	*/
5697
5698	ulong QString::toULong(bool *ok, int base) const
5699	{
5700	quint64 v = toULongLong(ok, base);
5701	if (v > ULONG_MAX) {
5702	if (ok)
5703	*ok = false;
5704	v = 0;
5705	}
5706	return (ulong)v;
5707	}
5708
5709
5710	/*!
5711	Returns the string converted to an \c int using base \a
5712	base, which is 10 by default and must be between 2 and 36, or 0.
5713	Returns 0 if the conversion fails.
5714
5715	If a conversion error occurs, *\a{ok} is set to false; otherwise
5716	*\a{ok} is set to true.
5717
5718	If \a base is 0, the C language convention is used: If the string
5719	begins with "0x", base 16 is used; if the string begins with "0",
5720	base 8 is used; otherwise, base 10 is used.
5721
5722	Example:
5723
5724	\snippet doc/src/snippets/qstring/main.cpp 72
5725
5726	\sa number(), toUInt(), toDouble()
5727	*/
5728
5729	int QString::toInt(bool *ok, int base) const
5730	{
5731	qint64 v = toLongLong(ok, base);
5732	if (v < INT_MIN || v > INT_MAX) {
5733	if (ok)
5734	*ok = false;
5735	v = 0;
5736	}
5737	return v;
5738	}
5739
5740	/*!
5741	Returns the string converted to an \c{unsigned int} using base \a
5742	base, which is 10 by default and must be between 2 and 36, or 0.
5743	Returns 0 if the conversion fails.
5744
5745	If a conversion error occurs, *\a{ok} is set to false; otherwise
5746	*\a{ok} is set to true.
5747
5748	If \a base is 0, the C language convention is used: If the string
5749	begins with "0x", base 16 is used; if the string begins with "0",
5750	base 8 is used; otherwise, base 10 is used.
5751
5752	Example:
5753
5754	\snippet doc/src/snippets/qstring/main.cpp 77
5755
5756	\sa number(), toInt()
5757	*/
5758
5759	uint QString::toUInt(bool *ok, int base) const
5760	{
5761	quint64 v = toULongLong(ok, base);
5762	if (v > UINT_MAX) {
5763	if (ok)
5764	*ok = false;
5765	v = 0;
5766	}
5767	return (uint)v;
5768	}
5769
5770	/*!
5771	Returns the string converted to a \c short using base \a
5772	base, which is 10 by default and must be between 2 and 36, or 0.
5773	Returns 0 if the conversion fails.
5774
5775	If a conversion error occurs, *\a{ok} is set to false; otherwise
5776	*\a{ok} is set to true.
5777
5778	If \a base is 0, the C language convention is used: If the string
5779	begins with "0x", base 16 is used; if the string begins with "0",
5780	base 8 is used; otherwise, base 10 is used.
5781
5782	Example:
5783
5784	\snippet doc/src/snippets/qstring/main.cpp 76
5785
5786	\sa number(), toUShort(), toInt()
5787	*/
5788
5789	short QString::toShort(bool *ok, int base) const
5790	{
5791	long v = toLongLong(ok, base);
5792	if (v < SHRT_MIN || v > SHRT_MAX) {
5793	if (ok)
5794	*ok = false;
5795	v = 0;
5796	}
5797	return (short)v;
5798	}
5799
5800	/*!
5801	Returns the string converted to an \c{unsigned short} using base \a
5802	base, which is 10 by default and must be between 2 and 36, or 0.
5803	Returns 0 if the conversion fails.
5804
5805	If a conversion error occurs, *\a{ok} is set to false; otherwise
5806	*\a{ok} is set to true.
5807
5808	If \a base is 0, the C language convention is used: If the string
5809	begins with "0x", base 16 is used; if the string begins with "0",
5810	base 8 is used; otherwise, base 10 is used.
5811
5812	Example:
5813
5814	\snippet doc/src/snippets/qstring/main.cpp 80
5815
5816	\sa number(), toShort()
5817	*/
5818
5819	ushort QString::toUShort(bool *ok, int base) const
5820	{
5821	ulong v = toULongLong(ok, base);
5822	if (v > USHRT_MAX) {
5823	if (ok)
5824	*ok = false;
5825	v = 0;
5826	}
5827	return (ushort)v;
5828	}
5829
5830
5831	/*!
5832	Returns the string converted to a \c double value.
5833
5834	Returns 0.0 if the conversion fails.
5835
5836	If a conversion error occurs, \c{*}\a{ok} is set to false;
5837	otherwise \c{*}\a{ok} is set to true.
5838
5839	\snippet doc/src/snippets/qstring/main.cpp 66
5840
5841	Various string formats for floating point numbers can be converted
5842	to double values:
5843
5844	\snippet doc/src/snippets/qstring/main.cpp 67
5845
5846	This function tries to interpret the string according to the
5847	current locale. The current locale is determined from the
5848	system at application startup and can be changed by calling
5849	QLocale::setDefault(). If the string cannot be interpreted
5850	according to the current locale, this function falls back
5851	on the "C" locale.
5852
5853	\snippet doc/src/snippets/qstring/main.cpp 69
5854	\snippet doc/src/snippets/qstring/main.cpp 70
5855
5856	Due to the ambiguity between the decimal point and thousands group
5857	separator in various locales, this function does not handle
5858	thousands group separators. If you need to convert such numbers,
5859	see QLocale::toDouble().
5860
5861	\snippet doc/src/snippets/qstring/main.cpp 68
5862
5863	\sa number() QLocale::setDefault() QLocale::toDouble() trimmed()
5864	*/
5865
5866	double QString::toDouble(bool *ok) const
5867	{
5868	bool my_ok;
5869	QLocale def_locale;
5870	double result = def_locale.d()->stringToDouble(*this, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5871	if (my_ok) {
5872	if (ok != 0)
5873	*ok = true;
5874	return result;
5875	}
5876
5877	QLocale c_locale(QLocale::C);
5878	return c_locale.d()->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators);
5879	}
5880
5881	/*!
5882	Returns the string converted to a \c float value.
5883
5884	If a conversion error occurs, *\a{ok} is set to false; otherwise
5885	*\a{ok} is set to true. Returns 0.0 if the conversion fails.
5886
5887	Example:
5888
5889	\snippet doc/src/snippets/qstring/main.cpp 71
5890
5891	\sa number(), toDouble(), toInt()
5892	*/
5893
5894	#define QT_MAX_FLOAT 3.4028234663852886e+38
5895
5896	float QString::toFloat(bool *ok) const
5897	{
5898	bool myOk;
5899	double d = toDouble(&myOk);
5900	if (!myOk || d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) {
5901	if (ok != 0)
5902	*ok = false;
5903	return 0.0;
5904	}
5905	if (ok != 0)
5906	*ok = true;
5907	return (float) d;
5908	}
5909
5910	/*! \fn QString &QString::setNum(int n, int base)
5911
5912	Sets the string to the printed value of \a n in the specified \a
5913	base, and returns a reference to the string.
5914
5915	The base is 10 by default and must be between 2 and 36. For bases
5916	other than 10, \a n is treated as an unsigned integer.
5917
5918	\snippet doc/src/snippets/qstring/main.cpp 56
5919
5920	The formatting always uses QLocale::C, i.e., English/UnitedStates.
5921	To get a localized string representation of a number, use
5922	QLocale::toString() with the appropriate locale.
5923	*/
5924
5925	/*! \fn QString &QString::setNum(uint n, int base)
5926
5927	\overload
5928	*/
5929
5930	/*! \fn QString &QString::setNum(long n, int base)
5931
5932	\overload
5933	*/
5934
5935	/*! \fn QString &QString::setNum(ulong n, int base)
5936
5937	\overload
5938	*/
5939
5940	/*!
5941	\overload
5942	*/
5943	QString &QString::setNum(qlonglong n, int base)
5944	{
5945	#if defined(QT_CHECK_RANGE)
5946	if (base < 2 || base > 36) {
5947	qWarning("QString::setNum: Invalid base (%d)", base);
5948	base = 10;
5949	}
5950	#endif
5951	QLocale locale(QLocale::C);
5952	*this = locale.d()->longLongToString(n, -1, base);
5953	return *this;
5954	}
5955
5956	/*!
5957	\overload
5958	*/
5959	QString &QString::setNum(qulonglong n, int base)
5960	{
5961	#if defined(QT_CHECK_RANGE)
5962	if (base < 2 || base > 36) {
5963	qWarning("QString::setNum: Invalid base (%d)", base);
5964	base = 10;
5965	}
5966	#endif
5967	QLocale locale(QLocale::C);
5968	*this = locale.d()->unsLongLongToString(n, -1, base);
5969	return *this;
5970	}
5971
5972	/*! \fn QString &QString::setNum(short n, int base)
5973
5974	\overload
5975	*/
5976
5977	/*! \fn QString &QString::setNum(ushort n, int base)
5978
5979	\overload
5980	*/
5981
5982	/*!
5983	\fn QString &QString::setNum(double n, char format, int precision)
5984	\overload
5985
5986	Sets the string to the printed value of \a n, formatted according
5987	to the given \a format and \a precision, and returns a reference
5988	to the string.
5989
5990	The \a format can be 'f', 'F', 'e', 'E', 'g' or 'G' (see the
5991	arg() function documentation for an explanation of the formats).
5992
5993	Unlike QLocale::toString(), this function doesn't honor the
5994	user's locale settings.
5995	*/
5996
5997	QString &QString::setNum(double n, char f, int prec)
5998	{
5999	QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
6000	uint flags = 0;
6001
6002	if (qIsUpper(f))
6003	flags = QLocalePrivate::CapitalEorX;
6004	f = qToLower(f);
6005
6006	switch (f) {
6007	case 'f':
6008	form = QLocalePrivate::DFDecimal;
6009	break;
6010	case 'e':
6011	form = QLocalePrivate::DFExponent;
6012	break;
6013	case 'g':
6014	form = QLocalePrivate::DFSignificantDigits;
6015	break;
6016	default:
6017	#if defined(QT_CHECK_RANGE)
6018	qWarning("QString::setNum: Invalid format char '%c'", f);
6019	#endif
6020	break;
6021	}
6022
6023	QLocale locale(QLocale::C);
6024	*this = locale.d()->doubleToString(n, prec, form, -1, flags);
6025	return *this;
6026	}
6027
6028	/*!
6029	\fn QString &QString::setNum(float n, char format, int precision)
6030	\overload
6031
6032	Sets the string to the printed value of \a n, formatted according
6033	to the given \a format and \a precision, and returns a reference
6034	to the string.
6035	*/
6036
6037
6038	/*!
6039	\fn QString QString::number(long n, int base)
6040
6041	Returns a string equivalent of the number \a n according to the
6042	specified \a base.
6043
6044	The base is 10 by default and must be between 2
6045	and 36. For bases other than 10, \a n is treated as an
6046	unsigned integer.
6047
6048	\snippet doc/src/snippets/qstring/main.cpp 35
6049
6050	\sa setNum()
6051	*/
6052
6053	QString QString::number(long n, int base)
6054	{
6055	QString s;
6056	s.setNum(n, base);
6057	return s;
6058	}
6059
6060	/*!
6061	\fn QString QString::number(ulong n, int base)
6062
6063	\overload
6064	*/
6065	QString QString::number(ulong n, int base)
6066	{
6067	QString s;
6068	s.setNum(n, base);
6069	return s;
6070	}
6071
6072	/*!
6073	\overload
6074	*/
6075	QString QString::number(int n, int base)
6076	{
6077	QString s;
6078	s.setNum(n, base);
6079	return s;
6080	}
6081
6082	/*!
6083	\overload
6084	*/
6085	QString QString::number(uint n, int base)
6086	{
6087	QString s;
6088	s.setNum(n, base);
6089	return s;
6090	}
6091
6092	/*!
6093	\overload
6094	*/
6095	QString QString::number(qlonglong n, int base)
6096	{
6097	QString s;
6098	s.setNum(n, base);
6099	return s;
6100	}
6101
6102	/*!
6103	\overload
6104	*/
6105	QString QString::number(qulonglong n, int base)
6106	{
6107	QString s;
6108	s.setNum(n, base);
6109	return s;
6110	}
6111
6112
6113	/*!
6114	\fn QString QString::number(double n, char format, int precision)
6115
6116	Returns a string equivalent of the number \a n, formatted
6117	according to the specified \a format and \a precision. See
6118	\l{Argument Formats} for details.
6119
6120	Unlike QLocale::toString(), this function does not honor the
6121	user's locale settings.
6122
6123	\sa setNum(), QLocale::toString()
6124	*/
6125	QString QString::number(double n, char f, int prec)
6126	{
6127	QString s;
6128	s.setNum(n, f, prec);
6129	return s;
6130	}
6131
6132	/*!
6133	Splits the string into substrings wherever \a sep occurs, and
6134	returns the list of those strings. If \a sep does not match
6135	anywhere in the string, split() returns a single-element list
6136	containing this string.
6137
6138	\a cs specifies whether \a sep should be matched case
6139	sensitively or case insensitively.
6140
6141	If \a behavior is QString::SkipEmptyParts, empty entries don't
6142	appear in the result. By default, empty entries are kept.
6143
6144	Example:
6145
6146	\snippet doc/src/snippets/qstring/main.cpp 62
6147
6148	\sa QStringList::join(), section()
6149	*/
6150	QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6151	{
6152	QStringList list;
6153	int start = 0;
6154	int extra = 0;
6155	int end;
6156	while ((end = indexOf(sep, start + extra, cs)) != -1) {
6157	if (start != end || behavior == KeepEmptyParts)
6158	list.append(mid(start, end - start));
6159	start = end + sep.size();
6160	extra = (sep.size() == 0 ? 1 : 0);
6161	}
6162	if (start != size() || behavior == KeepEmptyParts)
6163	list.append(mid(start));
6164	return list;
6165	}
6166
6167	/*!
6168	\overload
6169	*/
6170	QStringList QString::split(const QChar &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6171	{
6172	QStringList list;
6173	int start = 0;
6174	int end;
6175	while ((end = indexOf(sep, start, cs)) != -1) {
6176	if (start != end || behavior == KeepEmptyParts)
6177	list.append(mid(start, end - start));
6178	start = end + 1;
6179	}
6180	if (start != size() || behavior == KeepEmptyParts)
6181	list.append(mid(start));
6182	return list;
6183	}
6184
6185	#ifndef QT_NO_REGEXP
6186	/*!
6187	\overload
6188
6189	Splits the string into substrings wherever the regular expression
6190	\a rx matches, and returns the list of those strings. If \a rx
6191	does not match anywhere in the string, split() returns a
6192	single-element list containing this string.
6193
6194	Here's an example where we extract the words in a sentence
6195	using one or more whitespace characters as the separator:
6196
6197	\snippet doc/src/snippets/qstring/main.cpp 59
6198
6199	Here's a similar example, but this time we use any sequence of
6200	non-word characters as the separator:
6201
6202	\snippet doc/src/snippets/qstring/main.cpp 60
6203
6204	Here's a third example where we use a zero-length assertion,
6205	\bold{\\b} (word boundary), to split the string into an
6206	alternating sequence of non-word and word tokens:
6207
6208	\snippet doc/src/snippets/qstring/main.cpp 61
6209
6210	\sa QStringList::join(), section()
6211	*/
6212	QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const
6213	{
6214	QRegExp rx2(rx);
6215	QStringList list;
6216	int start = 0;
6217	int extra = 0;
6218	int end;
6219	while ((end = rx2.indexIn(*this, start + extra)) != -1) {
6220	int matchedLen = rx2.matchedLength();
6221	if (start != end || behavior == KeepEmptyParts)
6222	list.append(mid(start, end - start));
6223	start = end + matchedLen;
6224	extra = (matchedLen == 0) ? 1 : 0;
6225	}
6226	if (start != size() || behavior == KeepEmptyParts)
6227	list.append(mid(start));
6228	return list;
6229	}
6230	#endif
6231
6232	/*!
6233	\enum QString::NormalizationForm
6234
6235	This enum describes the various normalized forms of Unicode text.
6236
6237	\value NormalizationForm_D Canonical Decomposition
6238	\value NormalizationForm_C Canonical Decomposition followed by Canonical Composition
6239	\value NormalizationForm_KD Compatibility Decomposition
6240	\value NormalizationForm_KC Compatibility Decomposition followed by Canonical Composition
6241
6242	\sa normalized(),
6243	{http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15}
6244	*/
6245
6246	/*!
6247	\fn QString QString::normalized(NormalizationForm mode) const
6248	Returns the string in the given Unicode normalization \a mode.
6249	*/
6250	QString QString::normalized(QString::NormalizationForm mode) const
6251	{
6252	return normalized(mode, UNICODE_DATA_VERSION);
6253	}
6254
6255	/*!
6256	\since 4.5
6257
6258	Returns a copy of this string repeated the specified number of \a times.
6259
6260	If \a times is less than 1, an empty string is returned.
6261
6262	Example:
6263
6264	\code
6265	QString str("ab");
6266	str.repeated(4); // returns "abababab"
6267	\endcode
6268	*/
6269	QString QString::repeated(int times) const
6270	{
6271	if (d->size == 0)
6272	return *this;
6273
6274	if (times <= 1) {
6275	if (times == 1)
6276	return *this;
6277	return QString();
6278	}
6279
6280	const int resultSize = times * d->size;
6281
6282	QString result;
6283	result.reserve(resultSize);
6284	if (result.d->alloc != resultSize)
6285	return QString(); // not enough memory
6286
6287	memcpy(result.d->data, d->data, d->size * sizeof(ushort));
6288
6289	int sizeSoFar = d->size;
6290	ushort *end = result.d->data + sizeSoFar;
6291
6292	const int halfResultSize = resultSize >> 1;
6293	while (sizeSoFar <= halfResultSize) {
6294	memcpy(end, result.d->data, sizeSoFar * sizeof(ushort));
6295	end += sizeSoFar;
6296	sizeSoFar <<= 1;
6297	}
6298	memcpy(end, result.d->data, (resultSize - sizeSoFar) * sizeof(ushort));
6299	result.d->data[resultSize] = '\0';
6300	result.d->size = resultSize;
6301	return result;
6302	}
6303
6304	void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from);
6305	/*!
6306	\overload
6307	\fn QString QString::normalized(NormalizationForm mode, QChar::UnicodeVersion version) const
6308
6309	Returns the string in the given Unicode normalization \a mode,
6310	according to the given \a version of the Unicode standard.
6311	*/
6312	QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const
6313	{
6314	QString copy = *this;
6315	qt_string_normalize(&copy, mode, version, 0);
6316	return copy;
6317	}
6318
6319	void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from)
6320	{
6321	bool simple = true;
6322	const QChar *p = data->constData();
6323	int len = data->length();
6324	for (int i = from; i < len; ++i) {
6325	if (p[i].unicode() >= 0x80) {
6326	simple = false;
6327	break;
6328	}
6329	}
6330	if (simple)
6331	return;
6332
6333	if (version == QChar::Unicode_Unassigned) {
6334	version = UNICODE_DATA_VERSION;
6335	} else if (version != UNICODE_DATA_VERSION) {
6336	const QString &s = *data;
6337	QChar *d = 0;
6338	for (int i = 0; i < NumNormalizationCorrections; ++i) {
6339	const NormalizationCorrection &n = uc_normalization_corrections[i];
6340	if (n.version > version) {
6341	int pos = from;
6342	if (QChar::requiresSurrogates(n.ucs4)) {
6343	ushort ucs4High = QChar::highSurrogate(n.ucs4);
6344	ushort ucs4Low = QChar::lowSurrogate(n.ucs4);
6345	ushort oldHigh = QChar::highSurrogate(n.old_mapping);
6346	ushort oldLow = QChar::lowSurrogate(n.old_mapping);
6347	while (pos < s.length() - 1) {
6348	if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) {
6349	if (!d)
6350	d = data->data();
6351	d[pos] = QChar(oldHigh);
6352	d[++pos] = QChar(oldLow);
6353	}
6354	++pos;
6355	}
6356	} else {
6357	while (pos < s.length()) {
6358	if (s.at(pos).unicode() == n.ucs4) {
6359	if (!d)
6360	d = data->data();
6361	d[pos] = QChar(n.old_mapping);
6362	}
6363	++pos;
6364	}
6365	}
6366	}
6367	}
6368	}
6369	decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from);
6370
6371	canonicalOrderHelper(data, version, from);
6372
6373	if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD)
6374	return;
6375
6376	composeHelper(data, version, from);
6377	}
6378
6379
6380	struct ArgEscapeData
6381	{
6382	int min_escape; // lowest escape sequence number
6383	int occurrences; // number of occurrences of the lowest escape sequence number
6384	int locale_occurrences; // number of occurrences of the lowest escape sequence number that
6385	// contain 'L'
6386	int escape_len; // total length of escape sequences which will be replaced
6387	};
6388
6389	static ArgEscapeData findArgEscapes(const QString &s)
6390	{
6391	const QChar *uc_begin = s.unicode();
6392	const QChar *uc_end = uc_begin + s.length();
6393
6394	ArgEscapeData d;
6395
6396	d.min_escape = INT_MAX;
6397	d.occurrences = 0;
6398	d.escape_len = 0;
6399	d.locale_occurrences = 0;
6400
6401	const QChar *c = uc_begin;
6402	while (c != uc_end) {
6403	while (c != uc_end && c->unicode() != '%')
6404	++c;
6405
6406	if (c == uc_end)
6407	break;
6408	const QChar *escape_start = c;
6409	if (++c == uc_end)
6410	break;
6411
6412	bool locale_arg = false;
6413	if (c->unicode() == 'L') {
6414	locale_arg = true;
6415	if (++c == uc_end)
6416	break;
6417	}
6418
6419	if (c->digitValue() == -1)
6420	continue;
6421
6422	int escape = c->digitValue();
6423	++c;
6424
6425	if (c != uc_end && c->digitValue() != -1) {
6426	escape = (10 * escape) + c->digitValue();
6427	++c;
6428	}
6429
6430	if (escape > d.min_escape)
6431	continue;
6432
6433	if (escape < d.min_escape) {
6434	d.min_escape = escape;
6435	d.occurrences = 0;
6436	d.escape_len = 0;
6437	d.locale_occurrences = 0;
6438	}
6439
6440	++d.occurrences;
6441	if (locale_arg)
6442	++d.locale_occurrences;
6443	d.escape_len += c - escape_start;
6444	}
6445	return d;
6446	}
6447
6448	static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width,
6449	const QString &arg, const QString &larg, const QChar &fillChar = QLatin1Char(' '))
6450	{
6451	const QChar *uc_begin = s.unicode();
6452	const QChar *uc_end = uc_begin + s.length();
6453
6454	int abs_field_width = qAbs(field_width);
6455	int result_len = s.length()
6456	- d.escape_len
6457	+ (d.occurrences - d.locale_occurrences)
6458	*qMax(abs_field_width, arg.length())
6459	+ d.locale_occurrences
6460	*qMax(abs_field_width, larg.length());
6461
6462	QString result(result_len, Qt::Uninitialized);
6463	QChar *result_buff = (QChar*) result.unicode();
6464
6465	QChar *rc = result_buff;
6466	const QChar *c = uc_begin;
6467	int repl_cnt = 0;
6468	while (c != uc_end) {
6469	/* We don't have to check if we run off the end of the string with c,
6470	because as long as d.occurrences > 0 we KNOW there are valid escape
6471	sequences. */
6472
6473	const QChar *text_start = c;
6474
6475	while (c->unicode() != '%')
6476	++c;
6477
6478	const QChar *escape_start = c++;
6479
6480	bool locale_arg = false;
6481	if (c->unicode() == 'L') {
6482	locale_arg = true;
6483	++c;
6484	}
6485
6486	int escape = c->digitValue();
6487	if (escape != -1) {
6488	if (c + 1 != uc_end && (c + 1)->digitValue() != -1) {
6489	escape = (10 * escape) + (c + 1)->digitValue();
6490	++c;
6491	}
6492	}
6493
6494	if (escape != d.min_escape) {
6495	memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
6496	rc += c - text_start;
6497	}
6498	else {
6499	++c;
6500
6501	memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
6502	rc += escape_start - text_start;
6503
6504	uint pad_chars;
6505	if (locale_arg)
6506	pad_chars = qMax(abs_field_width, larg.length()) - larg.length();
6507	else
6508	pad_chars = qMax(abs_field_width, arg.length()) - arg.length();
6509
6510	if (field_width > 0) { // left padded
6511	for (uint i = 0; i < pad_chars; ++i)
6512	(rc++)->unicode() = fillChar.unicode();
6513	}
6514
6515	if (locale_arg) {
6516	memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar));
6517	rc += larg.length();
6518	}
6519	else {
6520	memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar));
6521	rc += arg.length();
6522	}
6523
6524	if (field_width < 0) { // right padded
6525	for (uint i = 0; i < pad_chars; ++i)
6526	(rc++)->unicode() = fillChar.unicode();
6527	}
6528
6529	if (++repl_cnt == d.occurrences) {
6530	memcpy(rc, c, (uc_end - c)*sizeof(QChar));
6531	rc += uc_end - c;
6532	Q_ASSERT(rc - result_buff == result_len);
6533	c = uc_end;
6534	}
6535	}
6536	}
6537	Q_ASSERT(rc == result_buff + result_len);
6538
6539	return result;
6540	}
6541
6542	/*!
6543	Returns a copy of this string with the lowest numbered place marker
6544	replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
6545
6546	\a fieldWidth specifies the minimum amount of space that argument \a
6547	a shall occupy. If \a a requires less space than \a fieldWidth, it
6548	is padded to \a fieldWidth with character \a fillChar. A positive
6549	\a fieldWidth produces right-aligned text. A negative \a fieldWidth
6550	produces left-aligned text.
6551
6552	This example shows how we might create a \c status string for
6553	reporting progress while processing a list of files:
6554
6555	\snippet doc/src/snippets/qstring/main.cpp 11
6556
6557	First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
6558	%2. Finally, \c arg(fileName) replaces \c %3.
6559
6560	One advantage of using arg() over sprintf() is that the order of the
6561	numbered place markers can change, if the application's strings are
6562	translated into other languages, but each arg() will still replace
6563	the lowest numbered unreplaced place marker, no matter where it
6564	appears. Also, if place marker \c %i appears more than once in the
6565	string, the arg() replaces all of them.
6566
6567	If there is no unreplaced place marker remaining, a warning message
6568	is output and the result is undefined. Place marker numbers must be
6569	in the range 1 to 99.
6570	*/
6571	QString QString::arg(const QString &a, int fieldWidth, const QChar &fillChar) const
6572	{
6573	ArgEscapeData d = findArgEscapes(*this);
6574
6575	if (d.occurrences == 0) {
6576	qWarning("QString::arg: Argument missing: %s, %s", toLocal8Bit().data(),
6577	a.toLocal8Bit().data());
6578	return *this;
6579	}
6580	return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar);
6581	}
6582
6583	/*!
6584	\fn QString QString::arg(const QString& a1, const QString& a2) const
6585	\overload arg()
6586
6587	This is the same as \c {str.arg(a1).arg(a2)}, except that the
6588	strings \a a1 and \a a2 are replaced in one pass. This can make a
6589	difference if \a a1 contains e.g. \c{%1}:
6590
6591	\snippet doc/src/snippets/qstring/main.cpp 13
6592	*/
6593
6594	/*!
6595	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const
6596	\overload arg()
6597
6598	This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except
6599	that the strings \a a1, \a a2 and \a a3 are replaced in one pass.
6600	*/
6601
6602	/*!
6603	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const
6604	\overload arg()
6605
6606	This is the same as calling \c
6607	{str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a
6608	a1, \a a2, \a a3 and \a a4 are replaced in one pass.
6609	*/
6610
6611	/*!
6612	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const
6613	\overload arg()
6614
6615	This is the same as calling \c
6616	{str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings
6617	\a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass.
6618	*/
6619
6620	/*!
6621	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const
6622	\overload arg()
6623
6624	This is the same as calling \c
6625	{str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that
6626	the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are
6627	replaced in one pass.
6628	*/
6629
6630	/*!
6631	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7) const
6632	\overload arg()
6633
6634	This is the same as calling \c
6635	{str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)},
6636	except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6,
6637	and \a a7 are replaced in one pass.
6638	*/
6639
6640	/*!
6641	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8) const
6642	\overload arg()
6643
6644	This is the same as calling \c
6645	{str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)},
6646	except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6647	a7, and \a a8 are replaced in one pass.
6648	*/
6649
6650	/*!
6651	\fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8, const QString& a9) const
6652	\overload arg()
6653
6654	This is the same as calling \c
6655	{str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)},
6656	except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6657	a7, \a a8, and \a a9 are replaced in one pass.
6658	*/
6659
6660	/*! \fn QString QString::arg(int a, int fieldWidth, int base, const QChar &fillChar) const
6661	\overload arg()
6662
6663	The \a a argument is expressed in base \a base, which is 10 by
6664	default and must be between 2 and 36. For bases other than 10, \a a
6665	is treated as an unsigned integer.
6666
6667	\a fieldWidth specifies the minimum amount of space that \a a is
6668	padded to and filled with the character \a fillChar. A positive
6669	value produces right-aligned text; a negative value produces
6670	left-aligned text.
6671
6672	The '%' can be followed by an 'L', in which case the sequence is
6673	replaced with a localized representation of \a a. The conversion
6674	uses the default locale, set by QLocale::setDefault(). If no default
6675	locale was specified, the "C" locale is used. The 'L' flag is
6676	ignored if \a base is not 10.
6677
6678	\snippet doc/src/snippets/qstring/main.cpp 12
6679	\snippet doc/src/snippets/qstring/main.cpp 14
6680
6681	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6682	used. For negative numbers, zero padding might appear before the
6683	minus sign.
6684	*/
6685
6686	/*! \fn QString QString::arg(uint a, int fieldWidth, int base, const QChar &fillChar) const
6687	\overload arg()
6688
6689	The \a base argument specifies the base to use when converting the
6690	integer \a a into a string. The base must be between 2 and 36.
6691
6692	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6693	used. For negative numbers, zero padding might appear before the
6694	minus sign.
6695	*/
6696
6697	/*! \fn QString QString::arg(long a, int fieldWidth, int base, const QChar &fillChar) const
6698	\overload arg()
6699
6700	\a fieldWidth specifies the minimum amount of space that \a a is
6701	padded to and filled with the character \a fillChar. A positive
6702	value produces right-aligned text; a negative value produces
6703	left-aligned text.
6704
6705	The \a a argument is expressed in the given \a base, which is 10 by
6706	default and must be between 2 and 36.
6707
6708	The '%' can be followed by an 'L', in which case the sequence is
6709	replaced with a localized representation of \a a. The conversion
6710	uses the default locale. The default locale is determined from the
6711	system's locale settings at application startup. It can be changed
6712	using QLocale::setDefault(). The 'L' flag is ignored if \a base is
6713	not 10.
6714
6715	\snippet doc/src/snippets/qstring/main.cpp 12
6716	\snippet doc/src/snippets/qstring/main.cpp 14
6717
6718	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6719	used. For negative numbers, zero padding might appear before the
6720	minus sign.
6721	*/
6722
6723	/*! \fn QString QString::arg(ulong a, int fieldWidth, int base, const QChar &fillChar) const
6724	\overload arg()
6725
6726	\a fieldWidth specifies the minimum amount of space that \a a is
6727	padded to and filled with the character \a fillChar. A positive
6728	value produces right-aligned text; a negative value produces
6729	left-aligned text.
6730
6731	The \a base argument specifies the base to use when converting the
6732	integer \a a to a string. The base must be between 2 and 36, with 8
6733	giving octal, 10 decimal, and 16 hexadecimal numbers.
6734
6735	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6736	used. For negative numbers, zero padding might appear before the
6737	minus sign.
6738	*/
6739
6740	/*!
6741	\overload arg()
6742
6743	\a fieldWidth specifies the minimum amount of space that \a a is
6744	padded to and filled with the character \a fillChar. A positive
6745	value produces right-aligned text; a negative value produces
6746	left-aligned text.
6747
6748	The \a base argument specifies the base to use when converting the
6749	integer \a a into a string. The base must be between 2 and 36, with
6750	8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6751
6752	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6753	used. For negative numbers, zero padding might appear before the
6754	minus sign.
6755	*/
6756	QString QString::arg(qlonglong a, int fieldWidth, int base, const QChar &fillChar) const
6757	{
6758	ArgEscapeData d = findArgEscapes(*this);
6759
6760	if (d.occurrences == 0) {
6761	qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6762	return *this;
6763	}
6764
6765	unsigned flags = QLocalePrivate::NoFlags;
6766	if (fillChar == QLatin1Char('0'))
6767	flags = QLocalePrivate::ZeroPadded;
6768
6769	QString arg;
6770	if (d.occurrences > d.locale_occurrences)
6771	arg = QLocale::c().d()->longLongToString(a, -1, base, fieldWidth, flags);
6772
6773	QString locale_arg;
6774	if (d.locale_occurrences > 0) {
6775	QLocale locale;
6776	if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6777	flags |= QLocalePrivate::ThousandsGroup;
6778	locale_arg = locale.d()->longLongToString(a, -1, base, fieldWidth, flags);
6779	}
6780
6781	return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6782	}
6783
6784	/*!
6785	\overload arg()
6786
6787	\a fieldWidth specifies the minimum amount of space that \a a is
6788	padded to and filled with the character \a fillChar. A positive
6789	value produces right-aligned text; a negative value produces
6790	left-aligned text.
6791
6792	The \a base argument specifies the base to use when converting the
6793	integer \a a into a string. \a base must be between 2 and 36, with 8
6794	giving octal, 10 decimal, and 16 hexadecimal numbers.
6795
6796	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6797	used. For negative numbers, zero padding might appear before the
6798	minus sign.
6799	*/
6800	QString QString::arg(qulonglong a, int fieldWidth, int base, const QChar &fillChar) const
6801	{
6802	ArgEscapeData d = findArgEscapes(*this);
6803
6804	if (d.occurrences == 0) {
6805	qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6806	return *this;
6807	}
6808
6809	unsigned flags = QLocalePrivate::NoFlags;
6810	if (fillChar == QLatin1Char('0'))
6811	flags = QLocalePrivate::ZeroPadded;
6812
6813	QString arg;
6814	if (d.occurrences > d.locale_occurrences)
6815	arg = QLocale::c().d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6816
6817	QString locale_arg;
6818	if (d.locale_occurrences > 0) {
6819	QLocale locale;
6820	if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6821	flags |= QLocalePrivate::ThousandsGroup;
6822	locale_arg = locale.d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6823	}
6824
6825	return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6826	}
6827
6828	/*!
6829	\overload arg()
6830
6831	\fn QString QString::arg(short a, int fieldWidth, int base, const QChar &fillChar) const
6832
6833	\a fieldWidth specifies the minimum amount of space that \a a is
6834	padded to and filled with the character \a fillChar. A positive
6835	value produces right-aligned text; a negative value produces
6836	left-aligned text.
6837
6838	The \a base argument specifies the base to use when converting the
6839	integer \a a into a string. The base must be between 2 and 36, with
6840	8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6841
6842	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6843	used. For negative numbers, zero padding might appear before the
6844	minus sign.
6845	*/
6846
6847	/*!
6848	\fn QString QString::arg(ushort a, int fieldWidth, int base, const QChar &fillChar) const
6849	\overload arg()
6850
6851	\a fieldWidth specifies the minimum amount of space that \a a is
6852	padded to and filled with the character \a fillChar. A positive
6853	value produces right-aligned text; a negative value produces
6854	left-aligned text.
6855
6856	The \a base argument specifies the base to use when converting the
6857	integer \a a into a string. The base must be between 2 and 36, with
6858	8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6859
6860	If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6861	used. For negative numbers, zero padding might appear before the
6862	minus sign.
6863	*/
6864
6865	/*!
6866	\overload arg()
6867	*/
6868	QString QString::arg(QChar a, int fieldWidth, const QChar &fillChar) const
6869	{
6870	QString c;
6871	c += a;
6872	return arg(c, fieldWidth, fillChar);
6873	}
6874
6875	/*!
6876	\overload arg()
6877
6878	The \a a argument is interpreted as a Latin-1 character.
6879	*/
6880	QString QString::arg(char a, int fieldWidth, const QChar &fillChar) const
6881	{
6882	QString c;
6883	c += QLatin1Char(a);
6884	return arg(c, fieldWidth, fillChar);
6885	}
6886
6887	/*!
6888	\fn QString QString::arg(double a, int fieldWidth, char format, int precision, const QChar &fillChar) const
6889	\overload arg()
6890
6891	Argument \a a is formatted according to the specified \a format and
6892	\a precision. See \l{Argument Formats} for details.
6893
6894	\a fieldWidth specifies the minimum amount of space that \a a is
6895	padded to and filled with the character \a fillChar. A positive
6896	value produces right-aligned text; a negative value produces
6897	left-aligned text.
6898
6899	\snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 2
6900
6901	The '%' can be followed by an 'L', in which case the sequence is
6902	replaced with a localized representation of \a a. The conversion
6903	uses the default locale, set by QLocale::setDefaultLocale(). If no
6904	default locale was specified, the "C" locale is used.
6905
6906	If \a fillChar is '0' (the number 0, ASCII 48), this function will
6907	use the locale's zero to pad. For negative numbers, the zero padding
6908	will probably appear before the minus sign.
6909
6910	\sa QLocale::toString()
6911	*/
6912	QString QString::arg(double a, int fieldWidth, char fmt, int prec, const QChar &fillChar) const
6913	{
6914	ArgEscapeData d = findArgEscapes(*this);
6915
6916	if (d.occurrences == 0) {
6917	qWarning("QString::arg: Argument missing: %s, %g", toLocal8Bit().data(), a);
6918	return *this;
6919	}
6920
6921	unsigned flags = QLocalePrivate::NoFlags;
6922	if (fillChar == QLatin1Char('0'))
6923	flags = QLocalePrivate::ZeroPadded;
6924
6925	if (qIsUpper(fmt))
6926	flags |= QLocalePrivate::CapitalEorX;
6927	fmt = qToLower(fmt);
6928
6929	QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
6930	switch (fmt) {
6931	case 'f':
6932	form = QLocalePrivate::DFDecimal;
6933	break;
6934	case 'e':
6935	form = QLocalePrivate::DFExponent;
6936	break;
6937	case 'g':
6938	form = QLocalePrivate::DFSignificantDigits;
6939	break;
6940	default:
6941	#if defined(QT_CHECK_RANGE)
6942	qWarning("QString::arg: Invalid format char '%c'", fmt);
6943	#endif
6944	break;
6945	}
6946
6947	QString arg;
6948	if (d.occurrences > d.locale_occurrences)
6949	arg = QLocale::c().d()->doubleToString(a, prec, form, fieldWidth, flags);
6950
6951	QString locale_arg;
6952	if (d.locale_occurrences > 0) {
6953	QLocale locale;
6954
6955	if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6956	flags |= QLocalePrivate::ThousandsGroup;
6957	locale_arg = locale.d()->doubleToString(a, prec, form, fieldWidth, flags);
6958	}
6959
6960	return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6961	}
6962
6963	static int getEscape(const QChar *uc, int *pos, int len, int maxNumber = 999)
6964	{
6965	int i = *pos;
6966	++i;
6967	if (i < len && uc[i] == QLatin1Char('L'))
6968	++i;
6969	if (i < len) {
6970	int escape = uc[i].unicode() - '0';
6971	if (uint(escape) >= 10U)
6972	return -1;
6973	++i;
6974	while (i < len) {
6975	int digit = uc[i].unicode() - '0';
6976	if (uint(digit) >= 10U)
6977	break;
6978	escape = (escape * 10) + digit;
6979	++i;
6980	}
6981	if (escape <= maxNumber) {
6982	*pos = i;
6983	return escape;
6984	}
6985	}
6986	return -1;
6987	}
6988
6989	QString QString::multiArg(int numArgs, const QString **args) const
6990	{
6991	QString result;
6992	QMap<int, int> numbersUsed;
6993	const QChar *uc = (const QChar *) d->data;
6994	const int len = d->size;
6995	const int end = len - 1;
6996	int lastNumber = -1;
6997	int i = 0;
6998
6999	// populate the numbersUsed map with the %n's that actually occur in the string
7000	while (i < end) {
7001	if (uc[i] == QLatin1Char('%')) {
7002	int number = getEscape(uc, &i, len);
7003	if (number != -1) {
7004	numbersUsed.insert(number, -1);
7005	continue;
7006	}
7007	}
7008	++i;
7009	}
7010
7011	// assign an argument number to each of the %n's
7012	QMap<int, int>::iterator j = numbersUsed.begin();
7013	QMap<int, int>::iterator jend = numbersUsed.end();
7014	int arg = 0;
7015	while (j != jend && arg < numArgs) {
7016	*j = arg++;
7017	lastNumber = j.key();
7018	++j;
7019	}
7020
7021	// sanity
7022	if (numArgs > arg) {
7023	qWarning("QString::arg: %d argument(s) missing in %s", numArgs - arg, toLocal8Bit().data());
7024	numArgs = arg;
7025	}
7026
7027	i = 0;
7028	while (i < len) {
7029	if (uc[i] == QLatin1Char('%') && i != end) {
7030	int number = getEscape(uc, &i, len, lastNumber);
7031	int arg = numbersUsed[number];
7032	if (number != -1 && arg != -1) {
7033	result += *args[arg];
7034	continue;
7035	}
7036	}
7037	result += uc[i++];
7038	}
7039	return result;
7040	}
7041
7042	static bool isStringRightToLeft(const ushort *p, const ushort *end)
7043	{
7044	bool righttoleft = false;
7045	while (p < end) {
7046	switch(QChar::direction(*p))
7047	{
7048	case QChar::DirL:
7049	goto end;
7050	case QChar::DirR:
7051	case QChar::DirAL:
7052	righttoleft = true;
7053	goto end;
7054	default:
7055	break;
7056	}
7057	++p;
7058	}
7059	end:
7060	return righttoleft;
7061	}
7062
7063	/*! \internal
7064	*/
7065	void QString::updateProperties() const
7066	{
7067	ushort *p = d->data;
7068	ushort *end = p + d->size;
7069	d->simpletext = true;
7070	while (p < end) {
7071	ushort uc = *p;
7072	// sort out regions of complex text formatting
7073	if (uc > 0x058f && (uc < 0x1100 || uc > 0xfb0f)) {
7074	d->simpletext = false;
7075	}
7076	p++;
7077	}
7078
7079	d->righttoleft = isStringRightToLeft(d->data, d->data + d->size);
7080	d->clean = true;
7081	}
7082
7083	bool QString::isRightToLeft() const
7084	{
7085	return isStringRightToLeft(d->data, d->data + d->size);
7086	}
7087
7088	/*! \fn bool QString::isSimpleText() const
7089
7090	\internal
7091	*/
7092
7093	/*! \fn bool QString::isRightToLeft() const
7094
7095	Returns true if the string is read right to left.
7096	*/
7097
7098
7099	/*! \fn QChar *QString::data()
7100
7101	Returns a pointer to the data stored in the QString. The pointer
7102	can be used to access and modify the characters that compose the
7103	string. For convenience, the data is '\\0'-terminated.
7104
7105	Example:
7106
7107	\snippet doc/src/snippets/qstring/main.cpp 19
7108
7109	Note that the pointer remains valid only as long as the string is
7110	not modified by other means. For read-only access, constData() is
7111	faster because it never causes a \l{deep copy} to occur.
7112
7113	\sa constData(), operator[]()
7114	*/
7115
7116	/*! \fn const QChar *QString::data() const
7117
7118	\overload
7119	*/
7120
7121	/*! \fn const QChar *QString::constData() const
7122
7123	Returns a pointer to the data stored in the QString. The pointer
7124	can be used to access the characters that compose the string. For
7125	convenience, the data is '\\0'-terminated.
7126
7127	Note that the pointer remains valid only as long as the string is
7128	not modified.
7129
7130	\sa data(), operator[]()
7131	*/
7132
7133	/*! \fn void QString::push_front(const QString &other)
7134
7135	This function is provided for STL compatibility, prepending the
7136	given \a other string to the beginning of this string. It is
7137	equivalent to \c prepend(other).
7138
7139	\sa prepend()
7140	*/
7141
7142	/*! \fn void QString::push_front(QChar ch)
7143
7144	\overload
7145
7146	Prepends the given \a ch character to the beginning of this string.
7147	*/
7148
7149	/*! \fn void QString::push_back(const QString &other)
7150
7151	This function is provided for STL compatibility, appending the
7152	given \a other string onto the end of this string. It is
7153	equivalent to \c append(other).
7154
7155	\sa append()
7156	*/
7157
7158	/*! \fn void QString::push_back(QChar ch)
7159
7160	\overload
7161
7162	Appends the given \a ch character onto the end of this string.
7163	*/
7164
7165	/*!
7166	\fn std::string QString::toStdString() const
7167
7168	Returns a std::string object with the data contained in this
7169	QString. The Unicode data is converted into 8-bit characters using
7170	the toAscii() function.
7171
7172	This operator is mostly useful to pass a QString to a function
7173	that accepts a std::string object.
7174
7175	If the QString contains Unicode characters that the
7176	QTextCodec::codecForCStrings() codec cannot handle, using this operator
7177	can lead to loss of information.
7178
7179	This operator is only available if Qt is configured with STL
7180	compatibility enabled.
7181
7182	\sa toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
7183	*/
7184
7185	/*!
7186	Constructs a QString that uses the first \a size Unicode characters
7187	in the array \a unicode. The data in \a unicode is \e not
7188	copied. The caller must be able to guarantee that \a unicode will
7189	not be deleted or modified as long as the QString (or an
7190	unmodified copy of it) exists.
7191
7192	Any attempts to modify the QString or copies of it will cause it
7193	to create a deep copy of the data, ensuring that the raw data
7194	isn't modified.
7195
7196	Here's an example of how we can use a QRegExp on raw data in
7197	memory without requiring to copy the data into a QString:
7198
7199	\snippet doc/src/snippets/qstring/main.cpp 22
7200	\snippet doc/src/snippets/qstring/main.cpp 23
7201
7202	\warning A string created with fromRawData() is \e not
7203	'\\0'-terminated, unless the raw data contains a '\\0' character
7204	at position \a size. This means unicode() will \e not return a
7205	'\\0'-terminated string (although utf16() does, at the cost of
7206	copying the raw data).
7207
7208	\sa fromUtf16(), setRawData()
7209	*/
7210	QString QString::fromRawData(const QChar *unicode, int size)
7211	{
7212	Data *x = static_cast<Data *>(qMalloc(sizeof(Data)));
7213	Q_CHECK_PTR(x);
7214	if (unicode) {
7215	x->data = (ushort *)unicode;
7216	} else {
7217	x->data = x->array;
7218	size = 0;
7219	}
7220	x->ref = 1;
7221	x->alloc = x->size = size;
7222	*x->array = '\0';
7223	x->clean = x->asciiCache = x->simpletext = x->righttoleft = x->capacity = 0;
7224	return QString(x, 0);
7225	}
7226
7227	/*!
7228	\since 4.7
7229
7230	Resets the QString to use the first \a size Unicode characters
7231	in the array \a unicode. The data in \a unicode is \e not
7232	copied. The caller must be able to guarantee that \a unicode will
7233	not be deleted or modified as long as the QString (or an
7234	unmodified copy of it) exists.
7235
7236	This function can be used instead of fromRawData() to re-use
7237	existings QString objects to save memory re-allocations.
7238
7239	\sa fromRawData()
7240	*/
7241	QString &QString::setRawData(const QChar *unicode, int size)
7242	{
7243	if (d->ref != 1 || (d->data == d->array && d->alloc)) {
7244	*this = fromRawData(unicode, size);
7245	} else {
7246	#ifdef QT3_SUPPORT
7247	if (d->asciiCache) {
7248	QMutexLocker locker(asciiCacheMutex());
7249	Q_ASSERT(asciiCache);
7250	asciiCache->remove(d);
7251	}
7252	#endif
7253	if (unicode) {
7254	d->data = (ushort *)unicode;
7255	} else {
7256	d->data = d->array;
7257	size = 0;
7258	}
7259	d->alloc = d->size = size;
7260	*d->array = '\0';
7261	d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0;
7262	}
7263	return *this;
7264	}
7265
7266	/*! \class QLatin1String
7267	\brief The QLatin1String class provides a thin wrapper around an US-ASCII/Latin-1 encoded string literal.
7268
7269	\ingroup string-processing
7270	\reentrant
7271
7272	Many of QString's member functions are overloaded to accept
7273	\c{const char *} instead of QString. This includes the copy
7274	constructor, the assignment operator, the comparison operators,
7275	and various other functions such as \link QString::insert()
7276	insert() \endlink, \link QString::replace() replace()\endlink,
7277	and \link QString::indexOf() indexOf()\endlink. These functions
7278	are usually optimized to avoid constructing a QString object for
7279	the \c{const char *} data. For example, assuming \c str is a
7280	QString,
7281
7282	\snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 3
7283
7284	is much faster than
7285
7286	\snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 4
7287
7288	because it doesn't construct four temporary QString objects and
7289	make a deep copy of the character data.
7290
7291	Applications that define \c QT_NO_CAST_FROM_ASCII (as explained
7292	in the QString documentation) don't have access to QString's
7293	\c{const char *} API. To provide an efficient way of specifying
7294	constant Latin-1 strings, Qt provides the QLatin1String, which is
7295	just a very thin wrapper around a \c{const char *}. Using
7296	QLatin1String, the example code above becomes
7297
7298	\snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 5
7299
7300	This is a bit longer to type, but it provides exactly the same
7301	benefits as the first version of the code, and is faster than
7302	converting the Latin-1 strings using QString::fromLatin1().
7303
7304	Thanks to the QString(const QLatin1String &) constructor,
7305	QLatin1String can be used everywhere a QString is expected. For
7306	example:
7307
7308	\snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 6
7309
7310	\sa QString, QLatin1Char
7311	*/
7312
7313	/*! \fn QLatin1String::QLatin1String(const char *str)
7314
7315	Constructs a QLatin1String object that stores \a str. Note that if
7316	\a str is 0, an empty string is created; this case is handled by
7317	QString.
7318
7319	The string data is \e not copied. The caller must be able to
7320	guarantee that \a str will not be deleted or modified as long as
7321	the QLatin1String object exists.
7322
7323	\sa latin1()
7324	*/
7325
7326	/*!
7327	\since 4.1
7328	\fn QLatin1String &QLatin1String::operator=(const QLatin1String &other)
7329
7330	Constructs a copy of \a other.
7331	*/
7332
7333	/*! \fn const char *QLatin1String::latin1() const
7334
7335	Returns the Latin-1 string stored in this object.
7336	*/
7337
7338	/*! \fn bool QLatin1String::operator==(const QString &other) const
7339
7340	Returns true if this string is equal to string \a other;
7341	otherwise returns false.
7342
7343	The comparison is based exclusively on the numeric Unicode values
7344	of the characters and is very fast, but is not what a human would
7345	expect. Consider sorting user-interface strings with
7346	QString::localeAwareCompare().
7347	*/
7348
7349	/*!
7350	\fn bool QLatin1String::operator==(const char *other) const
7351	\since 4.3
7352	\overload
7353
7354	The \a other const char pointer is converted to a QString using
7355	the QString::fromAscii() function.
7356
7357	You can disable this operator by defining \c
7358	QT_NO_CAST_FROM_ASCII when you compile your applications. This
7359	can be useful if you want to ensure that all user-visible strings
7360	go through QObject::tr(), for example.
7361	*/
7362
7363	/*! \fn bool QLatin1String::operator!=(const QString &other) const
7364
7365	Returns true if this string is not equal to string \a other;
7366	otherwise returns false.
7367
7368	The comparison is based exclusively on the numeric Unicode values
7369	of the characters and is very fast, but is not what a human would
7370	expect. Consider sorting user-interface strings with
7371	QString::localeAwareCompare().
7372	*/
7373
7374	/*!
7375	\fn bool QLatin1String::operator!=(const char *other) const
7376	\since 4.3
7377	\overload operator!=()
7378
7379	The \a other const char pointer is converted to a QString using
7380	the QString::fromAscii() function.
7381
7382	You can disable this operator by defining \c
7383	QT_NO_CAST_FROM_ASCII when you compile your applications. This
7384	can be useful if you want to ensure that all user-visible strings
7385	go through QObject::tr(), for example.
7386	*/
7387
7388	/*!
7389	\fn bool QLatin1String::operator>(const QString &other) const
7390
7391	Returns true if this string is lexically greater than string \a
7392	other; otherwise returns false.
7393
7394	The comparison is based exclusively on the numeric Unicode values
7395	of the characters and is very fast, but is not what a human would
7396	expect. Consider sorting user-interface strings with
7397	QString::localeAwareCompare().
7398	*/
7399
7400	/*!
7401	\fn bool QLatin1String::operator>(const char *other) const
7402	\since 4.3
7403	\overload
7404
7405	The \a other const char pointer is converted to a QString using
7406	the QString::fromAscii() function.
7407
7408	You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
7409	when you compile your applications. This can be useful if you want
7410	to ensure that all user-visible strings go through QObject::tr(),
7411	for example.
7412	*/
7413
7414	/*!
7415	\fn bool QLatin1String::operator<(const QString &other) const
7416
7417	Returns true if this string is lexically less than the \a other
7418	string; otherwise returns false.
7419
7420	The comparison is based exclusively on the numeric Unicode values
7421	of the characters and is very fast, but is not what a human would
7422	expect. Consider sorting user-interface strings using the
7423	QString::localeAwareCompare() function.
7424	*/
7425
7426	/*!
7427	\fn bool QLatin1String::operator<(const char *other) const
7428	\since 4.3
7429	\overload
7430
7431	The \a other const char pointer is converted to a QString using
7432	the QString::fromAscii() function.
7433
7434	You can disable this operator by defining \c
7435	QT_NO_CAST_FROM_ASCII when you compile your applications. This
7436	can be useful if you want to ensure that all user-visible strings
7437	go through QObject::tr(), for example.
7438	*/
7439
7440	/*!
7441	\fn bool QLatin1String::operator>=(const QString &other) const
7442
7443	Returns true if this string is lexically greater than or equal
7444	to string \a other; otherwise returns false.
7445
7446	The comparison is based exclusively on the numeric Unicode values
7447	of the characters and is very fast, but is not what a human would
7448	expect. Consider sorting user-interface strings with
7449	QString::localeAwareCompare().
7450	*/
7451
7452	/*!
7453	\fn bool QLatin1String::operator>=(const char *other) const
7454	\since 4.3
7455	\overload
7456
7457	The \a other const char pointer is converted to a QString using
7458	the QString::fromAscii() function.
7459
7460	You can disable this operator by defining \c
7461	QT_NO_CAST_FROM_ASCII when you compile your applications. This
7462	can be useful if you want to ensure that all user-visible strings
7463	go through QObject::tr(), for example.
7464	*/
7465
7466	/*! \fn bool QLatin1String::operator<=(const QString &other) const
7467
7468	Returns true if this string is lexically less than or equal
7469	to string \a other; otherwise returns false.
7470
7471	The comparison is based exclusively on the numeric Unicode values
7472	of the characters and is very fast, but is not what a human would
7473	expect. Consider sorting user-interface strings with
7474	QString::localeAwareCompare().
7475	*/
7476
7477	/*!
7478	\fn bool QLatin1String::operator<=(const char *other) const
7479	\since 4.3
7480	\overload
7481
7482	The \a other const char pointer is converted to a QString using
7483	the QString::fromAscii() function.
7484
7485	You can disable this operator by defining \c
7486	QT_NO_CAST_FROM_ASCII when you compile your applications. This
7487	can be useful if you want to ensure that all user-visible strings
7488	go through QObject::tr(), for example.
7489	*/
7490
7491
7492
7493	/* \fn bool operator==(const QLatin1String &s1, const QLatin1String &s2)
7494	\relates QLatin1String
7495
7496	Returns true if string \a s1 is lexically equal to string \a s2; otherwise
7497	returns false.
7498	*/
7499	/* \fn bool operator!=(const QLatin1String &s1, const QLatin1String &s2)
7500	\relates QLatin1String
7501
7502	Returns true if string \a s1 is lexically unequal to string \a s2; otherwise
7503	returns false.
7504	*/
7505	/* \fn bool operator<(const QLatin1String &s1, const QLatin1String &s2)
7506	\relates QLatin1String
7507
7508	Returns true if string \a s1 is lexically smaller than string \a s2; otherwise
7509	returns false.
7510	*/
7511	/* \fn bool operator<=(const QLatin1String &s1, const QLatin1String &s2)
7512	\relates QLatin1String
7513
7514	Returns true if string \a s1 is lexically smaller than or equal to string \a s2; otherwise
7515	returns false.
7516	*/
7517	/* \fn bool operator>(const QLatin1String &s1, const QLatin1String &s2)
7518	\relates QLatin1String
7519
7520	Returns true if string \a s1 is lexically greater than string \a s2; otherwise
7521	returns false.
7522	*/
7523	/* \fn bool operator>=(const QLatin1String &s1, const QLatin1String &s2)
7524	\relates QLatin1String
7525
7526	Returns true if string \a s1 is lexically greater than or equal to
7527	string \a s2; otherwise returns false.
7528	*/
7529
7530
7531	#if !defined(QT_NO_DATASTREAM) || (defined(QT_BOOTSTRAPPED) && !defined(QT_BUILD_QMAKE))
7532	/*!
7533	\fn QDataStream &operator<<(QDataStream &stream, const QString &string)
7534	\relates QString
7535
7536	Writes the given \a string to the specified \a stream.
7537
7538	\sa {Serializing Qt Data Types}
7539	*/
7540
7541	QDataStream &operator<<(QDataStream &out, const QString &str)
7542	{
7543	if (out.version() == 1) {
7544	out << str.toLatin1();
7545	} else {
7546	if (!str.isNull() || out.version() < 3) {
7547	if ((out.byteOrder() == QDataStream::BigEndian) == (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7548	out.writeBytes(reinterpret_cast<const char *>(str.unicode()), sizeof(QChar) * str.length());
7549	} else {
7550	QVarLengthArray<ushort> buffer(str.length());
7551	const ushort *data = reinterpret_cast<const ushort *>(str.constData());
7552	for (int i = 0; i < str.length(); i++) {
7553	buffer[i] = qbswap(*data);
7554	++data;
7555	}
7556	out.writeBytes(reinterpret_cast<const char *>(buffer.data()), sizeof(ushort) * buffer.size());
7557	}
7558	} else {
7559	// write null marker
7560	out << (quint32)0xffffffff;
7561	}
7562	}
7563	return out;
7564	}
7565
7566	/*!
7567	\fn QDataStream &operator>>(QDataStream &stream, QString &string)
7568	\relates QString
7569
7570	Reads a string from the specified \a stream into the given \a string.
7571
7572	\sa {Serializing Qt Data Types}
7573	*/
7574
7575	QDataStream &operator>>(QDataStream &in, QString &str)
7576	{
7577	#ifdef QT_QSTRING_UCS_4
7578	#if defined(Q_CC_GNU)
7579	#warning "operator>> not working properly"
7580	#endif
7581	#endif
7582
7583	if (in.version() == 1) {
7584	QByteArray l;
7585	in >> l;
7586	str = QString::fromLatin1(l);
7587	} else {
7588	quint32 bytes = 0;
7589	in >> bytes; // read size of string
7590	if (bytes == 0xffffffff) { // null string
7591	str.clear();
7592	} else if (bytes > 0) { // not empty
7593	if (bytes & 0x1) {
7594	str.clear();
7595	in.setStatus(QDataStream::ReadCorruptData);
7596	return in;
7597	}
7598
7599	const quint32 Step = 1024 * 1024;
7600	quint32 len = bytes / 2;
7601	quint32 allocated = 0;
7602
7603	while (allocated < len) {
7604	int blockSize = qMin(Step, len - allocated);
7605	str.resize(allocated + blockSize);
7606	if (in.readRawData(reinterpret_cast<char *>(str.data()) + allocated * 2,
7607	blockSize * 2) != blockSize * 2) {
7608	str.clear();
7609	in.setStatus(QDataStream::ReadPastEnd);
7610	return in;
7611	}
7612	allocated += blockSize;
7613	}
7614
7615	if ((in.byteOrder() == QDataStream::BigEndian)
7616	!= (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7617	ushort *data = reinterpret_cast<ushort *>(str.data());
7618	while (len--) {
7619	*data = qbswap(*data);
7620	++data;
7621	}
7622	}
7623	} else {
7624	str = QLatin1String("");
7625	}
7626	}
7627	return in;
7628	}
7629	#endif // QT_NO_DATASTREAM
7630
7631	/*!
7632	\fn void QString::setLength(int nl)
7633
7634	Use resize() instead.
7635	*/
7636
7637	/*!
7638	\fn QString QString::copy() const
7639
7640	Use simple assignment instead. QString is implicitly shared so if
7641	a copy is modified only the copy is changed.
7642	*/
7643
7644	/*!
7645	\fn QString &QString::remove(QChar c, bool cs)
7646
7647	Use the remove(QChar, Qt::CaseSensitive) overload instead.
7648	*/
7649
7650	/*!
7651	\fn QString &QString::remove(const QString &s, bool cs)
7652
7653	Use the remove(QString, Qt::CaseSensitive) overload instead.
7654	*/
7655
7656	/*!
7657	\fn QString &QString::replace(QChar c, const QString &after, bool cs)
7658
7659	Use the replace(QChar, QString, Qt::CaseSensitive) overload instead.
7660	*/
7661
7662	/*!
7663	\fn QString &QString::replace(const QString &before, const QString &after, bool cs)
7664
7665	Use the replace(QString, QString, Qt::CaseSensitive) overload instead.
7666	*/
7667
7668	/*!
7669	\fn QString &QString::replace(char c, const QString &after, bool cs)
7670
7671	Use the replace(QChar, QString, Qt::CaseSensitive) overload instead.
7672	*/
7673
7674	/*!
7675	\fn QString &QString::replace(char c, const QString &after, Qt::CaseSensitivity cs)
7676
7677	Use the replace(QChar, QString, Qt::CaseSensitive) overload instead.
7678	*/
7679
7680	/*!
7681	\fn int QString::find(QChar c, int i = 0, bool cs = true) const
7682
7683	Use indexOf() instead.
7684	*/
7685
7686	/*!
7687	\fn int QString::find(const QString &s, int i = 0, bool cs = true) const
7688
7689	Use indexOf() instead.
7690	*/
7691
7692	/*!
7693	\fn int QString::findRev(QChar c, int i = -1, bool cs = true) const
7694
7695	Use lastIndexOf() instead.
7696	*/
7697
7698	/*!
7699	\fn int QString::findRev(const QString &s, int i = -1, bool cs = true) const
7700
7701	Use lastIndexOf() instead.
7702	*/
7703
7704	/*!
7705	\fn int QString::find(const QRegExp &rx, int i=0) const
7706
7707	Use indexOf() instead.
7708	*/
7709
7710	/*!
7711	\fn int QString::find(QRegExp &rx, int i=0) const
7712	\internal
7713	\since 4.5
7714
7715	Use indexOf() instead.
7716	*/
7717
7718	/*!
7719	\fn int QString::findRev(const QRegExp &rx, int i=-1) const
7720
7721	Use lastIndexOf() instead.
7722	*/
7723
7724	/*!
7725	\fn int QString::findRev(QRegExp &rx, int i=0) const
7726	\internal
7727	\since 4.5
7728
7729	Use lastIndexOf() instead.
7730	*/
7731
7732	/*!
7733	\fn QBool QString::contains(QChar c, bool cs) const
7734
7735	Use the contains(QChar, Qt::CaseSensitive) overload instead.
7736	*/
7737
7738	/*!
7739	\fn QBool QString::contains(const QString &s, bool cs) const
7740
7741	Use the contains(QString, Qt::CaseSensitive) overload instead.
7742	*/
7743
7744	/*!
7745	\fn bool QString::startsWith(const QString &s, bool cs) const
7746
7747	Use the startsWith(QString, Qt::CaseSensitive) overload instead.
7748	*/
7749
7750
7751	/*!
7752	\fn bool QString::endsWith(const QString &s, bool cs) const
7753
7754	Use the endsWith(QString, Qt::CaseSensitive) overload instead.
7755	*/
7756
7757	/*!
7758	\fn QString QString::leftJustify(int width, QChar fill = QLatin1Char(' '), bool trunc=false) const
7759
7760	Use leftJustified() instead.
7761	*/
7762
7763	/*!
7764	\fn QString QString::rightJustify(int width, QChar fill = QLatin1Char(' '), bool trunc=false) const
7765
7766	Use rightJustified() instead.
7767	*/
7768
7769	/*!
7770	\fn QString QString::lower() const
7771
7772	Use toLower() instead.
7773	*/
7774
7775	/*!
7776	\fn QString QString::upper() const
7777
7778	Use toUpper() instead.
7779	*/
7780
7781	/*!
7782	\fn QString QString::stripWhiteSpace() const
7783
7784	Use trimmed() instead.
7785	*/
7786
7787	/*!
7788	\fn QString QString::simplifyWhiteSpace() const
7789
7790	Use simplified() instead.
7791	*/
7792
7793	/*!
7794	\fn QString &QString::setUnicodeCodes(const ushort *unicode_as_ushorts, int size)
7795
7796	Use setUtf16() instead.
7797	*/
7798
7799	/*!
7800	\fn ushort *QString::ucs2() const
7801
7802	Use utf16() instead.
7803	*/
7804
7805	/*!
7806	\fn QString QString::fromUcs2(const ushort *unicode, int size = -1)
7807
7808	Use fromUtf16() instead.
7809	*/
7810
7811	/*!
7812	\fn QString &QString::setAscii(const char *str, int len = -1)
7813
7814	Use fromAscii() instead.
7815	*/
7816
7817	/*!
7818	\fn QString &QString::setLatin1(const char *str, int len = -1)
7819
7820	Use fromLatin1() instead.
7821	*/
7822
7823	/*!
7824	\fn QChar QString::constref(uint i) const
7825
7826	Use at() instead.
7827	*/
7828
7829	/*!
7830	\fn QChar &QString::ref(uint i);
7831
7832	Use operator[]() instead.
7833	*/
7834
7835	/*!
7836	\fn QString::operator const char *() const
7837
7838	Use toAscii().constData() instead.
7839	*/
7840
7841	/*!
7842	\class QConstString
7843	\brief The QConstString class is a wrapper for constant Unicode string data.
7844	\compat
7845
7846	In Qt 4, QConstString is replaced by QString::fromRawData(), a
7847	static function that constructs a QString object based on Unicode
7848	string data.
7849
7850	Because QString::fromRawData() has slightly more stringent
7851	constraints than QConstString had in Qt 3, the new QConstString
7852	class takes a deep copy of the string data.
7853
7854	\sa QString::fromRawData()
7855	*/
7856
7857	/*!
7858	\fn QConstString::QConstString(const QChar *unicode, int size)
7859
7860	Use QString(\a unicode, \a size) or
7861	QString::fromRawData(\a unicode, \a size) instead.
7862	*/
7863
7864	/*!
7865	\fn const QString &QConstString::string() const
7866
7867	Returns \c *this. Not necessary in Qt 4.
7868	*/
7869
7870
7871
7872	/*!
7873	\class QStringRef
7874	\since 4.3
7875	\brief The QStringRef class provides a thin wrapper around QString substrings.
7876	\reentrant
7877	\ingroup tools
7878	\ingroup string-processing
7879
7880	QStringRef provides a read-only subset of the QString API.
7881
7882	A string reference explicitly references a portion of a string()
7883	with a given size(), starting at a specific position(). Calling
7884	toString() returns a copy of the data as a real QString instance.
7885
7886	This class is designed to improve the performance of substring
7887	handling when manipulating substrings obtained from existing QString
7888	instances. QStringRef avoids the memory allocation and reference
7889	counting overhead of a standard QString by simply referencing a
7890	part of the original string. This can prove to be advantageous in
7891	low level code, such as that used in a parser, at the expense of
7892	potentially more complex code.
7893
7894	For most users, there are no semantic benefits to using QStringRef
7895	instead of QString since QStringRef requires attention to be paid
7896	to memory management issues, potentially making code more complex
7897	to write and maintain.
7898
7899	\warning A QStringRef is only valid as long as the referenced
7900	string exists. If the original string is deleted, the string
7901	reference points to an invalid memory location.
7902
7903	We suggest that you only use this class in stable code where profiling
7904	has clearly identified that performance improvements can be made by
7905	replacing standard string operations with the optimized substring
7906	handling provided by this class.
7907
7908	\sa {Implicitly Shared Classes}
7909	*/
7910
7911
7912	/*!
7913	\fn QStringRef::QStringRef()
7914
7915	Constructs an empty string reference.
7916	*/
7917
7918	/*! \fn QStringRef::QStringRef(const QString *string, int position, int length)
7919
7920	Constructs a string reference to the range of characters in the given
7921	\a string specified by the starting \a position and \a length in characters.
7922
7923	\warning This function exists to improve performance as much as possible,
7924	and performs no bounds checking. For program correctness, \a position and
7925	\a length must describe a valid substring of \a string.
7926
7927	This means that the starting \a position must be positive or 0 and smaller
7928	than \a string's length, and \a length must be positive or 0 but smaller than
7929	the string's length minus the starting \a position;
7930	i.e, 0 <= position < string->length() and
7931	0 <= length <= string->length() - position must both be satisfied.
7932	*/
7933
7934	/*! \fn QStringRef::QStringRef(const QString *string)
7935
7936	Constructs a string reference to the given \a string.
7937	*/
7938
7939	/*! \fn QStringRef::QStringRef(const QStringRef &other)
7940
7941	Constructs a copy of the \a other string reference.
7942	*/
7943	/*!
7944	\fn QStringRef::~QStringRef()
7945
7946	Destroys the string reference.
7947
7948	Since this class is only used to refer to string data, and does not take
7949	ownership of it, no memory is freed when instances are destroyed.
7950	*/
7951
7952
7953	/*!
7954	\fn int QStringRef::position() const
7955
7956	Returns the starting position in the referenced string that is referred to
7957	by the string reference.
7958
7959	\sa size(), string()
7960	*/
7961
7962	/*!
7963	\fn int QStringRef::size() const
7964
7965	Returns the number of characters referred to by the string reference.
7966	Equivalent to length() and count().
7967
7968	\sa position(), string()
7969	*/
7970	/*!
7971	\fn int QStringRef::count() const
7972	Returns the number of characters referred to by the string reference.
7973	Equivalent to size() and length().
7974
7975	\sa position(), string()
7976	*/
7977	/*!
7978	\fn int QStringRef::length() const
7979	Returns the number of characters referred to by the string reference.
7980	Equivalent to size() and count().
7981
7982	\sa position(), string()
7983	*/
7984
7985
7986	/*!
7987	\fn bool QStringRef::isEmpty() const
7988
7989	Returns true if the string reference has no characters; otherwise returns
7990	false.
7991
7992	A string reference is empty if its size is zero.
7993
7994	\sa size()
7995	*/
7996
7997	/*!
7998	\fn bool QStringRef::isNull() const
7999
8000	Returns true if string() returns a null pointer or a pointer to a
8001	null string; otherwise returns true.
8002
8003	\sa size()
8004	*/
8005
8006	/*!
8007	\fn const QString *QStringRef::string() const
8008
8009	Returns a pointer to the string referred to by the string reference, or
8010	0 if it does not reference a string.
8011
8012	\sa unicode()
8013	*/
8014
8015
8016	/*!
8017	\fn const QChar *QStringRef::unicode() const
8018
8019	Returns a Unicode representation of the string reference. Since
8020	the data stems directly from the referenced string, it is not
8021	null-terminated unless the string reference includes the string's
8022	null terminator.
8023
8024	\sa string()
8025	*/
8026
8027	/*!
8028	\fn const QChar *QStringRef::data() const
8029
8030	Same as unicode().
8031	*/
8032
8033	/*!
8034	\fn const QChar *QStringRef::constData() const
8035
8036	Same as unicode().
8037	*/
8038
8039	/*!
8040	Returns a copy of the string reference as a QString object.
8041
8042	If the string reference is not a complete reference of the string
8043	(meaning that position() is 0 and size() equals string()->size()),
8044	this function will allocate a new string to return.
8045
8046	\sa string()
8047	*/
8048
8049	QString QStringRef::toString() const {
8050	if (!m_string)
8051	return QString();
8052	if (m_size && m_position == 0 && m_size == m_string->size())
8053	return *m_string;
8054	return QString(m_string->unicode() + m_position, m_size);
8055	}
8056
8057
8058	/*! \relates QStringRef
8059
8060	Returns true if string reference \a s1 is lexically equal to string reference \a s2; otherwise
8061	returns false.
8062	*/
8063	bool operator==(const QStringRef &s1,const QStringRef &s2)
8064	{ return (s1.size() == s2.size() &&
8065	qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
8066	}
8067
8068	/*! \relates QStringRef
8069
8070	Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
8071	returns false.
8072	*/
8073	bool operator==(const QString &s1,const QStringRef &s2)
8074	{ return (s1.size() == s2.size() &&
8075	qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
8076	}
8077
8078	/*! \relates QStringRef
8079
8080	Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
8081	returns false.
8082	*/
8083	bool operator==(const QLatin1String &s1, const QStringRef &s2)
8084	{
8085	const ushort *uc = reinterpret_cast<const ushort *>(s2.unicode());
8086	const ushort *e = uc + s2.size();
8087	const uchar *c = reinterpret_cast<const uchar *>(s1.latin1());
8088	if (!c)
8089	return s2.isEmpty();
8090
8091	while (*c) {
8092	if (uc == e || *uc != *c)
8093	return false;
8094	++uc;
8095	++c;
8096	}
8097	return (uc == e);
8098	}
8099
8100	/*!
8101	\relates QStringRef
8102
8103	Returns true if string reference \a s1 is lexically less than
8104	string reference \a s2; otherwise returns false.
8105
8106	The comparison is based exclusively on the numeric Unicode values
8107	of the characters and is very fast, but is not what a human would
8108	expect. Consider sorting user-interface strings using the
8109	QString::localeAwareCompare() function.
8110	*/
8111	bool operator<(const QStringRef &s1,const QStringRef &s2)
8112	{
8113	return ucstrcmp(s1.constData(), s1.length(), s2.constData(), s2.length()) < 0;
8114	}
8115
8116	/*!\fn bool operator<=(const QStringRef &s1,const QStringRef &s2)
8117
8118	\relates QStringRef
8119
8120	Returns true if string reference \a s1 is lexically less than
8121	or equal to string reference \a s2; otherwise returns false.
8122
8123	The comparison is based exclusively on the numeric Unicode values
8124	of the characters and is very fast, but is not what a human would
8125	expect. Consider sorting user-interface strings using the
8126	QString::localeAwareCompare() function.
8127	*/
8128
8129	/*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2)
8130
8131	\relates QStringRef
8132
8133	Returns true if string reference \a s1 is lexically greater than
8134	or equal to string reference \a s2; otherwise returns false.
8135
8136	The comparison is based exclusively on the numeric Unicode values
8137	of the characters and is very fast, but is not what a human would
8138	expect. Consider sorting user-interface strings using the
8139	QString::localeAwareCompare() function.
8140	*/
8141
8142	/*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2)
8143
8144	\relates QStringRef
8145
8146	Returns true if string reference \a s1 is lexically greater than
8147	string reference \a s2; otherwise returns false.
8148
8149	The comparison is based exclusively on the numeric Unicode values
8150	of the characters and is very fast, but is not what a human would
8151	expect. Consider sorting user-interface strings using the
8152	QString::localeAwareCompare() function.
8153	*/
8154
8155
8156	/*!
8157	\fn const QChar QStringRef::at(int position) const
8158
8159	Returns the character at the given index \a position in the
8160	string reference.
8161
8162	The \a position must be a valid index position in the string
8163	(i.e., 0 <= \a position < size()).
8164	*/
8165
8166	/*!
8167	\fn void QStringRef::clear()
8168
8169	Clears the contents of the string reference by making it null and empty.
8170
8171	\sa isEmpty(), isNull()
8172	*/
8173
8174	/*!
8175	\fn QStringRef &QStringRef::operator=(const QStringRef &other)
8176
8177	Assigns the \a other string reference to this string reference, and
8178	returns the result.
8179	*/
8180
8181	/*!
8182	\fn QStringRef &QStringRef::operator=(const QString *string)
8183
8184	Constructs a string reference to the given \a string and assigns it to
8185	this string reference, returning the result.
8186	*/
8187
8188	/*!
8189	\typedef QString::DataPtr
8190	\internal
8191	*/
8192
8193	/*!
8194	\fn DataPtr & QString::data_ptr()
8195	\internal
8196	*/
8197
8198
8199
8200	/*! Appends the string reference to \a string, and returns a new
8201	reference to the combined string data.
8202	*/
8203	QStringRef QStringRef::appendTo(QString *string) const
8204	{
8205	if (!string)
8206	return QStringRef();
8207	int pos = string->size();
8208	string->insert(pos, unicode(), size());
8209	return QStringRef(string, pos, size());
8210	}
8211
8212	/*!
8213	\fn int QStringRef::compare(const QStringRef &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8214	\since 4.5
8215
8216	Compares the string \a s1 with the string \a s2 and returns an
8217	integer less than, equal to, or greater than zero if \a s1
8218	is less than, equal to, or greater than \a s2.
8219
8220	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8221	otherwise the comparison is case insensitive.
8222	*/
8223
8224	/*!
8225	\fn int QStringRef::compare(const QStringRef &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8226	\since 4.5
8227	\overload
8228
8229	Compares the string \a s1 with the string \a s2 and returns an
8230	integer less than, equal to, or greater than zero if \a s1
8231	is less than, equal to, or greater than \a s2.
8232
8233	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8234	otherwise the comparison is case insensitive.
8235	*/
8236
8237	/*!
8238	\fn int QStringRef::compare(const QStringRef &s1, QLatin1String s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8239	\since 4.5
8240	\overload
8241
8242	Compares the string \a s1 with the string \a s2 and returns an
8243	integer less than, equal to, or greater than zero if \a s1
8244	is less than, equal to, or greater than \a s2.
8245
8246	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8247	otherwise the comparison is case insensitive.
8248	*/
8249
8250	/*!
8251	\overload
8252	\fn int QStringRef::compare(const QString &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8253	\since 4.5
8254
8255	Compares this string with the \a other string and returns an
8256	integer less than, equal to, or greater than zero if this string
8257	is less than, equal to, or greater than the \a other string.
8258
8259	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8260	otherwise the comparison is case insensitive.
8261
8262	Equivalent to \c {compare(*this, other, cs)}.
8263
8264	\sa QString::compare()
8265	*/
8266
8267	/*!
8268	\overload
8269	\fn int QStringRef::compare(const QStringRef &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8270	\since 4.5
8271
8272	Compares this string with the \a other string and returns an
8273	integer less than, equal to, or greater than zero if this string
8274	is less than, equal to, or greater than the \a other string.
8275
8276	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8277	otherwise the comparison is case insensitive.
8278
8279	Equivalent to \c {compare(*this, other, cs)}.
8280
8281	\sa QString::compare()
8282	*/
8283
8284	/*!
8285	\overload
8286	\fn int QStringRef::compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8287	\since 4.5
8288
8289	Compares this string with the \a other string and returns an
8290	integer less than, equal to, or greater than zero if this string
8291	is less than, equal to, or greater than the \a other string.
8292
8293	If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8294	otherwise the comparison is case insensitive.
8295
8296	Equivalent to \c {compare(*this, other, cs)}.
8297
8298	\sa QString::compare()
8299	*/
8300
8301	/*!
8302	\fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QString & s2)
8303	\since 4.5
8304
8305	Compares \a s1 with \a s2 and returns an integer less than, equal
8306	to, or greater than zero if \a s1 is less than, equal to, or
8307	greater than \a s2.
8308
8309	The comparison is performed in a locale- and also
8310	platform-dependent manner. Use this function to present sorted
8311	lists of strings to the user.
8312
8313	On Mac OS X, this function compares according the
8314	"Order for sorted lists" setting in the International prefereces panel.
8315
8316	\sa compare(), QTextCodec::locale()
8317	*/
8318
8319	/*!
8320	\fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QStringRef & s2)
8321	\since 4.5
8322	\overload
8323
8324	Compares \a s1 with \a s2 and returns an integer less than, equal
8325	to, or greater than zero if \a s1 is less than, equal to, or
8326	greater than \a s2.
8327
8328	The comparison is performed in a locale- and also
8329	platform-dependent manner. Use this function to present sorted
8330	lists of strings to the user.
8331
8332	*/
8333
8334	/*!
8335	\fn int QStringRef::localeAwareCompare(const QString &other) const
8336	\since 4.5
8337	\overload
8338
8339	Compares this string with the \a other string and returns an
8340	integer less than, equal to, or greater than zero if this string
8341	is less than, equal to, or greater than the \a other string.
8342
8343	The comparison is performed in a locale- and also
8344	platform-dependent manner. Use this function to present sorted
8345	lists of strings to the user.
8346	*/
8347
8348	/*!
8349	\fn int QStringRef::localeAwareCompare(const QStringRef &other) const
8350	\since 4.5
8351	\overload
8352
8353	Compares this string with the \a other string and returns an
8354	integer less than, equal to, or greater than zero if this string
8355	is less than, equal to, or greater than the \a other string.
8356
8357	The comparison is performed in a locale- and also
8358	platform-dependent manner. Use this function to present sorted
8359	lists of strings to the user.
8360	*/
8361
8362	/*!
8363	\fn QString &QString::append(const QStringRef &reference)
8364	\since 4.4
8365
8366	Appends the given string \a reference to this string and returns the result.
8367	*/
8368	QString &QString::append(const QStringRef &str)
8369	{
8370	if (str.string() == this) {
8371	str.appendTo(this);
8372	} else if (str.string()) {
8373	int oldSize = size();
8374	resize(oldSize + str.size());
8375	memcpy(data() + oldSize, str.unicode(), str.size() * sizeof(QChar));
8376	}
8377	return *this;
8378	}
8379
8380	/*!
8381	\since 4.4
8382
8383	Returns a substring reference to the \a n leftmost characters
8384	of the string.
8385
8386	If \a n is greater than size() or less than zero, a reference to the entire
8387	string is returned.
8388
8389	\snippet doc/src/snippets/qstring/main.cpp leftRef
8390
8391	\sa left(), rightRef(), midRef(), startsWith()
8392	*/
8393	QStringRef QString::leftRef(int n) const
8394	{
8395	if (n >= d->size || n < 0)
8396	n = d->size;
8397	return QStringRef(this, 0, n);
8398	}
8399
8400	/*!
8401	\since 4.4
8402
8403	Returns a substring reference to the \a n rightmost characters
8404	of the string.
8405
8406	If \a n is greater than size() or less than zero, a reference to the entire
8407	string is returned.
8408
8409	\snippet doc/src/snippets/qstring/main.cpp rightRef
8410
8411	\sa right(), leftRef(), midRef(), endsWith()
8412	*/
8413	QStringRef QString::rightRef(int n) const
8414	{
8415	if (n >= d->size || n < 0)
8416	n = d->size;
8417	return QStringRef(this, d->size - n, n);
8418	}
8419
8420	/*!
8421	\since 4.4
8422
8423	Returns a substring reference to \a n characters of this string,
8424	starting at the specified \a position.
8425
8426	If the \a position exceeds the length of the string, an empty
8427	reference is returned.
8428
8429	If there are less than \a n characters available in the string,
8430	starting at the given \a position, or if \a n is -1 (default), the
8431	function returns all characters from the specified \a position
8432	onwards.
8433
8434	Example:
8435
8436	\snippet doc/src/snippets/qstring/main.cpp midRef
8437
8438	\sa mid(), leftRef(), rightRef()
8439	*/
8440
8441	QStringRef QString::midRef(int position, int n) const
8442	{
8443	if (d == &shared_null || position >= d->size)
8444	return QStringRef();
8445	if (n < 0)
8446	n = d->size - position;
8447	if (position < 0) {
8448	n += position;
8449	position = 0;
8450	}
8451	if (n + position > d->size)
8452	n = d->size - position;
8453	return QStringRef(this, position, n);
8454	}
8455
8456	/*!
8457	\since 4.8
8458
8459	Returns the index position of the first occurrence of the string \a
8460	str in this string reference, searching forward from index position
8461	\a from. Returns -1 if \a str is not found.
8462
8463	If \a cs is Qt::CaseSensitive (default), the search is case
8464	sensitive; otherwise the search is case insensitive.
8465
8466	If \a from is -1, the search starts at the last character; if it is
8467	-2, at the next to last character and so on.
8468
8469	\sa QString::indexOf(), lastIndexOf(), contains(), count()
8470	*/
8471	int QStringRef::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8472	{
8473	return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
8474	}
8475
8476	/*!
8477	\since 4.8
8478	\overload indexOf()
8479
8480	Returns the index position of the first occurrence of the
8481	character \a ch in the string reference, searching forward from
8482	index position \a from. Returns -1 if \a ch could not be found.
8483
8484	\sa QString::indexOf(), lastIndexOf(), contains(), count()
8485	*/
8486	int QStringRef::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8487	{
8488	return findChar(unicode(), length(), ch, from, cs);
8489	}
8490
8491	/*!
8492	\since 4.8
8493
8494	Returns the index position of the first occurrence of the string \a
8495	str in this string reference, searching forward from index position
8496	\a from. Returns -1 if \a str is not found.
8497
8498	If \a cs is Qt::CaseSensitive (default), the search is case
8499	sensitive; otherwise the search is case insensitive.
8500
8501	If \a from is -1, the search starts at the last character; if it is
8502	-2, at the next to last character and so on.
8503
8504	\sa QString::indexOf(), lastIndexOf(), contains(), count()
8505	*/
8506	int QStringRef::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8507	{
8508	return qt_find_latin1_string(unicode(), size(), str, from, cs);
8509	}
8510
8511	/*!
8512	\since 4.8
8513
8514	\overload indexOf()
8515
8516	Returns the index position of the first occurrence of the string
8517	reference \a str in this string reference, searching forward from
8518	index position \a from. Returns -1 if \a str is not found.
8519
8520	If \a cs is Qt::CaseSensitive (default), the search is case
8521	sensitive; otherwise the search is case insensitive.
8522
8523	\sa QString::indexOf(), lastIndexOf(), contains(), count()
8524	*/
8525	int QStringRef::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8526	{
8527	return qFindString(unicode(), size(), from, str.unicode(), str.size(), cs);
8528	}
8529
8530	/*!
8531	\since 4.8
8532
8533	Returns the index position of the last occurrence of the string \a
8534	str in this string reference, searching backward from index position
8535	\a from. If \a from is -1 (default), the search starts at the last
8536	character; if \a from is -2, at the next to last character and so
8537	on. Returns -1 if \a str is not found.
8538
8539	If \a cs is Qt::CaseSensitive (default), the search is case
8540	sensitive; otherwise the search is case insensitive.
8541
8542	\sa QString::lastIndexOf(), indexOf(), contains(), count()
8543	*/
8544	int QStringRef::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8545	{
8546	const int sl = str.size();
8547	if (sl == 1)
8548	return lastIndexOf(str.at(0), from, cs);
8549
8550	const int l = size();;
8551	if (from < 0)
8552	from += l;
8553	int delta = l - sl;
8554	if (from == l && sl == 0)
8555	return from;
8556	if (from < 0 || from >= l || delta < 0)
8557	return -1;
8558	if (from > delta)
8559	from = delta;
8560
8561	return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8562	reinterpret_cast<const ushort*>(str.unicode()), str.size(), cs);
8563	}
8564
8565	/*!
8566	\since 4.8
8567	\overload lastIndexOf()
8568
8569	Returns the index position of the last occurrence of the character
8570	\a ch, searching backward from position \a from.
8571
8572	\sa QString::lastIndexOf(), indexOf(), contains(), count()
8573	*/
8574	int QStringRef::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8575	{
8576	return qt_last_index_of(unicode(), size(), ch, from, cs);
8577	}
8578
8579	/*!
8580	\since 4.8
8581	\overload lastIndexOf()
8582
8583	Returns the index position of the last occurrence of the string \a
8584	str in this string reference, searching backward from index position
8585	\a from. If \a from is -1 (default), the search starts at the last
8586	character; if \a from is -2, at the next to last character and so
8587	on. Returns -1 if \a str is not found.
8588
8589	If \a cs is Qt::CaseSensitive (default), the search is case
8590	sensitive; otherwise the search is case insensitive.
8591
8592	\sa QString::lastIndexOf(), indexOf(), contains(), count()
8593	*/
8594	int QStringRef::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8595	{
8596	const int sl = qstrlen(str.latin1());
8597	if (sl == 1)
8598	return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
8599
8600	const int l = size();
8601	if (from < 0)
8602	from += l;
8603	int delta = l - sl;
8604	if (from == l && sl == 0)
8605	return from;
8606	if (from < 0 || from >= l || delta < 0)
8607	return -1;
8608	if (from > delta)
8609	from = delta;
8610
8611	QVarLengthArray<ushort> s(sl);
8612	for (int i = 0; i < sl; ++i)
8613	s[i] = str.latin1()[i];
8614
8615	return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, s.data(), sl, cs);
8616	}
8617
8618	/*!
8619	\since 4.8
8620	\overload lastIndexOf()
8621
8622	Returns the index position of the last occurrence of the string
8623	reference \a str in this string reference, searching backward from
8624	index position \a from. If \a from is -1 (default), the search
8625	starts at the last character; if \a from is -2, at the next to last
8626	character and so on. Returns -1 if \a str is not found.
8627
8628	If \a cs is Qt::CaseSensitive (default), the search is case
8629	sensitive; otherwise the search is case insensitive.
8630
8631	\sa QString::lastIndexOf(), indexOf(), contains(), count()
8632	*/
8633	int QStringRef::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8634	{
8635	const int sl = str.size();
8636	if (sl == 1)
8637	return lastIndexOf(str.at(0), from, cs);
8638
8639	const int l = size();
8640	if (from < 0)
8641	from += l;
8642	int delta = l - sl;
8643	if (from == l && sl == 0)
8644	return from;
8645	if (from < 0 || from >= l || delta < 0)
8646	return -1;
8647	if (from > delta)
8648	from = delta;
8649
8650	return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8651	reinterpret_cast<const ushort*>(str.unicode()),
8652	str.size(), cs);
8653	}
8654
8655	/*!
8656	\since 4.8
8657	Returns the number of (potentially overlapping) occurrences of
8658	the string \a str in this string reference.
8659
8660	If \a cs is Qt::CaseSensitive (default), the search is
8661	case sensitive; otherwise the search is case insensitive.
8662
8663	\sa QString::count(), contains(), indexOf()
8664	*/
8665	int QStringRef::count(const QString &str, Qt::CaseSensitivity cs) const
8666	{
8667	return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8668	}
8669
8670	/*!
8671	\since 4.8
8672	\overload count()
8673
8674	Returns the number of occurrences of the character \a ch in the
8675	string reference.
8676
8677	If \a cs is Qt::CaseSensitive (default), the search is
8678	case sensitive; otherwise the search is case insensitive.
8679
8680	\sa QString::count(), contains(), indexOf()
8681	*/
8682	int QStringRef::count(QChar ch, Qt::CaseSensitivity cs) const
8683	{
8684	return qt_string_count(unicode(), size(), ch, cs);
8685	}
8686
8687	/*!
8688	\since 4.8
8689	\overload count()
8690
8691	Returns the number of (potentially overlapping) occurrences of the
8692	string reference \a str in this string reference.
8693
8694	If \a cs is Qt::CaseSensitive (default), the search is
8695	case sensitive; otherwise the search is case insensitive.
8696
8697	\sa QString::count(), contains(), indexOf()
8698	*/
8699	int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs) const
8700	{
8701	return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8702	}
8703
8704	/*!
8705	\since 4.8
8706
8707	Returns true if the string reference starts with \a str; otherwise
8708	returns false.
8709
8710	If \a cs is Qt::CaseSensitive (default), the search is
8711	case sensitive; otherwise the search is case insensitive.
8712
8713	\sa QString::startsWith(), endsWith()
8714	*/
8715	bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs) const
8716	{
8717	return qt_starts_with(isNull() ? 0 : unicode(), size(),
8718	str.isNull() ? 0 : str.unicode(), str.size(), cs);
8719	}
8720
8721	/*!
8722	\since 4.8
8723	\overload startsWith()
8724	\sa QString::startsWith(), endsWith()
8725	*/
8726	bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8727	{
8728	return qt_starts_with(isNull() ? 0 : unicode(), size(), str, cs);
8729	}
8730
8731	/*!
8732	\since 4.8
8733	\overload startsWith()
8734	\sa QString::startsWith(), endsWith()
8735	*/
8736	bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8737	{
8738	return qt_starts_with(isNull() ? 0 : unicode(), size(),
8739	str.isNull() ? 0 : str.unicode(), str.size(), cs);
8740	}
8741
8742	/*!
8743	\since 4.8
8744	\overload startsWith()
8745
8746	Returns true if the string reference starts with \a ch; otherwise
8747	returns false.
8748
8749	If \a cs is Qt::CaseSensitive (default), the search is case
8750	sensitive; otherwise the search is case insensitive.
8751
8752	\sa QString::startsWith(), endsWith()
8753	*/
8754	bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs) const
8755	{
8756	if (!isEmpty()) {
8757	const ushort *data = reinterpret_cast<const ushort*>(unicode());
8758	return (cs == Qt::CaseSensitive
8759	? data[0] == ch
8760	: foldCase(data[0]) == foldCase(ch.unicode()));
8761	} else {
8762	return false;
8763	}
8764	}
8765
8766	/*!
8767	\since 4.8
8768	Returns true if the string reference ends with \a str; otherwise
8769	returns false.
8770
8771	If \a cs is Qt::CaseSensitive (default), the search is case
8772	sensitive; otherwise the search is case insensitive.
8773
8774	\sa QString::endsWith(), startsWith()
8775	*/
8776	bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs) const
8777	{
8778	return qt_ends_with(isNull() ? 0 : unicode(), size(),
8779	str.isNull() ? 0 : str.unicode(), str.size(), cs);
8780	}
8781
8782	/*!
8783	\since 4.8
8784	\overload endsWith()
8785
8786	Returns true if the string reference ends with \a ch; otherwise
8787	returns false.
8788
8789	If \a cs is Qt::CaseSensitive (default), the search is case
8790	sensitive; otherwise the search is case insensitive.
8791
8792	\sa QString::endsWith(), endsWith()
8793	*/
8794	bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs) const
8795	{
8796	if (!isEmpty()) {
8797	const ushort *data = reinterpret_cast<const ushort*>(unicode());
8798	const int size = length();
8799	return (cs == Qt::CaseSensitive
8800	? data[size - 1] == ch
8801	: foldCase(data[size - 1]) == foldCase(ch.unicode()));
8802	} else {
8803	return false;
8804	}
8805	}
8806
8807	/*!
8808	\since 4.8
8809	\overload endsWith()
8810	\sa QString::endsWith(), endsWith()
8811	*/
8812	bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8813	{
8814	return qt_ends_with(isNull() ? 0 : unicode(), size(), str, cs);
8815	}
8816
8817	/*!
8818	\since 4.8
8819	\overload endsWith()
8820	\sa QString::endsWith(), endsWith()
8821	*/
8822	bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8823	{
8824	return qt_ends_with(isNull() ? 0 : unicode(), size(),
8825	str.isNull() ? 0 : str.unicode(), str.size(), cs);
8826	}
8827
8828
8829	/*! \fn bool QStringRef::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8830
8831	\since 4.8
8832	Returns true if this string reference contains an occurrence of
8833	the string \a str; otherwise returns false.
8834
8835	If \a cs is Qt::CaseSensitive (default), the search is
8836	case sensitive; otherwise the search is case insensitive.
8837
8838	\sa indexOf(), count()
8839	*/
8840
8841	/*! \fn bool QStringRef::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8842
8843	\overload contains()
8844	\since 4.8
8845
8846	Returns true if this string contains an occurrence of the
8847	character \a ch; otherwise returns false.
8848
8849	If \a cs is Qt::CaseSensitive (default), the search is
8850	case sensitive; otherwise the search is case insensitive.
8851
8852	*/
8853
8854	/*! \fn bool QStringRef::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8855	\overload contains()
8856	\since 4.8
8857
8858	Returns true if this string reference contains an occurrence of
8859	the string reference \a str; otherwise returns false.
8860
8861	If \a cs is Qt::CaseSensitive (default), the search is
8862	case sensitive; otherwise the search is case insensitive.
8863
8864	\sa indexOf(), count()
8865	*/
8866
8867	/*! \fn bool QStringRef::contains(QLatin1String str, Qt::CaseSensitivity cs) const
8868	\since 4,8
8869	\overload contains()
8870
8871	Returns true if this string reference contains an occurrence of
8872	the string \a str; otherwise returns false.
8873
8874	If \a cs is Qt::CaseSensitive (default), the search is
8875	case sensitive; otherwise the search is case insensitive.
8876
8877	\sa indexOf(), count()
8878	*/
8879
8880	static inline int qt_last_index_of(const QChar *haystack, int haystackLen, const QChar &needle,
8881	int from, Qt::CaseSensitivity cs)
8882	{
8883	ushort c = needle.unicode();
8884	if (from < 0)
8885	from += haystackLen;
8886	if (from < 0 || from >= haystackLen)
8887	return -1;
8888	if (from >= 0) {
8889	const ushort *b = reinterpret_cast<const ushort*>(haystack);
8890	const ushort *n = b + from;
8891	if (cs == Qt::CaseSensitive) {
8892	for (; n >= b; --n)
8893	if (*n == c)
8894	return n - b;
8895	} else {
8896	c = foldCase(c);
8897	for (; n >= b; --n)
8898	if (foldCase(*n) == c)
8899	return n - b;
8900	}
8901	}
8902	return -1;
8903
8904
8905	}
8906
8907	static inline int qt_string_count(const QChar *haystack, int haystackLen,
8908	const QChar *needle, int needleLen,
8909	Qt::CaseSensitivity cs)
8910	{
8911	int num = 0;
8912	int i = -1;
8913	if (haystackLen > 500 && needleLen > 5) {
8914	QStringMatcher matcher(needle, needleLen, cs);
8915	while ((i = matcher.indexIn(haystack, haystackLen, i + 1)) != -1)
8916	++num;
8917	} else {
8918	while ((i = qFindString(haystack, haystackLen, i + 1, needle, needleLen, cs)) != -1)
8919	++num;
8920	}
8921	return num;
8922	}
8923
8924	static inline int qt_string_count(const QChar *unicode, int size, const QChar &ch,
8925	Qt::CaseSensitivity cs)
8926	{
8927	ushort c = ch.unicode();
8928	int num = 0;
8929	const ushort *b = reinterpret_cast<const ushort*>(unicode);
8930	const ushort *i = b + size;
8931	if (cs == Qt::CaseSensitive) {
8932	while (i != b)
8933	if (*--i == c)
8934	++num;
8935	} else {
8936	c = foldCase(c);
8937	while (i != b)
8938	if (foldCase(*(--i)) == c)
8939	++num;
8940	}
8941	return num;
8942	}
8943
8944	static inline int qt_find_latin1_string(const QChar *haystack, int size,
8945	const QLatin1String &needle,
8946	int from, Qt::CaseSensitivity cs)
8947	{
8948	const char *latin1 = needle.latin1();
8949	int len = qstrlen(latin1);
8950	QVarLengthArray<ushort> s(len);
8951	for (int i = 0; i < len; ++i)
8952	s[i] = latin1[i];
8953
8954	return qFindString(haystack, size, from,
8955	reinterpret_cast<const QChar*>(s.constData()), len, cs);
8956	}
8957
8958	static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8959	const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
8960	{
8961	if (!haystack)
8962	return !needle;
8963	if (haystackLen == 0)
8964	return needleLen == 0;
8965	if (needleLen > haystackLen)
8966	return false;
8967
8968	const ushort *h = reinterpret_cast<const ushort*>(haystack);
8969	const ushort *n = reinterpret_cast<const ushort*>(needle);
8970
8971	if (cs == Qt::CaseSensitive) {
8972	return qMemEquals(h, n, needleLen);
8973	} else {
8974	uint last = 0;
8975	uint olast = 0;
8976	for (int i = 0; i < needleLen; ++i)
8977	if (foldCase(h[i], last) != foldCase(n[i], olast))
8978	return false;
8979	}
8980	return true;
8981	}
8982
8983	static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8984	const QLatin1String &needle, Qt::CaseSensitivity cs)
8985	{
8986	if (!haystack)
8987	return !needle.latin1();
8988	if (haystackLen == 0)
8989	return !needle.latin1() || *needle.latin1() == 0;
8990	const int slen = qstrlen(needle.latin1());
8991	if (slen > haystackLen)
8992	return false;
8993	const ushort *data = reinterpret_cast<const ushort*>(haystack);
8994	const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
8995	if (cs == Qt::CaseSensitive) {
8996	for (int i = 0; i < slen; ++i)
8997	if (data[i] != latin[i])
8998	return false;
8999	} else {
9000	for (int i = 0; i < slen; ++i)
9001	if (foldCase(data[i]) != foldCase((ushort)latin[i]))
9002	return false;
9003	}
9004	return true;
9005	}
9006
9007	static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
9008	const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
9009	{
9010	if (!haystack)
9011	return !needle;
9012	if (haystackLen == 0)
9013	return needleLen == 0;
9014	const int pos = haystackLen - needleLen;
9015	if (pos < 0)
9016	return false;
9017
9018	const ushort *h = reinterpret_cast<const ushort*>(haystack);
9019	const ushort *n = reinterpret_cast<const ushort*>(needle);
9020
9021	if (cs == Qt::CaseSensitive) {
9022	return qMemEquals(h + pos, n, needleLen);
9023	} else {
9024	uint last = 0;
9025	uint olast = 0;
9026	for (int i = 0; i < needleLen; i++)
9027	if (foldCase(h[pos+i], last) != foldCase(n[i], olast))
9028	return false;
9029	}
9030	return true;
9031	}
9032
9033
9034	static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
9035	const QLatin1String &needle, Qt::CaseSensitivity cs)
9036	{
9037	if (!haystack)
9038	return !needle.latin1();
9039	if (haystackLen == 0)
9040	return !needle.latin1() || *needle.latin1() == 0;
9041	const int slen = qstrlen(needle.latin1());
9042	int pos = haystackLen - slen;
9043	if (pos < 0)
9044	return false;
9045	const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
9046	const ushort *data = reinterpret_cast<const ushort*>(haystack);
9047	if (cs == Qt::CaseSensitive) {
9048	for (int i = 0; i < slen; i++)
9049	if (data[pos+i] != latin[i])
9050	return false;
9051	} else {
9052	for (int i = 0; i < slen; i++)
9053	if (foldCase(data[pos+i]) != foldCase((ushort)latin[i]))
9054	return false;
9055	}
9056	return true;
9057	}
9058
9059	/*!
9060	\since 4.8
9061
9062	Returns a Latin-1 representation of the string as a QByteArray.
9063
9064	The returned byte array is undefined if the string contains non-Latin1
9065	characters. Those characters may be suppressed or replaced with a
9066	question mark.
9067
9068	\sa toAscii(), toUtf8(), toLocal8Bit(), QTextCodec
9069	*/
9070	QByteArray QStringRef::toLatin1() const
9071	{
9072	return toLatin1_helper(unicode(), length());
9073	}
9074
9075	/*!
9076	\since 4.8
9077
9078	Returns an 8-bit representation of the string as a QByteArray.
9079
9080	If a codec has been set using QTextCodec::setCodecForCStrings(),
9081	it is used to convert Unicode to 8-bit char; otherwise this
9082	function does the same as toLatin1().
9083
9084	Note that, despite the name, this function does not necessarily return an US-ASCII
9085	(ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
9086
9087	\sa toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
9088	*/
9089	QByteArray QStringRef::toAscii() const
9090	{
9091	#ifndef QT_NO_TEXTCODEC
9092	if (QString::codecForCStrings)
9093	return QString::codecForCStrings->fromUnicode(unicode(), length());
9094	#endif // QT_NO_TEXTCODEC
9095	return toLatin1();
9096	}
9097
9098	/*!
9099	\since 4.8
9100
9101	Returns the local 8-bit representation of the string as a
9102	QByteArray. The returned byte array is undefined if the string
9103	contains characters not supported by the local 8-bit encoding.
9104
9105	QTextCodec::codecForLocale() is used to perform the conversion from
9106	Unicode. If the locale encoding could not be determined, this function
9107	does the same as toLatin1().
9108
9109	If this string contains any characters that cannot be encoded in the
9110	locale, the returned byte array is undefined. Those characters may be
9111	suppressed or replaced by another.
9112
9113	\sa toAscii(), toLatin1(), toUtf8(), QTextCodec
9114	*/
9115	QByteArray QStringRef::toLocal8Bit() const
9116	{
9117	#ifndef QT_NO_TEXTCODEC
9118	if (QTextCodec::codecForLocale())
9119	return QTextCodec::codecForLocale()->fromUnicode(unicode(), length());
9120	#endif // QT_NO_TEXTCODEC
9121	return toLatin1();
9122	}
9123
9124	/*!
9125	\since 4.8
9126
9127	Returns a UTF-8 representation of the string as a QByteArray.
9128
9129	UTF-8 is a Unicode codec and can represent all characters in a Unicode
9130	string like QString.
9131
9132	However, in the Unicode range, there are certain codepoints that are not
9133	considered characters. The Unicode standard reserves the last two
9134	codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
9135	U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF,
9136	inclusive, as non-characters. If any of those appear in the string, they
9137	may be discarded and will not appear in the UTF-8 representation, or they
9138	may be replaced by one or more replacement characters.
9139
9140	\sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
9141	*/
9142	QByteArray QStringRef::toUtf8() const
9143	{
9144	if (isNull())
9145	return QByteArray();
9146
9147	return QUtf8::convertFromUnicode(constData(), length(), 0);
9148	}
9149
9150	/*!
9151	\since 4.8
9152
9153	Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
9154
9155	UCS-4 is a Unicode codec and is lossless. All characters from this string
9156	can be encoded in UCS-4.
9157
9158	\sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
9159	*/
9160	QVector<uint> QStringRef::toUcs4() const
9161	{
9162	QVector<uint> v(length());
9163	uint *a = v.data();
9164	int len = toUcs4_helper<uint>(reinterpret_cast<const unsigned short *>(unicode()), length(), a);
9165	v.resize(len);
9166	return v;
9167	}
9168
9169	QT_END_NAMESPACE
9170

---

Generated on 2014-Aug-03 from project qt4 revision v4.8.6-54-g06ec7ba
Powered by Code Browser 1.7