1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtCore module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qstringlist.h"
44 #include "qunicodetables_p.h"
45 #ifndef QT_NO_TEXTCODEC
46 #include <qtextcodec.h>
48 #include <private/qutfcodec_p.h>
50 #include <qdatastream.h>
53 #include "qlocale_p.h"
54 #include "qstringmatcher.h"
55 #include "qvarlengtharray.h"
62 #include <private/qcore_mac_p.h>
65 #include <private/qfunctions_p.h>
74 #include "qstringmatcher.cpp"
77 # include <qt_windows.h>
88 #define LLONG_MAX qint64_C(9223372036854775807)
91 #define LLONG_MIN (-LLONG_MAX - qint64_C(1))
94 #define ULLONG_MAX quint64_C(18446744073709551615)
99 #ifndef QT_NO_TEXTCODEC
100 QTextCodec *QString::codecForCStrings;
105 extern bool qt_ucol_strcoll(const QChar *source, int sourceLength, const QChar *target, int targetLength, int *result);
110 int qFindString(const QChar *haystack, int haystackLen, int from,
111 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
112 int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from,
113 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
114 static inline int qt_last_index_of(const QChar *haystack, int haystackLen, QChar needle,
115 int from, Qt::CaseSensitivity cs);
116 static inline int qt_string_count(const QChar *haystack, int haystackLen,
117 const QChar *needle, int needleLen,
118 Qt::CaseSensitivity cs);
119 static inline int qt_string_count(const QChar *haystack, int haystackLen,
120 QChar needle, Qt::CaseSensitivity cs);
121 static inline int qt_find_latin1_string(const QChar *hay, int size, const QLatin1String &needle,
122 int from, Qt::CaseSensitivity cs);
123 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
124 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
125 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
126 const QLatin1String &needle, Qt::CaseSensitivity cs);
127 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
128 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
129 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
130 const QLatin1String &needle, Qt::CaseSensitivity cs);
132 // Unicode case-insensitive comparison
133 static int ucstricmp(const ushort *a, const ushort *ae, const ushort *b, const ushort *be)
142 const ushort *e = ae;
149 // qDebug() << hex << alast << blast;
150 // qDebug() << hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast);
151 // qDebug() << hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast);
152 int diff = foldCase(*a, alast) - foldCase(*b, blast);
166 // Case-insensitive comparison between a Unicode string and a QLatin1String
167 static int ucstricmp(const ushort *a, const ushort *ae, const uchar *b, const uchar *be)
177 const ushort *e = ae;
182 int diff = foldCase(*a) - foldCase(*b);
196 // Unicode case-sensitive compare two same-sized strings
197 static int ucstrncmp(const QChar *a, const QChar *b, int l)
199 while (l-- && *a == *b)
203 return a->unicode() - b->unicode();
206 // Unicode case-sensitive comparison
207 static int ucstrcmp(const QChar *a, int alen, const QChar *b, int blen)
209 if (a == b && alen == blen)
211 int l = qMin(alen, blen);
212 int cmp = ucstrncmp(a, b, l);
213 return cmp ? cmp : (alen-blen);
216 // Unicode case-insensitive compare two same-sized strings
217 static int ucstrnicmp(const ushort *a, const ushort *b, int l)
219 return ucstricmp(a, a + l, b, b + l);
222 // Benchmarking indicates that doing memcmp is much slower than
223 // executing the comparison ourselves.
225 // The profiling was done on a population of calls to qMemEquals, generated
226 // during a run of the demo browser. The profile of the data (32-bit x86
229 // total number of comparisons: 21353
230 // longest string compared: 95
231 // average comparison length: 14.8786
232 // cache-line crosses: 5661 (13.3%)
233 // alignment histogram:
234 // 0xXXX0 = 512 (1.2%) strings, 0 (0.0%) of which same-aligned
235 // 0xXXX2 = 15087 (35.3%) strings, 5145 (34.1%) of which same-aligned
236 // 0xXXX4 = 525 (1.2%) strings, 0 (0.0%) of which same-aligned
237 // 0xXXX6 = 557 (1.3%) strings, 6 (1.1%) of which same-aligned
238 // 0xXXX8 = 509 (1.2%) strings, 0 (0.0%) of which same-aligned
239 // 0xXXXa = 24358 (57.0%) strings, 9901 (40.6%) of which same-aligned
240 // 0xXXXc = 557 (1.3%) strings, 0 (0.0%) of which same-aligned
241 // 0xXXXe = 601 (1.4%) strings, 15 (2.5%) of which same-aligned
242 // total = 42706 (100%) strings, 15067 (35.3%) of which same-aligned
244 // 92% of the strings have alignment of 2 or 10, which is due to malloc on
245 // 32-bit Linux returning values aligned to 8 bytes, and offsetof(array, QString::Data) == 18.
247 // The profile on 64-bit will be different since offsetof(array, QString::Data) == 26.
249 // The benchmark results were, for a Core-i7 @ 2.67 GHz 32-bit, compiled with -O3 -funroll-loops:
250 // 16-bit loads only: 872,301 CPU ticks [Qt 4.5 / memcmp]
251 // 32- and 16-bit loads: 773,362 CPU ticks [Qt 4.6]
252 // SSE2 "movdqu" 128-bit loads: 618,736 CPU ticks
253 // SSE3 "lddqu" 128-bit loads: 619,954 CPU ticks
254 // SSSE3 "palignr" corrections: 852,147 CPU ticks
255 // SSE4.2 "pcmpestrm": 738,702 CPU ticks
257 // The same benchmark on an Atom N450 @ 1.66 GHz, is:
258 // 16-bit loads only: 2,185,882 CPU ticks
259 // 32- and 16-bit loads: 1,805,060 CPU ticks
260 // SSE2 "movdqu" 128-bit loads: 2,529,843 CPU ticks
261 // SSE3 "lddqu" 128-bit loads: 2,514,858 CPU ticks
262 // SSSE3 "palignr" corrections: 2,160,325 CPU ticks
263 // SSE4.2 not available
265 // The conclusion we reach is that alignment the SSE2 unaligned code can gain
266 // 20% improvement in performance in some systems, but suffers a penalty due
267 // to the unaligned loads on others.
269 static bool qMemEquals(const quint16 *a, const quint16 *b, int length)
271 if (a == b || !length)
283 if ((sa.value & 2) == (sb.value & 2)) {
284 // both addresses have the same alignment
286 // both addresses are not aligned to 4-bytes boundaries
287 // compare the first character
294 // now both addresses are 4-bytes aligned
297 // both addresses are 4-bytes aligned
298 // do a fast 32-bit comparison
299 register const quint32 *e = sa.d + (length >> 1);
300 for ( ; sa.d != e; ++sa.d, ++sb.d) {
305 // do we have a tail?
306 return (length & 1) ? *sa.w == *sb.w : true;
308 // one of the addresses isn't 4-byte aligned but the other is
309 register const quint16 *e = sa.w + length;
310 for ( ; sa.w != e; ++sa.w, ++sb.w) {
321 Returns the index position of the first occurrence of the
322 character \a ch in the string given by \a str and \a len,
323 searching forward from index
324 position \a from. Returns -1 if \a ch could not be found.
326 static int findChar(const QChar *str, int len, QChar ch, int from,
327 Qt::CaseSensitivity cs)
329 const ushort *s = (const ushort *)str;
330 ushort c = ch.unicode();
332 from = qMax(from + len, 0);
334 const ushort *n = s + from - 1;
335 const ushort *e = s + len;
336 if (cs == Qt::CaseSensitive) {
343 if (foldCase(*n) == c)
351 if (sl_minus_1 < (int)sizeof(int) * CHAR_BIT) \
352 hashHaystack -= (a) << sl_minus_1; \
355 inline bool qIsUpper(char ch)
357 return ch >= 'A' && ch <= 'Z';
360 inline bool qIsDigit(char ch)
362 return ch >= '0' && ch <= '9';
365 inline char qToLower(char ch)
367 if (ch >= 'A' && ch <= 'Z')
368 return ch - 'A' + 'a';
373 const QString::Null QString::null = { };
376 \macro QT_NO_CAST_FROM_ASCII
379 Disables automatic conversions from 8-bit strings (char *) to unicode QStrings
381 \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_BYTEARRAY
385 \macro QT_NO_CAST_TO_ASCII
388 disables automatic conversion from QString to 8-bit strings (char *)
390 \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
394 \macro QT_ASCII_CAST_WARNINGS
398 This macro can be defined to force a warning whenever a function is
399 called that automatically converts between unicode and 8-bit encodings.
401 Note: This only works for compilers that support warnings for
404 \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII
410 \brief The QCharRef class is a helper class for QString.
414 \ingroup string-processing
416 When you get an object of type QCharRef, if you can assign to it,
417 the assignment will apply to the character in the string from
418 which you got the reference. That is its whole purpose in life.
419 The QCharRef becomes invalid once modifications are made to the
420 string: if you want to keep the character, copy it into a QChar.
422 Most of the QChar member functions also exist in QCharRef.
423 However, they are not explicitly documented here.
425 \sa QString::operator[]() QString::at() QChar
432 \brief The QString class provides a Unicode character string.
436 \ingroup string-processing
438 QString stores a string of 16-bit \l{QChar}s, where each QChar
439 corresponds one Unicode 4.0 character. (Unicode characters
440 with code values above 65535 are stored using surrogate pairs,
441 i.e., two consecutive \l{QChar}s.)
443 \l{Unicode} is an international standard that supports most of the
444 writing systems in use today. It is a superset of US-ASCII (ANSI
445 X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1
446 characters are available at the same code positions.
448 Behind the scenes, QString uses \l{implicit sharing}
449 (copy-on-write) to reduce memory usage and to avoid the needless
450 copying of data. This also helps reduce the inherent overhead of
451 storing 16-bit characters instead of 8-bit characters.
453 In addition to QString, Qt also provides the QByteArray class to
454 store raw bytes and traditional 8-bit '\\0'-terminated strings.
455 For most purposes, QString is the class you want to use. It is
456 used throughout the Qt API, and the Unicode support ensures that
457 your applications will be easy to translate if you want to expand
458 your application's market at some point. The two main cases where
459 QByteArray is appropriate are when you need to store raw binary
460 data, and when memory conservation is critical (e.g., with
461 \l{Qt for Embedded Linux}).
465 \section1 Initializing a String
467 One way to initialize a QString is simply to pass a \c{const char
468 *} to its constructor. For example, the following code creates a
469 QString of size 5 containing the data "Hello":
471 \snippet doc/src/snippets/qstring/main.cpp 0
473 QString converts the \c{const char *} data into Unicode using the
474 fromAscii() function. By default, fromAscii() treats character
475 above 128 as Latin-1 characters, but this can be changed by
476 calling QTextCodec::setCodecForCStrings().
478 In all of the QString functions that take \c{const char *}
479 parameters, the \c{const char *} is interpreted as a classic
480 C-style '\\0'-terminated string. It is legal for the \c{const char
481 *} parameter to be 0.
483 You can also provide string data as an array of \l{QChar}s:
485 \snippet doc/src/snippets/qstring/main.cpp 1
487 QString makes a deep copy of the QChar data, so you can modify it
488 later without experiencing side effects. (If for performance
489 reasons you don't want to take a deep copy of the character data,
490 use QString::fromRawData() instead.)
492 Another approach is to set the size of the string using resize()
493 and to initialize the data character per character. QString uses
494 0-based indexes, just like C++ arrays. To access the character at
495 a particular index position, you can use \l operator[](). On
496 non-const strings, \l operator[]() returns a reference to a
497 character that can be used on the left side of an assignment. For
500 \snippet doc/src/snippets/qstring/main.cpp 2
502 For read-only access, an alternative syntax is to use the at()
505 \snippet doc/src/snippets/qstring/main.cpp 3
507 The at() function can be faster than \l operator[](), because it
508 never causes a \l{deep copy} to occur. Alternatively, use the
509 left(), right(), or mid() functions to extract several characters
512 A QString can embed '\\0' characters (QChar::Null). The size()
513 function always returns the size of the whole string, including
514 embedded '\\0' characters.
516 After a call to the resize() function, newly allocated characters
517 have undefined values. To set all the characters in the string to
518 a particular value, use the fill() function.
520 QString provides dozens of overloads designed to simplify string
521 usage. For example, if you want to compare a QString with a string
522 literal, you can write code like this and it will work as expected:
524 \snippet doc/src/snippets/qstring/main.cpp 4
526 You can also pass string literals to functions that take QStrings
527 as arguments, invoking the QString(const char *)
528 constructor. Similarly, you can pass a QString to a function that
529 takes a \c{const char *} argument using the \l qPrintable() macro
530 which returns the given QString as a \c{const char *}. This is
531 equivalent to calling <QString>.toLocal8Bit().constData().
533 \section1 Manipulating String Data
535 QString provides the following basic functions for modifying the
536 character data: append(), prepend(), insert(), replace(), and
537 remove(). For example:
539 \snippet doc/src/snippets/qstring/main.cpp 5
541 If you are building a QString gradually and know in advance
542 approximately how many characters the QString will contain, you
543 can call reserve(), asking QString to preallocate a certain amount
544 of memory. You can also call capacity() to find out how much
545 memory QString actually allocated.
547 The replace() and remove() functions' first two arguments are the
548 position from which to start erasing and the number of characters
549 that should be erased. If you want to replace all occurrences of
550 a particular substring with another, use one of the two-parameter
553 A frequent requirement is to remove whitespace characters from a
554 string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace
555 from both ends of a QString, use the trimmed() function. If you
556 want to remove whitespace from both ends and replace multiple
557 consecutive whitespaces with a single space character within the
558 string, use simplified().
560 If you want to find all occurrences of a particular character or
561 substring in a QString, use the indexOf() or lastIndexOf()
562 functions. The former searches forward starting from a given index
563 position, the latter searches backward. Both return the index
564 position of the character or substring if they find it; otherwise,
565 they return -1. For example, here's a typical loop that finds all
566 occurrences of a particular substring:
568 \snippet doc/src/snippets/qstring/main.cpp 6
570 QString provides many functions for converting numbers into
571 strings and strings into numbers. See the arg() functions, the
572 setNum() functions, the number() static functions, and the
573 toInt(), toDouble(), and similar functions.
575 To get an upper- or lowercase version of a string use toUpper() or
578 Lists of strings are handled by the QStringList class. You can
579 split a string into a list of strings using the split() function,
580 and join a list of strings into a single string with an optional
581 separator using QStringList::join(). You can obtain a list of
582 strings from a string list that contain a particular substring or
583 that match a particular QRegExp using the QStringList::filter()
586 \section1 Querying String Data
588 If you want to see if a QString starts or ends with a particular
589 substring use startsWith() or endsWith(). If you simply want to
590 check whether a QString contains a particular character or
591 substring, use the contains() function. If you want to find out
592 how many times a particular character or substring occurs in the
595 QStrings can be compared using overloaded operators such as \l
596 operator<(), \l operator<=(), \l operator==(), \l operator>=(),
597 and so on. Note that the comparison is based exclusively on the
598 numeric Unicode values of the characters. It is very fast, but is
599 not what a human would expect; the QString::localeAwareCompare()
600 function is a better choice for sorting user-interface strings.
602 To obtain a pointer to the actual character data, call data() or
603 constData(). These functions return a pointer to the beginning of
604 the QChar data. The pointer is guaranteed to remain valid until a
605 non-const function is called on the QString.
607 \section1 Converting Between 8-Bit Strings and Unicode Strings
609 QString provides the following four functions that return a
610 \c{const char *} version of the string as QByteArray: toAscii(),
611 toLatin1(), toUtf8(), and toLocal8Bit().
614 \o toAscii() returns an 8-bit string encoded using the codec
615 specified by QTextCodec::codecForCStrings (by default, that is
617 \o toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
618 \o toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a
619 superset of US-ASCII (ANSI X3.4-1986) that supports the entire
620 Unicode character set through multibyte sequences.
621 \o toLocal8Bit() returns an 8-bit string using the system's local
625 To convert from one of these encodings, QString provides
626 fromAscii(), fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other
627 encodings are supported through the QTextCodec class.
629 As mentioned above, QString provides a lot of functions and
630 operators that make it easy to interoperate with \c{const char *}
631 strings. But this functionality is a double-edged sword: It makes
632 QString more convenient to use if all strings are US-ASCII or
633 Latin-1, but there is always the risk that an implicit conversion
634 from or to \c{const char *} is done using the wrong 8-bit
635 encoding. To minimize these risks, you can turn off these implicit
636 conversions by defining the following two preprocessor symbols:
639 \o \c QT_NO_CAST_FROM_ASCII disables automatic conversions from
640 C string literals and pointers to Unicode.
641 \o \c QT_NO_CAST_TO_ASCII disables automatic conversion from QString
645 One way to define these preprocessor symbols globally for your
646 application is to add the following entry to your
647 \l{qmake Project Files}{qmake project file}:
649 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 0
651 You then need to explicitly call fromAscii(), fromLatin1(),
652 fromUtf8(), or fromLocal8Bit() to construct a QString from an
653 8-bit string, or use the lightweight QLatin1String class, for
656 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 1
658 Similarly, you must call toAscii(), toLatin1(), toUtf8(), or
659 toLocal8Bit() explicitly to convert the QString to an 8-bit
660 string. (Other encodings are supported through the QTextCodec
665 \o Note for C Programmers
669 Due to C++'s type system and the fact that QString is
670 \l{implicitly shared}, QStrings may be treated like \c{int}s or
671 other basic types. For example:
673 \snippet doc/src/snippets/qstring/main.cpp 7
675 The \c result variable, is a normal variable allocated on the
676 stack. When \c return is called, and because we're returning by
677 value, the copy constructor is called and a copy of the string is
678 returned. No actual copying takes place thanks to the implicit
683 \section1 Distinction Between Null and Empty Strings
685 For historical reasons, QString distinguishes between a null
686 string and an empty string. A \e null string is a string that is
687 initialized using QString's default constructor or by passing
688 (const char *)0 to the constructor. An \e empty string is any
689 string with size 0. A null string is always empty, but an empty
690 string isn't necessarily null:
692 \snippet doc/src/snippets/qstring/main.cpp 8
694 All functions except isNull() treat null strings the same as empty
695 strings. For example, toAscii().constData() returns a pointer to a
696 '\\0' character for a null string (\e not a null pointer), and
697 QString() compares equal to QString(""). We recommend that you
698 always use the isEmpty() function and avoid isNull().
700 \section1 Argument Formats
702 In member functions where an argument \e format can be specified
703 (e.g., arg(), number()), the argument \e format can be one of the
707 \header \o Format \o Meaning
708 \row \o \c e \o format as [-]9.9e[+|-]999
709 \row \o \c E \o format as [-]9.9E[+|-]999
710 \row \o \c f \o format as [-]9.9
711 \row \o \c g \o use \c e or \c f format, whichever is the most concise
712 \row \o \c G \o use \c E or \c f format, whichever is the most concise
715 A \e precision is also specified with the argument \e format. For
716 the 'e', 'E', and 'f' formats, the \e precision represents the
717 number of digits \e after the decimal point. For the 'g' and 'G'
718 formats, the \e precision represents the maximum number of
719 significant digits (trailing zeroes are omitted).
721 \section1 More Efficient String Construction
723 Many strings are known at compile time. But the trivial
724 constructor QString("Hello"), will convert the string literal
725 to a QString using the codecForCStrings(). To avoid this one
726 can use the QStringLiteral macro to directly create the required
727 data at compile time. Constructing a QString out of the literal
728 does then not cause any overhead at runtime.
730 A slightly less efficient way is to use QLatin1String. This class wraps
731 a C string literal, precalculates it length at compile time and can
732 then be used for faster comparison with QStrings and conversion to
733 QStrings than a regular C string literal.
735 Using the QString \c{'+'} operator, it is easy to construct a
736 complex string from multiple substrings. You will often write code
739 \snippet doc/src/snippets/qstring/stringbuilder.cpp 0
741 There is nothing wrong with either of these string constructions,
742 but there are a few hidden inefficiencies. Beginning with Qt 4.6,
743 you can eliminate them.
745 First, multiple uses of the \c{'+'} operator usually means
746 multiple memory allocations. When concatenating \e{n} substrings,
747 where \e{n > 2}, there can be as many as \e{n - 1} calls to the
750 In 4.6, an internal template class \c{QStringBuilder} has been
751 added along with a few helper functions. This class is marked
752 internal and does not appear in the documentation, because you
753 aren't meant to instantiate it in your code. Its use will be
754 automatic, as described below. The class is found in
755 \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
758 \c{QStringBuilder} uses expression templates and reimplements the
759 \c{'%'} operator so that when you use \c{'%'} for string
760 concatenation instead of \c{'+'}, multiple substring
761 concatenations will be postponed until the final result is about
762 to be assigned to a QString. At this point, the amount of memory
763 required for the final result is known. The memory allocator is
764 then called \e{once} to get the required space, and the substrings
765 are copied into it one by one.
767 Additional efficiency is gained by inlining and reduced reference
768 counting (the QString created from a \c{QStringBuilder} typically
769 has a ref count of 1, whereas QString::append() needs an extra
772 There are three ways you can access this improved method of string
773 construction. The straightforward way is to include
774 \c{QStringBuilder} wherever you want to use it, and use the
775 \c{'%'} operator instead of \c{'+'} when concatenating strings:
777 \snippet doc/src/snippets/qstring/stringbuilder.cpp 5
779 A more global approach which is the most convenient but
780 not entirely source compatible, is to this define in your
783 \snippet doc/src/snippets/qstring/stringbuilder.cpp 3
785 and the \c{'+'} will automatically be performed as the
786 \c{QStringBuilder} \c{'%'} everywhere.
788 \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
792 \enum QString::SplitBehavior
794 This enum specifies how the split() function should behave with
795 respect to empty strings.
797 \value KeepEmptyParts If a field is empty, keep it in the result.
798 \value SkipEmptyParts If a field is empty, don't include it in the result.
803 const QStaticStringData<1> QString::shared_null = { { Q_REFCOUNT_INITIALIZE_STATIC, 0, 0, false, { 0 } }, { 0 } };
804 const QStaticStringData<1> QString::shared_empty = { { Q_REFCOUNT_INITIALIZE_STATIC, 0, 0, false, { 0 } }, { 0 } };
806 int QString::grow(int size)
808 return qAllocMore(size * sizeof(QChar), sizeof(Data)) / sizeof(QChar);
811 /*! \typedef QString::ConstIterator
813 Qt-style synonym for QString::const_iterator.
816 /*! \typedef QString::Iterator
818 Qt-style synonym for QString::iterator.
821 /*! \typedef QString::const_iterator
823 The QString::const_iterator typedef provides an STL-style const
824 iterator for QString.
826 \sa QString::iterator
829 /*! \typedef QString::iterator
831 The QString::iterator typedef provides an STL-style non-const
832 iterator for QString.
834 \sa QString::const_iterator
838 \typedef QString::const_reference
840 The QString::const_reference typedef provides an STL-style
841 const reference for QString.
844 \typedef QString::reference
846 The QString::const_reference typedef provides an STL-style
847 reference for QString.
850 \typedef QString::value_type
852 The QString::const_reference typedef provides an STL-style
853 value type for QString.
856 /*! \fn QString::iterator QString::begin()
858 Returns an \l{STL-style iterator} pointing to the first character in
861 \sa constBegin(), end()
864 /*! \fn QString::const_iterator QString::begin() const
869 /*! \fn QString::const_iterator QString::constBegin() const
871 Returns a const \l{STL-style iterator} pointing to the first character
874 \sa begin(), constEnd()
877 /*! \fn QString::iterator QString::end()
879 Returns an \l{STL-style iterator} pointing to the imaginary character
880 after the last character in the string.
882 \sa begin(), constEnd()
885 /*! \fn QString::const_iterator QString::end() const
890 /*! \fn QString::const_iterator QString::constEnd() const
892 Returns a const \l{STL-style iterator} pointing to the imaginary
893 item after the last item in the list.
895 \sa constBegin(), end()
899 \fn QString::QString()
901 Constructs a null string. Null strings are also empty.
906 /*! \fn QString::QString(const char *str)
908 Constructs a string initialized with the 8-bit string \a str. The
909 given const char pointer is converted to Unicode using the
910 fromAscii() function.
912 You can disable this constructor by defining \c
913 QT_NO_CAST_FROM_ASCII when you compile your applications. This
914 can be useful if you want to ensure that all user-visible strings
915 go through QObject::tr(), for example.
917 \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
920 /*! \fn QString QString::fromStdString(const std::string &str)
922 Returns a copy of the \a str string. The given string is converted
923 to Unicode using the fromAscii() function.
925 This constructor is only available if Qt is configured with STL
926 compatibility enabled.
928 \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
931 /*! \fn QString QString::fromStdWString(const std::wstring &str)
933 Returns a copy of the \a str string. The given string is assumed
934 to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on
935 windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix
938 This method is only available if Qt is configured with STL
939 compatibility enabled.
941 \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4()
944 /*! \fn QString QString::fromWCharArray(const wchar_t *string, int size)
947 Returns a copy of the \a string, where the encoding of \a string depends on
948 the size of wchar. If wchar is 4 bytes, the \a string is interpreted as ucs-4,
949 if wchar is 2 bytes it is interpreted as ucs-2.
951 If \a size is -1 (default), the \a string has to be 0 terminated.
953 \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
956 /*! \fn std::wstring QString::toStdWString() const
958 Returns a std::wstring object with the data contained in this
959 QString. The std::wstring is encoded in utf16 on platforms where
960 wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
961 where wchar_t is 4 bytes wide (most Unix systems).
963 This operator is mostly useful to pass a QString to a function
964 that accepts a std::wstring object.
966 This operator is only available if Qt is configured with STL
967 compatibility enabled.
969 \sa utf16(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
972 // ### replace with QCharIterator
973 int QString::toUcs4_helper(const ushort *uc, int length, uint *out)
976 for (; i < length; ++i) {
978 if (QChar::isHighSurrogate(u) && i + 1 < length) {
979 ushort low = uc[i+1];
980 if (QChar::isLowSurrogate(low)) {
982 u = QChar::surrogateToUcs4(u, low);
990 /*! \fn int QString::toWCharArray(wchar_t *array) const
993 Fills the \a array with the data contained in this QString object.
994 The array is encoded in utf16 on platforms where
995 wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
996 where wchar_t is 4 bytes wide (most Unix systems).
998 \a array has to be allocated by the caller and contain enough space to
999 hold the complete string (allocating the array with the same length as the
1000 string is always sufficient).
1002 returns the actual length of the string in \a array.
1004 \note This function does not append a null character to the array.
1006 \sa utf16(), toUcs4(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString()
1009 /*! \fn QString::QString(const QString &other)
1011 Constructs a copy of \a other.
1013 This operation takes \l{constant time}, because QString is
1014 \l{implicitly shared}. This makes returning a QString from a
1015 function very fast. If a shared instance is modified, it will be
1016 copied (copy-on-write), and that takes \l{linear time}.
1022 Constructs a string initialized with the first \a size characters
1023 of the QChar array \a unicode.
1025 If \a unicode is 0, a null string is constructed.
1027 If \a size is negative, \a unicode is assumed to point to a nul-terminated
1028 array and its length is determined dynamically. The terminating
1029 nul-character is not considered part of the string.
1031 QString makes a deep copy of the string data. The unicode data is copied as
1032 is and the Byte Order Mark is preserved if present.
1036 QString::QString(const QChar *unicode, int size)
1039 d = const_cast<Data *>(&shared_null.str);
1043 while (unicode[size] != 0)
1047 d = const_cast<Data *>(&shared_empty.str);
1049 d = (Data*) ::malloc(sizeof(Data)+(size+1)*sizeof(QChar));
1051 d->ref.initializeOwned();
1053 d->alloc = (uint) size;
1054 d->capacityReserved = false;
1056 memcpy(d->data(), unicode, size * sizeof(QChar));
1057 d->data()[size] = '\0';
1063 Constructs a string of the given \a size with every character set
1068 QString::QString(int size, QChar ch)
1071 d = const_cast<Data *>(&shared_empty.str);
1073 d = (Data*) ::malloc(sizeof(Data)+(size+1)*sizeof(QChar));
1075 d->ref.initializeOwned();
1077 d->alloc = (uint) size;
1078 d->capacityReserved = false;
1080 d->data()[size] = '\0';
1081 ushort *i = d->data() + size;
1082 ushort *b = d->data();
1083 const ushort value = ch.unicode();
1089 /*! \fn QString::QString(int size, Qt::Initialization)
1092 Constructs a string of the given \a size without initializing the
1093 characters. This is only used in \c QStringBuilder::toString().
1095 QString::QString(int size, Qt::Initialization)
1097 d = (Data*) ::malloc(sizeof(Data)+(size+1)*sizeof(QChar));
1099 d->ref.initializeOwned();
1101 d->alloc = (uint) size;
1102 d->capacityReserved = false;
1104 d->data()[size] = '\0';
1107 /*! \fn QString::QString(const QLatin1String &str)
1109 Constructs a copy of the Latin-1 string \a str.
1115 Constructs a string of size 1 containing the character \a ch.
1117 QString::QString(QChar ch)
1119 d = (Data *) ::malloc(sizeof(Data) + 2*sizeof(QChar));
1121 d->ref.initializeOwned();
1124 d->capacityReserved = false;
1126 d->data()[0] = ch.unicode();
1127 d->data()[1] = '\0';
1130 /*! \fn QString::QString(const QByteArray &ba)
1132 Constructs a string initialized with the byte array \a ba. The
1133 given byte array is converted to Unicode using fromAscii(). Stops
1134 copying at the first 0 character, otherwise copies the entire byte
1137 You can disable this constructor by defining \c
1138 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1139 can be useful if you want to ensure that all user-visible strings
1140 go through QObject::tr(), for example.
1142 \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8()
1145 /*! \fn QString::QString(const Null &)
1149 /*! \fn QString &QString::operator=(const Null &)
1154 \fn QString::~QString()
1156 Destroys the string.
1160 /*! \fn void QString::swap(QString &other)
1163 Swaps string \a other with this string. This operation is very fast and
1167 /*! \fn void QString::detach()
1172 /*! \fn bool QString::isDetached() const
1177 /*! \fn bool QString::isSharedWith(const QString &other) const
1182 // ### Qt 5: rename freeData() to avoid confusion. See task 197625.
1183 void QString::free(Data *d)
1189 Sets the size of the string to \a size characters.
1191 If \a size is greater than the current size, the string is
1192 extended to make it \a size characters long with the extra
1193 characters added to the end. The new characters are uninitialized.
1195 If \a size is less than the current size, characters are removed
1200 \snippet doc/src/snippets/qstring/main.cpp 45
1202 If you want to append a certain number of identical characters to
1203 the string, use \l operator+=() as follows rather than resize():
1205 \snippet doc/src/snippets/qstring/main.cpp 46
1207 If you want to expand the string so that it reaches a certain
1208 width and fill the new positions with a particular character, use
1209 the leftJustified() function:
1211 If \a size is negative, it is equivalent to passing zero.
1213 \snippet doc/src/snippets/qstring/main.cpp 47
1215 \sa truncate(), reserve()
1218 void QString::resize(int size)
1223 if (d->offset && !d->ref.isShared() && size < d->size) {
1228 if (size == 0 && !d->capacityReserved) {
1229 Data *x = const_cast<Data *>(&shared_empty.str);
1230 if (!d->ref.deref())
1234 if (d->ref.isShared() || size > int(d->alloc) ||
1235 (!d->capacityReserved && size < d->size && size < int(d->alloc) >> 1))
1236 realloc(grow(size));
1237 if (int(d->alloc) >= size) {
1239 d->data()[size] = '\0';
1244 /*! \fn int QString::capacity() const
1246 Returns the maximum number of characters that can be stored in
1247 the string without forcing a reallocation.
1249 The sole purpose of this function is to provide a means of fine
1250 tuning QString's memory usage. In general, you will rarely ever
1251 need to call this function. If you want to know how many
1252 characters are in the string, call size().
1254 \sa reserve(), squeeze()
1258 \fn void QString::reserve(int size)
1260 Attempts to allocate memory for at least \a size characters. If
1261 you know in advance how large the string will be, you can call
1262 this function, and if you resize the string often you are likely
1263 to get better performance. If \a size is an underestimate, the
1264 worst that will happen is that the QString will be a bit slower.
1266 The sole purpose of this function is to provide a means of fine
1267 tuning QString's memory usage. In general, you will rarely ever
1268 need to call this function. If you want to change the size of the
1269 string, call resize().
1271 This function is useful for code that needs to build up a long
1272 string and wants to avoid repeated reallocation. In this example,
1273 we want to add to the string until some condition is true, and
1274 we're fairly sure that size is large enough to make a call to
1275 reserve() worthwhile:
1277 \snippet doc/src/snippets/qstring/main.cpp 44
1279 \sa squeeze(), capacity()
1283 \fn void QString::squeeze()
1285 Releases any memory not required to store the character data.
1287 The sole purpose of this function is to provide a means of fine
1288 tuning QString's memory usage. In general, you will rarely ever
1289 need to call this function.
1291 \sa reserve(), capacity()
1294 // ### Qt 5: rename reallocData() to avoid confusion. 197625
1295 void QString::realloc(int alloc)
1297 if (d->ref.isShared() || d->offset) {
1298 Data *x = static_cast<Data *>(::malloc(sizeof(Data) + (alloc+1) * sizeof(QChar)));
1300 x->ref.initializeOwned();
1301 x->size = qMin(alloc, d->size);
1302 x->alloc = (uint) alloc;
1303 x->capacityReserved = d->capacityReserved;
1305 ::memcpy(x->data(), d->data(), x->size * sizeof(QChar));
1306 x->data()[x->size] = 0;
1307 if (!d->ref.deref())
1311 Data *p = static_cast<Data *>(::realloc(d, sizeof(Data) + (alloc+1) * sizeof(QChar)));
1319 void QString::realloc()
1324 void QString::expand(int i)
1327 resize(qMax(i + 1, sz));
1328 if (d->size - 1 > sz) {
1329 ushort *n = d->data() + d->size - 1;
1330 ushort *e = d->data() + sz;
1336 /*! \fn void QString::clear()
1338 Clears the contents of the string and makes it empty.
1340 \sa resize(), isEmpty()
1343 /*! \fn QString &QString::operator=(const QString &other)
1345 Assigns \a other to this string and returns a reference to this
1349 QString &QString::operator=(const QString &other)
1352 if (!d->ref.deref())
1359 /*! \fn QString &QString::operator=(const QLatin1String &str)
1361 \overload operator=()
1363 Assigns the Latin-1 string \a str to this string.
1366 /*! \fn QString &QString::operator=(const QByteArray &ba)
1368 \overload operator=()
1370 Assigns \a ba to this string. The byte array is converted to Unicode
1371 using the fromAscii() function. This function stops conversion at the
1372 first NUL character found, or the end of the \a ba byte array.
1374 You can disable this operator by defining \c
1375 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1376 can be useful if you want to ensure that all user-visible strings
1377 go through QObject::tr(), for example.
1380 /*! \fn QString &QString::operator=(const char *str)
1382 \overload operator=()
1384 Assigns \a str to this string. The const char pointer is converted
1385 to Unicode using the fromAscii() function.
1387 You can disable this operator by defining \c
1388 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1389 can be useful if you want to ensure that all user-visible strings
1390 go through QObject::tr(), for example.
1393 /*! \fn QString &QString::operator=(char ch)
1395 \overload operator=()
1397 Assigns character \a ch to this string. The character is converted
1398 to Unicode using the fromAscii() function.
1400 You can disable this operator by defining \c
1401 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1402 can be useful if you want to ensure that all user-visible strings
1403 go through QObject::tr(), for example.
1407 \overload operator=()
1409 Sets the string to contain the single character \a ch.
1411 QString &QString::operator=(QChar ch)
1413 return operator=(QString(ch));
1417 \fn QString& QString::insert(int position, const QString &str)
1419 Inserts the string \a str at the given index \a position and
1420 returns a reference to this string.
1424 \snippet doc/src/snippets/qstring/main.cpp 26
1426 If the given \a position is greater than size(), the array is
1427 first extended using resize().
1429 \sa append(), prepend(), replace(), remove()
1434 \fn QString &QString::insert(int position, const QLatin1String &str)
1437 Inserts the Latin-1 string \a str at the given index \a position.
1439 QString &QString::insert(int i, const QLatin1String &str)
1441 const uchar *s = (const uchar *)str.latin1();
1442 if (i < 0 || !s || !(*s))
1445 int len = str.size();
1446 expand(qMax(d->size, i) + len - 1);
1448 ::memmove(d->data() + i + len, d->data() + i, (d->size - i - len) * sizeof(QChar));
1449 for (int j = 0; j < len; ++j)
1450 d->data()[i + j] = s[j];
1455 \fn QString& QString::insert(int position, const QChar *unicode, int size)
1458 Inserts the first \a size characters of the QChar array \a unicode
1459 at the given index \a position in the string.
1461 QString& QString::insert(int i, const QChar *unicode, int size)
1463 if (i < 0 || size <= 0)
1466 const ushort *s = (const ushort *)unicode;
1467 if (s >= d->data() && s < d->data() + d->alloc) {
1468 // Part of me - take a copy
1469 ushort *tmp = static_cast<ushort *>(::malloc(size * sizeof(QChar)));
1471 memcpy(tmp, s, size * sizeof(QChar));
1472 insert(i, reinterpret_cast<const QChar *>(tmp), size);
1477 expand(qMax(d->size, i) + size - 1);
1479 ::memmove(d->data() + i + size, d->data() + i, (d->size - i - size) * sizeof(QChar));
1480 memcpy(d->data() + i, s, size * sizeof(QChar));
1485 \fn QString& QString::insert(int position, QChar ch)
1488 Inserts \a ch at the given index \a position in the string.
1491 QString& QString::insert(int i, QChar ch)
1497 expand(qMax(i, d->size));
1498 ::memmove(d->data() + i + 1, d->data() + i, (d->size - i) * sizeof(QChar));
1499 d->data()[i] = ch.unicode();
1504 Appends the string \a str onto the end of this string.
1508 \snippet doc/src/snippets/qstring/main.cpp 9
1510 This is the same as using the insert() function:
1512 \snippet doc/src/snippets/qstring/main.cpp 10
1514 The append() function is typically very fast (\l{constant time}),
1515 because QString preallocates extra space at the end of the string
1516 data so it can grow without reallocating the entire string each
1519 \sa operator+=(), prepend(), insert()
1521 QString &QString::append(const QString &str)
1523 if (str.d != &shared_null.str) {
1524 if (d == &shared_null.str) {
1527 if (d->ref.isShared() || d->size + str.d->size > int(d->alloc))
1528 realloc(grow(d->size + str.d->size));
1529 memcpy(d->data() + d->size, str.d->data(), str.d->size * sizeof(QChar));
1530 d->size += str.d->size;
1531 d->data()[d->size] = '\0';
1540 Appends the Latin-1 string \a str to this string.
1542 QString &QString::append(const QLatin1String &str)
1544 const uchar *s = (const uchar *)str.latin1();
1546 int len = str.size();
1547 if (d->ref.isShared() || d->size + len > int(d->alloc))
1548 realloc(grow(d->size + len));
1549 ushort *i = d->data() + d->size;
1550 while ((*i++ = *s++))
1557 /*! \fn QString &QString::append(const QByteArray &ba)
1561 Appends the byte array \a ba to this string. The given byte array
1562 is converted to Unicode using the fromAscii() function.
1564 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1565 when you compile your applications. This can be useful if you want
1566 to ensure that all user-visible strings go through QObject::tr(),
1570 /*! \fn QString &QString::append(const char *str)
1574 Appends the string \a str to this string. The given const char
1575 pointer is converted to Unicode using the fromAscii() function.
1577 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1578 when you compile your applications. This can be useful if you want
1579 to ensure that all user-visible strings go through QObject::tr(),
1586 Appends the character \a ch to this string.
1588 QString &QString::append(QChar ch)
1590 if (d->ref.isShared() || d->size + 1 > int(d->alloc))
1591 realloc(grow(d->size + 1));
1592 d->data()[d->size++] = ch.unicode();
1593 d->data()[d->size] = '\0';
1597 /*! \fn QString &QString::prepend(const QString &str)
1599 Prepends the string \a str to the beginning of this string and
1600 returns a reference to this string.
1604 \snippet doc/src/snippets/qstring/main.cpp 36
1606 \sa append(), insert()
1609 /*! \fn QString &QString::prepend(const QLatin1String &str)
1613 Prepends the Latin-1 string \a str to this string.
1616 /*! \fn QString &QString::prepend(const QByteArray &ba)
1620 Prepends the byte array \a ba to this string. The byte array is
1621 converted to Unicode using the fromAscii() function.
1623 You can disable this function by defining \c
1624 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1625 can be useful if you want to ensure that all user-visible strings
1626 go through QObject::tr(), for example.
1629 /*! \fn QString &QString::prepend(const char *str)
1633 Prepends the string \a str to this string. The const char pointer
1634 is converted to Unicode using the fromAscii() function.
1636 You can disable this function by defining \c
1637 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1638 can be useful if you want to ensure that all user-visible strings
1639 go through QObject::tr(), for example.
1642 /*! \fn QString &QString::prepend(QChar ch)
1646 Prepends the character \a ch to this string.
1650 \fn QString &QString::remove(int position, int n)
1652 Removes \a n characters from the string, starting at the given \a
1653 position index, and returns a reference to the string.
1655 If the specified \a position index is within the string, but \a
1656 position + \a n is beyond the end of the string, the string is
1657 truncated at the specified \a position.
1659 \snippet doc/src/snippets/qstring/main.cpp 37
1661 \sa insert(), replace()
1663 QString &QString::remove(int pos, int len)
1665 if (pos < 0) // count from end of string
1667 if (pos < 0 || pos >= d->size) {
1669 } else if (len >= d->size - pos) {
1670 resize(pos); // truncate
1671 } else if (len > 0) {
1673 memmove(d->data() + pos, d->data() + pos + len,
1674 (d->size - pos - len + 1) * sizeof(ushort));
1681 Removes every occurrence of the given \a str string in this
1682 string, and returns a reference to this string.
1684 If \a cs is Qt::CaseSensitive (default), the search is
1685 case sensitive; otherwise the search is case insensitive.
1687 This is the same as \c replace(str, "", cs).
1691 QString &QString::remove(const QString &str, Qt::CaseSensitivity cs)
1695 while ((i = indexOf(str, i, cs)) != -1)
1696 remove(i, str.d->size);
1702 Removes every occurrence of the character \a ch in this string, and
1703 returns a reference to this string.
1705 If \a cs is Qt::CaseSensitive (default), the search is case
1706 sensitive; otherwise the search is case insensitive.
1710 \snippet doc/src/snippets/qstring/main.cpp 38
1712 This is the same as \c replace(ch, "", cs).
1716 QString &QString::remove(QChar ch, Qt::CaseSensitivity cs)
1719 ushort c = ch.unicode();
1720 if (cs == Qt::CaseSensitive) {
1722 if (d->data()[i] == ch)
1729 if (foldCase(d->data()[i]) == c)
1738 \fn QString &QString::remove(const QRegExp &rx)
1740 Removes every occurrence of the regular expression \a rx in the
1741 string, and returns a reference to the string. For example:
1743 \snippet doc/src/snippets/qstring/main.cpp 39
1745 \sa indexOf(), lastIndexOf(), replace()
1749 \fn QString &QString::replace(int position, int n, const QString &after)
1751 Replaces \a n characters beginning at index \a position with
1752 the string \a after and returns a reference to this string.
1756 \snippet doc/src/snippets/qstring/main.cpp 40
1758 \sa insert(), remove()
1760 QString &QString::replace(int pos, int len, const QString &after)
1762 QString copy = after;
1763 return replace(pos, len, copy.constData(), copy.length());
1767 \fn QString &QString::replace(int position, int n, const QChar *unicode, int size)
1769 Replaces \a n characters beginning at index \a position with the
1770 first \a size characters of the QChar array \a unicode and returns a
1771 reference to this string.
1773 QString &QString::replace(int pos, int len, const QChar *unicode, int size)
1775 if (pos < 0 || pos > d->size)
1777 if (pos + len > d->size)
1778 len = d->size - pos;
1781 replace_helper(&index, 1, len, unicode, size);
1786 \fn QString &QString::replace(int position, int n, QChar after)
1789 Replaces \a n characters beginning at index \a position with the
1790 character \a after and returns a reference to this string.
1792 QString &QString::replace(int pos, int len, QChar after)
1794 return replace(pos, len, &after, 1);
1799 Replaces every occurrence of the string \a before with the string \a
1800 after and returns a reference to this string.
1802 If \a cs is Qt::CaseSensitive (default), the search is case
1803 sensitive; otherwise the search is case insensitive.
1807 \snippet doc/src/snippets/qstring/main.cpp 41
1809 \note The replacement text is not rescanned after it is inserted.
1813 \snippet doc/src/snippets/qstring/main.cpp 86
1815 QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs)
1817 return replace(before.constData(), before.size(), after.constData(), after.size(), cs);
1823 void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen)
1825 // copy *after in case it lies inside our own d->data() area
1826 // (which we could possibly invalidate via a realloc or corrupt via memcpy operations.)
1827 QChar *afterBuffer = const_cast<QChar *>(after);
1828 if (after >= reinterpret_cast<QChar *>(d->data()) && after < reinterpret_cast<QChar *>(d->data()) + d->size) {
1829 afterBuffer = static_cast<QChar *>(::malloc(alen*sizeof(QChar)));
1830 Q_CHECK_PTR(afterBuffer);
1831 ::memcpy(afterBuffer, after, alen*sizeof(QChar));
1838 for (int i = 0; i < nIndices; ++i)
1839 memcpy(d->data() + indices[i], afterBuffer, alen * sizeof(QChar));
1840 } else if (alen < blen) {
1841 // replace from front
1843 uint to = indices[0];
1845 memcpy(d->data()+to, after, alen*sizeof(QChar));
1847 uint movestart = indices[0] + blen;
1848 for (int i = 1; i < nIndices; ++i) {
1849 int msize = indices[i] - movestart;
1851 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1855 memcpy(d->data() + to, afterBuffer, alen*sizeof(QChar));
1858 movestart = indices[i] + blen;
1860 int msize = d->size - movestart;
1862 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1863 resize(d->size - nIndices*(blen-alen));
1865 // replace from back
1866 int adjust = nIndices*(alen-blen);
1867 int newLen = d->size + adjust;
1868 int moveend = d->size;
1873 int movestart = indices[nIndices] + blen;
1874 int insertstart = indices[nIndices] + nIndices*(alen-blen);
1875 int moveto = insertstart + alen;
1876 memmove(d->data() + moveto, d->data() + movestart,
1877 (moveend - movestart)*sizeof(QChar));
1878 memcpy(d->data() + insertstart, afterBuffer, alen*sizeof(QChar));
1879 moveend = movestart-blen;
1882 } QT_CATCH(const std::bad_alloc &) {
1883 if (afterBuffer != after)
1884 ::free(afterBuffer);
1887 if (afterBuffer != after)
1888 ::free(afterBuffer);
1895 Replaces each occurrence in this string of the first \a blen
1896 characters of \a before with the first \a alen characters of \a
1897 after and returns a reference to this string.
1899 If \a cs is Qt::CaseSensitive (default), the search is case
1900 sensitive; otherwise the search is case insensitive.
1902 QString &QString::replace(const QChar *before, int blen,
1903 const QChar *after, int alen,
1904 Qt::CaseSensitivity cs)
1910 if (cs == Qt::CaseSensitive && before == after && blen == alen)
1913 if (alen == 0 && blen == 0)
1916 QStringMatcher matcher(before, blen, cs);
1922 while (pos < 1023) {
1923 index = matcher.indexIn(*this, index);
1926 indices[pos++] = index;
1928 // avoid infinite loop
1935 replace_helper(indices, pos, blen, after, alen);
1939 // index has to be adjusted in case we get back into the loop above.
1940 index += pos*(alen-blen);
1948 Replaces every occurrence of the character \a ch in the string with
1949 \a after and returns a reference to this string.
1951 If \a cs is Qt::CaseSensitive (default), the search is case
1952 sensitive; otherwise the search is case insensitive.
1954 QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs)
1956 if (after.d->size == 0)
1957 return remove(ch, cs);
1959 if (after.d->size == 1)
1960 return replace(ch, after.d->data()[0], cs);
1965 ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode());
1971 if (cs == Qt::CaseSensitive) {
1972 while (pos < 1023 && index < d->size) {
1973 if (d->data()[index] == cc)
1974 indices[pos++] = index;
1978 while (pos < 1023 && index < d->size) {
1979 if (QChar::toCaseFolded(d->data()[index]) == cc)
1980 indices[pos++] = index;
1987 replace_helper(indices, pos, 1, after.constData(), after.d->size);
1991 // index has to be adjusted in case we get back into the loop above.
1992 index += pos*(after.d->size - 1);
1999 Replaces every occurrence of the character \a before with the
2000 character \a after and returns a reference to this string.
2002 If \a cs is Qt::CaseSensitive (default), the search is case
2003 sensitive; otherwise the search is case insensitive.
2005 QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs)
2007 ushort a = after.unicode();
2008 ushort b = before.unicode();
2011 ushort *i = d->data();
2012 const ushort *e = i + d->size;
2013 if (cs == Qt::CaseSensitive) {
2020 if (foldCase(*i) == b)
2031 Replaces every occurrence of the string \a before with the string \a
2032 after and returns a reference to this string.
2034 If \a cs is Qt::CaseSensitive (default), the search is case
2035 sensitive; otherwise the search is case insensitive.
2037 \note The text is not rescanned after a replacement.
2039 QString &QString::replace(const QLatin1String &before,
2040 const QLatin1String &after,
2041 Qt::CaseSensitivity cs)
2043 int alen = after.size();
2044 QVarLengthArray<ushort> a(alen);
2045 for (int i = 0; i < alen; ++i)
2046 a[i] = (uchar)after.latin1()[i];
2047 int blen = before.size();
2048 QVarLengthArray<ushort> b(blen);
2049 for (int i = 0; i < blen; ++i)
2050 b[i] = (uchar)before.latin1()[i];
2051 return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs);
2058 Replaces every occurrence of the string \a before with the string \a
2059 after and returns a reference to this string.
2061 If \a cs is Qt::CaseSensitive (default), the search is case
2062 sensitive; otherwise the search is case insensitive.
2064 \note The text is not rescanned after a replacement.
2066 QString &QString::replace(const QLatin1String &before,
2067 const QString &after,
2068 Qt::CaseSensitivity cs)
2070 int blen = before.size();
2071 QVarLengthArray<ushort> b(blen);
2072 for (int i = 0; i < blen; ++i)
2073 b[i] = (uchar)before.latin1()[i];
2074 return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs);
2081 Replaces every occurrence of the string \a before with the string \a
2082 after and returns a reference to this string.
2084 If \a cs is Qt::CaseSensitive (default), the search is case
2085 sensitive; otherwise the search is case insensitive.
2087 \note The text is not rescanned after a replacement.
2089 QString &QString::replace(const QString &before,
2090 const QLatin1String &after,
2091 Qt::CaseSensitivity cs)
2093 int alen = after.size();
2094 QVarLengthArray<ushort> a(alen);
2095 for (int i = 0; i < alen; ++i)
2096 a[i] = (uchar)after.latin1()[i];
2097 return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs);
2104 Replaces every occurrence of the character \a c with the string \a
2105 after and returns a reference to this string.
2107 If \a cs is Qt::CaseSensitive (default), the search is case
2108 sensitive; otherwise the search is case insensitive.
2110 \note The text is not rescanned after a replacement.
2112 QString &QString::replace(QChar c, const QLatin1String &after, Qt::CaseSensitivity cs)
2114 int alen = after.size();
2115 QVarLengthArray<ushort> a(alen);
2116 for (int i = 0; i < alen; ++i)
2117 a[i] = (uchar)after.latin1()[i];
2118 return replace(&c, 1, (const QChar *)a.data(), alen, cs);
2123 Returns true if string \a other is equal to this string; otherwise
2126 The comparison is based exclusively on the numeric Unicode values of
2127 the characters and is very fast, but is not what a human would
2128 expect. Consider sorting user-interface strings with
2129 localeAwareCompare().
2131 bool QString::operator==(const QString &other) const
2133 if (d->size != other.d->size)
2136 return qMemEquals(d->data(), other.d->data(), d->size);
2140 \overload operator==()
2142 bool QString::operator==(const QLatin1String &other) const
2144 if (d->size != other.size())
2150 const ushort *uc = d->data();
2151 const ushort *e = uc + d->size;
2152 const uchar *c = (uchar *)other.latin1();
2163 /*! \fn bool QString::operator==(const QByteArray &other) const
2165 \overload operator==()
2167 The \a other byte array is converted to a QString using the
2168 fromAscii() function. This function stops conversion at the
2169 first NUL character found, or the end of the byte array.
2171 You can disable this operator by defining \c
2172 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2173 can be useful if you want to ensure that all user-visible strings
2174 go through QObject::tr(), for example.
2177 /*! \fn bool QString::operator==(const char *other) const
2179 \overload operator==()
2181 The \a other const char pointer is converted to a QString using
2182 the fromAscii() function.
2184 You can disable this operator by defining \c
2185 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2186 can be useful if you want to ensure that all user-visible strings
2187 go through QObject::tr(), for example.
2191 Returns true if this string is lexically less than string \a
2192 other; otherwise returns false.
2194 The comparison is based exclusively on the numeric Unicode values
2195 of the characters and is very fast, but is not what a human would
2196 expect. Consider sorting user-interface strings using the
2197 QString::localeAwareCompare() function.
2199 bool QString::operator<(const QString &other) const
2201 return ucstrcmp(constData(), length(), other.constData(), other.length()) < 0;
2205 \overload operator<()
2207 bool QString::operator<(const QLatin1String &other) const
2209 const uchar *c = (uchar *) other.latin1();
2213 const ushort *uc = d->data();
2214 const ushort *e = uc + qMin(d->size, other.size());
2222 return (uc == e ? d->size < other.size() : *uc < *c);
2225 /*! \fn bool QString::operator<(const QByteArray &other) const
2227 \overload operator<()
2229 The \a other byte array is converted to a QString using the
2230 fromAscii() function. If any NUL characters ('\0') are embedded
2231 in the byte array, they will be included in the transformation.
2233 You can disable this operator by defining \c
2234 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2235 can be useful if you want to ensure that all user-visible strings
2236 go through QObject::tr(), for example.
2239 /*! \fn bool QString::operator<(const char *other) const
2241 \overload operator<()
2243 The \a other const char pointer is converted to a QString using
2244 the fromAscii() function.
2246 You can disable this operator by defining \c
2247 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2248 can be useful if you want to ensure that all user-visible strings
2249 go through QObject::tr(), for example.
2252 /*! \fn bool QString::operator<=(const QString &other) const
2254 Returns true if this string is lexically less than or equal to
2255 string \a other; otherwise returns false.
2257 The comparison is based exclusively on the numeric Unicode values
2258 of the characters and is very fast, but is not what a human would
2259 expect. Consider sorting user-interface strings with
2260 localeAwareCompare().
2263 /*! \fn bool QString::operator<=(const QLatin1String &other) const
2265 \overload operator<=()
2268 /*! \fn bool QString::operator<=(const QByteArray &other) const
2270 \overload operator<=()
2272 The \a other byte array is converted to a QString using the
2273 fromAscii() function. If any NUL characters ('\0') are embedded
2274 in the byte array, they will be included in the transformation.
2276 You can disable this operator by defining \c
2277 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2278 can be useful if you want to ensure that all user-visible strings
2279 go through QObject::tr(), for example.
2282 /*! \fn bool QString::operator<=(const char *other) const
2284 \overload operator<=()
2286 The \a other const char pointer is converted to a QString using
2287 the fromAscii() function.
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.
2295 /*! \fn bool QString::operator>(const QString &other) const
2297 Returns true if this string is lexically greater than string \a
2298 other; otherwise returns false.
2300 The comparison is based exclusively on the numeric Unicode values
2301 of the characters and is very fast, but is not what a human would
2302 expect. Consider sorting user-interface strings with
2303 localeAwareCompare().
2307 \overload operator>()
2309 bool QString::operator>(const QLatin1String &other) const
2311 const uchar *c = (uchar *) other.latin1();
2312 if (!c || *c == '\0')
2315 const ushort *uc = d->data();
2316 const ushort *e = uc + qMin(d->size, other.size());
2324 return (uc == e) ? d->size > other.size() : *uc > *c;
2327 /*! \fn bool QString::operator>(const QByteArray &other) const
2329 \overload operator>()
2331 The \a other byte array is converted to a QString using the
2332 fromAscii() function. If any NUL characters ('\0') are embedded
2333 in the byte array, they will be included in the transformation.
2335 You can disable this operator by defining \c
2336 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2337 can be useful if you want to ensure that all user-visible strings
2338 go through QObject::tr(), for example.
2341 /*! \fn bool QString::operator>(const char *other) const
2343 \overload operator>()
2345 The \a other const char pointer is converted to a QString using
2346 the fromAscii() function.
2348 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2349 when you compile your applications. This can be useful if you want
2350 to ensure that all user-visible strings go through QObject::tr(),
2354 /*! \fn bool QString::operator>=(const QString &other) const
2356 Returns true if this string is lexically greater than or equal to
2357 string \a other; otherwise returns false.
2359 The comparison is based exclusively on the numeric Unicode values
2360 of the characters and is very fast, but is not what a human would
2361 expect. Consider sorting user-interface strings with
2362 localeAwareCompare().
2365 /*! \fn bool QString::operator>=(const QLatin1String &other) const
2367 \overload operator>=()
2370 /*! \fn bool QString::operator>=(const QByteArray &other) const
2372 \overload operator>=()
2374 The \a other byte array is converted to a QString using the
2375 fromAscii() function. If any NUL characters ('\0') are embedded in
2376 the byte array, they will be included in the transformation.
2378 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2379 when you compile your applications. This can be useful if you want
2380 to ensure that all user-visible strings go through QObject::tr(),
2384 /*! \fn bool QString::operator>=(const char *other) const
2386 \overload operator>=()
2388 The \a other const char pointer is converted to a QString using
2389 the fromAscii() function.
2391 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2392 when you compile your applications. This can be useful if you want
2393 to ensure that all user-visible strings go through QObject::tr(),
2397 /*! \fn bool QString::operator!=(const QString &other) const
2399 Returns true if this string is not equal to string \a other;
2400 otherwise returns false.
2402 The comparison is based exclusively on the numeric Unicode values
2403 of the characters and is very fast, but is not what a human would
2404 expect. Consider sorting user-interface strings with
2405 localeAwareCompare().
2408 /*! \fn bool QString::operator!=(const QLatin1String &other) const
2410 \overload operator!=()
2413 /*! \fn bool QString::operator!=(const QByteArray &other) const
2415 \overload operator!=()
2417 The \a other byte array is converted to a QString using the
2418 fromAscii() function. If any NUL characters ('\0') are embedded
2419 in the byte array, they will be included in the transformation.
2421 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2422 when you compile your applications. This can be useful if you want
2423 to ensure that all user-visible strings go through QObject::tr(),
2427 /*! \fn bool QString::operator!=(const char *other) const
2429 \overload operator!=()
2431 The \a other const char pointer is converted to a QString using
2432 the fromAscii() function.
2434 You can disable this operator by defining \c
2435 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2436 can be useful if you want to ensure that all user-visible strings
2437 go through QObject::tr(), for example.
2441 Returns the index position of the first occurrence of the string \a
2442 str in this string, searching forward from index position \a
2443 from. Returns -1 if \a str is not found.
2445 If \a cs is Qt::CaseSensitive (default), the search is case
2446 sensitive; otherwise the search is case insensitive.
2450 \snippet doc/src/snippets/qstring/main.cpp 24
2452 If \a from is -1, the search starts at the last character; if it is
2453 -2, at the next to last character and so on.
2455 \sa lastIndexOf(), contains(), count()
2457 int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2459 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2464 Returns the index position of the first occurrence of the string \a
2465 str in this string, searching forward from index position \a
2466 from. Returns -1 if \a str is not found.
2468 If \a cs is Qt::CaseSensitive (default), the search is case
2469 sensitive; otherwise the search is case insensitive.
2473 \snippet doc/src/snippets/qstring/main.cpp 24
2475 If \a from is -1, the search starts at the last character; if it is
2476 -2, at the next to last character and so on.
2478 \sa lastIndexOf(), contains(), count()
2481 int QString::indexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2483 return qt_find_latin1_string(unicode(), size(), str, from, cs);
2487 const QChar *haystack0, int haystackLen, int from,
2488 const QChar *needle0, int needleLen, Qt::CaseSensitivity cs)
2490 const int l = haystackLen;
2491 const int sl = needleLen;
2494 if (uint(sl + from) > (uint)l)
2502 return findChar(haystack0, haystackLen, needle0[0], from, cs);
2505 We use the Boyer-Moore algorithm in cases where the overhead
2506 for the skip table should pay off, otherwise we use a simple
2509 if (l > 500 && sl > 5)
2510 return qFindStringBoyerMoore(haystack0, haystackLen, from,
2511 needle0, needleLen, cs);
2514 We use some hashing for efficiency's sake. Instead of
2515 comparing strings, we compare the hash value of str with that
2516 of a part of this QString. Only if that matches, we call
2517 ucstrncmp() or ucstrnicmp().
2519 const ushort *needle = (const ushort *)needle0;
2520 const ushort *haystack = (const ushort *)haystack0 + from;
2521 const ushort *end = (const ushort *)haystack0 + (l-sl);
2522 const int sl_minus_1 = sl-1;
2523 int hashNeedle = 0, hashHaystack = 0, idx;
2525 if (cs == Qt::CaseSensitive) {
2526 for (idx = 0; idx < sl; ++idx) {
2527 hashNeedle = ((hashNeedle<<1) + needle[idx]);
2528 hashHaystack = ((hashHaystack<<1) + haystack[idx]);
2530 hashHaystack -= haystack[sl_minus_1];
2532 while (haystack <= end) {
2533 hashHaystack += haystack[sl_minus_1];
2534 if (hashHaystack == hashNeedle
2535 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2536 return haystack - (const ushort *)haystack0;
2542 const ushort *haystack_start = (const ushort *)haystack0;
2543 for (idx = 0; idx < sl; ++idx) {
2544 hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle);
2545 hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start);
2547 hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start);
2549 while (haystack <= end) {
2550 hashHaystack += foldCase(haystack + sl_minus_1, haystack_start);
2551 if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2552 return haystack - (const ushort *)haystack0;
2554 REHASH(foldCase(haystack, haystack_start));
2564 Returns the index position of the first occurrence of the
2565 character \a ch in the string, searching forward from index
2566 position \a from. Returns -1 if \a ch could not be found.
2568 int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2570 return findChar(unicode(), length(), ch, from, cs);
2578 Returns the index position of the first occurrence of the string
2579 reference \a str in this string, searching forward from index
2580 position \a from. Returns -1 if \a str is not found.
2582 If \a cs is Qt::CaseSensitive (default), the search is case
2583 sensitive; otherwise the search is case insensitive.
2585 int QString::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2587 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2590 static int lastIndexOfHelper(const ushort *haystack, int from, const ushort *needle, int sl, Qt::CaseSensitivity cs)
2593 See indexOf() for explanations.
2596 const ushort *end = haystack;
2598 const int sl_minus_1 = sl-1;
2599 const ushort *n = needle+sl_minus_1;
2600 const ushort *h = haystack+sl_minus_1;
2601 int hashNeedle = 0, hashHaystack = 0, idx;
2603 if (cs == Qt::CaseSensitive) {
2604 for (idx = 0; idx < sl; ++idx) {
2605 hashNeedle = ((hashNeedle<<1) + *(n-idx));
2606 hashHaystack = ((hashHaystack<<1) + *(h-idx));
2608 hashHaystack -= *haystack;
2610 while (haystack >= end) {
2611 hashHaystack += *haystack;
2612 if (hashHaystack == hashNeedle
2613 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2614 return haystack - end;
2616 REHASH(haystack[sl]);
2619 for (idx = 0; idx < sl; ++idx) {
2620 hashNeedle = ((hashNeedle<<1) + foldCase(n-idx, needle));
2621 hashHaystack = ((hashHaystack<<1) + foldCase(h-idx, end));
2623 hashHaystack -= foldCase(haystack, end);
2625 while (haystack >= end) {
2626 hashHaystack += foldCase(haystack, end);
2627 if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2628 return haystack - end;
2630 REHASH(foldCase(haystack + sl, end));
2637 Returns the index position of the last occurrence of the string \a
2638 str in this string, searching backward from index position \a
2639 from. If \a from is -1 (default), the search starts at the last
2640 character; if \a from is -2, at the next to last character and so
2641 on. Returns -1 if \a str is not found.
2643 If \a cs is Qt::CaseSensitive (default), the search is case
2644 sensitive; otherwise the search is case insensitive.
2648 \snippet doc/src/snippets/qstring/main.cpp 29
2650 \sa indexOf(), contains(), count()
2652 int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2654 const int sl = str.d->size;
2656 return lastIndexOf(QChar(str.d->data()[0]), from, cs);
2658 const int l = d->size;
2662 if (from == l && sl == 0)
2664 if (from < 0 || from >= l || delta < 0)
2669 return lastIndexOfHelper(d->data(), from, str.d->data(), str.d->size, cs);
2674 \overload lastIndexOf()
2676 Returns the index position of the last occurrence of the string \a
2677 str in this string, searching backward from index position \a
2678 from. If \a from is -1 (default), the search starts at the last
2679 character; if \a from is -2, at the next to last character and so
2680 on. Returns -1 if \a str is not found.
2682 If \a cs is Qt::CaseSensitive (default), the search is case
2683 sensitive; otherwise the search is case insensitive.
2687 \snippet doc/src/snippets/qstring/main.cpp 29
2689 \sa indexOf(), contains(), count()
2691 int QString::lastIndexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const
2693 const int sl = str.size();
2695 return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
2697 const int l = d->size;
2701 if (from == l && sl == 0)
2703 if (from < 0 || from >= l || delta < 0)
2708 QVarLengthArray<ushort> s(sl);
2709 for (int i = 0; i < sl; ++i)
2710 s[i] = str.latin1()[i];
2712 return lastIndexOfHelper(d->data(), from, s.data(), sl, cs);
2716 \overload lastIndexOf()
2718 Returns the index position of the last occurrence of the character
2719 \a ch, searching backward from position \a from.
2721 int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2723 return qt_last_index_of(unicode(), size(), ch, from, cs);
2728 \overload lastIndexOf()
2730 Returns the index position of the last occurrence of the string
2731 reference \a str in this string, searching backward from index
2732 position \a from. If \a from is -1 (default), the search starts at
2733 the last character; if \a from is -2, at the next to last character
2734 and so on. Returns -1 if \a str is not found.
2736 If \a cs is Qt::CaseSensitive (default), the search is case
2737 sensitive; otherwise the search is case insensitive.
2739 \sa indexOf(), contains(), count()
2741 int QString::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2743 const int sl = str.size();
2745 return lastIndexOf(str.at(0), from, cs);
2747 const int l = d->size;
2751 if (from == l && sl == 0)
2753 if (from < 0 || from >= l || delta < 0)
2758 return lastIndexOfHelper(d->data(), from, reinterpret_cast<const ushort*>(str.unicode()),
2762 #ifndef QT_NO_REGEXP
2763 struct QStringCapture
2773 Replaces every occurrence of the regular expression \a rx in the
2774 string with \a after. Returns a reference to the string. For
2777 \snippet doc/src/snippets/qstring/main.cpp 42
2779 For regular expressions containing \l{capturing parentheses},
2780 occurrences of \bold{\\1}, \bold{\\2}, ..., in \a after are replaced
2781 with \a{rx}.cap(1), cap(2), ...
2783 \snippet doc/src/snippets/qstring/main.cpp 43
2785 \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap()
2787 QString& QString::replace(const QRegExp &rx, const QString &after)
2791 if (isEmpty() && rx2.indexIn(*this) == -1)
2797 int numCaptures = rx2.captureCount();
2798 int al = after.length();
2799 QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
2801 if (numCaptures > 0) {
2802 const QChar *uc = after.unicode();
2803 int numBackRefs = 0;
2805 for (int i = 0; i < al - 1; i++) {
2806 if (uc[i] == QLatin1Char('\\')) {
2807 int no = uc[i + 1].digitValue();
2808 if (no > 0 && no <= numCaptures)
2814 This is the harder case where we have back-references.
2816 if (numBackRefs > 0) {
2817 QVarLengthArray<QStringCapture, 16> captures(numBackRefs);
2820 for (int i = 0; i < al - 1; i++) {
2821 if (uc[i] == QLatin1Char('\\')) {
2822 int no = uc[i + 1].digitValue();
2823 if (no > 0 && no <= numCaptures) {
2824 QStringCapture capture;
2829 int secondDigit = uc[i + 2].digitValue();
2830 if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
2831 no = (no * 10) + secondDigit;
2837 captures[j++] = capture;
2842 while (index <= length()) {
2843 index = rx2.indexIn(*this, index, caretMode);
2847 QString after2(after);
2848 for (j = numBackRefs - 1; j >= 0; j--) {
2849 const QStringCapture &capture = captures[j];
2850 after2.replace(capture.pos, capture.len, rx2.cap(capture.no));
2853 replace(index, rx2.matchedLength(), after2);
2854 index += after2.length();
2856 // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*"))
2857 if (rx2.matchedLength() == 0)
2860 caretMode = QRegExp::CaretWontMatch;
2867 This is the simple and optimized case where we don't have
2870 while (index != -1) {
2874 } replacements[2048];
2878 while (pos < 2047) {
2879 index = rx2.indexIn(*this, index, caretMode);
2882 int ml = rx2.matchedLength();
2883 replacements[pos].pos = index;
2884 replacements[pos++].length = ml;
2887 // avoid infinite loop
2893 replacements[pos].pos = d->size;
2894 int newlen = d->size + adjust;
2896 // to continue searching at the right position after we did
2897 // the first round of replacements
2901 newstring.reserve(newlen + 1);
2902 QChar *newuc = newstring.data();
2907 int copyend = replacements[i].pos;
2908 int size = copyend - copystart;
2909 memcpy(uc, d->data() + copystart, size * sizeof(QChar));
2911 memcpy(uc, after.d->data(), al * sizeof(QChar));
2913 copystart = copyend + replacements[i].length;
2916 memcpy(uc, d->data() + copystart, (d->size - copystart) * sizeof(QChar));
2917 newstring.resize(newlen);
2919 caretMode = QRegExp::CaretWontMatch;
2926 Returns the number of (potentially overlapping) occurrences of
2927 the string \a str in this string.
2929 If \a cs is Qt::CaseSensitive (default), the search is
2930 case sensitive; otherwise the search is case insensitive.
2932 \sa contains(), indexOf()
2935 int QString::count(const QString &str, Qt::CaseSensitivity cs) const
2937 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
2943 Returns the number of occurrences of character \a ch in the string.
2946 int QString::count(QChar ch, Qt::CaseSensitivity cs) const
2948 return qt_string_count(unicode(), size(), ch, cs);
2954 Returns the number of (potentially overlapping) occurrences of the
2955 string reference \a str in this string.
2957 If \a cs is Qt::CaseSensitive (default), the search is
2958 case sensitive; otherwise the search is case insensitive.
2960 \sa contains(), indexOf()
2962 int QString::count(const QStringRef &str, Qt::CaseSensitivity cs) const
2964 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
2968 /*! \fn bool QString::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
2970 Returns true if this string contains an occurrence of the string
2971 \a str; otherwise returns false.
2973 If \a cs is Qt::CaseSensitive (default), the search is
2974 case sensitive; otherwise the search is case insensitive.
2977 \snippet doc/src/snippets/qstring/main.cpp 17
2979 \sa indexOf(), count()
2982 /*! \fn bool QString::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
2984 \overload contains()
2986 Returns true if this string contains an occurrence of the
2987 character \a ch; otherwise returns false.
2990 /*! \fn bool QString::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
2993 Returns true if this string contains an occurrence of the string
2994 reference \a str; otherwise returns false.
2996 If \a cs is Qt::CaseSensitive (default), the search is
2997 case sensitive; otherwise the search is case insensitive.
2999 \sa indexOf(), count()
3002 /*! \fn bool QString::contains(const QRegExp &rx) const
3004 \overload contains()
3006 Returns true if the regular expression \a rx matches somewhere in
3007 this string; otherwise returns false.
3010 /*! \fn bool QString::contains(QRegExp &rx) const
3011 \overload contains()
3014 Returns true if the regular expression \a rx matches somewhere in
3015 this string; otherwise returns false.
3017 If there is a match, the \a rx regular expression will contain the
3018 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3021 #ifndef QT_NO_REGEXP
3025 Returns the index position of the first match of the regular
3026 expression \a rx in the string, searching forward from index
3027 position \a from. Returns -1 if \a rx didn't match anywhere.
3031 \snippet doc/src/snippets/qstring/main.cpp 25
3033 int QString::indexOf(const QRegExp& rx, int from) const
3036 return rx2.indexIn(*this, from);
3043 Returns the index position of the first match of the regular
3044 expression \a rx in the string, searching forward from index
3045 position \a from. Returns -1 if \a rx didn't match anywhere.
3047 If there is a match, the \a rx regular expression will contain the
3048 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3052 \snippet doc/src/snippets/qstring/main.cpp 25
3054 int QString::indexOf(QRegExp& rx, int from) const
3056 return rx.indexIn(*this, from);
3060 \overload lastIndexOf()
3062 Returns the index position of the last match of the regular
3063 expression \a rx in the string, searching backward from index
3064 position \a from. Returns -1 if \a rx didn't match anywhere.
3068 \snippet doc/src/snippets/qstring/main.cpp 30
3070 int QString::lastIndexOf(const QRegExp& rx, int from) const
3073 return rx2.lastIndexIn(*this, from);
3077 \overload lastIndexOf()
3080 Returns the index position of the last match of the regular
3081 expression \a rx in the string, searching backward from index
3082 position \a from. Returns -1 if \a rx didn't match anywhere.
3084 If there is a match, the \a rx regular expression will contain the
3085 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3089 \snippet doc/src/snippets/qstring/main.cpp 30
3091 int QString::lastIndexOf(QRegExp& rx, int from) const
3093 return rx.lastIndexIn(*this, from);
3099 Returns the number of times the regular expression \a rx matches
3102 This function counts overlapping matches, so in the example
3103 below, there are four instances of "ana" or "ama":
3105 \snippet doc/src/snippets/qstring/main.cpp 18
3108 int QString::count(const QRegExp& rx) const
3114 while (index < len - 1) { // count overlapping matches
3115 index = rx2.indexIn(*this, index + 1);
3122 #endif // QT_NO_REGEXP
3124 /*! \fn int QString::count() const
3133 \enum QString::SectionFlag
3135 This enum specifies flags that can be used to affect various
3136 aspects of the section() function's behavior with respect to
3137 separators and empty fields.
3139 \value SectionDefault Empty fields are counted, leading and
3140 trailing separators are not included, and the separator is
3141 compared case sensitively.
3143 \value SectionSkipEmpty Treat empty fields as if they don't exist,
3144 i.e. they are not considered as far as \e start and \e end are
3147 \value SectionIncludeLeadingSep Include the leading separator (if
3148 any) in the result string.
3150 \value SectionIncludeTrailingSep Include the trailing separator
3151 (if any) in the result string.
3153 \value SectionCaseInsensitiveSeps Compare the separator
3160 \fn QString QString::section(QChar sep, int start, int end = -1, SectionFlags flags) const
3162 This function returns a section of the string.
3164 This string is treated as a sequence of fields separated by the
3165 character, \a sep. The returned string consists of the fields from
3166 position \a start to position \a end inclusive. If \a end is not
3167 specified, all fields from position \a start to the end of the
3168 string are included. Fields are numbered 0, 1, 2, etc., counting
3169 from the left, and -1, -2, etc., counting from right to left.
3171 The \a flags argument can be used to affect some aspects of the
3172 function's behavior, e.g. whether to be case sensitive, whether
3173 to skip empty fields and how to deal with leading and trailing
3174 separators; see \l{SectionFlags}.
3176 \snippet doc/src/snippets/qstring/main.cpp 52
3178 If \a start or \a end is negative, we count fields from the right
3179 of the string, the right-most field being -1, the one from
3180 right-most field being -2, and so on.
3182 \snippet doc/src/snippets/qstring/main.cpp 53
3190 \snippet doc/src/snippets/qstring/main.cpp 51
3191 \snippet doc/src/snippets/qstring/main.cpp 54
3196 QString QString::section(const QString &sep, int start, int end, SectionFlags flags) const
3198 QStringList sections = split(sep, KeepEmptyParts,
3199 (flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive : Qt::CaseSensitive);
3200 if (sections.isEmpty())
3202 if (!(flags & SectionSkipEmpty)) {
3204 start += sections.count();
3206 end += sections.count();
3209 for (int k=0; k<sections.size(); ++k) {
3210 if (sections.at(k).isEmpty())
3214 start += sections.count() - skip;
3216 end += sections.count() - skip;
3220 int first_i = start, last_i = end;
3221 for (int i = 0; x <= end && i < sections.size(); ++i) {
3222 QString section = sections.at(i);
3223 const bool empty = section.isEmpty();
3233 if (!empty || !(flags & SectionSkipEmpty))
3236 if((flags & SectionIncludeLeadingSep) && first_i)
3238 if((flags & SectionIncludeTrailingSep) && last_i < sections.size()-1)
3243 #ifndef QT_NO_REGEXP
3244 class qt_section_chunk {
3246 qt_section_chunk(int l, QString s) { length = l; string = s; }
3254 This string is treated as a sequence of fields separated by the
3255 regular expression, \a reg.
3257 \snippet doc/src/snippets/qstring/main.cpp 55
3259 \warning Using this QRegExp version is much more expensive than
3260 the overloaded string and character versions.
3262 \sa split() simplified()
3264 QString QString::section(const QRegExp ®, int start, int end, SectionFlags flags) const
3266 const QChar *uc = unicode();
3271 sep.setCaseSensitivity((flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive
3272 : Qt::CaseSensitive);
3274 QList<qt_section_chunk> sections;
3275 int n = length(), m = 0, last_m = 0, last_len = 0;
3276 while ((m = sep.indexIn(*this, m)) != -1) {
3277 sections.append(qt_section_chunk(last_len, QString(uc + last_m, m - last_m)));
3279 last_len = sep.matchedLength();
3280 m += qMax(sep.matchedLength(), 1);
3282 sections.append(qt_section_chunk(last_len, QString(uc + last_m, n - last_m)));
3285 start += sections.count();
3287 end += sections.count();
3291 int first_i = start, last_i = end;
3292 for (int i = 0; x <= end && i < sections.size(); ++i) {
3293 const qt_section_chunk §ion = sections.at(i);
3294 const bool empty = (section.length == section.string.length());
3301 ret += section.string;
3303 ret += section.string.mid(section.length);
3305 if (!empty || !(flags & SectionSkipEmpty))
3308 if((flags & SectionIncludeLeadingSep) && first_i < sections.size()) {
3309 const qt_section_chunk §ion = sections.at(first_i);
3310 ret.prepend(section.string.left(section.length));
3312 if((flags & SectionIncludeTrailingSep) && last_i+1 <= sections.size()-1) {
3313 const qt_section_chunk §ion = sections.at(last_i+1);
3314 ret += section.string.left(section.length);
3321 Returns a substring that contains the \a n leftmost characters
3324 The entire string is returned if \a n is greater than size() or
3327 \snippet doc/src/snippets/qstring/main.cpp 31
3329 \sa right(), mid(), startsWith()
3331 QString QString::left(int n) const
3333 if (n >= d->size || n < 0)
3335 return QString((const QChar*) d->data(), n);
3339 Returns a substring that contains the \a n rightmost characters
3342 The entire string is returned if \a n is greater than size() or
3345 \snippet doc/src/snippets/qstring/main.cpp 48
3347 \sa left(), mid(), endsWith()
3349 QString QString::right(int n) const
3351 if (n >= d->size || n < 0)
3353 return QString((const QChar*) d->data() + d->size - n, n);
3357 Returns a string that contains \a n characters of this string,
3358 starting at the specified \a position index.
3360 Returns a null string if the \a position index exceeds the
3361 length of the string. If there are less than \a n characters
3362 available in the string starting at the given \a position, or if
3363 \a n is -1 (default), the function returns all characters that
3364 are available from the specified \a position.
3368 \snippet doc/src/snippets/qstring/main.cpp 34
3373 QString QString::mid(int position, int n) const
3375 if (position > d->size)
3379 if (n < 0 || n > d->size - position)
3380 n = d->size - position;
3381 if (position == 0 && n == d->size)
3383 return QString((const QChar*) d->data() + position, n);
3387 Returns true if the string starts with \a s; otherwise returns
3390 If \a cs is Qt::CaseSensitive (default), the search is
3391 case sensitive; otherwise the search is case insensitive.
3393 \snippet doc/src/snippets/qstring/main.cpp 65
3397 bool QString::startsWith(const QString& s, Qt::CaseSensitivity cs) const
3399 return qt_starts_with(isNull() ? 0 : unicode(), size(),
3400 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3404 \overload startsWith()
3406 bool QString::startsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const
3408 return qt_starts_with(isNull() ? 0 : unicode(), size(), s, cs);
3412 \overload startsWith()
3414 Returns true if the string starts with \a c; otherwise returns
3417 bool QString::startsWith(QChar c, Qt::CaseSensitivity cs) const
3420 && (cs == Qt::CaseSensitive
3422 : foldCase(d->data()[0]) == foldCase(c.unicode()));
3428 Returns true if the string starts with the string reference \a s;
3429 otherwise returns false.
3431 If \a cs is Qt::CaseSensitive (default), the search is case
3432 sensitive; otherwise the search is case insensitive.
3436 bool QString::startsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
3438 return qt_starts_with(isNull() ? 0 : unicode(), size(),
3439 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3443 Returns true if the string ends with \a s; otherwise returns
3446 If \a cs is Qt::CaseSensitive (default), the search is case
3447 sensitive; otherwise the search is case insensitive.
3449 \snippet doc/src/snippets/qstring/main.cpp 20
3453 bool QString::endsWith(const QString& s, Qt::CaseSensitivity cs) const
3455 return qt_ends_with(isNull() ? 0 : unicode(), size(),
3456 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3461 \overload endsWith()
3462 Returns true if the string ends with the string reference \a s;
3463 otherwise returns false.
3465 If \a cs is Qt::CaseSensitive (default), the search is case
3466 sensitive; otherwise the search is case insensitive.
3470 bool QString::endsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
3472 return qt_ends_with(isNull() ? 0 : unicode(), size(),
3473 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3478 \overload endsWith()
3480 bool QString::endsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const
3482 return qt_ends_with(isNull() ? 0 : unicode(), size(), s, cs);
3486 Returns true if the string ends with \a c; otherwise returns
3489 \overload endsWith()
3491 bool QString::endsWith(QChar c, Qt::CaseSensitivity cs) const
3494 && (cs == Qt::CaseSensitive
3495 ? d->data()[d->size - 1] == c
3496 : foldCase(d->data()[d->size - 1]) == foldCase(c.unicode()));
3500 #if defined(QT_ALWAYS_HAVE_SSE2)
3501 static inline __m128i mergeQuestionMarks(__m128i chunk)
3503 const __m128i questionMark = _mm_set1_epi16('?');
3506 // compare the unsigned shorts for the range 0x0100-0xFFFF
3507 // note on the use of _mm_cmpestrm:
3508 // The MSDN documentation online (http://technet.microsoft.com/en-us/library/bb514080.aspx)
3509 // says for range search the following:
3510 // For each character c in a, determine whether b0 <= c <= b1 or b2 <= c <= b3
3512 // However, all examples on the Internet, including from Intel
3513 // (see http://software.intel.com/en-us/articles/xml-parsing-accelerator-with-intel-streaming-simd-extensions-4-intel-sse4/)
3514 // put the range to be searched first
3516 // Disassembly and instruction-level debugging with GCC and ICC show
3517 // that they are doing the right thing. Inverting the arguments in the
3518 // instruction does cause a bunch of test failures.
3520 const int mode = _SIDD_UWORD_OPS | _SIDD_CMP_RANGES | _SIDD_UNIT_MASK;
3521 const __m128i rangeMatch = _mm_cvtsi32_si128(0xffff0100);
3522 const __m128i offLimitMask = _mm_cmpestrm(rangeMatch, 2, chunk, 8, mode);
3524 // replace the non-Latin 1 characters in the chunk with question marks
3525 chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask);
3527 // SSE has no compare instruction for unsigned comparison.
3528 // The variables must be shiffted + 0x8000 to be compared
3529 const __m128i signedBitOffset = _mm_set1_epi16(0x8000);
3530 const __m128i thresholdMask = _mm_set1_epi16(0xff + 0x8000);
3532 const __m128i signedChunk = _mm_add_epi16(chunk, signedBitOffset);
3533 const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask);
3536 // replace the non-Latin 1 characters in the chunk with question marks
3537 chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask);
3539 // offLimitQuestionMark contains '?' for each 16 bits that was off-limit
3540 // the 16 bits that were correct contains zeros
3541 const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark);
3543 // correctBytes contains the bytes that were in limit
3544 // the 16 bits that were off limits contains zeros
3545 const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk);
3547 // merge offLimitQuestionMark and correctBytes to have the result
3548 chunk = _mm_or_si128(correctBytes, offLimitQuestionMark);
3555 static QByteArray toLatin1_helper(const QChar *data, int length)
3560 const ushort *src = reinterpret_cast<const ushort *>(data);
3561 uchar *dst = (uchar*) ba.data();
3562 #if defined(QT_ALWAYS_HAVE_SSE2)
3564 const int chunkCount = length >> 4; // divided by 16
3566 for (int i = 0; i < chunkCount; ++i) {
3567 __m128i chunk1 = _mm_loadu_si128((__m128i*)src); // load
3568 chunk1 = mergeQuestionMarks(chunk1);
3571 __m128i chunk2 = _mm_loadu_si128((__m128i*)src); // load
3572 chunk2 = mergeQuestionMarks(chunk2);
3575 // pack the two vector to 16 x 8bits elements
3576 const __m128i result = _mm_packus_epi16(chunk1, chunk2);
3578 _mm_storeu_si128((__m128i*)dst, result); // store
3581 length = length % 16;
3583 #elif defined(QT_ALWAYS_HAVE_NEON)
3584 // Refer to the documentation of the SSE2 implementation
3585 // this use eactly the same method as for SSE except:
3586 // 1) neon has unsigned comparison
3587 // 2) packing is done to 64 bits (8 x 8bits component).
3589 const int chunkCount = length >> 3; // divided by 8
3590 const uint16x8_t questionMark = vdupq_n_u16('?'); // set
3591 const uint16x8_t thresholdMask = vdupq_n_u16(0xff); // set
3592 for (int i = 0; i < chunkCount; ++i) {
3593 uint16x8_t chunk = vld1q_u16((uint16_t *)src); // load
3596 const uint16x8_t offLimitMask = vcgtq_u16(chunk, thresholdMask); // chunk > thresholdMask
3597 const uint16x8_t offLimitQuestionMark = vandq_u16(offLimitMask, questionMark); // offLimitMask & questionMark
3598 const uint16x8_t correctBytes = vbicq_u16(chunk, offLimitMask); // !offLimitMask & chunk
3599 chunk = vorrq_u16(correctBytes, offLimitQuestionMark); // correctBytes | offLimitQuestionMark
3600 const uint8x8_t result = vmovn_u16(chunk); // narrowing move->packing
3601 vst1_u8(dst, result); // store
3604 length = length % 8;
3608 *dst++ = (*src>0xff) ? '?' : (uchar) *src;
3616 Returns a Latin-1 representation of the string as a QByteArray.
3618 The returned byte array is undefined if the string contains non-Latin1
3619 characters. Those characters may be suppressed or replaced with a
3622 \sa fromLatin1(), toAscii(), toUtf8(), toLocal8Bit(), QTextCodec
3624 QByteArray QString::toLatin1() const
3626 return toLatin1_helper(unicode(), length());
3630 Returns an 8-bit representation of the string as a QByteArray.
3632 If a codec has been set using QTextCodec::setCodecForCStrings(),
3633 it is used to convert Unicode to 8-bit char; otherwise this
3634 function does the same as toLatin1().
3636 Note that, despite the name, this function does not necessarily return an US-ASCII
3637 (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
3639 \sa fromAscii(), toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
3641 QByteArray QString::toAscii() const
3643 #ifndef QT_NO_TEXTCODEC
3644 if (codecForCStrings)
3645 return codecForCStrings->fromUnicode(*this);
3646 #endif // QT_NO_TEXTCODEC
3650 #if !defined(Q_OS_MAC) && defined(Q_OS_UNIX)
3651 static QByteArray toLocal8Bit_helper(const QChar *data, int length)
3653 #ifndef QT_NO_TEXTCODEC
3654 if (QTextCodec::codecForLocale())
3655 return QTextCodec::codecForLocale()->fromUnicode(data, length);
3656 #endif // QT_NO_TEXTCODEC
3657 return toLatin1_helper(data, length);
3662 Returns the local 8-bit representation of the string as a
3663 QByteArray. The returned byte array is undefined if the string
3664 contains characters not supported by the local 8-bit encoding.
3666 QTextCodec::codecForLocale() is used to perform the conversion from
3667 Unicode. If the locale encoding could not be determined, this function
3668 does the same as toLatin1().
3670 If this string contains any characters that cannot be encoded in the
3671 locale, the returned byte array is undefined. Those characters may be
3672 suppressed or replaced by another.
3674 \sa fromLocal8Bit(), toAscii(), toLatin1(), toUtf8(), QTextCodec
3676 QByteArray QString::toLocal8Bit() const
3678 #ifndef QT_NO_TEXTCODEC
3679 if (QTextCodec::codecForLocale())
3680 return QTextCodec::codecForLocale()->fromUnicode(*this);
3681 #endif // QT_NO_TEXTCODEC
3686 Returns a UTF-8 representation of the string as a QByteArray.
3688 UTF-8 is a Unicode codec and can represent all characters in a Unicode
3689 string like QString.
3691 However, in the Unicode range, there are certain codepoints that are not
3692 considered characters. The Unicode standard reserves the last two
3693 codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
3694 U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF,
3695 inclusive, as non-characters. If any of those appear in the string, they
3696 may be discarded and will not appear in the UTF-8 representation, or they
3697 may be replaced by one or more replacement characters.
3699 \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
3701 QByteArray QString::toUtf8() const
3704 return QByteArray();
3706 return QUtf8::convertFromUnicode(constData(), length(), 0);
3712 Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
3714 UCS-4 is a Unicode codec and is lossless. All characters from this string
3715 can be encoded in UCS-4. The vector is not null terminated.
3717 \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
3719 QVector<uint> QString::toUcs4() const
3721 QVector<uint> v(length());
3723 int len = toUcs4_helper(d->data(), length(), a);
3728 QString::Data *QString::fromLatin1_helper(const char *str, int size)
3732 d = const_cast<Data *>(&shared_null.str);
3733 } else if (size == 0 || (!*str && size < 0)) {
3734 d = const_cast<Data *>(&shared_empty.str);
3737 size = qstrlen(str);
3738 d = static_cast<Data *>(::malloc(sizeof(Data) + (size+1) * sizeof(QChar)));
3740 d->ref.initializeOwned();
3742 d->alloc = (uint) size;
3743 d->capacityReserved = false;
3745 d->data()[size] = '\0';
3746 ushort *dst = d->data();
3748 * Unpacking with SSE has been shown to improve performance on recent CPUs
3749 * The same method gives no improvement with NEON.
3751 #if defined(QT_ALWAYS_HAVE_SSE2)
3753 int chunkCount = size >> 4; // divided by 16
3754 const __m128i nullMask = _mm_set1_epi32(0);
3755 for (int i = 0; i < chunkCount; ++i) {
3756 const __m128i chunk = _mm_loadu_si128((__m128i*)str); // load
3759 // unpack the first 8 bytes, padding with zeros
3760 const __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullMask);
3761 _mm_storeu_si128((__m128i*)dst, firstHalf); // store
3764 // unpack the last 8 bytes, padding with zeros
3765 const __m128i secondHalf = _mm_unpackhi_epi8 (chunk, nullMask);
3766 _mm_storeu_si128((__m128i*)dst, secondHalf); // store
3773 *dst++ = (uchar)*str++;
3778 QString::Data *QString::fromAscii_helper(const char *str, int size)
3780 #ifndef QT_NO_TEXTCODEC
3781 if (codecForCStrings) {
3784 d = const_cast<Data *>(&shared_null.str);
3785 } else if (size == 0 || (!*str && size < 0)) {
3786 d = const_cast<Data *>(&shared_empty.str);
3789 size = qstrlen(str);
3790 QString s = codecForCStrings->toUnicode(str, size);
3797 return fromLatin1_helper(str, size);
3800 /*! \fn QString QString::fromLatin1(const char *str, int size)
3801 Returns a QString initialized with the first \a size characters
3802 of the Latin-1 string \a str.
3804 If \a size is -1 (default), it is taken to be strlen(\a
3807 \sa toLatin1(), fromAscii(), fromUtf8(), fromLocal8Bit()
3811 /*! \fn QString QString::fromLocal8Bit(const char *str, int size)
3812 Returns a QString initialized with the first \a size characters
3813 of the 8-bit string \a str.
3815 If \a size is -1 (default), it is taken to be strlen(\a
3818 QTextCodec::codecForLocale() is used to perform the conversion.
3820 \sa toLocal8Bit(), fromAscii(), fromLatin1(), fromUtf8()
3822 QString QString::fromLocal8Bit_helper(const char *str, int size)
3826 if (size == 0 || (!*str && size < 0))
3827 return QString(shared_empty);
3828 #if !defined(QT_NO_TEXTCODEC)
3830 size = qstrlen(str);
3831 QTextCodec *codec = QTextCodec::codecForLocale();
3833 return codec->toUnicode(str, size);
3834 #endif // !QT_NO_TEXTCODEC
3835 return fromLatin1(str, size);
3838 /*! \fn QString QString::fromAscii(const char *, int size);
3839 Returns a QString initialized with the first \a size characters
3840 from the string \a str.
3842 If \a size is -1 (default), it is taken to be strlen(\a
3845 Note that, despite the name, this function actually uses the codec
3846 defined by QTextCodec::setCodecForCStrings() to convert \a str to
3847 Unicode. Depending on the codec, it may not accept valid US-ASCII (ANSI
3848 X3.4-1986) input. If no codec has been set, this function does the same
3851 \sa toAscii(), fromLatin1(), fromUtf8(), fromLocal8Bit()
3854 /*! \fn QString QString::fromUtf8(const char *str, int size)
3855 Returns a QString initialized with the first \a size bytes
3856 of the UTF-8 string \a str.
3858 If \a size is -1 (default), it is taken to be strlen(\a
3861 UTF-8 is a Unicode codec and can represent all characters in a Unicode
3862 string like QString. However, invalid sequences are possible with UTF-8
3863 and, if any such are found, they will be replaced with one or more
3864 "replacement characters", or suppressed. These include non-Unicode
3865 sequences, non-characters, overlong sequences or surrogate codepoints
3868 Non-characters are codepoints that the Unicode standard reserves and must
3869 not be used in text interchange. They are the last two codepoints in each
3870 Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well
3871 as 16 codepoints in the range U+FDD0..U+FDDF, inclusive.
3873 \sa toUtf8(), fromAscii(), fromLatin1(), fromLocal8Bit()
3875 QString QString::fromUtf8_helper(const char *str, int size)
3880 Q_ASSERT(size != -1);
3881 return QUtf8::convertToUnicode(str, size, 0);
3885 Returns a QString initialized with the first \a size characters
3886 of the Unicode string \a unicode (ISO-10646-UTF-16 encoded).
3888 If \a size is -1 (default), \a unicode must be terminated
3891 This function checks for a Byte Order Mark (BOM). If it is missing,
3892 host byte order is assumed.
3894 This function is slow compared to the other Unicode conversions.
3895 Use QString(const QChar *, int) or QString(const QChar *) if possible.
3897 QString makes a deep copy of the Unicode data.
3899 \sa utf16(), setUtf16()
3901 QString QString::fromUtf16(const ushort *unicode, int size)
3907 while (unicode[size] != 0)
3910 return QUtf16::convertToUnicode((const char *)unicode, size*2, 0);
3917 Returns a QString initialized with the first \a size characters
3918 of the Unicode string \a unicode (ISO-10646-UCS-4 encoded).
3920 If \a size is -1 (default), \a unicode must be terminated
3923 \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray()
3925 QString QString::fromUcs4(const uint *unicode, int size)
3931 while (unicode[size] != 0)
3934 return QUtf32::convertToUnicode((const char *)unicode, size*4, 0);
3938 Resizes the string to \a size characters and copies \a unicode
3941 If \a unicode is 0, nothing is copied, but the string is still
3944 \sa unicode(), setUtf16()
3946 QString& QString::setUnicode(const QChar *unicode, int size)
3949 if (unicode && size)
3950 memcpy(d->data(), unicode, size * sizeof(QChar));
3955 \fn QString &QString::setUtf16(const ushort *unicode, int size)
3957 Resizes the string to \a size characters and copies \a unicode
3960 If \a unicode is 0, nothing is copied, but the string is still
3963 Note that unlike fromUtf16(), this function does not consider BOMs and
3964 possibly differing byte ordering.
3966 \sa utf16(), setUnicode()
3970 Returns a string that has whitespace removed from the start
3971 and the end, and that has each sequence of internal whitespace
3972 replaced with a single space.
3974 Whitespace means any character for which QChar::isSpace() returns
3975 true. This includes the ASCII characters '\\t', '\\n', '\\v',
3976 '\\f', '\\r', and ' '.
3980 \snippet doc/src/snippets/qstring/main.cpp 57
3984 QString QString::simplified() const
3989 const QChar * const start = reinterpret_cast<QChar *>(d->data());
3990 const QChar *from = start;
3991 const QChar *fromEnd = start + d->size;
3996 if (++from == fromEnd) {
3997 // All-whitespace string
3998 return QString(shared_empty);
4001 // This loop needs no underflow check, as we already determined that
4002 // the string contains non-whitespace. If the string has exactly one
4003 // non-whitespace, it will be checked twice - we can live with that.
4004 while (fromEnd[-1].isSpace())
4006 // The rest of the function depends on the fact that we already know
4007 // that the last character in the source is no whitespace.
4008 const QChar *copyFrom = from;
4011 if (++from == fromEnd) {
4012 // Only leading and/or trailing whitespace, if any at all
4013 return mid(copyFrom - start, from - copyFrom);
4018 if (ch != QLatin1Char(' ')) {
4019 copyCount = from - copyFrom;
4024 copyCount = from - copyFrom - 1;
4028 // 'from' now points at the non-trailing whitespace which made the
4029 // string not simplified in the first place. 'copyCount' is the number
4030 // of already simplified characters - at least one, obviously -
4031 // without a trailing space.
4032 QString result((fromEnd - from) + copyCount, Qt::Uninitialized);
4033 QChar *to = reinterpret_cast<QChar *>(result.d->data());
4034 ::memcpy(to, copyFrom, copyCount * 2);
4039 *to++ = QLatin1Char(' ');
4042 } while (ch.isSpace());
4043 if (from == fromEnd)
4048 if (from == fromEnd)
4050 } while (!ch.isSpace());
4054 result.truncate(to - reinterpret_cast<QChar *>(result.d->data()));
4059 Returns a string that has whitespace removed from the start and
4062 Whitespace means any character for which QChar::isSpace() returns
4063 true. This includes the ASCII characters '\\t', '\\n', '\\v',
4064 '\\f', '\\r', and ' '.
4068 \snippet doc/src/snippets/qstring/main.cpp 82
4070 Unlike simplified(), trimmed() leaves internal whitespace alone.
4074 QString QString::trimmed() const
4078 const QChar *s = (const QChar*)d->data();
4079 if (!s->isSpace() && !s[d->size-1].isSpace())
4082 int end = d->size - 1;
4083 while (start<=end && s[start].isSpace()) // skip white space from start
4085 if (start <= end) { // only white space
4086 while (end && s[end].isSpace()) // skip white space from end
4089 int l = end - start + 1;
4091 return QString(shared_empty);
4093 return QString(s + start, l);
4096 /*! \fn const QChar QString::at(int position) const
4098 Returns the character at the given index \a position in the
4101 The \a position must be a valid index position in the string
4102 (i.e., 0 <= \a position < size()).
4108 \fn QCharRef QString::operator[](int position)
4110 Returns the character at the specified \a position in the string as a
4111 modifiable reference.
4115 \snippet doc/src/snippets/qstring/main.cpp 85
4117 The return value is of type QCharRef, a helper class for QString.
4118 When you get an object of type QCharRef, you can use it as if it
4119 were a QChar &. If you assign to it, the assignment will apply to
4120 the character in the QString from which you got the reference.
4126 \fn const QChar QString::operator[](int position) const
4128 \overload operator[]()
4131 /*! \fn QCharRef QString::operator[](uint position)
4133 \overload operator[]()
4135 Returns the character at the specified \a position in the string as a
4136 modifiable reference. Equivalent to \c at(position).
4139 /*! \fn const QChar QString::operator[](uint position) const
4141 \overload operator[]()
4145 \fn void QString::truncate(int position)
4147 Truncates the string at the given \a position index.
4149 If the specified \a position index is beyond the end of the
4150 string, nothing happens.
4154 \snippet doc/src/snippets/qstring/main.cpp 83
4156 If \a position is negative, it is equivalent to passing zero.
4158 \sa chop(), resize(), left()
4161 void QString::truncate(int pos)
4169 Removes \a n characters from the end of the string.
4171 If \a n is greater than size(), the result is an empty string.
4174 \snippet doc/src/snippets/qstring/main.cpp 15
4176 If you want to remove characters from the \e beginning of the
4177 string, use remove() instead.
4179 \sa truncate(), resize(), remove()
4181 void QString::chop(int n)
4184 resize(d->size - n);
4188 Sets every character in the string to character \a ch. If \a size
4189 is different from -1 (default), the string is resized to \a
4194 \snippet doc/src/snippets/qstring/main.cpp 21
4199 QString& QString::fill(QChar ch, int size)
4201 resize(size < 0 ? d->size : size);
4203 QChar *i = (QChar*)d->data() + d->size;
4204 QChar *b = (QChar*)d->data();
4212 \fn int QString::length() const
4214 Returns the number of characters in this string. Equivalent to
4221 \fn int QString::size() const
4223 Returns the number of characters in this string.
4225 The last character in the string is at position size() - 1. In
4226 addition, QString ensures that the character at position size()
4227 is always '\\0', so that you can use the return value of data()
4228 and constData() as arguments to functions that expect
4229 '\\0'-terminated strings.
4233 \snippet doc/src/snippets/qstring/main.cpp 58
4235 \sa isEmpty(), resize()
4238 /*! \fn bool QString::isNull() const
4240 Returns true if this string is null; otherwise returns false.
4244 \snippet doc/src/snippets/qstring/main.cpp 28
4246 Qt makes a distinction between null strings and empty strings for
4247 historical reasons. For most applications, what matters is
4248 whether or not a string contains any data, and this can be
4249 determined using the isEmpty() function.
4254 /*! \fn bool QString::isEmpty() const
4256 Returns true if the string has no characters; otherwise returns
4261 \snippet doc/src/snippets/qstring/main.cpp 27
4266 /*! \fn QString &QString::operator+=(const QString &other)
4268 Appends the string \a other onto the end of this string and
4269 returns a reference to this string.
4273 \snippet doc/src/snippets/qstring/main.cpp 84
4275 This operation is typically very fast (\l{constant time}),
4276 because QString preallocates extra space at the end of the string
4277 data so it can grow without reallocating the entire string each
4280 \sa append(), prepend()
4283 /*! \fn QString &QString::operator+=(const QLatin1String &str)
4285 \overload operator+=()
4287 Appends the Latin-1 string \a str to this string.
4290 /*! \fn QString &QString::operator+=(const QByteArray &ba)
4292 \overload operator+=()
4294 Appends the byte array \a ba to this string. The byte array is converted
4295 to Unicode using the fromAscii() function. If any NUL characters ('\0')
4296 are embedded in the \a ba byte array, they will be included in the
4299 You can disable this function by defining \c
4300 QT_NO_CAST_FROM_ASCII when you compile your applications. This
4301 can be useful if you want to ensure that all user-visible strings
4302 go through QObject::tr(), for example.
4305 /*! \fn QString &QString::operator+=(const char *str)
4307 \overload operator+=()
4309 Appends the string \a str to this string. The const char pointer
4310 is converted to Unicode using the fromAscii() function.
4312 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4313 when you compile your applications. This can be useful if you want
4314 to ensure that all user-visible strings go through QObject::tr(),
4318 /*! \fn QString &QString::operator+=(const QStringRef &str)
4320 \overload operator+=()
4322 Appends the string section referenced by \a str to this string.
4325 /*! \fn QString &QString::operator+=(char ch)
4327 \overload operator+=()
4329 Appends the character \a ch to this string. The character is
4330 converted to Unicode using the fromAscii() function.
4332 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4333 when you compile your applications. This can be useful if you want
4334 to ensure that all user-visible strings go through QObject::tr(),
4338 /*! \fn QString &QString::operator+=(QChar ch)
4340 \overload operator+=()
4342 Appends the character \a ch to the string.
4345 /*! \fn QString &QString::operator+=(QChar::SpecialCharacter c)
4347 \overload operator+=()
4353 \fn bool operator==(const char *s1, const QString &s2)
4355 \overload operator==()
4358 Returns true if \a s1 is equal to \a s2; otherwise returns false.
4359 Note that no string is equal to \a s1 being 0.
4361 Equivalent to \c {s1 != 0 && compare(s1, s2) == 0}.
4363 \sa QString::compare()
4367 \fn bool operator!=(const char *s1, const QString &s2)
4370 Returns true if \a s1 is not equal to \a s2; otherwise returns
4373 For \a s1 != 0, this is equivalent to \c {compare(} \a s1, \a s2
4374 \c {) != 0}. Note that no string is equal to \a s1 being 0.
4376 \sa QString::compare()
4380 \fn bool operator<(const char *s1, const QString &s2)
4383 Returns true if \a s1 is lexically less than \a s2; otherwise
4384 returns false. For \a s1 != 0, this is equivalent to \c
4385 {compare(s1, s2) < 0}.
4387 The comparison is based exclusively on the numeric Unicode values
4388 of the characters and is very fast, but is not what a human would
4389 expect. Consider sorting user-interface strings using the
4390 QString::localeAwareCompare() function.
4392 \sa QString::compare()
4396 \fn bool operator<=(const char *s1, const QString &s2)
4399 Returns true if \a s1 is lexically less than or equal to \a s2;
4400 otherwise returns false. For \a s1 != 0, this is equivalent to \c
4401 {compare(s1, s2) <= 0}.
4403 The comparison is based exclusively on the numeric Unicode values
4404 of the characters and is very fast, but is not what a human would
4405 expect. Consider sorting user-interface strings with
4406 QString::localeAwareCompare().
4408 \sa QString::compare()
4412 \fn bool operator>(const char *s1, const QString &s2)
4415 Returns true if \a s1 is lexically greater than \a s2; otherwise
4416 returns false. Equivalent to \c {compare(s1, s2) > 0}.
4418 The comparison is based exclusively on the numeric Unicode values
4419 of the characters and is very fast, but is not what a human would
4420 expect. Consider sorting user-interface strings using the
4421 QString::localeAwareCompare() function.
4423 \sa QString::compare()
4427 \fn bool operator>=(const char *s1, const QString &s2)
4430 Returns true if \a s1 is lexically greater than or equal to \a s2;
4431 otherwise returns false. For \a s1 != 0, this is equivalent to \c
4432 {compare(s1, s2) >= 0}.
4434 The comparison is based exclusively on the numeric Unicode values
4435 of the characters and is very fast, but is not what a human would
4436 expect. Consider sorting user-interface strings using the
4437 QString::localeAwareCompare() function.
4441 \fn const QString operator+(const QString &s1, const QString &s2)
4444 Returns a string which is the result of concatenating \a s1 and \a
4449 \fn const QString operator+(const QString &s1, const char *s2)
4452 Returns a string which is the result of concatenating \a s1 and \a
4453 s2 (\a s2 is converted to Unicode using the QString::fromAscii()
4456 \sa QString::fromAscii()
4460 \fn const QString operator+(const char *s1, const QString &s2)
4463 Returns a string which is the result of concatenating \a s1 and \a
4464 s2 (\a s1 is converted to Unicode using the QString::fromAscii()
4467 \sa QString::fromAscii()
4471 \fn const QString operator+(const QString &s, char ch)
4474 Returns a string which is the result of concatenating the string
4475 \a s and the character \a ch.
4479 \fn const QString operator+(char ch, const QString &s)
4482 Returns a string which is the result of concatenating the
4483 character \a ch and the string \a s.
4487 \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs)
4490 Compares \a s1 with \a s2 and returns an integer less than, equal
4491 to, or greater than zero if \a s1 is less than, equal to, or
4494 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
4495 otherwise the comparison is case insensitive.
4497 Case sensitive comparison is based exclusively on the numeric
4498 Unicode values of the characters and is very fast, but is not what
4499 a human would expect. Consider sorting user-visible strings with
4500 localeAwareCompare().
4502 \snippet doc/src/snippets/qstring/main.cpp 16
4504 \sa operator==(), operator<(), operator>()
4508 \fn int QString::compare(const QString &s1, const QLatin1String &s2, Qt::CaseSensitivity cs)
4512 Performs a comparison of \a s1 and \a s2, using the case
4513 sensitivity setting \a cs.
4517 \fn int QString::compare(const QLatin1String &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4522 Performs a comparison of \a s1 and \a s2, using the case
4523 sensitivity setting \a cs.
4531 Lexically compares this string with the \a other string and
4532 returns an integer less than, equal to, or greater than zero if
4533 this string is less than, equal to, or greater than the other
4536 Same as compare(*this, \a other, \a cs).
4538 int QString::compare(const QString &other, Qt::CaseSensitivity cs) const
4540 if (cs == Qt::CaseSensitive)
4541 return ucstrcmp(constData(), length(), other.constData(), other.length());
4542 return ucstricmp(d->data(), d->data() + d->size, other.d->data(), other.d->data() + other.d->size);
4549 int QString::compare_helper(const QChar *data1, int length1, const QChar *data2, int length2,
4550 Qt::CaseSensitivity cs)
4552 if (cs == Qt::CaseSensitive)
4553 return ucstrcmp(data1, length1, data2, length2);
4554 register const ushort *s1 = reinterpret_cast<const ushort *>(data1);
4555 register const ushort *s2 = reinterpret_cast<const ushort *>(data2);
4556 return ucstricmp(s1, s1 + length1, s2, s2 + length2);
4563 Same as compare(*this, \a other, \a cs).
4565 int QString::compare(const QLatin1String &other, Qt::CaseSensitivity cs) const
4567 return compare_helper(unicode(), length(), other, cs);
4571 \fn int QString::compare(const QStringRef &ref, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4574 Compares the string reference, \a ref, with the string and returns
4575 an integer less than, equal to, or greater than zero if the string
4576 is less than, equal to, or greater than \a ref.
4580 \fn int QString::compare(const QString &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4588 int QString::compare_helper(const QChar *data1, int length1, QLatin1String s2,
4589 Qt::CaseSensitivity cs)
4591 const ushort *uc = reinterpret_cast<const ushort *>(data1);
4592 const ushort *uce = uc + length1;
4593 const uchar *c = (uchar *)s2.latin1();
4598 if (cs == Qt::CaseSensitive) {
4599 const ushort *e = uc + length1;
4600 if (s2.size() < length1)
4603 int diff = *uc - *c;
4610 if (c == (const uchar *)s2.latin1() + s2.size())
4616 return ucstricmp(uc, uce, c, c + s2.size());
4621 \fn int QString::localeAwareCompare(const QString & s1, const QString & s2)
4623 Compares \a s1 with \a s2 and returns an integer less than, equal
4624 to, or greater than zero if \a s1 is less than, equal to, or
4627 The comparison is performed in a locale- and also
4628 platform-dependent manner. Use this function to present sorted
4629 lists of strings to the user.
4631 On Mac OS X since Qt 4.3, this function compares according the
4632 "Order for sorted lists" setting in the International prefereces panel.
4634 \sa compare(), QTextCodec::locale()
4638 \fn int QString::localeAwareCompare(const QStringRef &other) const
4640 \overload localeAwareCompare()
4642 Compares this string with the \a other string and returns an
4643 integer less than, equal to, or greater than zero if this string
4644 is less than, equal to, or greater than the \a other string.
4646 The comparison is performed in a locale- and also
4647 platform-dependent manner. Use this function to present sorted
4648 lists of strings to the user.
4650 Same as \c {localeAwareCompare(*this, other)}.
4654 \fn int QString::localeAwareCompare(const QString &s1, const QStringRef &s2)
4656 \overload localeAwareCompare()
4658 Compares \a s1 with \a s2 and returns an integer less than, equal
4659 to, or greater than zero if \a s1 is less than, equal to, or
4662 The comparison is performed in a locale- and also
4663 platform-dependent manner. Use this function to present sorted
4664 lists of strings to the user.
4668 #if !defined(CSTR_LESS_THAN)
4669 #define CSTR_LESS_THAN 1
4670 #define CSTR_EQUAL 2
4671 #define CSTR_GREATER_THAN 3
4675 \overload localeAwareCompare()
4677 Compares this string with the \a other string and returns an
4678 integer less than, equal to, or greater than zero if this string
4679 is less than, equal to, or greater than the \a other string.
4681 The comparison is performed in a locale- and also
4682 platform-dependent manner. Use this function to present sorted
4683 lists of strings to the user.
4685 Same as \c {localeAwareCompare(*this, other)}.
4687 int QString::localeAwareCompare(const QString &other) const
4689 return localeAwareCompare_helper(constData(), length(), other.constData(), other.length());
4696 int QString::localeAwareCompare_helper(const QChar *data1, int length1,
4697 const QChar *data2, int length2)
4699 // do the right thing for null and empty
4700 if (length1 == 0 || length2 == 0)
4701 return ucstrcmp(data1, length1, data2, length2);
4703 #if defined(Q_OS_WIN32) || defined(Q_OS_WINCE)
4704 int res = CompareString(GetUserDefaultLCID(), 0, (wchar_t*)data1, length1, (wchar_t*)data2, length2);
4707 case CSTR_LESS_THAN:
4709 case CSTR_GREATER_THAN:
4714 #elif defined (Q_OS_MAC)
4715 // Use CFStringCompare for comparing strings on Mac. This makes Qt order
4716 // strings the same way as native applications do, and also respects
4717 // the "Order for sorted lists" setting in the International preferences
4719 const CFStringRef thisString =
4720 CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
4721 reinterpret_cast<const UniChar *>(data1), length1, kCFAllocatorNull);
4722 const CFStringRef otherString =
4723 CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
4724 reinterpret_cast<const UniChar *>(data2), length2, kCFAllocatorNull);
4726 const int result = CFStringCompare(thisString, otherString, kCFCompareLocalized);
4727 CFRelease(thisString);
4728 CFRelease(otherString);
4730 #elif defined(Q_OS_UNIX)
4731 # if defined(QT_USE_ICU)
4733 if (qt_ucol_strcoll(data1, length1, data2, length2, &res)) {
4735 res = ucstrcmp(data1, length1, data2, length2);
4737 } // else fall through
4739 // declared in <string.h>
4740 int delta = strcoll(toLocal8Bit_helper(data1, length1), toLocal8Bit_helper(data2, length2));
4742 delta = ucstrcmp(data1, length1, data2, length2);
4745 return ucstrcmp(data1, length1, data2, length2);
4751 \fn const QChar *QString::unicode() const
4753 Returns a '\\0'-terminated Unicode representation of the string.
4754 The result remains valid until the string is modified.
4760 \fn const ushort *QString::utf16() const
4762 Returns the QString as a '\\0\'-terminated array of unsigned
4763 shorts. The result remains valid until the string is modified.
4765 The returned string is in host byte order.
4770 const ushort *QString::utf16() const
4773 const_cast<QString*>(this)->realloc(); // ensure '\\0'-termination for ::fromRawData strings
4778 Returns a string of size \a width that contains this string
4779 padded by the \a fill character.
4781 If \a truncate is false and the size() of the string is more than
4782 \a width, then the returned string is a copy of the string.
4784 \snippet doc/src/snippets/qstring/main.cpp 32
4786 If \a truncate is true and the size() of the string is more than
4787 \a width, then any characters in a copy of the string after
4788 position \a width are removed, and the copy is returned.
4790 \snippet doc/src/snippets/qstring/main.cpp 33
4792 \sa rightJustified()
4795 QString QString::leftJustified(int width, QChar fill, bool truncate) const
4799 int padlen = width - len;
4801 result.resize(len+padlen);
4803 memcpy(result.d->data(), d->data(), sizeof(QChar)*len);
4804 QChar *uc = (QChar*)result.d->data() + len;
4809 result = left(width);
4817 Returns a string of size() \a width that contains the \a fill
4818 character followed by the string. For example:
4820 \snippet doc/src/snippets/qstring/main.cpp 49
4822 If \a truncate is false and the size() of the string is more than
4823 \a width, then the returned string is a copy of the string.
4825 If \a truncate is true and the size() of the string is more than
4826 \a width, then the resulting string is truncated at position \a
4829 \snippet doc/src/snippets/qstring/main.cpp 50
4834 QString QString::rightJustified(int width, QChar fill, bool truncate) const
4838 int padlen = width - len;
4840 result.resize(len+padlen);
4841 QChar *uc = (QChar*)result.d->data();
4845 memcpy(uc, d->data(), sizeof(QChar)*len);
4848 result = left(width);
4856 Returns a lowercase copy of the string.
4858 \snippet doc/src/snippets/qstring/main.cpp 75
4860 The case conversion will always happen in the 'C' locale. For locale dependent
4861 case folding use QLocale::toLower()
4863 \sa toUpper(), QLocale::toLower()
4866 QString QString::toLower() const
4868 const ushort *p = d->data();
4874 const ushort *e = d->data() + d->size;
4876 // this avoids one out of bounds check in the loop
4877 if (QChar(*p).isLowSurrogate())
4882 if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4883 c = QChar::surrogateToUcs4(*(p - 1), c);
4884 const QUnicodeTables::Properties *prop = qGetProp(c);
4885 if (prop->lowerCaseDiff || prop->lowerCaseSpecial) {
4886 QString s(d->size, Qt::Uninitialized);
4887 memcpy(s.d->data(), d->data(), (p - d->data())*sizeof(ushort));
4888 ushort *pp = s.d->data() + (p - d->data());
4891 if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4892 c = QChar::surrogateToUcs4(*(p - 1), c);
4894 if (prop->lowerCaseSpecial) {
4895 int pos = pp - s.d->data();
4896 s.resize(s.d->size + SPECIAL_CASE_MAX_LEN);
4897 pp = s.d->data() + pos;
4898 const ushort *specialCase = specialCaseMap + prop->lowerCaseDiff;
4899 while (*specialCase)
4900 *pp++ = *specialCase++;
4902 *pp++ = *p + prop->lowerCaseDiff;
4906 s.truncate(pp - s.d->data());
4915 Returns the case folded equivalent of the string. For most Unicode
4916 characters this is the same as toLower().
4918 QString QString::toCaseFolded() const
4923 const ushort *p = d->data();
4927 const ushort *e = d->data() + d->size;
4931 ushort folded = foldCase(*p, last);
4935 ushort *pp = s.d->data() + (p - d->data());
4936 const ushort *ppe = s.d->data() + s.d->size;
4937 last = pp > s.d->data() ? *(pp - 1) : 0;
4939 *pp = foldCase(*pp, last);
4950 Returns an uppercase copy of the string.
4952 \snippet doc/src/snippets/qstring/main.cpp 81
4954 The case conversion will always happen in the 'C' locale. For locale dependent
4955 case folding use QLocale::toUpper()
4957 \sa toLower(), QLocale::toLower()
4960 QString QString::toUpper() const
4962 const ushort *p = d->data();
4968 const ushort *e = d->data() + d->size;
4970 // this avoids one out of bounds check in the loop
4971 if (QChar(*p).isLowSurrogate())
4976 if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4977 c = QChar::surrogateToUcs4(*(p - 1), c);
4978 const QUnicodeTables::Properties *prop = qGetProp(c);
4979 if (prop->upperCaseDiff || prop->upperCaseSpecial) {
4980 QString s(d->size, Qt::Uninitialized);
4981 memcpy(s.d->data(), d->data(), (p - d->data())*sizeof(ushort));
4982 ushort *pp = s.d->data() + (p - d->data());
4985 if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate())
4986 c = QChar::surrogateToUcs4(*(p - 1), c);
4988 if (prop->upperCaseSpecial) {
4989 int pos = pp - s.d->data();
4990 s.resize(s.d->size + SPECIAL_CASE_MAX_LEN);
4991 pp = s.d->data() + pos;
4992 const ushort *specialCase = specialCaseMap + prop->upperCaseDiff;
4993 while (*specialCase)
4994 *pp++ = *specialCase++;
4996 *pp++ = *p + prop->upperCaseDiff;
5000 s.truncate(pp - s.d->data());
5008 // ### Qt 5: Consider whether this function shouldn't be removed See task 202871.
5010 Safely builds a formatted string from the format string \a cformat
5011 and an arbitrary list of arguments.
5013 The %lc escape sequence expects a unicode character of type ushort
5014 (as returned by QChar::unicode()). The %ls escape sequence expects
5015 a pointer to a zero-terminated array of unicode characters of type
5016 ushort (as returned by QString::utf16()).
5018 \note This function expects a UTF-8 string for %s and Latin-1 for
5021 The format string supports most of the conversion specifiers
5022 provided by printf() in the standard C++ library. It doesn't
5023 honor the length modifiers (e.g. \c h for \c short, \c ll for
5024 \c{long long}). If you need those, use the standard snprintf()
5027 \snippet doc/src/snippets/qstring/main.cpp 63
5029 \warning We do not recommend using QString::sprintf() in new Qt
5030 code. Instead, consider using QTextStream or arg(), both of
5031 which support Unicode strings seamlessly and are type-safe.
5032 Here's an example that uses QTextStream:
5034 \snippet doc/src/snippets/qstring/main.cpp 64
5036 For \l {QObject::tr()}{translations}, especially if the strings
5037 contains more than one escape sequence, you should consider using
5038 the arg() function instead. This allows the order of the
5039 replacements to be controlled by the translator.
5044 QString &QString::sprintf(const char *cformat, ...)
5047 va_start(ap, cformat);
5048 QString &s = vsprintf(cformat, ap);
5054 Equivalent method to sprintf(), but takes a va_list \a ap
5055 instead a list of variable arguments. See the sprintf()
5056 documentation for an explanation of \a cformat.
5058 This method does not call the va_end macro, the caller
5059 is responsible to call va_end on \a ap.
5064 QString &QString::vsprintf(const char* cformat, va_list ap)
5066 QLocale locale(QLocale::C);
5068 if (!cformat || !*cformat) {
5070 *this = fromLatin1("");
5077 const char *c = cformat;
5079 // Copy non-escape chars to result
5080 #ifndef QT_NO_TEXTCODEC
5082 while (*(c + i) != '\0' && *(c + i) != '%')
5084 if (codecForCStrings)
5085 result.append(codecForCStrings->toUnicode(c, i));
5087 result.append(fromLatin1(c, i));
5090 while (*c != '\0' && *c != '%')
5091 result.append(QLatin1Char(*c++));
5098 const char *escape_start = c;
5102 result.append(QLatin1Char('%')); // a % at the end of the string - treat as non-escape text
5106 result.append(QLatin1Char('%')); // %%
5111 // Parse flag characters
5113 bool no_more_flags = false;
5116 case '#': flags |= QLocalePrivate::Alternate; break;
5117 case '0': flags |= QLocalePrivate::ZeroPadded; break;
5118 case '-': flags |= QLocalePrivate::LeftAdjusted; break;
5119 case ' ': flags |= QLocalePrivate::BlankBeforePositive; break;
5120 case '+': flags |= QLocalePrivate::AlwaysShowSign; break;
5121 case '\'': flags |= QLocalePrivate::ThousandsGroup; break;
5122 default: no_more_flags = true; break;
5127 } while (!no_more_flags);
5130 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5134 // Parse field width
5135 int width = -1; // -1 means unspecified
5138 while (*c != '\0' && qIsDigit(*c))
5139 width_str.append(QLatin1Char(*c++));
5141 // can't be negative - started with a digit
5142 // contains at least one digit
5143 width = width_str.toInt();
5145 else if (*c == '*') {
5146 width = va_arg(ap, int);
5148 width = -1; // treat all negative numbers as unspecified
5153 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5158 int precision = -1; // -1 means unspecified
5162 QString precision_str;
5163 while (*c != '\0' && qIsDigit(*c))
5164 precision_str.append(QLatin1Char(*c++));
5166 // can't be negative - started with a digit
5167 // contains at least one digit
5168 precision = precision_str.toInt();
5170 else if (*c == '*') {
5171 precision = va_arg(ap, int);
5173 precision = -1; // treat all negative numbers as unspecified
5179 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5183 // Parse the length modifier
5184 enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t };
5185 LengthMod length_mod = lm_none;
5232 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5236 // Parse the conversion specifier and do the conversion
5242 switch (length_mod) {
5243 case lm_none: i = va_arg(ap, int); break;
5244 case lm_hh: i = va_arg(ap, int); break;
5245 case lm_h: i = va_arg(ap, int); break;
5246 case lm_l: i = va_arg(ap, long int); break;
5247 case lm_ll: i = va_arg(ap, qint64); break;
5248 case lm_j: i = va_arg(ap, long int); break;
5249 case lm_z: i = va_arg(ap, size_t); break;
5250 case lm_t: i = va_arg(ap, int); break;
5251 default: i = 0; break;
5253 subst = locale.d()->longLongToString(i, precision, 10, width, flags);
5262 switch (length_mod) {
5263 case lm_none: u = va_arg(ap, uint); break;
5264 case lm_hh: u = va_arg(ap, uint); break;
5265 case lm_h: u = va_arg(ap, uint); break;
5266 case lm_l: u = va_arg(ap, ulong); break;
5267 case lm_ll: u = va_arg(ap, quint64); break;
5268 case lm_z: u = va_arg(ap, size_t); break;
5269 default: u = 0; break;
5273 flags |= QLocalePrivate::CapitalEorX;
5276 switch (qToLower(*c)) {
5285 subst = locale.d()->unsLongLongToString(u, precision, base, width, flags);
5298 if (length_mod == lm_L)
5299 d = va_arg(ap, long double); // not supported - converted to a double
5301 d = va_arg(ap, double);
5304 flags |= QLocalePrivate::CapitalEorX;
5306 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5307 switch (qToLower(*c)) {
5308 case 'e': form = QLocalePrivate::DFExponent; break;
5309 case 'a': // not supported - decimal form used instead
5310 case 'f': form = QLocalePrivate::DFDecimal; break;
5311 case 'g': form = QLocalePrivate::DFSignificantDigits; break;
5314 subst = locale.d()->doubleToString(d, precision, form, width, flags);
5319 if (length_mod == lm_l)
5320 subst = QChar((ushort) va_arg(ap, int));
5322 subst = QLatin1Char((uchar) va_arg(ap, int));
5327 if (length_mod == lm_l) {
5328 const ushort *buff = va_arg(ap, const ushort*);
5329 const ushort *ch = buff;
5332 subst.setUtf16(buff, ch - buff);
5334 subst = QString::fromUtf8(va_arg(ap, const char*));
5335 if (precision != -1)
5336 subst.truncate(precision);
5341 void *arg = va_arg(ap, void*);
5343 quint64 i = reinterpret_cast<quint64>(arg);
5345 quint64 i = reinterpret_cast<unsigned long>(arg);
5347 flags |= QLocalePrivate::Alternate;
5348 subst = locale.d()->unsLongLongToString(i, precision, 16, width, flags);
5353 switch (length_mod) {
5355 signed char *n = va_arg(ap, signed char*);
5356 *n = result.length();
5360 short int *n = va_arg(ap, short int*);
5361 *n = result.length();
5365 long int *n = va_arg(ap, long int*);
5366 *n = result.length();
5370 qint64 *n = va_arg(ap, qint64*);
5371 volatile uint tmp = result.length(); // egcs-2.91.66 gets internal
5372 *n = tmp; // compiler error without volatile
5376 int *n = va_arg(ap, int*);
5377 *n = result.length();
5384 default: // bad escape, treat as non-escape text
5385 for (const char *cc = escape_start; cc != c; ++cc)
5386 result.append(QLatin1Char(*cc));
5390 if (flags & QLocalePrivate::LeftAdjusted)
5391 result.append(subst.leftJustified(width));
5393 result.append(subst.rightJustified(width));
5402 Returns the string converted to a \c{long long} using base \a
5403 base, which is 10 by default and must be between 2 and 36, or 0.
5404 Returns 0 if the conversion fails.
5406 If a conversion error occurs, *\a{ok} is set to false; otherwise
5407 *\a{ok} is set to true.
5409 If \a base is 0, the C language convention is used: If the string
5410 begins with "0x", base 16 is used; if the string begins with "0",
5411 base 8 is used; otherwise, base 10 is used.
5413 The string conversion will always happen in the 'C' locale. For locale
5414 dependent conversion use QLocale::toLongLong()
5418 \snippet doc/src/snippets/qstring/main.cpp 74
5420 \sa number(), toULongLong(), toInt(), QLocale::toLongLong()
5423 qint64 QString::toLongLong(bool *ok, int base) const
5425 #if defined(QT_CHECK_RANGE)
5426 if (base != 0 && (base < 2 || base > 36)) {
5427 qWarning("QString::toLongLong: Invalid base (%d)", base);
5432 QLocale c_locale(QLocale::C);
5433 return c_locale.d()->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5437 Returns the string converted to an \c{unsigned long long} using base \a
5438 base, which is 10 by default and must be between 2 and 36, or 0.
5439 Returns 0 if the conversion fails.
5441 If a conversion error occurs, *\a{ok} is set to false; otherwise
5442 *\a{ok} is set to true.
5444 If \a base is 0, the C language convention is used: If the string
5445 begins with "0x", base 16 is used; if the string begins with "0",
5446 base 8 is used; otherwise, base 10 is used.
5448 The string conversion will always happen in the 'C' locale. For locale
5449 dependent conversion use QLocale::toULongLong()
5453 \snippet doc/src/snippets/qstring/main.cpp 79
5455 \sa number(), toLongLong(), QLocale::toULongLong()
5458 quint64 QString::toULongLong(bool *ok, int base) const
5460 #if defined(QT_CHECK_RANGE)
5461 if (base != 0 && (base < 2 || base > 36)) {
5462 qWarning("QString::toULongLong: Invalid base (%d)", base);
5467 QLocale c_locale(QLocale::C);
5468 return c_locale.d()->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5472 \fn long QString::toLong(bool *ok, int base) const
5474 Returns the string converted to a \c long using base \a
5475 base, which is 10 by default and must be between 2 and 36, or 0.
5476 Returns 0 if the conversion fails.
5478 If a conversion error occurs, *\a{ok} is set to false; otherwise
5479 *\a{ok} is set to true.
5481 If \a base is 0, the C language convention is used: If the string
5482 begins with "0x", base 16 is used; if the string begins with "0",
5483 base 8 is used; otherwise, base 10 is used.
5485 The string conversion will always happen in the 'C' locale. For locale
5486 dependent conversion use QLocale::toLong()
5490 \snippet doc/src/snippets/qstring/main.cpp 73
5492 \sa number(), toULong(), toInt(), QLocale::toLong()
5495 long QString::toLong(bool *ok, int base) const
5497 qint64 v = toLongLong(ok, base);
5498 if (v < LONG_MIN || v > LONG_MAX) {
5507 \fn ulong QString::toULong(bool *ok, int base) const
5509 Returns the string converted to an \c{unsigned long} using base \a
5510 base, which is 10 by default and must be between 2 and 36, or 0.
5511 Returns 0 if the conversion fails.
5513 If a conversion error occurs, *\a{ok} is set to false; otherwise
5514 *\a{ok} is set to true.
5516 If \a base is 0, the C language convention is used: If the string
5517 begins with "0x", base 16 is used; if the string begins with "0",
5518 base 8 is used; otherwise, base 10 is used.
5520 The string conversion will always happen in the 'C' locale. For locale
5521 dependent conversion use QLocale::toULong()
5525 \snippet doc/src/snippets/qstring/main.cpp 78
5527 \sa number(), QLocale::toULong()
5530 ulong QString::toULong(bool *ok, int base) const
5532 quint64 v = toULongLong(ok, base);
5533 if (v > ULONG_MAX) {
5543 Returns the string converted to an \c int using base \a
5544 base, which is 10 by default and must be between 2 and 36, or 0.
5545 Returns 0 if the conversion fails.
5547 If a conversion error occurs, *\a{ok} is set to false; otherwise
5548 *\a{ok} is set to true.
5550 If \a base is 0, the C language convention is used: If the string
5551 begins with "0x", base 16 is used; if the string begins with "0",
5552 base 8 is used; otherwise, base 10 is used.
5554 The string conversion will always happen in the 'C' locale. For locale
5555 dependent conversion use QLocale::toInt()
5559 \snippet doc/src/snippets/qstring/main.cpp 72
5561 \sa number(), toUInt(), toDouble(), QLocale::toInt()
5564 int QString::toInt(bool *ok, int base) const
5566 qint64 v = toLongLong(ok, base);
5567 if (v < INT_MIN || v > INT_MAX) {
5576 Returns the string converted to an \c{unsigned int} using base \a
5577 base, which is 10 by default and must be between 2 and 36, or 0.
5578 Returns 0 if the conversion fails.
5580 If a conversion error occurs, *\a{ok} is set to false; otherwise
5581 *\a{ok} is set to true.
5583 If \a base is 0, the C language convention is used: If the string
5584 begins with "0x", base 16 is used; if the string begins with "0",
5585 base 8 is used; otherwise, base 10 is used.
5587 The string conversion will always happen in the 'C' locale. For locale
5588 dependent conversion use QLocale::toUInt()
5592 \snippet doc/src/snippets/qstring/main.cpp 77
5594 \sa number(), toInt(), QLocale::toUInt()
5597 uint QString::toUInt(bool *ok, int base) const
5599 quint64 v = toULongLong(ok, base);
5609 Returns the string converted to a \c short using base \a
5610 base, which is 10 by default and must be between 2 and 36, or 0.
5611 Returns 0 if the conversion fails.
5613 If a conversion error occurs, *\a{ok} is set to false; otherwise
5614 *\a{ok} is set to true.
5616 If \a base is 0, the C language convention is used: If the string
5617 begins with "0x", base 16 is used; if the string begins with "0",
5618 base 8 is used; otherwise, base 10 is used.
5620 The string conversion will always happen in the 'C' locale. For locale
5621 dependent conversion use QLocale::toShort()
5625 \snippet doc/src/snippets/qstring/main.cpp 76
5627 \sa number(), toUShort(), toInt(), QLocale::toShort()
5630 short QString::toShort(bool *ok, int base) const
5632 long v = toLongLong(ok, base);
5633 if (v < SHRT_MIN || v > SHRT_MAX) {
5642 Returns the string converted to an \c{unsigned short} using base \a
5643 base, which is 10 by default and must be between 2 and 36, or 0.
5644 Returns 0 if the conversion fails.
5646 If a conversion error occurs, *\a{ok} is set to false; otherwise
5647 *\a{ok} is set to true.
5649 If \a base is 0, the C language convention is used: If the string
5650 begins with "0x", base 16 is used; if the string begins with "0",
5651 base 8 is used; otherwise, base 10 is used.
5653 The string conversion will always happen in the 'C' locale. For locale
5654 dependent conversion use QLocale::toUShort()
5658 \snippet doc/src/snippets/qstring/main.cpp 80
5660 \sa number(), toShort(), QLocale::toUShort()
5663 ushort QString::toUShort(bool *ok, int base) const
5665 ulong v = toULongLong(ok, base);
5666 if (v > USHRT_MAX) {
5676 Returns the string converted to a \c double value.
5678 Returns 0.0 if the conversion fails.
5680 If a conversion error occurs, \c{*}\a{ok} is set to false;
5681 otherwise \c{*}\a{ok} is set to true.
5683 \snippet doc/src/snippets/qstring/main.cpp 66
5685 Various string formats for floating point numbers can be converted
5688 \snippet doc/src/snippets/qstring/main.cpp 67
5690 The string conversion will always happen in the 'C' locale. For locale
5691 dependent conversion use QLocale::toDouble()
5693 \snippet doc/src/snippets/qstring/main.cpp 68
5695 For historic reasons, this function does not handle
5696 thousands group separators. If you need to convert such numbers,
5697 use QLocale::toDouble().
5699 \snippet doc/src/snippets/qstring/main.cpp 69
5701 \sa number() QLocale::setDefault() QLocale::toDouble() trimmed()
5704 double QString::toDouble(bool *ok) const
5706 QLocale c_locale(QLocale::C);
5707 return c_locale.d()->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators);
5711 Returns the string converted to a \c float value.
5713 If a conversion error occurs, *\a{ok} is set to false; otherwise
5714 *\a{ok} is set to true. Returns 0.0 if the conversion fails.
5716 The string conversion will always happen in the 'C' locale. For locale
5717 dependent conversion use QLocale::toFloat()
5721 \snippet doc/src/snippets/qstring/main.cpp 71
5723 \sa number(), toDouble(), toInt(), QLocale::toFloat()
5726 #define QT_MAX_FLOAT 3.4028234663852886e+38
5728 float QString::toFloat(bool *ok) const
5731 double d = toDouble(&myOk);
5732 if (!myOk || d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) {
5742 /*! \fn QString &QString::setNum(int n, int base)
5744 Sets the string to the printed value of \a n in the specified \a
5745 base, and returns a reference to the string.
5747 The base is 10 by default and must be between 2 and 36. For bases
5748 other than 10, \a n is treated as an unsigned integer.
5750 \snippet doc/src/snippets/qstring/main.cpp 56
5752 The formatting always uses QLocale::C, i.e., English/UnitedStates.
5753 To get a localized string representation of a number, use
5754 QLocale::toString() with the appropriate locale.
5757 /*! \fn QString &QString::setNum(uint n, int base)
5762 /*! \fn QString &QString::setNum(long n, int base)
5767 /*! \fn QString &QString::setNum(ulong n, int base)
5775 QString &QString::setNum(qlonglong n, int base)
5777 #if defined(QT_CHECK_RANGE)
5778 if (base < 2 || base > 36) {
5779 qWarning("QString::setNum: Invalid base (%d)", base);
5783 QLocale locale(QLocale::C);
5784 *this = locale.d()->longLongToString(n, -1, base);
5791 QString &QString::setNum(qulonglong n, int base)
5793 #if defined(QT_CHECK_RANGE)
5794 if (base < 2 || base > 36) {
5795 qWarning("QString::setNum: Invalid base (%d)", base);
5799 QLocale locale(QLocale::C);
5800 *this = locale.d()->unsLongLongToString(n, -1, base);
5804 /*! \fn QString &QString::setNum(short n, int base)
5809 /*! \fn QString &QString::setNum(ushort n, int base)
5815 \fn QString &QString::setNum(double n, char format, int precision)
5818 Sets the string to the printed value of \a n, formatted according
5819 to the given \a format and \a precision, and returns a reference
5822 The \a format can be 'f', 'F', 'e', 'E', 'g' or 'G' (see the
5823 arg() function documentation for an explanation of the formats).
5825 The formatting always uses QLocale::C, i.e., English/UnitedStates.
5826 To get a localized string representation of a number, use
5827 QLocale::toString() with the appropriate locale.
5830 QString &QString::setNum(double n, char f, int prec)
5832 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5836 flags = QLocalePrivate::CapitalEorX;
5841 form = QLocalePrivate::DFDecimal;
5844 form = QLocalePrivate::DFExponent;
5847 form = QLocalePrivate::DFSignificantDigits;
5850 #if defined(QT_CHECK_RANGE)
5851 qWarning("QString::setNum: Invalid format char '%c'", f);
5856 QLocale locale(QLocale::C);
5857 *this = locale.d()->doubleToString(n, prec, form, -1, flags);
5862 \fn QString &QString::setNum(float n, char format, int precision)
5865 Sets the string to the printed value of \a n, formatted according
5866 to the given \a format and \a precision, and returns a reference
5869 The formatting always uses QLocale::C, i.e., English/UnitedStates.
5870 To get a localized string representation of a number, use
5871 QLocale::toString() with the appropriate locale.
5876 \fn QString QString::number(long n, int base)
5878 Returns a string equivalent of the number \a n according to the
5881 The base is 10 by default and must be between 2
5882 and 36. For bases other than 10, \a n is treated as an
5885 The formatting always uses QLocale::C, i.e., English/UnitedStates.
5886 To get a localized string representation of a number, use
5887 QLocale::toString() with the appropriate locale.
5889 \snippet doc/src/snippets/qstring/main.cpp 35
5894 QString QString::number(long n, int base)
5902 \fn QString QString::number(ulong n, int base)
5906 QString QString::number(ulong n, int base)
5916 QString QString::number(int n, int base)
5926 QString QString::number(uint n, int base)
5936 QString QString::number(qlonglong n, int base)
5946 QString QString::number(qulonglong n, int base)
5955 \fn QString QString::number(double n, char format, int precision)
5957 Returns a string equivalent of the number \a n, formatted
5958 according to the specified \a format and \a precision. See
5959 \l{Argument Formats} for details.
5961 Unlike QLocale::toString(), this function does not honor the
5962 user's locale settings.
5964 \sa setNum(), QLocale::toString()
5966 QString QString::number(double n, char f, int prec)
5969 s.setNum(n, f, prec);
5974 Splits the string into substrings wherever \a sep occurs, and
5975 returns the list of those strings. If \a sep does not match
5976 anywhere in the string, split() returns a single-element list
5977 containing this string.
5979 \a cs specifies whether \a sep should be matched case
5980 sensitively or case insensitively.
5982 If \a behavior is QString::SkipEmptyParts, empty entries don't
5983 appear in the result. By default, empty entries are kept.
5987 \snippet doc/src/snippets/qstring/main.cpp 62
5989 \sa QStringList::join(), section()
5991 QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
5997 while ((end = indexOf(sep, start + extra, cs)) != -1) {
5998 if (start != end || behavior == KeepEmptyParts)
5999 list.append(mid(start, end - start));
6000 start = end + sep.size();
6001 extra = (sep.size() == 0 ? 1 : 0);
6003 if (start != size() || behavior == KeepEmptyParts)
6004 list.append(mid(start));
6011 QStringList QString::split(QChar sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6016 while ((end = indexOf(sep, start, cs)) != -1) {
6017 if (start != end || behavior == KeepEmptyParts)
6018 list.append(mid(start, end - start));
6021 if (start != size() || behavior == KeepEmptyParts)
6022 list.append(mid(start));
6026 #ifndef QT_NO_REGEXP
6030 Splits the string into substrings wherever the regular expression
6031 \a rx matches, and returns the list of those strings. If \a rx
6032 does not match anywhere in the string, split() returns a
6033 single-element list containing this string.
6035 Here's an example where we extract the words in a sentence
6036 using one or more whitespace characters as the separator:
6038 \snippet doc/src/snippets/qstring/main.cpp 59
6040 Here's a similar example, but this time we use any sequence of
6041 non-word characters as the separator:
6043 \snippet doc/src/snippets/qstring/main.cpp 60
6045 Here's a third example where we use a zero-length assertion,
6046 \bold{\\b} (word boundary), to split the string into an
6047 alternating sequence of non-word and word tokens:
6049 \snippet doc/src/snippets/qstring/main.cpp 61
6051 \sa QStringList::join(), section()
6053 QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const
6060 while ((end = rx2.indexIn(*this, start + extra)) != -1) {
6061 int matchedLen = rx2.matchedLength();
6062 if (start != end || behavior == KeepEmptyParts)
6063 list.append(mid(start, end - start));
6064 start = end + matchedLen;
6065 extra = (matchedLen == 0) ? 1 : 0;
6067 if (start != size() || behavior == KeepEmptyParts)
6068 list.append(mid(start));
6074 \enum QString::NormalizationForm
6076 This enum describes the various normalized forms of Unicode text.
6078 \value NormalizationForm_D Canonical Decomposition
6079 \value NormalizationForm_C Canonical Decomposition followed by Canonical Composition
6080 \value NormalizationForm_KD Compatibility Decomposition
6081 \value NormalizationForm_KC Compatibility Decomposition followed by Canonical Composition
6084 {http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15}
6088 \fn QString QString::normalized(NormalizationForm mode) const
6089 Returns the string in the given Unicode normalization \a mode.
6091 QString QString::normalized(QString::NormalizationForm mode) const
6093 return normalized(mode, UNICODE_DATA_VERSION);
6099 Returns a copy of this string repeated the specified number of \a times.
6101 If \a times is less than 1, an empty string is returned.
6107 str.repeated(4); // returns "abababab"
6110 QString QString::repeated(int times) const
6121 const int resultSize = times * d->size;
6124 result.reserve(resultSize);
6125 if (int(result.d->alloc) != resultSize)
6126 return QString(); // not enough memory
6128 memcpy(result.d->data(), d->data(), d->size * sizeof(ushort));
6130 int sizeSoFar = d->size;
6131 ushort *end = result.d->data() + sizeSoFar;
6133 const int halfResultSize = resultSize >> 1;
6134 while (sizeSoFar <= halfResultSize) {
6135 memcpy(end, result.d->data(), sizeSoFar * sizeof(ushort));
6139 memcpy(end, result.d->data(), (resultSize - sizeSoFar) * sizeof(ushort));
6140 result.d->data()[resultSize] = '\0';
6141 result.d->size = resultSize;
6145 void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from);
6148 \fn QString QString::normalized(NormalizationForm mode, QChar::UnicodeVersion version) const
6150 Returns the string in the given Unicode normalization \a mode,
6151 according to the given \a version of the Unicode standard.
6153 QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const
6155 QString copy = *this;
6156 qt_string_normalize(©, mode, version, 0);
6160 void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from)
6163 const QChar *p = data->constData();
6164 int len = data->length();
6165 for (int i = from; i < len; ++i) {
6166 if (p[i].unicode() >= 0x80) {
6174 if (version == QChar::Unicode_Unassigned) {
6175 version = UNICODE_DATA_VERSION;
6176 } else if (version != UNICODE_DATA_VERSION) {
6177 const QString &s = *data;
6179 for (int i = 0; i < NumNormalizationCorrections; ++i) {
6180 const NormalizationCorrection &n = uc_normalization_corrections[i];
6181 if (n.version > version) {
6183 if (QChar::requiresSurrogates(n.ucs4)) {
6184 ushort ucs4High = QChar::highSurrogate(n.ucs4);
6185 ushort ucs4Low = QChar::lowSurrogate(n.ucs4);
6186 ushort oldHigh = QChar::highSurrogate(n.old_mapping);
6187 ushort oldLow = QChar::lowSurrogate(n.old_mapping);
6188 while (pos < s.length() - 1) {
6189 if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) {
6192 d[pos] = QChar(oldHigh);
6193 d[++pos] = QChar(oldLow);
6198 while (pos < s.length()) {
6199 if (s.at(pos).unicode() == n.ucs4) {
6202 d[pos] = QChar(n.old_mapping);
6210 decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from);
6212 canonicalOrderHelper(data, version, from);
6214 if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD)
6217 composeHelper(data, version, from);
6221 struct ArgEscapeData
6223 int min_escape; // lowest escape sequence number
6224 int occurrences; // number of occurrences of the lowest escape sequence number
6225 int locale_occurrences; // number of occurrences of the lowest escape sequence number that
6227 int escape_len; // total length of escape sequences which will be replaced
6230 static ArgEscapeData findArgEscapes(const QString &s)
6232 const QChar *uc_begin = s.unicode();
6233 const QChar *uc_end = uc_begin + s.length();
6237 d.min_escape = INT_MAX;
6240 d.locale_occurrences = 0;
6242 const QChar *c = uc_begin;
6243 while (c != uc_end) {
6244 while (c != uc_end && c->unicode() != '%')
6249 const QChar *escape_start = c;
6253 bool locale_arg = false;
6254 if (c->unicode() == 'L') {
6260 if (c->digitValue() == -1)
6263 int escape = c->digitValue();
6266 if (c != uc_end && c->digitValue() != -1) {
6267 escape = (10 * escape) + c->digitValue();
6271 if (escape > d.min_escape)
6274 if (escape < d.min_escape) {
6275 d.min_escape = escape;
6278 d.locale_occurrences = 0;
6283 ++d.locale_occurrences;
6284 d.escape_len += c - escape_start;
6289 static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width,
6290 const QString &arg, const QString &larg, QChar fillChar = QLatin1Char(' '))
6292 const QChar *uc_begin = s.unicode();
6293 const QChar *uc_end = uc_begin + s.length();
6295 int abs_field_width = qAbs(field_width);
6296 int result_len = s.length()
6298 + (d.occurrences - d.locale_occurrences)
6299 *qMax(abs_field_width, arg.length())
6300 + d.locale_occurrences
6301 *qMax(abs_field_width, larg.length());
6303 QString result(result_len, Qt::Uninitialized);
6304 QChar *result_buff = (QChar*) result.unicode();
6306 QChar *rc = result_buff;
6307 const QChar *c = uc_begin;
6309 while (c != uc_end) {
6310 /* We don't have to check if we run off the end of the string with c,
6311 because as long as d.occurrences > 0 we KNOW there are valid escape
6314 const QChar *text_start = c;
6316 while (c->unicode() != '%')
6319 const QChar *escape_start = c++;
6321 bool locale_arg = false;
6322 if (c->unicode() == 'L') {
6327 int escape = c->digitValue();
6329 if (c + 1 != uc_end && (c + 1)->digitValue() != -1) {
6330 escape = (10 * escape) + (c + 1)->digitValue();
6335 if (escape != d.min_escape) {
6336 memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
6337 rc += c - text_start;
6342 memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
6343 rc += escape_start - text_start;
6347 pad_chars = qMax(abs_field_width, larg.length()) - larg.length();
6349 pad_chars = qMax(abs_field_width, arg.length()) - arg.length();
6351 if (field_width > 0) { // left padded
6352 for (uint i = 0; i < pad_chars; ++i)
6353 (rc++)->unicode() = fillChar.unicode();
6357 memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar));
6358 rc += larg.length();
6361 memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar));
6365 if (field_width < 0) { // right padded
6366 for (uint i = 0; i < pad_chars; ++i)
6367 (rc++)->unicode() = fillChar.unicode();
6370 if (++repl_cnt == d.occurrences) {
6371 memcpy(rc, c, (uc_end - c)*sizeof(QChar));
6373 Q_ASSERT(rc - result_buff == result_len);
6378 Q_ASSERT(rc == result_buff + result_len);
6384 Returns a copy of this string with the lowest numbered place marker
6385 replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
6387 \a fieldWidth specifies the minimum amount of space that argument \a
6388 a shall occupy. If \a a requires less space than \a fieldWidth, it
6389 is padded to \a fieldWidth with character \a fillChar. A positive
6390 \a fieldWidth produces right-aligned text. A negative \a fieldWidth
6391 produces left-aligned text.
6393 This example shows how we might create a \c status string for
6394 reporting progress while processing a list of files:
6396 \snippet doc/src/snippets/qstring/main.cpp 11
6398 First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
6399 %2. Finally, \c arg(fileName) replaces \c %3.
6401 One advantage of using arg() over sprintf() is that the order of the
6402 numbered place markers can change, if the application's strings are
6403 translated into other languages, but each arg() will still replace
6404 the lowest numbered unreplaced place marker, no matter where it
6405 appears. Also, if place marker \c %i appears more than once in the
6406 string, the arg() replaces all of them.
6408 If there is no unreplaced place marker remaining, a warning message
6409 is output and the result is undefined. Place marker numbers must be
6410 in the range 1 to 99.
6412 QString QString::arg(const QString &a, int fieldWidth, QChar fillChar) const
6414 ArgEscapeData d = findArgEscapes(*this);
6416 if (d.occurrences == 0) {
6417 qWarning("QString::arg: Argument missing: %s, %s", toLocal8Bit().data(),
6418 a.toLocal8Bit().data());
6421 return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar);
6425 \fn QString QString::arg(const QString& a1, const QString& a2) const
6428 This is the same as \c {str.arg(a1).arg(a2)}, except that the
6429 strings \a a1 and \a a2 are replaced in one pass. This can make a
6430 difference if \a a1 contains e.g. \c{%1}:
6432 \snippet doc/src/snippets/qstring/main.cpp 13
6436 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const
6439 This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except
6440 that the strings \a a1, \a a2 and \a a3 are replaced in one pass.
6444 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const
6447 This is the same as calling \c
6448 {str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a
6449 a1, \a a2, \a a3 and \a a4 are replaced in one pass.
6453 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const
6456 This is the same as calling \c
6457 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings
6458 \a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass.
6462 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const
6465 This is the same as calling \c
6466 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that
6467 the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are
6468 replaced in one pass.
6472 \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
6475 This is the same as calling \c
6476 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)},
6477 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6,
6478 and \a a7 are replaced in one pass.
6482 \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
6485 This is the same as calling \c
6486 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)},
6487 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6488 a7, and \a a8 are replaced in one pass.
6492 \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
6495 This is the same as calling \c
6496 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)},
6497 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6498 a7, \a a8, and \a a9 are replaced in one pass.
6501 /*! \fn QString QString::arg(int a, int fieldWidth, int base, QChar fillChar) const
6504 The \a a argument is expressed in base \a base, which is 10 by
6505 default and must be between 2 and 36. For bases other than 10, \a a
6506 is treated as an unsigned integer.
6508 \a fieldWidth specifies the minimum amount of space that \a a is
6509 padded to and filled with the character \a fillChar. A positive
6510 value produces right-aligned text; a negative value produces
6513 The '%' can be followed by an 'L', in which case the sequence is
6514 replaced with a localized representation of \a a. The conversion
6515 uses the default locale, set by QLocale::setDefault(). If no default
6516 locale was specified, the "C" locale is used. The 'L' flag is
6517 ignored if \a base is not 10.
6519 \snippet doc/src/snippets/qstring/main.cpp 12
6520 \snippet doc/src/snippets/qstring/main.cpp 14
6522 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6523 used. For negative numbers, zero padding might appear before the
6527 /*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const
6530 The \a base argument specifies the base to use when converting the
6531 integer \a a into a string. The base must be between 2 and 36.
6533 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6534 used. For negative numbers, zero padding might appear before the
6538 /*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const
6541 \a fieldWidth specifies the minimum amount of space that \a a is
6542 padded to and filled with the character \a fillChar. A positive
6543 value produces right-aligned text; a negative value produces
6546 The \a a argument is expressed in the given \a base, which is 10 by
6547 default and must be between 2 and 36.
6549 The '%' can be followed by an 'L', in which case the sequence is
6550 replaced with a localized representation of \a a. The conversion
6551 uses the default locale. The default locale is determined from the
6552 system's locale settings at application startup. It can be changed
6553 using QLocale::setDefault(). The 'L' flag is ignored if \a base is
6556 \snippet doc/src/snippets/qstring/main.cpp 12
6557 \snippet doc/src/snippets/qstring/main.cpp 14
6559 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6560 used. For negative numbers, zero padding might appear before the
6564 /*! \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
6567 \a fieldWidth specifies the minimum amount of space that \a a is
6568 padded to and filled with the character \a fillChar. A positive
6569 value produces right-aligned text; a negative value produces
6572 The \a base argument specifies the base to use when converting the
6573 integer \a a to a string. The base must be between 2 and 36, with 8
6574 giving octal, 10 decimal, and 16 hexadecimal numbers.
6576 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6577 used. For negative numbers, zero padding might appear before the
6584 \a fieldWidth specifies the minimum amount of space that \a a is
6585 padded to and filled with the character \a fillChar. A positive
6586 value produces right-aligned text; a negative value produces
6589 The \a base argument specifies the base to use when converting the
6590 integer \a a into a string. The base must be between 2 and 36, with
6591 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6593 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6594 used. For negative numbers, zero padding might appear before the
6597 QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const
6599 ArgEscapeData d = findArgEscapes(*this);
6601 if (d.occurrences == 0) {
6602 qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6606 unsigned flags = QLocalePrivate::NoFlags;
6607 if (fillChar == QLatin1Char('0'))
6608 flags = QLocalePrivate::ZeroPadded;
6611 if (d.occurrences > d.locale_occurrences)
6612 arg = QLocale::c().d()->longLongToString(a, -1, base, fieldWidth, flags);
6615 if (d.locale_occurrences > 0) {
6617 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6618 flags |= QLocalePrivate::ThousandsGroup;
6619 locale_arg = locale.d()->longLongToString(a, -1, base, fieldWidth, flags);
6622 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6628 \a fieldWidth specifies the minimum amount of space that \a a is
6629 padded to and filled with the character \a fillChar. A positive
6630 value produces right-aligned text; a negative value produces
6633 The \a base argument specifies the base to use when converting the
6634 integer \a a into a string. \a base must be between 2 and 36, with 8
6635 giving octal, 10 decimal, and 16 hexadecimal numbers.
6637 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6638 used. For negative numbers, zero padding might appear before the
6641 QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const
6643 ArgEscapeData d = findArgEscapes(*this);
6645 if (d.occurrences == 0) {
6646 qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6650 unsigned flags = QLocalePrivate::NoFlags;
6651 if (fillChar == QLatin1Char('0'))
6652 flags = QLocalePrivate::ZeroPadded;
6655 if (d.occurrences > d.locale_occurrences)
6656 arg = QLocale::c().d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6659 if (d.locale_occurrences > 0) {
6661 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6662 flags |= QLocalePrivate::ThousandsGroup;
6663 locale_arg = locale.d()->unsLongLongToString(a, -1, base, fieldWidth, flags);
6666 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6672 \fn QString QString::arg(short a, int fieldWidth, int base, QChar fillChar) const
6674 \a fieldWidth specifies the minimum amount of space that \a a is
6675 padded to and filled with the character \a fillChar. A positive
6676 value produces right-aligned text; a negative value produces
6679 The \a base argument specifies the base to use when converting the
6680 integer \a a into a string. The base must be between 2 and 36, with
6681 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6683 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6684 used. For negative numbers, zero padding might appear before the
6689 \fn QString QString::arg(ushort a, int fieldWidth, int base, QChar fillChar) const
6692 \a fieldWidth specifies the minimum amount of space that \a a is
6693 padded to and filled with the character \a fillChar. A positive
6694 value produces right-aligned text; a negative value produces
6697 The \a base argument specifies the base to use when converting the
6698 integer \a a into a string. The base must be between 2 and 36, with
6699 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6701 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6702 used. For negative numbers, zero padding might appear before the
6709 QString QString::arg(QChar a, int fieldWidth, QChar fillChar) const
6713 return arg(c, fieldWidth, fillChar);
6719 The \a a argument is interpreted as a Latin-1 character.
6721 QString QString::arg(char a, int fieldWidth, QChar fillChar) const
6724 c += QLatin1Char(a);
6725 return arg(c, fieldWidth, fillChar);
6729 \fn QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
6732 Argument \a a is formatted according to the specified \a format and
6733 \a precision. See \l{Argument Formats} for details.
6735 \a fieldWidth specifies the minimum amount of space that \a a is
6736 padded to and filled with the character \a fillChar. A positive
6737 value produces right-aligned text; a negative value produces
6740 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 2
6742 The '%' can be followed by an 'L', in which case the sequence is
6743 replaced with a localized representation of \a a. The conversion
6744 uses the default locale, set by QLocale::setDefaultLocale(). If no
6745 default locale was specified, the "C" locale is used.
6747 If \a fillChar is '0' (the number 0, ASCII 48), this function will
6748 use the locale's zero to pad. For negative numbers, the zero padding
6749 will probably appear before the minus sign.
6751 \sa QLocale::toString()
6753 QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillChar) const
6755 ArgEscapeData d = findArgEscapes(*this);
6757 if (d.occurrences == 0) {
6758 qWarning("QString::arg: Argument missing: %s, %g", toLocal8Bit().data(), a);
6762 unsigned flags = QLocalePrivate::NoFlags;
6763 if (fillChar == QLatin1Char('0'))
6764 flags = QLocalePrivate::ZeroPadded;
6767 flags |= QLocalePrivate::CapitalEorX;
6768 fmt = qToLower(fmt);
6770 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
6773 form = QLocalePrivate::DFDecimal;
6776 form = QLocalePrivate::DFExponent;
6779 form = QLocalePrivate::DFSignificantDigits;
6782 #if defined(QT_CHECK_RANGE)
6783 qWarning("QString::arg: Invalid format char '%c'", fmt);
6789 if (d.occurrences > d.locale_occurrences)
6790 arg = QLocale::c().d()->doubleToString(a, prec, form, fieldWidth, flags);
6793 if (d.locale_occurrences > 0) {
6796 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6797 flags |= QLocalePrivate::ThousandsGroup;
6798 locale_arg = locale.d()->doubleToString(a, prec, form, fieldWidth, flags);
6801 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6804 static int getEscape(const QChar *uc, int *pos, int len, int maxNumber = 999)
6808 if (i < len && uc[i] == QLatin1Char('L'))
6811 int escape = uc[i].unicode() - '0';
6812 if (uint(escape) >= 10U)
6816 int digit = uc[i].unicode() - '0';
6817 if (uint(digit) >= 10U)
6819 escape = (escape * 10) + digit;
6822 if (escape <= maxNumber) {
6830 QString QString::multiArg(int numArgs, const QString **args) const
6833 QMap<int, int> numbersUsed;
6834 const QChar *uc = (const QChar *) d->data();
6835 const int len = d->size;
6836 const int end = len - 1;
6837 int lastNumber = -1;
6840 // populate the numbersUsed map with the %n's that actually occur in the string
6842 if (uc[i] == QLatin1Char('%')) {
6843 int number = getEscape(uc, &i, len);
6845 numbersUsed.insert(number, -1);
6852 // assign an argument number to each of the %n's
6853 QMap<int, int>::iterator j = numbersUsed.begin();
6854 QMap<int, int>::iterator jend = numbersUsed.end();
6856 while (j != jend && arg < numArgs) {
6858 lastNumber = j.key();
6863 if (numArgs > arg) {
6864 qWarning("QString::arg: %d argument(s) missing in %s", numArgs - arg, toLocal8Bit().data());
6870 if (uc[i] == QLatin1Char('%') && i != end) {
6871 int number = getEscape(uc, &i, len, lastNumber);
6872 int arg = numbersUsed[number];
6873 if (number != -1 && arg != -1) {
6874 result += *args[arg];
6884 /*! \fn bool QString::isSimpleText() const
6888 bool QString::isSimpleText() const
6890 const ushort *p = d->data();
6891 const ushort * const end = p + d->size;
6894 // sort out regions of complex text formatting
6895 if (uc > 0x058f && (uc < 0x1100 || uc > 0xfb0f)) {
6904 /*! \fn bool QString::isRightToLeft() const
6906 Returns true if the string is read right to left.
6908 bool QString::isRightToLeft() const
6910 const ushort *p = d->data();
6911 const ushort * const end = p + d->size;
6913 switch(QChar::direction(*p))
6928 /*! \fn QChar *QString::data()
6930 Returns a pointer to the data stored in the QString. The pointer
6931 can be used to access and modify the characters that compose the
6932 string. For convenience, the data is '\\0'-terminated.
6936 \snippet doc/src/snippets/qstring/main.cpp 19
6938 Note that the pointer remains valid only as long as the string is
6939 not modified by other means. For read-only access, constData() is
6940 faster because it never causes a \l{deep copy} to occur.
6942 \sa constData(), operator[]()
6945 /*! \fn const QChar *QString::data() const
6950 /*! \fn const QChar *QString::constData() const
6952 Returns a pointer to the data stored in the QString. The pointer
6953 can be used to access the characters that compose the string. For
6954 convenience, the data is '\\0'-terminated.
6956 Note that the pointer remains valid only as long as the string is
6959 \sa data(), operator[]()
6962 /*! \fn void QString::push_front(const QString &other)
6964 This function is provided for STL compatibility, prepending the
6965 given \a other string to the beginning of this string. It is
6966 equivalent to \c prepend(other).
6971 /*! \fn void QString::push_front(QChar ch)
6975 Prepends the given \a ch character to the beginning of this string.
6978 /*! \fn void QString::push_back(const QString &other)
6980 This function is provided for STL compatibility, appending the
6981 given \a other string onto the end of this string. It is
6982 equivalent to \c append(other).
6987 /*! \fn void QString::push_back(QChar ch)
6991 Appends the given \a ch character onto the end of this string.
6995 \fn std::string QString::toStdString() const
6997 Returns a std::string object with the data contained in this
6998 QString. The Unicode data is converted into 8-bit characters using
6999 the toAscii() function.
7001 This operator is mostly useful to pass a QString to a function
7002 that accepts a std::string object.
7004 If the QString contains Unicode characters that the
7005 QTextCodec::codecForCStrings() codec cannot handle, using this operator
7006 can lead to loss of information.
7008 This operator is only available if Qt is configured with STL
7009 compatibility enabled.
7011 \sa toAscii(), toLatin1(), toUtf8(), toLocal8Bit()
7015 Constructs a QString that uses the first \a size Unicode characters
7016 in the array \a unicode. The data in \a unicode is \e not
7017 copied. The caller must be able to guarantee that \a unicode will
7018 not be deleted or modified as long as the QString (or an
7019 unmodified copy of it) exists.
7021 Any attempts to modify the QString or copies of it will cause it
7022 to create a deep copy of the data, ensuring that the raw data
7025 Here's an example of how we can use a QRegExp on raw data in
7026 memory without requiring to copy the data into a QString:
7028 \snippet doc/src/snippets/qstring/main.cpp 22
7029 \snippet doc/src/snippets/qstring/main.cpp 23
7031 \warning A string created with fromRawData() is \e not
7032 '\\0'-terminated, unless the raw data contains a '\\0' character
7033 at position \a size. This means unicode() will \e not return a
7034 '\\0'-terminated string (although utf16() does, at the cost of
7035 copying the raw data).
7037 \sa fromUtf16(), setRawData()
7039 QString QString::fromRawData(const QChar *unicode, int size)
7043 x = const_cast<Data *>(&shared_null.str);
7045 x = const_cast<Data *>(&shared_empty.str);
7047 x = static_cast<Data *>(::malloc(sizeof(Data) + sizeof(ushort)));
7049 x->ref.initializeOwned();
7052 x->capacityReserved = false;
7053 x->offset = (const ushort *)unicode - (x->d + sizeof(qptrdiff)/sizeof(ushort));
7055 return QString(x, 0);
7061 Resets the QString to use the first \a size Unicode characters
7062 in the array \a unicode. The data in \a unicode is \e not
7063 copied. The caller must be able to guarantee that \a unicode will
7064 not be deleted or modified as long as the QString (or an
7065 unmodified copy of it) exists.
7067 This function can be used instead of fromRawData() to re-use
7068 existings QString objects to save memory re-allocations.
7072 QString &QString::setRawData(const QChar *unicode, int size)
7074 if (d->ref.isShared() || d->alloc) {
7075 *this = fromRawData(unicode, size);
7079 d->offset = (const ushort *)unicode - (d->d + sizeof(qptrdiff)/sizeof(ushort));
7088 /*! \class QLatin1String
7089 \brief The QLatin1String class provides a thin wrapper around an US-ASCII/Latin-1 encoded string literal.
7091 \ingroup string-processing
7094 Many of QString's member functions are overloaded to accept
7095 \c{const char *} instead of QString. This includes the copy
7096 constructor, the assignment operator, the comparison operators,
7097 and various other functions such as \link QString::insert()
7098 insert() \endlink, \link QString::replace() replace()\endlink,
7099 and \link QString::indexOf() indexOf()\endlink. These functions
7100 are usually optimized to avoid constructing a QString object for
7101 the \c{const char *} data. For example, assuming \c str is a
7104 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 3
7108 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 4
7110 because it doesn't construct four temporary QString objects and
7111 make a deep copy of the character data.
7113 Applications that define \c QT_NO_CAST_FROM_ASCII (as explained
7114 in the QString documentation) don't have access to QString's
7115 \c{const char *} API. To provide an efficient way of specifying
7116 constant Latin-1 strings, Qt provides the QLatin1String, which is
7117 just a very thin wrapper around a \c{const char *}. Using
7118 QLatin1String, the example code above becomes
7120 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 5
7122 This is a bit longer to type, but it provides exactly the same
7123 benefits as the first version of the code, and is faster than
7124 converting the Latin-1 strings using QString::fromLatin1().
7126 Thanks to the QString(const QLatin1String &) constructor,
7127 QLatin1String can be used everywhere a QString is expected. For
7130 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 6
7132 \sa QString, QLatin1Char, QStringLiteral
7135 /*! \fn QLatin1String::QLatin1String(const char *str)
7137 Constructs a QLatin1String object that stores \a str. Note that if
7138 \a str is 0, an empty string is created; this case is handled by
7141 The string data is \e not copied. The caller must be able to
7142 guarantee that \a str will not be deleted or modified as long as
7143 the QLatin1String object exists.
7148 /*! \fn QLatin1String::QLatin1String(const char *str, int size)
7150 Constructs a QLatin1String object that stores \a str with \a size.
7151 Note that if \a str is 0, an empty string is created; this case
7152 is handled by QString.
7154 The string data is \e not copied. The caller must be able to
7155 guarantee that \a str will not be deleted or modified as long as
7156 the QLatin1String object exists.
7161 /*! \fn const char *QLatin1String::latin1() const
7163 Returns the Latin-1 string stored in this object.
7166 /*! \fn int QLatin1String::size() const
7168 Returns the size of the Latin-1 string stored in this object.
7171 /*! \fn bool QLatin1String::operator==(const QString &other) const
7173 Returns true if this string is equal to string \a other;
7174 otherwise returns false.
7176 The comparison is based exclusively on the numeric Unicode values
7177 of the characters and is very fast, but is not what a human would
7178 expect. Consider sorting user-interface strings with
7179 QString::localeAwareCompare().
7183 \fn bool QLatin1String::operator==(const char *other) const
7187 The \a other const char pointer is converted to a QString using
7188 the QString::fromAscii() function.
7190 You can disable this operator by defining \c
7191 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7192 can be useful if you want to ensure that all user-visible strings
7193 go through QObject::tr(), for example.
7196 /*! \fn bool QLatin1String::operator!=(const QString &other) const
7198 Returns true if this string is not equal to string \a other;
7199 otherwise returns false.
7201 The comparison is based exclusively on the numeric Unicode values
7202 of the characters and is very fast, but is not what a human would
7203 expect. Consider sorting user-interface strings with
7204 QString::localeAwareCompare().
7208 \fn bool QLatin1String::operator!=(const char *other) const
7210 \overload operator!=()
7212 The \a other const char pointer is converted to a QString using
7213 the QString::fromAscii() function.
7215 You can disable this operator by defining \c
7216 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7217 can be useful if you want to ensure that all user-visible strings
7218 go through QObject::tr(), for example.
7222 \fn bool QLatin1String::operator>(const QString &other) const
7224 Returns true if this string is lexically greater than string \a
7225 other; otherwise returns false.
7227 The comparison is based exclusively on the numeric Unicode values
7228 of the characters and is very fast, but is not what a human would
7229 expect. Consider sorting user-interface strings with
7230 QString::localeAwareCompare().
7234 \fn bool QLatin1String::operator>(const char *other) const
7238 The \a other const char pointer is converted to a QString using
7239 the QString::fromAscii() function.
7241 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
7242 when you compile your applications. This can be useful if you want
7243 to ensure that all user-visible strings go through QObject::tr(),
7248 \fn bool QLatin1String::operator<(const QString &other) const
7250 Returns true if this string is lexically less than the \a other
7251 string; otherwise returns false.
7253 The comparison is based exclusively on the numeric Unicode values
7254 of the characters and is very fast, but is not what a human would
7255 expect. Consider sorting user-interface strings using the
7256 QString::localeAwareCompare() function.
7260 \fn bool QLatin1String::operator<(const char *other) const
7264 The \a other const char pointer is converted to a QString using
7265 the QString::fromAscii() function.
7267 You can disable this operator by defining \c
7268 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7269 can be useful if you want to ensure that all user-visible strings
7270 go through QObject::tr(), for example.
7274 \fn bool QLatin1String::operator>=(const QString &other) const
7276 Returns true if this string is lexically greater than or equal
7277 to string \a other; otherwise returns false.
7279 The comparison is based exclusively on the numeric Unicode values
7280 of the characters and is very fast, but is not what a human would
7281 expect. Consider sorting user-interface strings with
7282 QString::localeAwareCompare().
7286 \fn bool QLatin1String::operator>=(const char *other) const
7290 The \a other const char pointer is converted to a QString using
7291 the QString::fromAscii() function.
7293 You can disable this operator by defining \c
7294 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7295 can be useful if you want to ensure that all user-visible strings
7296 go through QObject::tr(), for example.
7299 /*! \fn bool QLatin1String::operator<=(const QString &other) const
7301 Returns true if this string is lexically less than or equal
7302 to string \a other; otherwise returns false.
7304 The comparison is based exclusively on the numeric Unicode values
7305 of the characters and is very fast, but is not what a human would
7306 expect. Consider sorting user-interface strings with
7307 QString::localeAwareCompare().
7311 \fn bool QLatin1String::operator<=(const char *other) const
7315 The \a other const char pointer is converted to a QString using
7316 the QString::fromAscii() function.
7318 You can disable this operator by defining \c
7319 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7320 can be useful if you want to ensure that all user-visible strings
7321 go through QObject::tr(), for example.
7326 /*! \fn bool operator==(const QLatin1String &s1, const QLatin1String &s2)
7327 \relates QLatin1String
7329 Returns true if string \a s1 is lexically equal to string \a s2; otherwise
7332 /*! \fn bool operator!=(const QLatin1String &s1, const QLatin1String &s2)
7333 \relates QLatin1String
7335 Returns true if string \a s1 is lexically unequal to string \a s2; otherwise
7338 /*! \fn bool operator<(const QLatin1String &s1, const QLatin1String &s2)
7339 \relates QLatin1String
7341 Returns true if string \a s1 is lexically smaller than string \a s2; otherwise
7344 /*! \fn bool operator<=(const QLatin1String &s1, const QLatin1String &s2)
7345 \relates QLatin1String
7347 Returns true if string \a s1 is lexically smaller than or equal to string \a s2; otherwise
7350 /*! \fn bool operator>(const QLatin1String &s1, const QLatin1String &s2)
7351 \relates QLatin1String
7353 Returns true if string \a s1 is lexically greater than string \a s2; otherwise
7356 /*! \fn bool operator>=(const QLatin1String &s1, const QLatin1String &s2)
7357 \relates QLatin1String
7359 Returns true if string \a s1 is lexically greater than or equal to
7360 string \a s2; otherwise returns false.
7364 #if !defined(QT_NO_DATASTREAM) || (defined(QT_BOOTSTRAPPED) && !defined(QT_BUILD_QMAKE))
7366 \fn QDataStream &operator<<(QDataStream &stream, const QString &string)
7369 Writes the given \a string to the specified \a stream.
7371 \sa {Serializing Qt Data Types}
7374 QDataStream &operator<<(QDataStream &out, const QString &str)
7376 if (out.version() == 1) {
7377 out << str.toLatin1();
7379 if (!str.isNull() || out.version() < 3) {
7380 if ((out.byteOrder() == QDataStream::BigEndian) == (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7381 out.writeBytes(reinterpret_cast<const char *>(str.unicode()), sizeof(QChar) * str.length());
7383 QVarLengthArray<ushort> buffer(str.length());
7384 const ushort *data = reinterpret_cast<const ushort *>(str.constData());
7385 for (int i = 0; i < str.length(); i++) {
7386 buffer[i] = qbswap(*data);
7389 out.writeBytes(reinterpret_cast<const char *>(buffer.data()), sizeof(ushort) * buffer.size());
7392 // write null marker
7393 out << (quint32)0xffffffff;
7400 \fn QDataStream &operator>>(QDataStream &stream, QString &string)
7403 Reads a string from the specified \a stream into the given \a string.
7405 \sa {Serializing Qt Data Types}
7408 QDataStream &operator>>(QDataStream &in, QString &str)
7410 #ifdef QT_QSTRING_UCS_4
7411 #if defined(Q_CC_GNU)
7412 #warning "operator>> not working properly"
7416 if (in.version() == 1) {
7419 str = QString::fromLatin1(l);
7422 in >> bytes; // read size of string
7423 if (bytes == 0xffffffff) { // null string
7425 } else if (bytes > 0) { // not empty
7428 in.setStatus(QDataStream::ReadCorruptData);
7432 const quint32 Step = 1024 * 1024;
7433 quint32 len = bytes / 2;
7434 quint32 allocated = 0;
7436 while (allocated < len) {
7437 int blockSize = qMin(Step, len - allocated);
7438 str.resize(allocated + blockSize);
7439 if (in.readRawData(reinterpret_cast<char *>(str.data()) + allocated * 2,
7440 blockSize * 2) != blockSize * 2) {
7442 in.setStatus(QDataStream::ReadPastEnd);
7445 allocated += blockSize;
7448 if ((in.byteOrder() == QDataStream::BigEndian)
7449 != (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7450 ushort *data = reinterpret_cast<ushort *>(str.data());
7452 *data = qbswap(*data);
7457 str = QString(QLatin1String(""));
7462 #endif // QT_NO_DATASTREAM
7470 \brief The QStringRef class provides a thin wrapper around QString substrings.
7473 \ingroup string-processing
7475 QStringRef provides a read-only subset of the QString API.
7477 A string reference explicitly references a portion of a string()
7478 with a given size(), starting at a specific position(). Calling
7479 toString() returns a copy of the data as a real QString instance.
7481 This class is designed to improve the performance of substring
7482 handling when manipulating substrings obtained from existing QString
7483 instances. QStringRef avoids the memory allocation and reference
7484 counting overhead of a standard QString by simply referencing a
7485 part of the original string. This can prove to be advantageous in
7486 low level code, such as that used in a parser, at the expense of
7487 potentially more complex code.
7489 For most users, there are no semantic benefits to using QStringRef
7490 instead of QString since QStringRef requires attention to be paid
7491 to memory management issues, potentially making code more complex
7492 to write and maintain.
7494 \warning A QStringRef is only valid as long as the referenced
7495 string exists. If the original string is deleted, the string
7496 reference points to an invalid memory location.
7498 We suggest that you only use this class in stable code where profiling
7499 has clearly identified that performance improvements can be made by
7500 replacing standard string operations with the optimized substring
7501 handling provided by this class.
7503 \sa {Implicitly Shared Classes}
7508 \fn QStringRef::QStringRef()
7510 Constructs an empty string reference.
7513 /*! \fn QStringRef::QStringRef(const QString *string, int position, int length)
7515 Constructs a string reference to the range of characters in the given
7516 \a string specified by the starting \a position and \a length in characters.
7518 \warning This function exists to improve performance as much as possible,
7519 and performs no bounds checking. For program correctness, \a position and
7520 \a length must describe a valid substring of \a string.
7522 This means that the starting \a position must be positive or 0 and smaller
7523 than \a string's length, and \a length must be positive or 0 but smaller than
7524 the string's length minus the starting \a position;
7525 i.e, 0 <= position < string->length() and
7526 0 <= length <= string->length() - position must both be satisfied.
7529 /*! \fn QStringRef::QStringRef(const QString *string)
7531 Constructs a string reference to the given \a string.
7534 /*! \fn QStringRef::QStringRef(const QStringRef &other)
7536 Constructs a copy of the \a other string reference.
7539 \fn QStringRef::~QStringRef()
7541 Destroys the string reference.
7543 Since this class is only used to refer to string data, and does not take
7544 ownership of it, no memory is freed when instances are destroyed.
7549 \fn int QStringRef::position() const
7551 Returns the starting position in the referenced string that is referred to
7552 by the string reference.
7554 \sa size(), string()
7558 \fn int QStringRef::size() const
7560 Returns the number of characters referred to by the string reference.
7561 Equivalent to length() and count().
7563 \sa position(), string()
7566 \fn int QStringRef::count() const
7567 Returns the number of characters referred to by the string reference.
7568 Equivalent to size() and length().
7570 \sa position(), string()
7573 \fn int QStringRef::length() const
7574 Returns the number of characters referred to by the string reference.
7575 Equivalent to size() and count().
7577 \sa position(), string()
7582 \fn bool QStringRef::isEmpty() const
7584 Returns true if the string reference has no characters; otherwise returns
7587 A string reference is empty if its size is zero.
7593 \fn bool QStringRef::isNull() const
7595 Returns true if string() returns a null pointer or a pointer to a
7596 null string; otherwise returns true.
7602 \fn const QString *QStringRef::string() const
7604 Returns a pointer to the string referred to by the string reference, or
7605 0 if it does not reference a string.
7612 \fn const QChar *QStringRef::unicode() const
7614 Returns a Unicode representation of the string reference. Since
7615 the data stems directly from the referenced string, it is not
7616 null-terminated unless the string reference includes the string's
7623 \fn const QChar *QStringRef::data() const
7629 \fn const QChar *QStringRef::constData() const
7635 Returns a copy of the string reference as a QString object.
7637 If the string reference is not a complete reference of the string
7638 (meaning that position() is 0 and size() equals string()->size()),
7639 this function will allocate a new string to return.
7644 QString QStringRef::toString() const {
7647 if (m_size && m_position == 0 && m_size == m_string->size())
7649 return QString(m_string->unicode() + m_position, m_size);
7653 /*! \relates QStringRef
7655 Returns true if string reference \a s1 is lexically equal to string reference \a s2; otherwise
7658 bool operator==(const QStringRef &s1,const QStringRef &s2)
7659 { return (s1.size() == s2.size() &&
7660 qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
7663 /*! \relates QStringRef
7665 Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
7668 bool operator==(const QString &s1,const QStringRef &s2)
7669 { return (s1.size() == s2.size() &&
7670 qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
7673 /*! \relates QStringRef
7675 Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
7678 bool operator==(const QLatin1String &s1, const QStringRef &s2)
7680 if (s1.size() != s2.size())
7683 const ushort *uc = reinterpret_cast<const ushort *>(s2.unicode());
7684 const ushort *e = uc + s2.size();
7685 const uchar *c = reinterpret_cast<const uchar *>(s1.latin1());
7687 return s2.isEmpty();
7690 if (uc == e || *uc != *c)
7701 Returns true if string reference \a s1 is lexically less than
7702 string reference \a s2; otherwise returns false.
7704 The comparison is based exclusively on the numeric Unicode values
7705 of the characters and is very fast, but is not what a human would
7706 expect. Consider sorting user-interface strings using the
7707 QString::localeAwareCompare() function.
7709 bool operator<(const QStringRef &s1,const QStringRef &s2)
7711 return ucstrcmp(s1.constData(), s1.length(), s2.constData(), s2.length()) < 0;
7714 /*!\fn bool operator<=(const QStringRef &s1,const QStringRef &s2)
7718 Returns true if string reference \a s1 is lexically less than
7719 or equal to string reference \a s2; otherwise returns false.
7721 The comparison is based exclusively on the numeric Unicode values
7722 of the characters and is very fast, but is not what a human would
7723 expect. Consider sorting user-interface strings using the
7724 QString::localeAwareCompare() function.
7727 /*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2)
7731 Returns true if string reference \a s1 is lexically greater than
7732 or equal to string reference \a s2; otherwise returns false.
7734 The comparison is based exclusively on the numeric Unicode values
7735 of the characters and is very fast, but is not what a human would
7736 expect. Consider sorting user-interface strings using the
7737 QString::localeAwareCompare() function.
7740 /*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2)
7744 Returns true if string reference \a s1 is lexically greater than
7745 string reference \a s2; otherwise returns false.
7747 The comparison is based exclusively on the numeric Unicode values
7748 of the characters and is very fast, but is not what a human would
7749 expect. Consider sorting user-interface strings using the
7750 QString::localeAwareCompare() function.
7755 \fn const QChar QStringRef::at(int position) const
7757 Returns the character at the given index \a position in the
7760 The \a position must be a valid index position in the string
7761 (i.e., 0 <= \a position < size()).
7765 \fn void QStringRef::clear()
7767 Clears the contents of the string reference by making it null and empty.
7769 \sa isEmpty(), isNull()
7773 \fn QStringRef &QStringRef::operator=(const QStringRef &other)
7775 Assigns the \a other string reference to this string reference, and
7780 \fn QStringRef &QStringRef::operator=(const QString *string)
7782 Constructs a string reference to the given \a string and assigns it to
7783 this string reference, returning the result.
7787 \typedef QString::DataPtr
7792 \fn DataPtr & QString::data_ptr()
7798 /*! Appends the string reference to \a string, and returns a new
7799 reference to the combined string data.
7801 QStringRef QStringRef::appendTo(QString *string) const
7804 return QStringRef();
7805 int pos = string->size();
7806 string->insert(pos, unicode(), size());
7807 return QStringRef(string, pos, size());
7811 \fn int QStringRef::compare(const QStringRef &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
7814 Compares the string \a s1 with the string \a s2 and returns an
7815 integer less than, equal to, or greater than zero if \a s1
7816 is less than, equal to, or greater than \a s2.
7818 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7819 otherwise the comparison is case insensitive.
7823 \fn int QStringRef::compare(const QStringRef &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
7827 Compares the string \a s1 with the string \a s2 and returns an
7828 integer less than, equal to, or greater than zero if \a s1
7829 is less than, equal to, or greater than \a s2.
7831 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7832 otherwise the comparison is case insensitive.
7836 \fn int QStringRef::compare(const QStringRef &s1, QLatin1String s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
7840 Compares the string \a s1 with the string \a s2 and returns an
7841 integer less than, equal to, or greater than zero if \a s1
7842 is less than, equal to, or greater than \a s2.
7844 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7845 otherwise the comparison is case insensitive.
7850 \fn int QStringRef::compare(const QString &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
7853 Compares this string with the \a other string and returns an
7854 integer less than, equal to, or greater than zero if this string
7855 is less than, equal to, or greater than the \a other string.
7857 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7858 otherwise the comparison is case insensitive.
7860 Equivalent to \c {compare(*this, other, cs)}.
7862 \sa QString::compare()
7867 \fn int QStringRef::compare(const QStringRef &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
7870 Compares this string with the \a other string and returns an
7871 integer less than, equal to, or greater than zero if this string
7872 is less than, equal to, or greater than the \a other string.
7874 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7875 otherwise the comparison is case insensitive.
7877 Equivalent to \c {compare(*this, other, cs)}.
7879 \sa QString::compare()
7884 \fn int QStringRef::compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
7887 Compares this string with the \a other string and returns an
7888 integer less than, equal to, or greater than zero if this string
7889 is less than, equal to, or greater than the \a other string.
7891 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
7892 otherwise the comparison is case insensitive.
7894 Equivalent to \c {compare(*this, other, cs)}.
7896 \sa QString::compare()
7900 \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QString & s2)
7903 Compares \a s1 with \a s2 and returns an integer less than, equal
7904 to, or greater than zero if \a s1 is less than, equal to, or
7907 The comparison is performed in a locale- and also
7908 platform-dependent manner. Use this function to present sorted
7909 lists of strings to the user.
7911 On Mac OS X, this function compares according the
7912 "Order for sorted lists" setting in the International prefereces panel.
7914 \sa compare(), QTextCodec::locale()
7918 \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QStringRef & s2)
7922 Compares \a s1 with \a s2 and returns an integer less than, equal
7923 to, or greater than zero if \a s1 is less than, equal to, or
7926 The comparison is performed in a locale- and also
7927 platform-dependent manner. Use this function to present sorted
7928 lists of strings to the user.
7933 \fn int QStringRef::localeAwareCompare(const QString &other) const
7937 Compares this string with the \a other string and returns an
7938 integer less than, equal to, or greater than zero if this string
7939 is less than, equal to, or greater than the \a other string.
7941 The comparison is performed in a locale- and also
7942 platform-dependent manner. Use this function to present sorted
7943 lists of strings to the user.
7947 \fn int QStringRef::localeAwareCompare(const QStringRef &other) const
7951 Compares this string with the \a other string and returns an
7952 integer less than, equal to, or greater than zero if this string
7953 is less than, equal to, or greater than the \a other string.
7955 The comparison is performed in a locale- and also
7956 platform-dependent manner. Use this function to present sorted
7957 lists of strings to the user.
7961 \fn QString &QString::append(const QStringRef &reference)
7964 Appends the given string \a reference to this string and returns the result.
7966 QString &QString::append(const QStringRef &str)
7968 if (str.string() == this) {
7970 } else if (str.string()) {
7971 int oldSize = size();
7972 resize(oldSize + str.size());
7973 memcpy(data() + oldSize, str.unicode(), str.size() * sizeof(QChar));
7981 Returns a substring reference to the \a n leftmost characters
7984 If \a n is greater than size() or less than zero, a reference to the entire
7987 \snippet doc/src/snippets/qstring/main.cpp leftRef
7989 \sa left(), rightRef(), midRef(), startsWith()
7991 QStringRef QString::leftRef(int n) const
7993 if (n >= d->size || n < 0)
7995 return QStringRef(this, 0, n);
8001 Returns a substring reference to the \a n rightmost characters
8004 If \a n is greater than size() or less than zero, a reference to the entire
8007 \snippet doc/src/snippets/qstring/main.cpp rightRef
8009 \sa right(), leftRef(), midRef(), endsWith()
8011 QStringRef QString::rightRef(int n) const
8013 if (n >= d->size || n < 0)
8015 return QStringRef(this, d->size - n, n);
8021 Returns a substring reference to \a n characters of this string,
8022 starting at the specified \a position.
8024 If the \a position exceeds the length of the string, a null
8025 reference is returned.
8027 If there are less than \a n characters available in the string,
8028 starting at the given \a position, or if \a n is -1 (default), the
8029 function returns all characters from the specified \a position
8034 \snippet doc/src/snippets/qstring/main.cpp midRef
8036 \sa mid(), leftRef(), rightRef()
8039 QStringRef QString::midRef(int position, int n) const
8041 if (position > d->size)
8042 return QStringRef();
8045 if (n < 0 || n > d->size - position)
8046 n = d->size - position;
8047 return QStringRef(this, position, n);
8053 Returns the index position of the first occurrence of the string \a
8054 str in this string reference, searching forward from index position
8055 \a from. Returns -1 if \a str is not found.
8057 If \a cs is Qt::CaseSensitive (default), the search is case
8058 sensitive; otherwise the search is case insensitive.
8060 If \a from is -1, the search starts at the last character; if it is
8061 -2, at the next to last character and so on.
8063 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8065 int QStringRef::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8067 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
8074 Returns the index position of the first occurrence of the
8075 character \a ch in the string reference, searching forward from
8076 index position \a from. Returns -1 if \a ch could not be found.
8078 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8080 int QStringRef::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8082 return findChar(unicode(), length(), ch, from, cs);
8088 Returns the index position of the first occurrence of the string \a
8089 str in this string reference, searching forward from index position
8090 \a from. Returns -1 if \a str is not found.
8092 If \a cs is Qt::CaseSensitive (default), the search is case
8093 sensitive; otherwise the search is case insensitive.
8095 If \a from is -1, the search starts at the last character; if it is
8096 -2, at the next to last character and so on.
8098 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8100 int QStringRef::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8102 return qt_find_latin1_string(unicode(), size(), str, from, cs);
8110 Returns the index position of the first occurrence of the string
8111 reference \a str in this string reference, searching forward from
8112 index position \a from. Returns -1 if \a str is not found.
8114 If \a cs is Qt::CaseSensitive (default), the search is case
8115 sensitive; otherwise the search is case insensitive.
8117 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8119 int QStringRef::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8121 return qFindString(unicode(), size(), from, str.unicode(), str.size(), cs);
8127 Returns the index position of the last occurrence of the string \a
8128 str in this string reference, searching backward from index position
8129 \a from. If \a from is -1 (default), the search starts at the last
8130 character; if \a from is -2, at the next to last character and so
8131 on. Returns -1 if \a str is not found.
8133 If \a cs is Qt::CaseSensitive (default), the search is case
8134 sensitive; otherwise the search is case insensitive.
8136 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8138 int QStringRef::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8140 const int sl = str.size();
8142 return lastIndexOf(str.at(0), from, cs);
8144 const int l = size();;
8148 if (from == l && sl == 0)
8150 if (from < 0 || from >= l || delta < 0)
8155 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8156 reinterpret_cast<const ushort*>(str.unicode()), str.size(), cs);
8161 \overload lastIndexOf()
8163 Returns the index position of the last occurrence of the character
8164 \a ch, searching backward from position \a from.
8166 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8168 int QStringRef::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8170 return qt_last_index_of(unicode(), size(), ch, from, cs);
8175 \overload lastIndexOf()
8177 Returns the index position of the last occurrence of the string \a
8178 str in this string reference, searching backward from index position
8179 \a from. If \a from is -1 (default), the search starts at the last
8180 character; if \a from is -2, at the next to last character and so
8181 on. Returns -1 if \a str is not found.
8183 If \a cs is Qt::CaseSensitive (default), the search is case
8184 sensitive; otherwise the search is case insensitive.
8186 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8188 int QStringRef::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8190 const int sl = str.size();
8192 return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
8194 const int l = size();
8198 if (from == l && sl == 0)
8200 if (from < 0 || from >= l || delta < 0)
8205 QVarLengthArray<ushort> s(sl);
8206 for (int i = 0; i < sl; ++i)
8207 s[i] = str.latin1()[i];
8209 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, s.data(), sl, cs);
8214 \overload lastIndexOf()
8216 Returns the index position of the last occurrence of the string
8217 reference \a str in this string reference, searching backward from
8218 index position \a from. If \a from is -1 (default), the search
8219 starts at the last character; if \a from is -2, at the next to last
8220 character and so on. Returns -1 if \a str is not found.
8222 If \a cs is Qt::CaseSensitive (default), the search is case
8223 sensitive; otherwise the search is case insensitive.
8225 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8227 int QStringRef::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8229 const int sl = str.size();
8231 return lastIndexOf(str.at(0), from, cs);
8233 const int l = size();
8237 if (from == l && sl == 0)
8239 if (from < 0 || from >= l || delta < 0)
8244 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8245 reinterpret_cast<const ushort*>(str.unicode()),
8251 Returns the number of (potentially overlapping) occurrences of
8252 the string \a str in this string reference.
8254 If \a cs is Qt::CaseSensitive (default), the search is
8255 case sensitive; otherwise the search is case insensitive.
8257 \sa QString::count(), contains(), indexOf()
8259 int QStringRef::count(const QString &str, Qt::CaseSensitivity cs) const
8261 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8268 Returns the number of occurrences of the character \a ch in the
8271 If \a cs is Qt::CaseSensitive (default), the search is
8272 case sensitive; otherwise the search is case insensitive.
8274 \sa QString::count(), contains(), indexOf()
8276 int QStringRef::count(QChar ch, Qt::CaseSensitivity cs) const
8278 return qt_string_count(unicode(), size(), ch, cs);
8285 Returns the number of (potentially overlapping) occurrences of the
8286 string reference \a str in this string reference.
8288 If \a cs is Qt::CaseSensitive (default), the search is
8289 case sensitive; otherwise the search is case insensitive.
8291 \sa QString::count(), contains(), indexOf()
8293 int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs) const
8295 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8301 Returns true if the string reference starts with \a str; otherwise
8304 If \a cs is Qt::CaseSensitive (default), the search is
8305 case sensitive; otherwise the search is case insensitive.
8307 \sa QString::startsWith(), endsWith()
8309 bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs) const
8311 return qt_starts_with(isNull() ? 0 : unicode(), size(),
8312 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8317 \overload startsWith()
8318 \sa QString::startsWith(), endsWith()
8320 bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8322 return qt_starts_with(isNull() ? 0 : unicode(), size(), str, cs);
8327 \overload startsWith()
8328 \sa QString::startsWith(), endsWith()
8330 bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8332 return qt_starts_with(isNull() ? 0 : unicode(), size(),
8333 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8338 \overload startsWith()
8340 Returns true if the string reference starts with \a ch; otherwise
8343 If \a cs is Qt::CaseSensitive (default), the search is case
8344 sensitive; otherwise the search is case insensitive.
8346 \sa QString::startsWith(), endsWith()
8348 bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs) const
8351 const ushort *data = reinterpret_cast<const ushort*>(unicode());
8352 return (cs == Qt::CaseSensitive
8354 : foldCase(data[0]) == foldCase(ch.unicode()));
8362 Returns true if the string reference ends with \a str; otherwise
8365 If \a cs is Qt::CaseSensitive (default), the search is case
8366 sensitive; otherwise the search is case insensitive.
8368 \sa QString::endsWith(), startsWith()
8370 bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs) const
8372 return qt_ends_with(isNull() ? 0 : unicode(), size(),
8373 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8378 \overload endsWith()
8380 Returns true if the string reference ends with \a ch; otherwise
8383 If \a cs is Qt::CaseSensitive (default), the search is case
8384 sensitive; otherwise the search is case insensitive.
8386 \sa QString::endsWith(), endsWith()
8388 bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs) const
8391 const ushort *data = reinterpret_cast<const ushort*>(unicode());
8392 const int size = length();
8393 return (cs == Qt::CaseSensitive
8394 ? data[size - 1] == ch
8395 : foldCase(data[size - 1]) == foldCase(ch.unicode()));
8403 \overload endsWith()
8404 \sa QString::endsWith(), endsWith()
8406 bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8408 return qt_ends_with(isNull() ? 0 : unicode(), size(), str, cs);
8413 \overload endsWith()
8414 \sa QString::endsWith(), endsWith()
8416 bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8418 return qt_ends_with(isNull() ? 0 : unicode(), size(),
8419 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8423 /*! \fn bool QStringRef::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8426 Returns true if this string reference contains an occurrence of
8427 the string \a str; otherwise returns false.
8429 If \a cs is Qt::CaseSensitive (default), the search is
8430 case sensitive; otherwise the search is case insensitive.
8432 \sa indexOf(), count()
8435 /*! \fn bool QStringRef::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8437 \overload contains()
8440 Returns true if this string contains an occurrence of the
8441 character \a ch; otherwise returns false.
8443 If \a cs is Qt::CaseSensitive (default), the search is
8444 case sensitive; otherwise the search is case insensitive.
8448 /*! \fn bool QStringRef::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8449 \overload contains()
8452 Returns true if this string reference contains an occurrence of
8453 the string reference \a str; otherwise returns false.
8455 If \a cs is Qt::CaseSensitive (default), the search is
8456 case sensitive; otherwise the search is case insensitive.
8458 \sa indexOf(), count()
8461 /*! \fn bool QStringRef::contains(QLatin1String str, Qt::CaseSensitivity cs) const
8463 \overload contains()
8465 Returns true if this string reference contains an occurrence of
8466 the string \a str; otherwise returns false.
8468 If \a cs is Qt::CaseSensitive (default), the search is
8469 case sensitive; otherwise the search is case insensitive.
8471 \sa indexOf(), count()
8474 static inline int qt_last_index_of(const QChar *haystack, int haystackLen, QChar needle,
8475 int from, Qt::CaseSensitivity cs)
8477 ushort c = needle.unicode();
8479 from += haystackLen;
8480 if (from < 0 || from >= haystackLen)
8483 const ushort *b = reinterpret_cast<const ushort*>(haystack);
8484 const ushort *n = b + from;
8485 if (cs == Qt::CaseSensitive) {
8492 if (foldCase(*n) == c)
8501 static inline int qt_string_count(const QChar *haystack, int haystackLen,
8502 const QChar *needle, int needleLen,
8503 Qt::CaseSensitivity cs)
8507 if (haystackLen > 500 && needleLen > 5) {
8508 QStringMatcher matcher(needle, needleLen, cs);
8509 while ((i = matcher.indexIn(haystack, haystackLen, i + 1)) != -1)
8512 while ((i = qFindString(haystack, haystackLen, i + 1, needle, needleLen, cs)) != -1)
8518 static inline int qt_string_count(const QChar *unicode, int size, QChar ch,
8519 Qt::CaseSensitivity cs)
8521 ushort c = ch.unicode();
8523 const ushort *b = reinterpret_cast<const ushort*>(unicode);
8524 const ushort *i = b + size;
8525 if (cs == Qt::CaseSensitive) {
8532 if (foldCase(*(--i)) == c)
8538 static inline int qt_find_latin1_string(const QChar *haystack, int size,
8539 const QLatin1String &needle,
8540 int from, Qt::CaseSensitivity cs)
8542 const char *latin1 = needle.latin1();
8543 int len = needle.size();
8544 QVarLengthArray<ushort> s(len);
8545 for (int i = 0; i < len; ++i)
8548 return qFindString(haystack, size, from,
8549 reinterpret_cast<const QChar*>(s.constData()), len, cs);
8552 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8553 const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
8557 if (haystackLen == 0)
8558 return needleLen == 0;
8559 if (needleLen > haystackLen)
8562 const ushort *h = reinterpret_cast<const ushort*>(haystack);
8563 const ushort *n = reinterpret_cast<const ushort*>(needle);
8565 if (cs == Qt::CaseSensitive) {
8566 return qMemEquals(h, n, needleLen);
8570 for (int i = 0; i < needleLen; ++i)
8571 if (foldCase(h[i], last) != foldCase(n[i], olast))
8577 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8578 const QLatin1String &needle, Qt::CaseSensitivity cs)
8581 return !needle.latin1();
8582 if (haystackLen == 0)
8583 return !needle.latin1() || *needle.latin1() == 0;
8584 const int slen = needle.size();
8585 if (slen > haystackLen)
8587 const ushort *data = reinterpret_cast<const ushort*>(haystack);
8588 const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
8589 if (cs == Qt::CaseSensitive) {
8590 for (int i = 0; i < slen; ++i)
8591 if (data[i] != latin[i])
8594 for (int i = 0; i < slen; ++i)
8595 if (foldCase(data[i]) != foldCase((ushort)latin[i]))
8601 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
8602 const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
8606 if (haystackLen == 0)
8607 return needleLen == 0;
8608 const int pos = haystackLen - needleLen;
8612 const ushort *h = reinterpret_cast<const ushort*>(haystack);
8613 const ushort *n = reinterpret_cast<const ushort*>(needle);
8615 if (cs == Qt::CaseSensitive) {
8616 return qMemEquals(h + pos, n, needleLen);
8620 for (int i = 0; i < needleLen; i++)
8621 if (foldCase(h[pos+i], last) != foldCase(n[i], olast))
8628 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
8629 const QLatin1String &needle, Qt::CaseSensitivity cs)
8632 return !needle.latin1();
8633 if (haystackLen == 0)
8634 return !needle.latin1() || *needle.latin1() == 0;
8635 const int slen = needle.size();
8636 int pos = haystackLen - slen;
8639 const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
8640 const ushort *data = reinterpret_cast<const ushort*>(haystack);
8641 if (cs == Qt::CaseSensitive) {
8642 for (int i = 0; i < slen; i++)
8643 if (data[pos+i] != latin[i])
8646 for (int i = 0; i < slen; i++)
8647 if (foldCase(data[pos+i]) != foldCase((ushort)latin[i]))
8656 Returns a Latin-1 representation of the string as a QByteArray.
8658 The returned byte array is undefined if the string contains non-Latin1
8659 characters. Those characters may be suppressed or replaced with a
8662 \sa toAscii(), toUtf8(), toLocal8Bit(), QTextCodec
8664 QByteArray QStringRef::toLatin1() const
8666 return toLatin1_helper(unicode(), length());
8672 Returns an 8-bit representation of the string as a QByteArray.
8674 If a codec has been set using QTextCodec::setCodecForCStrings(),
8675 it is used to convert Unicode to 8-bit char; otherwise this
8676 function does the same as toLatin1().
8678 Note that, despite the name, this function does not necessarily return an US-ASCII
8679 (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
8681 \sa toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
8683 QByteArray QStringRef::toAscii() const
8685 #ifndef QT_NO_TEXTCODEC
8686 if (QString::codecForCStrings)
8687 return QString::codecForCStrings->fromUnicode(unicode(), length());
8688 #endif // QT_NO_TEXTCODEC
8695 Returns the local 8-bit representation of the string as a
8696 QByteArray. The returned byte array is undefined if the string
8697 contains characters not supported by the local 8-bit encoding.
8699 QTextCodec::codecForLocale() is used to perform the conversion from
8700 Unicode. If the locale encoding could not be determined, this function
8701 does the same as toLatin1().
8703 If this string contains any characters that cannot be encoded in the
8704 locale, the returned byte array is undefined. Those characters may be
8705 suppressed or replaced by another.
8707 \sa toAscii(), toLatin1(), toUtf8(), QTextCodec
8709 QByteArray QStringRef::toLocal8Bit() const
8711 #ifndef QT_NO_TEXTCODEC
8712 if (QTextCodec::codecForLocale())
8713 return QTextCodec::codecForLocale()->fromUnicode(unicode(), length());
8714 #endif // QT_NO_TEXTCODEC
8721 Returns a UTF-8 representation of the string as a QByteArray.
8723 UTF-8 is a Unicode codec and can represent all characters in a Unicode
8724 string like QString.
8726 However, in the Unicode range, there are certain codepoints that are not
8727 considered characters. The Unicode standard reserves the last two
8728 codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
8729 U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF,
8730 inclusive, as non-characters. If any of those appear in the string, they
8731 may be discarded and will not appear in the UTF-8 representation, or they
8732 may be replaced by one or more replacement characters.
8734 \sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
8736 QByteArray QStringRef::toUtf8() const
8739 return QByteArray();
8741 return QUtf8::convertFromUnicode(constData(), length(), 0);
8747 Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
8749 UCS-4 is a Unicode codec and is lossless. All characters from this string
8750 can be encoded in UCS-4.
8752 \sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
8754 QVector<uint> QStringRef::toUcs4() const
8756 QVector<uint> v(length());
8758 int len = QString::toUcs4_helper(reinterpret_cast<const ushort *>(unicode()), length(), a);
8766 \fn QString Qt::escape(const QString &plain)
8768 \sa QString::toHtmlEscaped()
8772 Converts the plain text string \a plain to a HTML string with
8773 HTML metacharacters \c{<}, \c{>}, \c{&}, and \c{"} replaced by HTML
8778 \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 7
8780 QString QString::toHtmlEscaped() const
8783 const int len = length();
8784 rich.reserve(int(len * 1.1));
8785 for (int i = 0; i < len; ++i) {
8786 if (at(i) == QLatin1Char('<'))
8787 rich += QLatin1String("<");
8788 else if (at(i) == QLatin1Char('>'))
8789 rich += QLatin1String(">");
8790 else if (at(i) == QLatin1Char('&'))
8791 rich += QLatin1String("&");
8792 else if (at(i) == QLatin1Char('"'))
8793 rich += QLatin1String(""");
8802 \macro QStringLiteral(str)
8805 The macro generates the data for a QString out of \a str at compile time if the compiler supports it.
8806 Creating a QString from it is free in this case, and the generated string data is stored in
8807 the read-only segment of the compiled object file.
8809 For compilers not supporting the creation of compile time strings, QStringLiteral will fall back to
8812 The result of the QStringLiteral expression can be cast into a QString.
8814 If you have code looking like:
8816 if (node.hasAttribute("http-contents-length")) //...
8818 One temporary QString will be created to be passed as the hasAttribute function parameter.
8819 This can be quite expensive, as it involves a memory allocation and the copy and the conversion
8820 of the data into QString's internal encoding.
8822 This can be avoided by doing
8824 if (node.hasAttribute(QStringLiteral("http-contents-length"))) //...
8826 Then the QString's internal data will be generated at compile time and no conversion or allocation
8827 will occur at runtime
8829 Using QStringLiteral instead of a double quoted ascii literal can significantly speed up creation
8830 of QString's from data known at compile time.
8832 If the compiler is C++11 enabled the string \a str can actually contain unicode data.
8834 \note There are still a few cases in which QLatin1String is more efficient than QStringLiteral:
8835 If it is passed to a function that has an overload that takes the QLatin1String directly, without
8836 conversion to QString. For instance, this is the case of QString::operator==
8838 if (attribute.name() == QLatin1String("http-contents-length")) //...