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 "qregularexpression.h"
45 #include "qunicodetables_p.h"
46 #ifndef QT_NO_TEXTCODEC
47 #include <qtextcodec.h>
49 #include <private/qutfcodec_p.h>
52 #include <qdatastream.h>
55 #include "qlocale_p.h"
56 #include "qstringmatcher.h"
57 #include "qvarlengtharray.h"
64 #include <private/qcore_mac_p.h>
67 #include <private/qfunctions_p.h>
76 #include "qstringmatcher.cpp"
79 # include <qt_windows.h>
90 #define LLONG_MAX qint64_C(9223372036854775807)
93 #define LLONG_MIN (-LLONG_MAX - qint64_C(1))
96 #define ULLONG_MAX quint64_C(18446744073709551615)
99 #define IS_RAW_DATA(d) ((d)->offset != sizeof(QStringData))
104 int qFindString(const QChar *haystack, int haystackLen, int from,
105 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
106 int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from,
107 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
108 static inline int qt_last_index_of(const QChar *haystack, int haystackLen, QChar needle,
109 int from, Qt::CaseSensitivity cs);
110 static inline int qt_string_count(const QChar *haystack, int haystackLen,
111 const QChar *needle, int needleLen,
112 Qt::CaseSensitivity cs);
113 static inline int qt_string_count(const QChar *haystack, int haystackLen,
114 QChar needle, Qt::CaseSensitivity cs);
115 static inline int qt_find_latin1_string(const QChar *hay, int size, QLatin1String needle,
116 int from, Qt::CaseSensitivity cs);
117 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
118 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
119 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
120 QLatin1String needle, Qt::CaseSensitivity cs);
121 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
122 const QChar *needle, int needleLen, Qt::CaseSensitivity cs);
123 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
124 QLatin1String needle, Qt::CaseSensitivity cs);
126 // Unicode case-insensitive comparison
127 static int ucstricmp(const ushort *a, const ushort *ae, const ushort *b, const ushort *be)
136 const ushort *e = ae;
143 // qDebug() << hex << alast << blast;
144 // qDebug() << hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast);
145 // qDebug() << hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast);
146 int diff = foldCase(*a, alast) - foldCase(*b, blast);
160 // Case-insensitive comparison between a Unicode string and a QLatin1String
161 static int ucstricmp(const ushort *a, const ushort *ae, const uchar *b, const uchar *be)
171 const ushort *e = ae;
176 int diff = foldCase(*a) - foldCase(*b);
190 // Unicode case-sensitive compare two same-sized strings
191 static int ucstrncmp(const QChar *a, const QChar *b, int l)
193 while (l-- && *a == *b)
197 return a->unicode() - b->unicode();
200 // Unicode case-sensitive comparison
201 static int ucstrcmp(const QChar *a, int alen, const QChar *b, int blen)
203 if (a == b && alen == blen)
205 int l = qMin(alen, blen);
206 int cmp = ucstrncmp(a, b, l);
207 return cmp ? cmp : (alen-blen);
210 // Unicode case-insensitive compare two same-sized strings
211 static int ucstrnicmp(const ushort *a, const ushort *b, int l)
213 return ucstricmp(a, a + l, b, b + l);
216 // Benchmarking indicates that doing memcmp is much slower than
217 // executing the comparison ourselves.
219 // The profiling was done on a population of calls to qMemEquals, generated
220 // during a run of the demo browser. The profile of the data (32-bit x86
223 // total number of comparisons: 21353
224 // longest string compared: 95
225 // average comparison length: 14.8786
226 // cache-line crosses: 5661 (13.3%)
227 // alignment histogram:
228 // 0xXXX0 = 512 (1.2%) strings, 0 (0.0%) of which same-aligned
229 // 0xXXX2 = 15087 (35.3%) strings, 5145 (34.1%) of which same-aligned
230 // 0xXXX4 = 525 (1.2%) strings, 0 (0.0%) of which same-aligned
231 // 0xXXX6 = 557 (1.3%) strings, 6 (1.1%) of which same-aligned
232 // 0xXXX8 = 509 (1.2%) strings, 0 (0.0%) of which same-aligned
233 // 0xXXXa = 24358 (57.0%) strings, 9901 (40.6%) of which same-aligned
234 // 0xXXXc = 557 (1.3%) strings, 0 (0.0%) of which same-aligned
235 // 0xXXXe = 601 (1.4%) strings, 15 (2.5%) of which same-aligned
236 // total = 42706 (100%) strings, 15067 (35.3%) of which same-aligned
238 // 92% of the strings have alignment of 2 or 10, which is due to malloc on
239 // 32-bit Linux returning values aligned to 8 bytes, and offsetof(array, QString::Data) == 18.
241 // The profile on 64-bit will be different since offsetof(array, QString::Data) == 26.
243 // The benchmark results were, for a Core-i7 @ 2.67 GHz 32-bit, compiled with -O3 -funroll-loops:
244 // 16-bit loads only: 872,301 CPU ticks [Qt 4.5 / memcmp]
245 // 32- and 16-bit loads: 773,362 CPU ticks [Qt 4.6]
246 // SSE2 "movdqu" 128-bit loads: 618,736 CPU ticks
247 // SSE3 "lddqu" 128-bit loads: 619,954 CPU ticks
248 // SSSE3 "palignr" corrections: 852,147 CPU ticks
249 // SSE4.2 "pcmpestrm": 738,702 CPU ticks
251 // The same benchmark on an Atom N450 @ 1.66 GHz, is:
252 // 16-bit loads only: 2,185,882 CPU ticks
253 // 32- and 16-bit loads: 1,805,060 CPU ticks
254 // SSE2 "movdqu" 128-bit loads: 2,529,843 CPU ticks
255 // SSE3 "lddqu" 128-bit loads: 2,514,858 CPU ticks
256 // SSSE3 "palignr" corrections: 2,160,325 CPU ticks
257 // SSE4.2 not available
259 // The conclusion we reach is that alignment the SSE2 unaligned code can gain
260 // 20% improvement in performance in some systems, but suffers a penalty due
261 // to the unaligned loads on others.
263 static bool qMemEquals(const quint16 *a, const quint16 *b, int length)
265 if (a == b || !length)
277 if ((sa.value & 2) == (sb.value & 2)) {
278 // both addresses have the same alignment
280 // both addresses are not aligned to 4-bytes boundaries
281 // compare the first character
288 // now both addresses are 4-bytes aligned
291 // both addresses are 4-bytes aligned
292 // do a fast 32-bit comparison
293 register const quint32 *e = sa.d + (length >> 1);
294 for ( ; sa.d != e; ++sa.d, ++sb.d) {
299 // do we have a tail?
300 return (length & 1) ? *sa.w == *sb.w : true;
302 // one of the addresses isn't 4-byte aligned but the other is
303 register const quint16 *e = sa.w + length;
304 for ( ; sa.w != e; ++sa.w, ++sb.w) {
315 Returns the index position of the first occurrence of the
316 character \a ch in the string given by \a str and \a len,
317 searching forward from index
318 position \a from. Returns -1 if \a ch could not be found.
320 static int findChar(const QChar *str, int len, QChar ch, int from,
321 Qt::CaseSensitivity cs)
323 const ushort *s = (const ushort *)str;
324 ushort c = ch.unicode();
326 from = qMax(from + len, 0);
328 const ushort *n = s + from - 1;
329 const ushort *e = s + len;
330 if (cs == Qt::CaseSensitive) {
337 if (foldCase(*n) == c)
345 if (sl_minus_1 < (int)sizeof(int) * CHAR_BIT) \
346 hashHaystack -= (a) << sl_minus_1; \
349 inline bool qIsUpper(char ch)
351 return ch >= 'A' && ch <= 'Z';
354 inline bool qIsDigit(char ch)
356 return ch >= '0' && ch <= '9';
359 inline char qToLower(char ch)
361 if (ch >= 'A' && ch <= 'Z')
362 return ch - 'A' + 'a';
368 const QString::Null QString::null = { };
371 \macro QT_NO_CAST_FROM_ASCII
374 Disables automatic conversions from 8-bit strings (char *) to unicode QStrings
376 \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_BYTEARRAY
380 \macro QT_NO_CAST_TO_ASCII
383 disables automatic conversion from QString to 8-bit strings (char *)
385 \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
389 \macro QT_ASCII_CAST_WARNINGS
393 This macro can be defined to force a warning whenever a function is
394 called that automatically converts between unicode and 8-bit encodings.
396 Note: This only works for compilers that support warnings for
399 \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII
405 \brief The QCharRef class is a helper class for QString.
409 \ingroup string-processing
411 When you get an object of type QCharRef, if you can assign to it,
412 the assignment will apply to the character in the string from
413 which you got the reference. That is its whole purpose in life.
414 The QCharRef becomes invalid once modifications are made to the
415 string: if you want to keep the character, copy it into a QChar.
417 Most of the QChar member functions also exist in QCharRef.
418 However, they are not explicitly documented here.
420 \sa QString::operator[](), QString::at(), QChar
427 \brief The QString class provides a Unicode character string.
431 \ingroup string-processing
433 QString stores a string of 16-bit \l{QChar}s, where each QChar
434 corresponds one Unicode 4.0 character. (Unicode characters
435 with code values above 65535 are stored using surrogate pairs,
436 i.e., two consecutive \l{QChar}s.)
438 \l{Unicode} is an international standard that supports most of the
439 writing systems in use today. It is a superset of US-ASCII (ANSI
440 X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1
441 characters are available at the same code positions.
443 Behind the scenes, QString uses \l{implicit sharing}
444 (copy-on-write) to reduce memory usage and to avoid the needless
445 copying of data. This also helps reduce the inherent overhead of
446 storing 16-bit characters instead of 8-bit characters.
448 In addition to QString, Qt also provides the QByteArray class to
449 store raw bytes and traditional 8-bit '\\0'-terminated strings.
450 For most purposes, QString is the class you want to use. It is
451 used throughout the Qt API, and the Unicode support ensures that
452 your applications will be easy to translate if you want to expand
453 your application's market at some point. The two main cases where
454 QByteArray is appropriate are when you need to store raw binary
455 data, and when memory conservation is critical (e.g., with
456 \l{Qt for Embedded Linux}).
460 \section1 Initializing a String
462 One way to initialize a QString is simply to pass a \c{const char
463 *} to its constructor. For example, the following code creates a
464 QString of size 5 containing the data "Hello":
466 \snippet qstring/main.cpp 0
468 QString converts the \c{const char *} data into Unicode using the
471 In all of the QString functions that take \c{const char *}
472 parameters, the \c{const char *} is interpreted as a classic
473 C-style '\\0'-terminated string encoded in UTF-8. It is legal for
474 the \c{const char *} parameter to be 0.
476 You can also provide string data as an array of \l{QChar}s:
478 \snippet qstring/main.cpp 1
480 QString makes a deep copy of the QChar data, so you can modify it
481 later without experiencing side effects. (If for performance
482 reasons you don't want to take a deep copy of the character data,
483 use QString::fromRawData() instead.)
485 Another approach is to set the size of the string using resize()
486 and to initialize the data character per character. QString uses
487 0-based indexes, just like C++ arrays. To access the character at
488 a particular index position, you can use \l operator[](). On
489 non-const strings, \l operator[]() returns a reference to a
490 character that can be used on the left side of an assignment. For
493 \snippet qstring/main.cpp 2
495 For read-only access, an alternative syntax is to use the at()
498 \snippet qstring/main.cpp 3
500 The at() function can be faster than \l operator[](), because it
501 never causes a \l{deep copy} to occur. Alternatively, use the
502 left(), right(), or mid() functions to extract several characters
505 A QString can embed '\\0' characters (QChar::Null). The size()
506 function always returns the size of the whole string, including
507 embedded '\\0' characters.
509 After a call to the resize() function, newly allocated characters
510 have undefined values. To set all the characters in the string to
511 a particular value, use the fill() function.
513 QString provides dozens of overloads designed to simplify string
514 usage. For example, if you want to compare a QString with a string
515 literal, you can write code like this and it will work as expected:
517 \snippet qstring/main.cpp 4
519 You can also pass string literals to functions that take QStrings
520 as arguments, invoking the QString(const char *)
521 constructor. Similarly, you can pass a QString to a function that
522 takes a \c{const char *} argument using the \l qPrintable() macro
523 which returns the given QString as a \c{const char *}. This is
524 equivalent to calling <QString>.toLocal8Bit().constData().
526 \section1 Manipulating String Data
528 QString provides the following basic functions for modifying the
529 character data: append(), prepend(), insert(), replace(), and
530 remove(). For example:
532 \snippet qstring/main.cpp 5
534 If you are building a QString gradually and know in advance
535 approximately how many characters the QString will contain, you
536 can call reserve(), asking QString to preallocate a certain amount
537 of memory. You can also call capacity() to find out how much
538 memory QString actually allocated.
540 The replace() and remove() functions' first two arguments are the
541 position from which to start erasing and the number of characters
542 that should be erased. If you want to replace all occurrences of
543 a particular substring with another, use one of the two-parameter
546 A frequent requirement is to remove whitespace characters from a
547 string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace
548 from both ends of a QString, use the trimmed() function. If you
549 want to remove whitespace from both ends and replace multiple
550 consecutive whitespaces with a single space character within the
551 string, use simplified().
553 If you want to find all occurrences of a particular character or
554 substring in a QString, use the indexOf() or lastIndexOf()
555 functions. The former searches forward starting from a given index
556 position, the latter searches backward. Both return the index
557 position of the character or substring if they find it; otherwise,
558 they return -1. For example, here's a typical loop that finds all
559 occurrences of a particular substring:
561 \snippet qstring/main.cpp 6
563 QString provides many functions for converting numbers into
564 strings and strings into numbers. See the arg() functions, the
565 setNum() functions, the number() static functions, and the
566 toInt(), toDouble(), and similar functions.
568 To get an upper- or lowercase version of a string use toUpper() or
571 Lists of strings are handled by the QStringList class. You can
572 split a string into a list of strings using the split() function,
573 and join a list of strings into a single string with an optional
574 separator using QStringList::join(). You can obtain a list of
575 strings from a string list that contain a particular substring or
576 that match a particular QRegExp using the QStringList::filter()
579 \section1 Querying String Data
581 If you want to see if a QString starts or ends with a particular
582 substring use startsWith() or endsWith(). If you simply want to
583 check whether a QString contains a particular character or
584 substring, use the contains() function. If you want to find out
585 how many times a particular character or substring occurs in the
588 QStrings can be compared using overloaded operators such as \l
589 operator<(), \l operator<=(), \l operator==(), \l operator>=(),
590 and so on. Note that the comparison is based exclusively on the
591 numeric Unicode values of the characters. It is very fast, but is
592 not what a human would expect; the QString::localeAwareCompare()
593 function is a better choice for sorting user-interface strings.
595 To obtain a pointer to the actual character data, call data() or
596 constData(). These functions return a pointer to the beginning of
597 the QChar data. The pointer is guaranteed to remain valid until a
598 non-const function is called on the QString.
600 \section1 Converting Between 8-Bit Strings and Unicode Strings
602 QString provides the following three functions that return a
603 \c{const char *} version of the string as QByteArray: toUtf8(),
604 toLatin1(), and toLocal8Bit().
607 \li toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
608 \li toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a
609 superset of US-ASCII (ANSI X3.4-1986) that supports the entire
610 Unicode character set through multibyte sequences.
611 \li toLocal8Bit() returns an 8-bit string using the system's local
615 To convert from one of these encodings, QString provides
616 fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other
617 encodings are supported through the QTextCodec class.
619 As mentioned above, QString provides a lot of functions and
620 operators that make it easy to interoperate with \c{const char *}
621 strings. But this functionality is a double-edged sword: It makes
622 QString more convenient to use if all strings are US-ASCII or
623 Latin-1, but there is always the risk that an implicit conversion
624 from or to \c{const char *} is done using the wrong 8-bit
625 encoding. To minimize these risks, you can turn off these implicit
626 conversions by defining the following two preprocessor symbols:
629 \li \c QT_NO_CAST_FROM_ASCII disables automatic conversions from
630 C string literals and pointers to Unicode.
631 \li \c QT_NO_CAST_TO_ASCII disables automatic conversion from QString
635 One way to define these preprocessor symbols globally for your
636 application is to add the following entry to your
637 \l{qmake Project Files}{qmake project file}:
639 \snippet code/src_corelib_tools_qstring.cpp 0
641 You then need to explicitly call fromUtf8(), fromLatin1(),
642 or fromLocal8Bit() to construct a QString from an
643 8-bit string, or use the lightweight QLatin1String class, for
646 \snippet code/src_corelib_tools_qstring.cpp 1
648 Similarly, you must call toLatin1(), toUtf8(), or
649 toLocal8Bit() explicitly to convert the QString to an 8-bit
650 string. (Other encodings are supported through the QTextCodec
655 \li Note for C Programmers
659 Due to C++'s type system and the fact that QString is
660 \l{implicitly shared}, QStrings may be treated like \c{int}s or
661 other basic types. For example:
663 \snippet qstring/main.cpp 7
665 The \c result variable, is a normal variable allocated on the
666 stack. When \c return is called, and because we're returning by
667 value, the copy constructor is called and a copy of the string is
668 returned. No actual copying takes place thanks to the implicit
673 \section1 Distinction Between Null and Empty Strings
675 For historical reasons, QString distinguishes between a null
676 string and an empty string. A \e null string is a string that is
677 initialized using QString's default constructor or by passing
678 (const char *)0 to the constructor. An \e empty string is any
679 string with size 0. A null string is always empty, but an empty
680 string isn't necessarily null:
682 \snippet qstring/main.cpp 8
684 All functions except isNull() treat null strings the same as empty
685 strings. For example, toUtf8().constData() returns a pointer to a
686 '\\0' character for a null string (\e not a null pointer), and
687 QString() compares equal to QString(""). We recommend that you
688 always use the isEmpty() function and avoid isNull().
690 \section1 Argument Formats
692 In member functions where an argument \e format can be specified
693 (e.g., arg(), number()), the argument \e format can be one of the
697 \header \li Format \li Meaning
698 \row \li \c e \li format as [-]9.9e[+|-]999
699 \row \li \c E \li format as [-]9.9E[+|-]999
700 \row \li \c f \li format as [-]9.9
701 \row \li \c g \li use \c e or \c f format, whichever is the most concise
702 \row \li \c G \li use \c E or \c f format, whichever is the most concise
705 A \e precision is also specified with the argument \e format. For
706 the 'e', 'E', and 'f' formats, the \e precision represents the
707 number of digits \e after the decimal point. For the 'g' and 'G'
708 formats, the \e precision represents the maximum number of
709 significant digits (trailing zeroes are omitted).
711 \section1 More Efficient String Construction
713 Many strings are known at compile time. But the trivial
714 constructor QString("Hello"), will copy the contents of the string,
715 treating the contents as Latin-1. To avoid this one can use the
716 QStringLiteral macro to directly create the required data at compile
717 time. Constructing a QString out of the literal does then not cause
718 any overhead at runtime.
720 A slightly less efficient way is to use QLatin1String. This class wraps
721 a C string literal, precalculates it length at compile time and can
722 then be used for faster comparison with QStrings and conversion to
723 QStrings than a regular C string literal.
725 Using the QString \c{'+'} operator, it is easy to construct a
726 complex string from multiple substrings. You will often write code
729 \snippet qstring/stringbuilder.cpp 0
731 There is nothing wrong with either of these string constructions,
732 but there are a few hidden inefficiencies. Beginning with Qt 4.6,
733 you can eliminate them.
735 First, multiple uses of the \c{'+'} operator usually means
736 multiple memory allocations. When concatenating \e{n} substrings,
737 where \e{n > 2}, there can be as many as \e{n - 1} calls to the
740 In 4.6, an internal template class \c{QStringBuilder} has been
741 added along with a few helper functions. This class is marked
742 internal and does not appear in the documentation, because you
743 aren't meant to instantiate it in your code. Its use will be
744 automatic, as described below. The class is found in
745 \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
748 \c{QStringBuilder} uses expression templates and reimplements the
749 \c{'%'} operator so that when you use \c{'%'} for string
750 concatenation instead of \c{'+'}, multiple substring
751 concatenations will be postponed until the final result is about
752 to be assigned to a QString. At this point, the amount of memory
753 required for the final result is known. The memory allocator is
754 then called \e{once} to get the required space, and the substrings
755 are copied into it one by one.
757 Additional efficiency is gained by inlining and reduced reference
758 counting (the QString created from a \c{QStringBuilder} typically
759 has a ref count of 1, whereas QString::append() needs an extra
762 There are three ways you can access this improved method of string
763 construction. The straightforward way is to include
764 \c{QStringBuilder} wherever you want to use it, and use the
765 \c{'%'} operator instead of \c{'+'} when concatenating strings:
767 \snippet qstring/stringbuilder.cpp 5
769 A more global approach which is the most convenient but
770 not entirely source compatible, is to this define in your
773 \snippet qstring/stringbuilder.cpp 3
775 and the \c{'+'} will automatically be performed as the
776 \c{QStringBuilder} \c{'%'} everywhere.
778 \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
782 \enum QString::SplitBehavior
784 This enum specifies how the split() function should behave with
785 respect to empty strings.
787 \value KeepEmptyParts If a field is empty, keep it in the result.
788 \value SkipEmptyParts If a field is empty, don't include it in the result.
793 /*! \typedef QString::ConstIterator
795 Qt-style synonym for QString::const_iterator.
798 /*! \typedef QString::Iterator
800 Qt-style synonym for QString::iterator.
803 /*! \typedef QString::const_iterator
805 The QString::const_iterator typedef provides an STL-style const
806 iterator for QString.
808 \sa QString::iterator
811 /*! \typedef QString::iterator
813 The QString::iterator typedef provides an STL-style non-const
814 iterator for QString.
816 \sa QString::const_iterator
820 \typedef QString::const_reference
822 The QString::const_reference typedef provides an STL-style
823 const reference for QString.
826 \typedef QString::reference
828 The QString::const_reference typedef provides an STL-style
829 reference for QString.
832 \typedef QString::value_type
834 The QString::const_reference typedef provides an STL-style
835 value type for QString.
838 /*! \fn QString::iterator QString::begin()
840 Returns an \l{STL-style iterator} pointing to the first character in
843 \sa constBegin(), end()
846 /*! \fn QString::const_iterator QString::begin() const
851 /*! \fn QString::const_iterator QString::cbegin() const
854 Returns a const \l{STL-style iterator} pointing to the first character
860 /*! \fn QString::const_iterator QString::constBegin() const
862 Returns a const \l{STL-style iterator} pointing to the first character
865 \sa begin(), constEnd()
868 /*! \fn QString::iterator QString::end()
870 Returns an \l{STL-style iterator} pointing to the imaginary character
871 after the last character in the string.
873 \sa begin(), constEnd()
876 /*! \fn QString::const_iterator QString::end() const
881 /*! \fn QString::const_iterator QString::cend() const
884 Returns a const \l{STL-style iterator} pointing to the imaginary
885 item after the last item in the list.
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
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 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 fromUtf8() function.
925 This constructor is only available if Qt is configured with STL
926 compatibility enabled.
928 \sa 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 \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4()
941 /*! \fn QString QString::fromWCharArray(const wchar_t *string, int size)
944 Returns a copy of the \a string, where the encoding of \a string depends on
945 the size of wchar. If wchar is 4 bytes, the \a string is interpreted as ucs-4,
946 if wchar is 2 bytes it is interpreted as ucs-2.
948 If \a size is -1 (default), the \a string has to be 0 terminated.
950 \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
953 /*! \fn std::wstring QString::toStdWString() const
955 Returns a std::wstring object with the data contained in this
956 QString. The std::wstring is encoded in utf16 on platforms where
957 wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
958 where wchar_t is 4 bytes wide (most Unix systems).
960 This operator is mostly useful to pass a QString to a function
961 that accepts a std::wstring object.
963 \sa utf16(), toLatin1(), toUtf8(), toLocal8Bit()
966 // ### replace with QCharIterator
967 int QString::toUcs4_helper(const ushort *uc, int length, uint *out)
970 for (; i < length; ++i) {
972 if (QChar::isHighSurrogate(u) && i + 1 < length) {
973 ushort low = uc[i+1];
974 if (QChar::isLowSurrogate(low)) {
976 u = QChar::surrogateToUcs4(u, low);
984 /*! \fn int QString::toWCharArray(wchar_t *array) const
987 Fills the \a array with the data contained in this QString object.
988 The array is encoded in utf16 on platforms where
989 wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
990 where wchar_t is 4 bytes wide (most Unix systems).
992 \a array has to be allocated by the caller and contain enough space to
993 hold the complete string (allocating the array with the same length as the
994 string is always sufficient).
996 This function returns the actual length of the string in \a array.
998 \note This function does not append a null character to the array.
1000 \sa utf16(), toUcs4(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString()
1003 /*! \fn QString::QString(const QString &other)
1005 Constructs a copy of \a other.
1007 This operation takes \l{constant time}, because QString is
1008 \l{implicitly shared}. This makes returning a QString from a
1009 function very fast. If a shared instance is modified, it will be
1010 copied (copy-on-write), and that takes \l{linear time}.
1016 Constructs a string initialized with the first \a size characters
1017 of the QChar array \a unicode.
1019 If \a unicode is 0, a null string is constructed.
1021 If \a size is negative, \a unicode is assumed to point to a nul-terminated
1022 array and its length is determined dynamically. The terminating
1023 nul-character is not considered part of the string.
1025 QString makes a deep copy of the string data. The unicode data is copied as
1026 is and the Byte Order Mark is preserved if present.
1030 QString::QString(const QChar *unicode, int size)
1033 d = Data::sharedNull();
1037 while (unicode[size] != 0)
1041 d = Data::allocate(0);
1043 d = Data::allocate(size + 1);
1046 memcpy(d->data(), unicode, size * sizeof(QChar));
1047 d->data()[size] = '\0';
1053 Constructs a string of the given \a size with every character set
1058 QString::QString(int size, QChar ch)
1061 d = Data::allocate(0);
1063 d = Data::allocate(size + 1);
1066 d->data()[size] = '\0';
1067 ushort *i = d->data() + size;
1068 ushort *b = d->data();
1069 const ushort value = ch.unicode();
1075 /*! \fn QString::QString(int size, Qt::Initialization)
1078 Constructs a string of the given \a size without initializing the
1079 characters. This is only used in \c QStringBuilder::toString().
1081 QString::QString(int size, Qt::Initialization)
1083 d = Data::allocate(size + 1);
1086 d->data()[size] = '\0';
1089 /*! \fn QString::QString(QLatin1String str)
1091 Constructs a copy of the Latin-1 string \a str.
1097 Constructs a string of size 1 containing the character \a ch.
1099 QString::QString(QChar ch)
1101 d = Data::allocate(2);
1104 d->data()[0] = ch.unicode();
1105 d->data()[1] = '\0';
1108 /*! \fn QString::QString(const QByteArray &ba)
1110 Constructs a string initialized with the byte array \a ba. The
1111 given byte array is converted to Unicode using fromUtf8(). Stops
1112 copying at the first 0 character, otherwise copies the entire byte
1115 You can disable this constructor by defining \c
1116 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1117 can be useful if you want to ensure that all user-visible strings
1118 go through QObject::tr(), for example.
1120 \sa fromLatin1(), fromLocal8Bit(), fromUtf8()
1123 /*! \fn QString::QString(const Null &)
1127 /*! \fn QString &QString::operator=(const Null &)
1132 \fn QString::~QString()
1134 Destroys the string.
1138 /*! \fn void QString::swap(QString &other)
1141 Swaps string \a other with this string. This operation is very fast and
1145 /*! \fn void QString::detach()
1150 /*! \fn bool QString::isDetached() const
1155 /*! \fn bool QString::isSharedWith(const QString &other) const
1161 Sets the size of the string to \a size characters.
1163 If \a size is greater than the current size, the string is
1164 extended to make it \a size characters long with the extra
1165 characters added to the end. The new characters are uninitialized.
1167 If \a size is less than the current size, characters are removed
1172 \snippet qstring/main.cpp 45
1174 If you want to append a certain number of identical characters to
1175 the string, use \l operator+=() as follows rather than resize():
1177 \snippet qstring/main.cpp 46
1179 If you want to expand the string so that it reaches a certain
1180 width and fill the new positions with a particular character, use
1181 the leftJustified() function:
1183 If \a size is negative, it is equivalent to passing zero.
1185 \snippet qstring/main.cpp 47
1187 \sa truncate(), reserve()
1190 void QString::resize(int size)
1195 if (IS_RAW_DATA(d) && !d->ref.isShared() && size < d->size) {
1200 if (size == 0 && !d->capacityReserved) {
1201 Data *x = Data::allocate(0);
1202 if (!d->ref.deref())
1203 Data::deallocate(d);
1206 if (d->ref.isShared() || uint(size) + 1u > d->alloc
1207 || (!d->capacityReserved && size < d->size
1208 && uint(size) + 1u < uint(d->alloc >> 1)))
1209 reallocData(uint(size) + 1u, true);
1212 d->data()[size] = '\0';
1217 /*! \fn int QString::capacity() const
1219 Returns the maximum number of characters that can be stored in
1220 the string without forcing a reallocation.
1222 The sole purpose of this function is to provide a means of fine
1223 tuning QString's memory usage. In general, you will rarely ever
1224 need to call this function. If you want to know how many
1225 characters are in the string, call size().
1227 \sa reserve(), squeeze()
1231 \fn void QString::reserve(int size)
1233 Attempts to allocate memory for at least \a size characters. If
1234 you know in advance how large the string will be, you can call
1235 this function, and if you resize the string often you are likely
1236 to get better performance. If \a size is an underestimate, the
1237 worst that will happen is that the QString will be a bit slower.
1239 The sole purpose of this function is to provide a means of fine
1240 tuning QString's memory usage. In general, you will rarely ever
1241 need to call this function. If you want to change the size of the
1242 string, call resize().
1244 This function is useful for code that needs to build up a long
1245 string and wants to avoid repeated reallocation. In this example,
1246 we want to add to the string until some condition is true, and
1247 we're fairly sure that size is large enough to make a call to
1248 reserve() worthwhile:
1250 \snippet qstring/main.cpp 44
1252 \sa squeeze(), capacity()
1256 \fn void QString::squeeze()
1258 Releases any memory not required to store the character data.
1260 The sole purpose of this function is to provide a means of fine
1261 tuning QString's memory usage. In general, you will rarely ever
1262 need to call this function.
1264 \sa reserve(), capacity()
1267 void QString::reallocData(uint alloc, bool grow)
1270 alloc = qAllocMore(alloc * sizeof(QChar), sizeof(Data)) / sizeof(QChar);
1272 if (d->ref.isShared() || IS_RAW_DATA(d)) {
1273 Data::AllocationOptions allocOptions(d->capacityReserved ? Data::CapacityReserved : 0);
1274 Data *x = Data::allocate(alloc, allocOptions);
1276 x->size = qMin(int(alloc) - 1, d->size);
1277 ::memcpy(x->data(), d->data(), x->size * sizeof(QChar));
1278 x->data()[x->size] = 0;
1279 if (!d->ref.deref())
1280 Data::deallocate(d);
1283 Data *p = static_cast<Data *>(::realloc(d, sizeof(Data) + alloc * sizeof(QChar)));
1287 d->offset = sizeof(QStringData);
1291 void QString::expand(int i)
1294 resize(qMax(i + 1, sz));
1295 if (d->size - 1 > sz) {
1296 ushort *n = d->data() + d->size - 1;
1297 ushort *e = d->data() + sz;
1303 /*! \fn void QString::clear()
1305 Clears the contents of the string and makes it empty.
1307 \sa resize(), isEmpty()
1310 /*! \fn QString &QString::operator=(const QString &other)
1312 Assigns \a other to this string and returns a reference to this
1316 QString &QString::operator=(const QString &other)
1319 if (!d->ref.deref())
1320 Data::deallocate(d);
1326 /*! \fn QString &QString::operator=(QLatin1String str)
1328 \overload operator=()
1330 Assigns the Latin-1 string \a str to this string.
1333 /*! \fn QString &QString::operator=(const QByteArray &ba)
1335 \overload operator=()
1337 Assigns \a ba to this string. The byte array is converted to Unicode
1338 using the fromUtf8() function. This function stops conversion at the
1339 first NUL character found, or the end of the \a ba byte array.
1341 You can disable this operator by defining \c
1342 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1343 can be useful if you want to ensure that all user-visible strings
1344 go through QObject::tr(), for example.
1347 /*! \fn QString &QString::operator=(const char *str)
1349 \overload operator=()
1351 Assigns \a str to this string. The const char pointer is converted
1352 to Unicode using the fromUtf8() function.
1354 You can disable this operator by defining \c
1355 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1356 can be useful if you want to ensure that all user-visible strings
1357 go through QObject::tr(), for example.
1360 /*! \fn QString &QString::operator=(char ch)
1362 \overload operator=()
1364 Assigns character \a ch to this string. Note that the character is
1365 converted to Unicode using the fromLatin1() function, unlike other 8-bit
1366 functions that operate on UTF-8 data.
1368 You can disable this operator by defining \c
1369 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1370 can be useful if you want to ensure that all user-visible strings
1371 go through QObject::tr(), for example.
1375 \overload operator=()
1377 Sets the string to contain the single character \a ch.
1379 QString &QString::operator=(QChar ch)
1381 return operator=(QString(ch));
1385 \fn QString& QString::insert(int position, const QString &str)
1387 Inserts the string \a str at the given index \a position and
1388 returns a reference to this string.
1392 \snippet qstring/main.cpp 26
1394 If the given \a position is greater than size(), the array is
1395 first extended using resize().
1397 \sa append(), prepend(), replace(), remove()
1402 \fn QString &QString::insert(int position, QLatin1String str)
1405 Inserts the Latin-1 string \a str at the given index \a position.
1407 QString &QString::insert(int i, QLatin1String str)
1409 const uchar *s = (const uchar *)str.latin1();
1410 if (i < 0 || !s || !(*s))
1413 int len = str.size();
1414 expand(qMax(d->size, i) + len - 1);
1416 ::memmove(d->data() + i + len, d->data() + i, (d->size - i - len) * sizeof(QChar));
1417 for (int j = 0; j < len; ++j)
1418 d->data()[i + j] = s[j];
1423 \fn QString& QString::insert(int position, const QChar *unicode, int size)
1426 Inserts the first \a size characters of the QChar array \a unicode
1427 at the given index \a position in the string.
1429 QString& QString::insert(int i, const QChar *unicode, int size)
1431 if (i < 0 || size <= 0)
1434 const ushort *s = (const ushort *)unicode;
1435 if (s >= d->data() && s < d->data() + d->alloc) {
1436 // Part of me - take a copy
1437 ushort *tmp = static_cast<ushort *>(::malloc(size * sizeof(QChar)));
1439 memcpy(tmp, s, size * sizeof(QChar));
1440 insert(i, reinterpret_cast<const QChar *>(tmp), size);
1445 expand(qMax(d->size, i) + size - 1);
1447 ::memmove(d->data() + i + size, d->data() + i, (d->size - i - size) * sizeof(QChar));
1448 memcpy(d->data() + i, s, size * sizeof(QChar));
1453 \fn QString& QString::insert(int position, QChar ch)
1456 Inserts \a ch at the given index \a position in the string.
1459 QString& QString::insert(int i, QChar ch)
1465 expand(qMax(i, d->size));
1466 ::memmove(d->data() + i + 1, d->data() + i, (d->size - i - 1) * sizeof(QChar));
1467 d->data()[i] = ch.unicode();
1472 Appends the string \a str onto the end of this string.
1476 \snippet qstring/main.cpp 9
1478 This is the same as using the insert() function:
1480 \snippet qstring/main.cpp 10
1482 The append() function is typically very fast (\l{constant time}),
1483 because QString preallocates extra space at the end of the string
1484 data so it can grow without reallocating the entire string each
1487 \sa operator+=(), prepend(), insert()
1489 QString &QString::append(const QString &str)
1491 if (str.d != Data::sharedNull()) {
1492 if (d == Data::sharedNull()) {
1495 if (d->ref.isShared() || uint(d->size + str.d->size) + 1u > d->alloc)
1496 reallocData(uint(d->size + str.d->size) + 1u, true);
1497 memcpy(d->data() + d->size, str.d->data(), str.d->size * sizeof(QChar));
1498 d->size += str.d->size;
1499 d->data()[d->size] = '\0';
1508 Appends the Latin-1 string \a str to this string.
1510 QString &QString::append(QLatin1String str)
1512 const uchar *s = (const uchar *)str.latin1();
1514 int len = str.size();
1515 if (d->ref.isShared() || uint(d->size + len) + 1u > d->alloc)
1516 reallocData(uint(d->size + len) + 1u, true);
1517 ushort *i = d->data() + d->size;
1518 while ((*i++ = *s++))
1525 /*! \fn QString &QString::append(const QByteArray &ba)
1529 Appends the byte array \a ba to this string. The given byte array
1530 is converted to Unicode using the fromUtf8() function.
1532 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1533 when you compile your applications. This can be useful if you want
1534 to ensure that all user-visible strings go through QObject::tr(),
1538 /*! \fn QString &QString::append(const char *str)
1542 Appends the string \a str to this string. The given const char
1543 pointer is converted to Unicode using the fromUtf8() function.
1545 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
1546 when you compile your applications. This can be useful if you want
1547 to ensure that all user-visible strings go through QObject::tr(),
1554 Appends the character \a ch to this string.
1556 QString &QString::append(QChar ch)
1558 if (d->ref.isShared() || uint(d->size) + 2u > d->alloc)
1559 reallocData(uint(d->size) + 2u, true);
1560 d->data()[d->size++] = ch.unicode();
1561 d->data()[d->size] = '\0';
1565 /*! \fn QString &QString::prepend(const QString &str)
1567 Prepends the string \a str to the beginning of this string and
1568 returns a reference to this string.
1572 \snippet qstring/main.cpp 36
1574 \sa append(), insert()
1577 /*! \fn QString &QString::prepend(QLatin1String str)
1581 Prepends the Latin-1 string \a str to this string.
1584 /*! \fn QString &QString::prepend(const QByteArray &ba)
1588 Prepends the byte array \a ba to this string. The byte array is
1589 converted to Unicode using the fromUtf8() function.
1591 You can disable this function by defining \c
1592 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1593 can be useful if you want to ensure that all user-visible strings
1594 go through QObject::tr(), for example.
1597 /*! \fn QString &QString::prepend(const char *str)
1601 Prepends the string \a str to this string. The const char pointer
1602 is converted to Unicode using the fromUtf8() function.
1604 You can disable this function by defining \c
1605 QT_NO_CAST_FROM_ASCII when you compile your applications. This
1606 can be useful if you want to ensure that all user-visible strings
1607 go through QObject::tr(), for example.
1610 /*! \fn QString &QString::prepend(QChar ch)
1614 Prepends the character \a ch to this string.
1618 \fn QString &QString::remove(int position, int n)
1620 Removes \a n characters from the string, starting at the given \a
1621 position index, and returns a reference to the string.
1623 If the specified \a position index is within the string, but \a
1624 position + \a n is beyond the end of the string, the string is
1625 truncated at the specified \a position.
1627 \snippet qstring/main.cpp 37
1629 \sa insert(), replace()
1631 QString &QString::remove(int pos, int len)
1633 if (pos < 0) // count from end of string
1635 if (pos < 0 || pos >= d->size) {
1637 } else if (len >= d->size - pos) {
1638 resize(pos); // truncate
1639 } else if (len > 0) {
1641 memmove(d->data() + pos, d->data() + pos + len,
1642 (d->size - pos - len + 1) * sizeof(ushort));
1649 Removes every occurrence of the given \a str string in this
1650 string, and returns a reference to this string.
1652 If \a cs is Qt::CaseSensitive (default), the search is
1653 case sensitive; otherwise the search is case insensitive.
1655 This is the same as \c replace(str, "", cs).
1659 QString &QString::remove(const QString &str, Qt::CaseSensitivity cs)
1663 while ((i = indexOf(str, i, cs)) != -1)
1664 remove(i, str.d->size);
1670 Removes every occurrence of the character \a ch in this string, and
1671 returns a reference to this string.
1673 If \a cs is Qt::CaseSensitive (default), the search is case
1674 sensitive; otherwise the search is case insensitive.
1678 \snippet qstring/main.cpp 38
1680 This is the same as \c replace(ch, "", cs).
1684 QString &QString::remove(QChar ch, Qt::CaseSensitivity cs)
1687 ushort c = ch.unicode();
1688 if (cs == Qt::CaseSensitive) {
1690 if (d->data()[i] == ch)
1697 if (foldCase(d->data()[i]) == c)
1706 \fn QString &QString::remove(const QRegExp &rx)
1708 Removes every occurrence of the regular expression \a rx in the
1709 string, and returns a reference to the string. For example:
1711 \snippet qstring/main.cpp 39
1713 \sa indexOf(), lastIndexOf(), replace()
1717 \fn QString &QString::remove(const QRegularExpression &re)
1720 Removes every occurrence of the regular expression \a re in the
1721 string, and returns a reference to the string. For example:
1723 \snippet qstring/main.cpp 96
1725 \sa indexOf(), lastIndexOf(), replace()
1729 \fn QString &QString::replace(int position, int n, const QString &after)
1731 Replaces \a n characters beginning at index \a position with
1732 the string \a after and returns a reference to this string.
1736 \snippet qstring/main.cpp 40
1738 \sa insert(), remove()
1740 QString &QString::replace(int pos, int len, const QString &after)
1742 QString copy = after;
1743 return replace(pos, len, copy.constData(), copy.length());
1747 \fn QString &QString::replace(int position, int n, const QChar *unicode, int size)
1749 Replaces \a n characters beginning at index \a position with the
1750 first \a size characters of the QChar array \a unicode and returns a
1751 reference to this string.
1753 QString &QString::replace(int pos, int len, const QChar *unicode, int size)
1755 if (pos < 0 || pos > d->size)
1757 if (pos + len > d->size)
1758 len = d->size - pos;
1761 replace_helper(&index, 1, len, unicode, size);
1766 \fn QString &QString::replace(int position, int n, QChar after)
1769 Replaces \a n characters beginning at index \a position with the
1770 character \a after and returns a reference to this string.
1772 QString &QString::replace(int pos, int len, QChar after)
1774 return replace(pos, len, &after, 1);
1779 Replaces every occurrence of the string \a before with the string \a
1780 after and returns a reference to this string.
1782 If \a cs is Qt::CaseSensitive (default), the search is case
1783 sensitive; otherwise the search is case insensitive.
1787 \snippet qstring/main.cpp 41
1789 \note The replacement text is not rescanned after it is inserted.
1793 \snippet qstring/main.cpp 86
1795 QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs)
1797 return replace(before.constData(), before.size(), after.constData(), after.size(), cs);
1803 void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen)
1805 // copy *after in case it lies inside our own d->data() area
1806 // (which we could possibly invalidate via a realloc or corrupt via memcpy operations.)
1807 QChar *afterBuffer = const_cast<QChar *>(after);
1808 if (after >= reinterpret_cast<QChar *>(d->data()) && after < reinterpret_cast<QChar *>(d->data()) + d->size) {
1809 afterBuffer = static_cast<QChar *>(::malloc(alen*sizeof(QChar)));
1810 Q_CHECK_PTR(afterBuffer);
1811 ::memcpy(afterBuffer, after, alen*sizeof(QChar));
1818 for (int i = 0; i < nIndices; ++i)
1819 memcpy(d->data() + indices[i], afterBuffer, alen * sizeof(QChar));
1820 } else if (alen < blen) {
1821 // replace from front
1823 uint to = indices[0];
1825 memcpy(d->data()+to, after, alen*sizeof(QChar));
1827 uint movestart = indices[0] + blen;
1828 for (int i = 1; i < nIndices; ++i) {
1829 int msize = indices[i] - movestart;
1831 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1835 memcpy(d->data() + to, afterBuffer, alen*sizeof(QChar));
1838 movestart = indices[i] + blen;
1840 int msize = d->size - movestart;
1842 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
1843 resize(d->size - nIndices*(blen-alen));
1845 // replace from back
1846 int adjust = nIndices*(alen-blen);
1847 int newLen = d->size + adjust;
1848 int moveend = d->size;
1853 int movestart = indices[nIndices] + blen;
1854 int insertstart = indices[nIndices] + nIndices*(alen-blen);
1855 int moveto = insertstart + alen;
1856 memmove(d->data() + moveto, d->data() + movestart,
1857 (moveend - movestart)*sizeof(QChar));
1858 memcpy(d->data() + insertstart, afterBuffer, alen*sizeof(QChar));
1859 moveend = movestart-blen;
1862 } QT_CATCH(const std::bad_alloc &) {
1863 if (afterBuffer != after)
1864 ::free(afterBuffer);
1867 if (afterBuffer != after)
1868 ::free(afterBuffer);
1875 Replaces each occurrence in this string of the first \a blen
1876 characters of \a before with the first \a alen characters of \a
1877 after and returns a reference to this string.
1879 If \a cs is Qt::CaseSensitive (default), the search is case
1880 sensitive; otherwise the search is case insensitive.
1882 QString &QString::replace(const QChar *before, int blen,
1883 const QChar *after, int alen,
1884 Qt::CaseSensitivity cs)
1890 if (cs == Qt::CaseSensitive && before == after && blen == alen)
1893 if (alen == 0 && blen == 0)
1896 QStringMatcher matcher(before, blen, cs);
1902 while (pos < 1023) {
1903 index = matcher.indexIn(*this, index);
1906 indices[pos++] = index;
1908 // avoid infinite loop
1915 replace_helper(indices, pos, blen, after, alen);
1919 // index has to be adjusted in case we get back into the loop above.
1920 index += pos*(alen-blen);
1928 Replaces every occurrence of the character \a ch in the string with
1929 \a after and returns a reference to this string.
1931 If \a cs is Qt::CaseSensitive (default), the search is case
1932 sensitive; otherwise the search is case insensitive.
1934 QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs)
1936 if (after.d->size == 0)
1937 return remove(ch, cs);
1939 if (after.d->size == 1)
1940 return replace(ch, after.d->data()[0], cs);
1945 ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode());
1951 if (cs == Qt::CaseSensitive) {
1952 while (pos < 1023 && index < d->size) {
1953 if (d->data()[index] == cc)
1954 indices[pos++] = index;
1958 while (pos < 1023 && index < d->size) {
1959 if (QChar::toCaseFolded(d->data()[index]) == cc)
1960 indices[pos++] = index;
1967 replace_helper(indices, pos, 1, after.constData(), after.d->size);
1971 // index has to be adjusted in case we get back into the loop above.
1972 index += pos*(after.d->size - 1);
1979 Replaces every occurrence of the character \a before with the
1980 character \a after and returns a reference to this string.
1982 If \a cs is Qt::CaseSensitive (default), the search is case
1983 sensitive; otherwise the search is case insensitive.
1985 QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs)
1987 ushort a = after.unicode();
1988 ushort b = before.unicode();
1991 ushort *i = d->data();
1992 const ushort *e = i + d->size;
1993 if (cs == Qt::CaseSensitive) {
2000 if (foldCase(*i) == b)
2011 Replaces every occurrence of the string \a before with the string \a
2012 after and returns a reference to this string.
2014 If \a cs is Qt::CaseSensitive (default), the search is case
2015 sensitive; otherwise the search is case insensitive.
2017 \note The text is not rescanned after a replacement.
2019 QString &QString::replace(QLatin1String before, QLatin1String after, Qt::CaseSensitivity cs)
2021 int alen = after.size();
2022 QVarLengthArray<ushort> a(alen);
2023 for (int i = 0; i < alen; ++i)
2024 a[i] = (uchar)after.latin1()[i];
2025 int blen = before.size();
2026 QVarLengthArray<ushort> b(blen);
2027 for (int i = 0; i < blen; ++i)
2028 b[i] = (uchar)before.latin1()[i];
2029 return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs);
2036 Replaces every occurrence of the string \a before with the string \a
2037 after and returns a reference to this string.
2039 If \a cs is Qt::CaseSensitive (default), the search is case
2040 sensitive; otherwise the search is case insensitive.
2042 \note The text is not rescanned after a replacement.
2044 QString &QString::replace(QLatin1String before, const QString &after, Qt::CaseSensitivity cs)
2046 int blen = before.size();
2047 QVarLengthArray<ushort> b(blen);
2048 for (int i = 0; i < blen; ++i)
2049 b[i] = (uchar)before.latin1()[i];
2050 return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs);
2057 Replaces every occurrence of the string \a before with the string \a
2058 after and returns a reference to this string.
2060 If \a cs is Qt::CaseSensitive (default), the search is case
2061 sensitive; otherwise the search is case insensitive.
2063 \note The text is not rescanned after a replacement.
2065 QString &QString::replace(const QString &before, QLatin1String after, Qt::CaseSensitivity cs)
2067 int alen = after.size();
2068 QVarLengthArray<ushort> a(alen);
2069 for (int i = 0; i < alen; ++i)
2070 a[i] = (uchar)after.latin1()[i];
2071 return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs);
2078 Replaces every occurrence of the character \a c with the string \a
2079 after and returns a reference to this string.
2081 If \a cs is Qt::CaseSensitive (default), the search is case
2082 sensitive; otherwise the search is case insensitive.
2084 \note The text is not rescanned after a replacement.
2086 QString &QString::replace(QChar c, QLatin1String after, Qt::CaseSensitivity cs)
2088 int alen = after.size();
2089 QVarLengthArray<ushort> a(alen);
2090 for (int i = 0; i < alen; ++i)
2091 a[i] = (uchar)after.latin1()[i];
2092 return replace(&c, 1, (const QChar *)a.data(), alen, cs);
2098 Returns true if string \a s1 is equal to string \a s2; otherwise
2101 The comparison is based exclusively on the numeric Unicode values of
2102 the characters and is very fast, but is not what a human would
2103 expect. Consider sorting user-interface strings with
2104 localeAwareCompare().
2106 bool operator==(const QString &s1, const QString &s2)
2108 if (s1.d->size != s2.d->size)
2111 return qMemEquals(s1.d->data(), s2.d->data(), s1.d->size);
2115 \overload operator==()
2117 bool QString::operator==(QLatin1String other) const
2119 if (d->size != other.size())
2125 const ushort *uc = d->data();
2126 const ushort *e = uc + d->size;
2127 const uchar *c = (uchar *)other.latin1();
2138 /*! \fn bool QString::operator==(const QByteArray &other) const
2140 \overload operator==()
2142 The \a other byte array is converted to a QString using the
2143 fromUtf8() function. This function stops conversion at the
2144 first NUL character found, or the end of the byte array.
2146 You can disable this operator by defining \c
2147 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2148 can be useful if you want to ensure that all user-visible strings
2149 go through QObject::tr(), for example.
2152 /*! \fn bool QString::operator==(const char *other) const
2154 \overload operator==()
2156 The \a other const char pointer is converted to a QString using
2157 the fromUtf8() function.
2159 You can disable this operator by defining \c
2160 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2161 can be useful if you want to ensure that all user-visible strings
2162 go through QObject::tr(), for example.
2167 Returns true if string \a s1 is lexically less than string
2168 \a s2; otherwise returns false.
2170 The comparison is based exclusively on the numeric Unicode values
2171 of the characters and is very fast, but is not what a human would
2172 expect. Consider sorting user-interface strings using the
2173 QString::localeAwareCompare() function.
2175 bool operator<(const QString &s1, const QString &s2)
2177 return ucstrcmp(s1.constData(), s1.length(), s2.constData(), s2.length()) < 0;
2181 \overload operator<()
2183 bool QString::operator<(QLatin1String other) const
2185 const uchar *c = (uchar *) other.latin1();
2189 const ushort *uc = d->data();
2190 const ushort *e = uc + qMin(d->size, other.size());
2198 return (uc == e ? d->size < other.size() : *uc < *c);
2201 /*! \fn bool QString::operator<(const QByteArray &other) const
2203 \overload operator<()
2205 The \a other byte array is converted to a QString using the
2206 fromUtf8() function. If any NUL characters ('\\0') are embedded
2207 in the byte array, they will be included in the transformation.
2209 You can disable this operator by defining \c
2210 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2211 can be useful if you want to ensure that all user-visible strings
2212 go through QObject::tr(), for example.
2215 /*! \fn bool QString::operator<(const char *other) const
2217 \overload operator<()
2219 The \a other const char pointer is converted to a QString using
2220 the fromUtf8() function.
2222 You can disable this operator by defining \c
2223 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2224 can be useful if you want to ensure that all user-visible strings
2225 go through QObject::tr(), for example.
2228 /*! \fn bool QString::operator<=(const QString &s1, const QString &s2)
2230 Returns true if string \a s1 is lexically less than or equal to
2231 string \a s2; otherwise returns false.
2233 The comparison is based exclusively on the numeric Unicode values
2234 of the characters and is very fast, but is not what a human would
2235 expect. Consider sorting user-interface strings with
2236 localeAwareCompare().
2239 /*! \fn bool QString::operator<=(QLatin1String other) const
2241 \overload operator<=()
2244 /*! \fn bool QString::operator<=(const QByteArray &other) const
2246 \overload operator<=()
2248 The \a other byte array is converted to a QString using the
2249 fromUtf8() function. If any NUL characters ('\\0') are embedded
2250 in the byte array, they will be included in the transformation.
2252 You can disable this operator by defining \c
2253 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2254 can be useful if you want to ensure that all user-visible strings
2255 go through QObject::tr(), for example.
2258 /*! \fn bool QString::operator<=(const char *other) const
2260 \overload operator<=()
2262 The \a other const char pointer is converted to a QString using
2263 the fromUtf8() function.
2265 You can disable this operator by defining \c
2266 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2267 can be useful if you want to ensure that all user-visible strings
2268 go through QObject::tr(), for example.
2271 /*! \fn bool QString::operator>(const QString &s1, const QString &s2)
2273 Returns true if string \a s1 is lexically greater than string \a
2274 s2; otherwise returns false.
2276 The comparison is based exclusively on the numeric Unicode values
2277 of the characters and is very fast, but is not what a human would
2278 expect. Consider sorting user-interface strings with
2279 localeAwareCompare().
2283 \overload operator>()
2285 bool QString::operator>(QLatin1String other) const
2287 const uchar *c = (uchar *) other.latin1();
2288 if (!c || *c == '\0')
2291 const ushort *uc = d->data();
2292 const ushort *e = uc + qMin(d->size, other.size());
2300 return (uc == e) ? d->size > other.size() : *uc > *c;
2303 /*! \fn bool QString::operator>(const QByteArray &other) const
2305 \overload operator>()
2307 The \a other byte array is converted to a QString using the
2308 fromUtf8() function. If any NUL characters ('\\0') are embedded
2309 in the byte array, they will be included in the transformation.
2311 You can disable this operator by defining \c
2312 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2313 can be useful if you want to ensure that all user-visible strings
2314 go through QObject::tr(), for example.
2317 /*! \fn bool QString::operator>(const char *other) const
2319 \overload operator>()
2321 The \a other const char pointer is converted to a QString using
2322 the fromUtf8() function.
2324 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2325 when you compile your applications. This can be useful if you want
2326 to ensure that all user-visible strings go through QObject::tr(),
2330 /*! \fn bool operator>=(const QString &s1, const QString &s2)
2333 Returns true if string \a s1 is lexically greater than or equal to
2334 string \a s2; otherwise returns false.
2336 The comparison is based exclusively on the numeric Unicode values
2337 of the characters and is very fast, but is not what a human would
2338 expect. Consider sorting user-interface strings with
2339 localeAwareCompare().
2342 /*! \fn bool QString::operator>=(QLatin1String other) const
2344 \overload operator>=()
2347 /*! \fn bool QString::operator>=(const QByteArray &other) const
2349 \overload operator>=()
2351 The \a other byte array is converted to a QString using the
2352 fromUtf8() function. If any NUL characters ('\\0') are embedded in
2353 the byte array, they will be included in the transformation.
2355 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2356 when you compile your applications. This can be useful if you want
2357 to ensure that all user-visible strings go through QObject::tr(),
2361 /*! \fn bool QString::operator>=(const char *other) const
2363 \overload operator>=()
2365 The \a other const char pointer is converted to a QString using
2366 the fromUtf8() function.
2368 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2369 when you compile your applications. This can be useful if you want
2370 to ensure that all user-visible strings go through QObject::tr(),
2374 /*! \fn bool operator!=(const QString &s1, const QString &s2)
2377 Returns true if string \a s1 is not equal to string \a s2;
2378 otherwise returns false.
2380 The comparison is based exclusively on the numeric Unicode values
2381 of the characters and is very fast, but is not what a human would
2382 expect. Consider sorting user-interface strings with
2383 localeAwareCompare().
2386 /*! \fn bool QString::operator!=(QLatin1String other) const
2388 \overload operator!=()
2391 /*! \fn bool QString::operator!=(const QByteArray &other) const
2393 \overload operator!=()
2395 The \a other byte array is converted to a QString using the
2396 fromUtf8() function. If any NUL characters ('\\0') are embedded
2397 in the byte array, they will be included in the transformation.
2399 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2400 when you compile your applications. This can be useful if you want
2401 to ensure that all user-visible strings go through QObject::tr(),
2405 /*! \fn bool QString::operator!=(const char *other) const
2407 \overload operator!=()
2409 The \a other const char pointer is converted to a QString using
2410 the fromUtf8() function.
2412 You can disable this operator by defining \c
2413 QT_NO_CAST_FROM_ASCII when you compile your applications. This
2414 can be useful if you want to ensure that all user-visible strings
2415 go through QObject::tr(), for example.
2419 Returns the index position of the first occurrence of the string \a
2420 str in this string, searching forward from index position \a
2421 from. Returns -1 if \a str is not found.
2423 If \a cs is Qt::CaseSensitive (default), the search is case
2424 sensitive; otherwise the search is case insensitive.
2428 \snippet qstring/main.cpp 24
2430 If \a from is -1, the search starts at the last character; if it is
2431 -2, at the next to last character and so on.
2433 \sa lastIndexOf(), contains(), count()
2435 int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2437 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2442 Returns the index position of the first occurrence of the string \a
2443 str in this string, searching forward from index position \a
2444 from. Returns -1 if \a str is not found.
2446 If \a cs is Qt::CaseSensitive (default), the search is case
2447 sensitive; otherwise the search is case insensitive.
2451 \snippet qstring/main.cpp 24
2453 If \a from is -1, the search starts at the last character; if it is
2454 -2, at the next to last character and so on.
2456 \sa lastIndexOf(), contains(), count()
2459 int QString::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
2461 return qt_find_latin1_string(unicode(), size(), str, from, cs);
2465 const QChar *haystack0, int haystackLen, int from,
2466 const QChar *needle0, int needleLen, Qt::CaseSensitivity cs)
2468 const int l = haystackLen;
2469 const int sl = needleLen;
2472 if (uint(sl + from) > (uint)l)
2480 return findChar(haystack0, haystackLen, needle0[0], from, cs);
2483 We use the Boyer-Moore algorithm in cases where the overhead
2484 for the skip table should pay off, otherwise we use a simple
2487 if (l > 500 && sl > 5)
2488 return qFindStringBoyerMoore(haystack0, haystackLen, from,
2489 needle0, needleLen, cs);
2492 We use some hashing for efficiency's sake. Instead of
2493 comparing strings, we compare the hash value of str with that
2494 of a part of this QString. Only if that matches, we call
2495 ucstrncmp() or ucstrnicmp().
2497 const ushort *needle = (const ushort *)needle0;
2498 const ushort *haystack = (const ushort *)haystack0 + from;
2499 const ushort *end = (const ushort *)haystack0 + (l-sl);
2500 const int sl_minus_1 = sl-1;
2501 int hashNeedle = 0, hashHaystack = 0, idx;
2503 if (cs == Qt::CaseSensitive) {
2504 for (idx = 0; idx < sl; ++idx) {
2505 hashNeedle = ((hashNeedle<<1) + needle[idx]);
2506 hashHaystack = ((hashHaystack<<1) + haystack[idx]);
2508 hashHaystack -= haystack[sl_minus_1];
2510 while (haystack <= end) {
2511 hashHaystack += haystack[sl_minus_1];
2512 if (hashHaystack == hashNeedle
2513 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2514 return haystack - (const ushort *)haystack0;
2520 const ushort *haystack_start = (const ushort *)haystack0;
2521 for (idx = 0; idx < sl; ++idx) {
2522 hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle);
2523 hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start);
2525 hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start);
2527 while (haystack <= end) {
2528 hashHaystack += foldCase(haystack + sl_minus_1, haystack_start);
2529 if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2530 return haystack - (const ushort *)haystack0;
2532 REHASH(foldCase(haystack, haystack_start));
2542 Returns the index position of the first occurrence of the
2543 character \a ch in the string, searching forward from index
2544 position \a from. Returns -1 if \a ch could not be found.
2546 int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2548 return findChar(unicode(), length(), ch, from, cs);
2556 Returns the index position of the first occurrence of the string
2557 reference \a str in this string, searching forward from index
2558 position \a from. Returns -1 if \a str is not found.
2560 If \a cs is Qt::CaseSensitive (default), the search is case
2561 sensitive; otherwise the search is case insensitive.
2563 int QString::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2565 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
2568 static int lastIndexOfHelper(const ushort *haystack, int from, const ushort *needle, int sl, Qt::CaseSensitivity cs)
2571 See indexOf() for explanations.
2574 const ushort *end = haystack;
2576 const int sl_minus_1 = sl-1;
2577 const ushort *n = needle+sl_minus_1;
2578 const ushort *h = haystack+sl_minus_1;
2579 int hashNeedle = 0, hashHaystack = 0, idx;
2581 if (cs == Qt::CaseSensitive) {
2582 for (idx = 0; idx < sl; ++idx) {
2583 hashNeedle = ((hashNeedle<<1) + *(n-idx));
2584 hashHaystack = ((hashHaystack<<1) + *(h-idx));
2586 hashHaystack -= *haystack;
2588 while (haystack >= end) {
2589 hashHaystack += *haystack;
2590 if (hashHaystack == hashNeedle
2591 && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0)
2592 return haystack - end;
2594 REHASH(haystack[sl]);
2597 for (idx = 0; idx < sl; ++idx) {
2598 hashNeedle = ((hashNeedle<<1) + foldCase(n-idx, needle));
2599 hashHaystack = ((hashHaystack<<1) + foldCase(h-idx, end));
2601 hashHaystack -= foldCase(haystack, end);
2603 while (haystack >= end) {
2604 hashHaystack += foldCase(haystack, end);
2605 if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0)
2606 return haystack - end;
2608 REHASH(foldCase(haystack + sl, end));
2615 Returns the index position of the last occurrence of the string \a
2616 str in this string, searching backward from index position \a
2617 from. If \a from is -1 (default), the search starts at the last
2618 character; if \a from is -2, at the next to last character and so
2619 on. Returns -1 if \a str is not found.
2621 If \a cs is Qt::CaseSensitive (default), the search is case
2622 sensitive; otherwise the search is case insensitive.
2626 \snippet qstring/main.cpp 29
2628 \sa indexOf(), contains(), count()
2630 int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
2632 const int sl = str.d->size;
2634 return lastIndexOf(QChar(str.d->data()[0]), from, cs);
2636 const int l = d->size;
2640 if (from == l && sl == 0)
2642 if (from < 0 || from >= l || delta < 0)
2647 return lastIndexOfHelper(d->data(), from, str.d->data(), str.d->size, cs);
2652 \overload lastIndexOf()
2654 Returns the index position of the last occurrence of the string \a
2655 str in this string, searching backward from index position \a
2656 from. If \a from is -1 (default), the search starts at the last
2657 character; if \a from is -2, at the next to last character and so
2658 on. Returns -1 if \a str is not found.
2660 If \a cs is Qt::CaseSensitive (default), the search is case
2661 sensitive; otherwise the search is case insensitive.
2665 \snippet qstring/main.cpp 29
2667 \sa indexOf(), contains(), count()
2669 int QString::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
2671 const int sl = str.size();
2673 return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
2675 const int l = d->size;
2679 if (from == l && sl == 0)
2681 if (from < 0 || from >= l || delta < 0)
2686 QVarLengthArray<ushort> s(sl);
2687 for (int i = 0; i < sl; ++i)
2688 s[i] = str.latin1()[i];
2690 return lastIndexOfHelper(d->data(), from, s.data(), sl, cs);
2694 \overload lastIndexOf()
2696 Returns the index position of the last occurrence of the character
2697 \a ch, searching backward from position \a from.
2699 int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
2701 return qt_last_index_of(unicode(), size(), ch, from, cs);
2706 \overload lastIndexOf()
2708 Returns the index position of the last occurrence of the string
2709 reference \a str in this string, searching backward from index
2710 position \a from. If \a from is -1 (default), the search starts at
2711 the last character; if \a from is -2, at the next to last character
2712 and so on. Returns -1 if \a str is not found.
2714 If \a cs is Qt::CaseSensitive (default), the search is case
2715 sensitive; otherwise the search is case insensitive.
2717 \sa indexOf(), contains(), count()
2719 int QString::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
2721 const int sl = str.size();
2723 return lastIndexOf(str.at(0), from, cs);
2725 const int l = d->size;
2729 if (from == l && sl == 0)
2731 if (from < 0 || from >= l || delta < 0)
2736 return lastIndexOfHelper(d->data(), from, reinterpret_cast<const ushort*>(str.unicode()),
2740 #ifndef QT_NO_REGEXP
2741 struct QStringCapture
2751 Replaces every occurrence of the regular expression \a rx in the
2752 string with \a after. Returns a reference to the string. For
2755 \snippet qstring/main.cpp 42
2757 For regular expressions containing \l{capturing parentheses},
2758 occurrences of \b{\\1}, \b{\\2}, ..., in \a after are replaced
2759 with \a{rx}.cap(1), cap(2), ...
2761 \snippet qstring/main.cpp 43
2763 \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap()
2765 QString& QString::replace(const QRegExp &rx, const QString &after)
2769 if (isEmpty() && rx2.indexIn(*this) == -1)
2772 reallocData(uint(d->size) + 1u);
2775 int numCaptures = rx2.captureCount();
2776 int al = after.length();
2777 QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
2779 if (numCaptures > 0) {
2780 const QChar *uc = after.unicode();
2781 int numBackRefs = 0;
2783 for (int i = 0; i < al - 1; i++) {
2784 if (uc[i] == QLatin1Char('\\')) {
2785 int no = uc[i + 1].digitValue();
2786 if (no > 0 && no <= numCaptures)
2792 This is the harder case where we have back-references.
2794 if (numBackRefs > 0) {
2795 QVarLengthArray<QStringCapture, 16> captures(numBackRefs);
2798 for (int i = 0; i < al - 1; i++) {
2799 if (uc[i] == QLatin1Char('\\')) {
2800 int no = uc[i + 1].digitValue();
2801 if (no > 0 && no <= numCaptures) {
2802 QStringCapture capture;
2807 int secondDigit = uc[i + 2].digitValue();
2808 if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
2809 no = (no * 10) + secondDigit;
2815 captures[j++] = capture;
2820 while (index <= length()) {
2821 index = rx2.indexIn(*this, index, caretMode);
2825 QString after2(after);
2826 for (j = numBackRefs - 1; j >= 0; j--) {
2827 const QStringCapture &capture = captures[j];
2828 after2.replace(capture.pos, capture.len, rx2.cap(capture.no));
2831 replace(index, rx2.matchedLength(), after2);
2832 index += after2.length();
2834 // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*"))
2835 if (rx2.matchedLength() == 0)
2838 caretMode = QRegExp::CaretWontMatch;
2845 This is the simple and optimized case where we don't have
2848 while (index != -1) {
2852 } replacements[2048];
2856 while (pos < 2047) {
2857 index = rx2.indexIn(*this, index, caretMode);
2860 int ml = rx2.matchedLength();
2861 replacements[pos].pos = index;
2862 replacements[pos++].length = ml;
2865 // avoid infinite loop
2871 replacements[pos].pos = d->size;
2872 int newlen = d->size + adjust;
2874 // to continue searching at the right position after we did
2875 // the first round of replacements
2879 newstring.reserve(newlen + 1);
2880 QChar *newuc = newstring.data();
2885 int copyend = replacements[i].pos;
2886 int size = copyend - copystart;
2887 memcpy(uc, d->data() + copystart, size * sizeof(QChar));
2889 memcpy(uc, after.d->data(), al * sizeof(QChar));
2891 copystart = copyend + replacements[i].length;
2894 memcpy(uc, d->data() + copystart, (d->size - copystart) * sizeof(QChar));
2895 newstring.resize(newlen);
2897 caretMode = QRegExp::CaretWontMatch;
2903 #ifndef QT_NO_REGEXP
2904 #ifndef QT_BOOTSTRAPPED
2909 Replaces every occurrence of the regular expression \a re in the
2910 string with \a after. Returns a reference to the string. For
2913 \snippet qstring/main.cpp 87
2915 For regular expressions containing capturing groups,
2916 occurrences of \b{\\1}, \b{\\2}, ..., in \a after are replaced
2917 with the string captured by the corresponding capturing group.
2919 \snippet qstring/main.cpp 88
2921 \sa indexOf(), lastIndexOf(), remove(), QRegularExpression, QRegularExpressionMatch
2923 QString &QString::replace(const QRegularExpression &re, const QString &after)
2925 if (!re.isValid()) {
2926 qWarning("QString::replace: invalid QRegularExpresssion object");
2930 const QString copy(*this);
2931 QRegularExpressionMatchIterator iterator = re.globalMatch(copy);
2932 if (!iterator.hasNext()) // no matches at all
2935 reallocData(uint(d->size) + 1u);
2937 int numCaptures = re.captureCount();
2939 // 1. build the backreferences vector, holding where the backreferences
2940 // are in the replacement string
2941 QVector<QStringCapture> backReferences;
2942 const int al = after.length();
2943 const QChar *ac = after.unicode();
2945 for (int i = 0; i < al - 1; i++) {
2946 if (ac[i] == QLatin1Char('\\')) {
2947 int no = ac[i + 1].digitValue();
2948 if (no > 0 && no <= numCaptures) {
2949 QStringCapture backReference;
2950 backReference.pos = i;
2951 backReference.len = 2;
2954 int secondDigit = ac[i + 2].digitValue();
2955 if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
2956 no = (no * 10) + secondDigit;
2957 ++backReference.len;
2961 backReference.no = no;
2962 backReferences.append(backReference);
2967 // 2. iterate on the matches. For every match, copy in chunks
2968 // - the part before the match
2969 // - the after string, with the proper replacements for the backreferences
2971 int newLength = 0; // length of the new string, with all the replacements
2973 QVector<QStringRef> chunks;
2974 while (iterator.hasNext()) {
2975 QRegularExpressionMatch match = iterator.next();
2977 // add the part before the match
2978 len = match.capturedStart() - lastEnd;
2980 chunks << copy.midRef(lastEnd, len);
2985 // add the after string, with replacements for the backreferences
2986 foreach (const QStringCapture &backReference, backReferences) {
2987 // part of "after" before the backreference
2988 len = backReference.pos - lastEnd;
2990 chunks << after.midRef(lastEnd, len);
2994 // backreference itself
2995 len = match.capturedLength(backReference.no);
2997 chunks << copy.midRef(match.capturedStart(backReference.no), len);
3001 lastEnd = backReference.pos + backReference.len;
3004 // add the last part of the after string
3005 len = after.length() - lastEnd;
3007 chunks << after.midRef(lastEnd, len);
3011 lastEnd = match.capturedEnd();
3014 // 3. trailing string after the last match
3015 if (copy.length() > lastEnd) {
3016 chunks << copy.midRef(lastEnd);
3017 newLength += copy.length() - lastEnd;
3020 // 4. assemble the chunks together
3024 foreach (const QStringRef &chunk, chunks) {
3025 int len = chunk.length();
3026 memcpy(uc + i, chunk.unicode(), len * sizeof(QChar));
3032 #endif // QT_BOOTSTRAPPED
3033 #endif // QT_NO_REGEXP
3036 Returns the number of (potentially overlapping) occurrences of
3037 the string \a str in this string.
3039 If \a cs is Qt::CaseSensitive (default), the search is
3040 case sensitive; otherwise the search is case insensitive.
3042 \sa contains(), indexOf()
3045 int QString::count(const QString &str, Qt::CaseSensitivity cs) const
3047 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
3053 Returns the number of occurrences of character \a ch in the string.
3056 int QString::count(QChar ch, Qt::CaseSensitivity cs) const
3058 return qt_string_count(unicode(), size(), ch, cs);
3064 Returns the number of (potentially overlapping) occurrences of the
3065 string reference \a str in this string.
3067 If \a cs is Qt::CaseSensitive (default), the search is
3068 case sensitive; otherwise the search is case insensitive.
3070 \sa contains(), indexOf()
3072 int QString::count(const QStringRef &str, Qt::CaseSensitivity cs) const
3074 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
3078 /*! \fn bool QString::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
3080 Returns true if this string contains an occurrence of the string
3081 \a str; otherwise returns false.
3083 If \a cs is Qt::CaseSensitive (default), the search is
3084 case sensitive; otherwise the search is case insensitive.
3087 \snippet qstring/main.cpp 17
3089 \sa indexOf(), count()
3092 /*! \fn bool QString::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
3094 \overload contains()
3096 Returns true if this string contains an occurrence of the
3097 character \a ch; otherwise returns false.
3100 /*! \fn bool QString::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
3103 Returns true if this string contains an occurrence of the string
3104 reference \a str; otherwise returns false.
3106 If \a cs is Qt::CaseSensitive (default), the search is
3107 case sensitive; otherwise the search is case insensitive.
3109 \sa indexOf(), count()
3112 /*! \fn bool QString::contains(const QRegExp &rx) const
3114 \overload contains()
3116 Returns true if the regular expression \a rx matches somewhere in
3117 this string; otherwise returns false.
3120 /*! \fn bool QString::contains(QRegExp &rx) const
3121 \overload contains()
3124 Returns true if the regular expression \a rx matches somewhere in
3125 this string; otherwise returns false.
3127 If there is a match, the \a rx regular expression will contain the
3128 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3131 #ifndef QT_NO_REGEXP
3135 Returns the index position of the first match of the regular
3136 expression \a rx in the string, searching forward from index
3137 position \a from. Returns -1 if \a rx didn't match anywhere.
3141 \snippet qstring/main.cpp 25
3143 int QString::indexOf(const QRegExp& rx, int from) const
3146 return rx2.indexIn(*this, from);
3153 Returns the index position of the first match of the regular
3154 expression \a rx in the string, searching forward from index
3155 position \a from. Returns -1 if \a rx didn't match anywhere.
3157 If there is a match, the \a rx regular expression will contain the
3158 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3162 \snippet qstring/main.cpp 25
3164 int QString::indexOf(QRegExp& rx, int from) const
3166 return rx.indexIn(*this, from);
3170 \overload lastIndexOf()
3172 Returns the index position of the last match of the regular
3173 expression \a rx in the string, searching backward from index
3174 position \a from. Returns -1 if \a rx didn't match anywhere.
3178 \snippet qstring/main.cpp 30
3180 int QString::lastIndexOf(const QRegExp& rx, int from) const
3183 return rx2.lastIndexIn(*this, from);
3187 \overload lastIndexOf()
3190 Returns the index position of the last match of the regular
3191 expression \a rx in the string, searching backward from index
3192 position \a from. Returns -1 if \a rx didn't match anywhere.
3194 If there is a match, the \a rx regular expression will contain the
3195 matched captures (see QRegExp::matchedLength, QRegExp::cap).
3199 \snippet qstring/main.cpp 30
3201 int QString::lastIndexOf(QRegExp& rx, int from) const
3203 return rx.lastIndexIn(*this, from);
3209 Returns the number of times the regular expression \a rx matches
3212 This function counts overlapping matches, so in the example
3213 below, there are four instances of "ana" or "ama":
3215 \snippet qstring/main.cpp 18
3218 int QString::count(const QRegExp& rx) const
3224 while (index < len - 1) { // count overlapping matches
3225 index = rx2.indexIn(*this, index + 1);
3232 #endif // QT_NO_REGEXP
3234 #ifndef QT_NO_REGEXP
3235 #ifndef QT_BOOTSTRAPPED
3240 Returns the index position of the first match of the regular
3241 expression \a re in the string, searching forward from index
3242 position \a from. Returns -1 if \a re didn't match anywhere.
3246 \snippet qstring/main.cpp 93
3248 int QString::indexOf(const QRegularExpression& re, int from) const
3250 if (!re.isValid()) {
3251 qWarning("QString::indexOf: invalid QRegularExpresssion object");
3255 QRegularExpressionMatch match = re.match(*this, from);
3256 if (match.hasMatch())
3257 return match.capturedStart();
3263 \overload lastIndexOf()
3266 Returns the index position of the last match of the regular
3267 expression \a re in the string, which starts before the index
3268 position \a from. Returns -1 if \a re didn't match anywhere.
3272 \snippet qstring/main.cpp 94
3274 int QString::lastIndexOf(const QRegularExpression &re, int from) const
3276 if (!re.isValid()) {
3277 qWarning("QString::lastIndexOf: invalid QRegularExpresssion object");
3281 int endpos = (from < 0) ? (size() + from + 1) : (from + 1);
3283 QRegularExpressionMatchIterator iterator = re.globalMatch(*this);
3285 while (iterator.hasNext()) {
3286 QRegularExpressionMatch match = iterator.next();
3287 int start = match.capturedStart();
3297 /*! \overload contains()
3300 Returns true if the regular expression \a re matches somewhere in
3301 this string; otherwise returns false.
3303 bool QString::contains(const QRegularExpression &re) const
3305 if (!re.isValid()) {
3306 qWarning("QString::contains: invalid QRegularExpresssion object");
3309 QRegularExpressionMatch match = re.match(*this);
3310 return match.hasMatch();
3317 Returns the number of times the regular expression \a re matches
3320 This function counts overlapping matches, so in the example
3321 below, there are four instances of "ana" or "ama":
3323 \snippet qstring/main.cpp 95
3325 int QString::count(const QRegularExpression &re) const
3327 if (!re.isValid()) {
3328 qWarning("QString::count: invalid QRegularExpresssion object");
3334 while (index < len - 1) {
3335 QRegularExpressionMatch match = re.match(*this, index + 1);
3336 if (!match.hasMatch())
3338 index = match.capturedStart();
3343 #endif // QT_BOOTSTRAPPED
3344 #endif // QT_NO_REGEXP
3346 /*! \fn int QString::count() const
3355 \enum QString::SectionFlag
3357 This enum specifies flags that can be used to affect various
3358 aspects of the section() function's behavior with respect to
3359 separators and empty fields.
3361 \value SectionDefault Empty fields are counted, leading and
3362 trailing separators are not included, and the separator is
3363 compared case sensitively.
3365 \value SectionSkipEmpty Treat empty fields as if they don't exist,
3366 i.e. they are not considered as far as \e start and \e end are
3369 \value SectionIncludeLeadingSep Include the leading separator (if
3370 any) in the result string.
3372 \value SectionIncludeTrailingSep Include the trailing separator
3373 (if any) in the result string.
3375 \value SectionCaseInsensitiveSeps Compare the separator
3382 \fn QString QString::section(QChar sep, int start, int end = -1, SectionFlags flags) const
3384 This function returns a section of the string.
3386 This string is treated as a sequence of fields separated by the
3387 character, \a sep. The returned string consists of the fields from
3388 position \a start to position \a end inclusive. If \a end is not
3389 specified, all fields from position \a start to the end of the
3390 string are included. Fields are numbered 0, 1, 2, etc., counting
3391 from the left, and -1, -2, etc., counting from right to left.
3393 The \a flags argument can be used to affect some aspects of the
3394 function's behavior, e.g. whether to be case sensitive, whether
3395 to skip empty fields and how to deal with leading and trailing
3396 separators; see \l{SectionFlags}.
3398 \snippet qstring/main.cpp 52
3400 If \a start or \a end is negative, we count fields from the right
3401 of the string, the right-most field being -1, the one from
3402 right-most field being -2, and so on.
3404 \snippet qstring/main.cpp 53
3412 \snippet qstring/main.cpp 51
3413 \snippet qstring/main.cpp 54
3418 QString QString::section(const QString &sep, int start, int end, SectionFlags flags) const
3420 QStringList sections = split(sep, KeepEmptyParts,
3421 (flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive : Qt::CaseSensitive);
3422 if (sections.isEmpty())
3424 if (!(flags & SectionSkipEmpty)) {
3426 start += sections.count();
3428 end += sections.count();
3431 for (int k=0; k<sections.size(); ++k) {
3432 if (sections.at(k).isEmpty())
3436 start += sections.count() - skip;
3438 end += sections.count() - skip;
3442 int first_i = start, last_i = end;
3443 for (int i = 0; x <= end && i < sections.size(); ++i) {
3444 QString section = sections.at(i);
3445 const bool empty = section.isEmpty();
3455 if (!empty || !(flags & SectionSkipEmpty))
3458 if((flags & SectionIncludeLeadingSep) && first_i)
3460 if((flags & SectionIncludeTrailingSep) && last_i < sections.size()-1)
3465 #ifndef QT_NO_REGEXP
3466 class qt_section_chunk {
3468 qt_section_chunk(int l, QString s) { length = l; string = s; }
3473 static QString extractSections(const QList<qt_section_chunk> §ions,
3476 QString::SectionFlags flags)
3479 start += sections.count();
3481 end += sections.count();
3485 int first_i = start, last_i = end;
3486 for (int i = 0; x <= end && i < sections.size(); ++i) {
3487 const qt_section_chunk §ion = sections.at(i);
3488 const bool empty = (section.length == section.string.length());
3495 ret += section.string;
3497 ret += section.string.mid(section.length);
3499 if (!empty || !(flags & QString::SectionSkipEmpty))
3503 if ((flags & QString::SectionIncludeLeadingSep) && first_i < sections.size()) {
3504 const qt_section_chunk §ion = sections.at(first_i);
3505 ret.prepend(section.string.left(section.length));
3508 if ((flags & QString::SectionIncludeTrailingSep) && last_i+1 <= sections.size()-1) {
3509 const qt_section_chunk §ion = sections.at(last_i+1);
3510 ret += section.string.left(section.length);
3519 This string is treated as a sequence of fields separated by the
3520 regular expression, \a reg.
3522 \snippet qstring/main.cpp 55
3524 \warning Using this QRegExp version is much more expensive than
3525 the overloaded string and character versions.
3527 \sa split(), simplified()
3529 QString QString::section(const QRegExp ®, int start, int end, SectionFlags flags) const
3531 const QChar *uc = unicode();
3536 sep.setCaseSensitivity((flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive
3537 : Qt::CaseSensitive);
3539 QList<qt_section_chunk> sections;
3540 int n = length(), m = 0, last_m = 0, last_len = 0;
3541 while ((m = sep.indexIn(*this, m)) != -1) {
3542 sections.append(qt_section_chunk(last_len, QString(uc + last_m, m - last_m)));
3544 last_len = sep.matchedLength();
3545 m += qMax(sep.matchedLength(), 1);
3547 sections.append(qt_section_chunk(last_len, QString(uc + last_m, n - last_m)));
3549 return extractSections(sections, start, end, flags);
3553 #ifndef QT_NO_REGEXP
3554 #ifndef QT_BOOTSTRAPPED
3559 This string is treated as a sequence of fields separated by the
3560 regular expression, \a re.
3562 \snippet qstring/main.cpp 89
3564 \warning Using this QRegularExpression version is much more expensive than
3565 the overloaded string and character versions.
3567 \sa split(), simplified()
3569 QString QString::section(const QRegularExpression &re, int start, int end, SectionFlags flags) const
3571 if (!re.isValid()) {
3572 qWarning("QString::section: invalid QRegularExpression object");
3576 const QChar *uc = unicode();
3580 QRegularExpression sep(re);
3581 if (flags & SectionCaseInsensitiveSeps)
3582 sep.setPatternOptions(sep.patternOptions() | QRegularExpression::CaseInsensitiveOption);
3584 QList<qt_section_chunk> sections;
3585 int n = length(), m = 0, last_m = 0, last_len = 0;
3586 QRegularExpressionMatchIterator iterator = sep.globalMatch(*this);
3587 while (iterator.hasNext()) {
3588 QRegularExpressionMatch match = iterator.next();
3589 m = match.capturedStart();
3590 sections.append(qt_section_chunk(last_len, QString(uc + last_m, m - last_m)));
3592 last_len = match.capturedLength();
3594 sections.append(qt_section_chunk(last_len, QString(uc + last_m, n - last_m)));
3596 return extractSections(sections, start, end, flags);
3598 #endif // QT_BOOTSTRAPPED
3599 #endif // QT_NO_REGEXP
3602 Returns a substring that contains the \a n leftmost characters
3605 The entire string is returned if \a n is greater than size() or
3608 \snippet qstring/main.cpp 31
3610 \sa right(), mid(), startsWith()
3612 QString QString::left(int n) const
3614 if (n >= d->size || n < 0)
3616 return QString((const QChar*) d->data(), n);
3620 Returns a substring that contains the \a n rightmost characters
3623 The entire string is returned if \a n is greater than size() or
3626 \snippet qstring/main.cpp 48
3628 \sa left(), mid(), endsWith()
3630 QString QString::right(int n) const
3632 if (n >= d->size || n < 0)
3634 return QString((const QChar*) d->data() + d->size - n, n);
3638 Returns a string that contains \a n characters of this string,
3639 starting at the specified \a position index.
3641 Returns a null string if the \a position index exceeds the
3642 length of the string. If there are less than \a n characters
3643 available in the string starting at the given \a position, or if
3644 \a n is -1 (default), the function returns all characters that
3645 are available from the specified \a position.
3649 \snippet qstring/main.cpp 34
3654 QString QString::mid(int position, int n) const
3656 if (position > d->size)
3659 if (n < 0 || n + position >= d->size)
3661 if (n + position <= 0)
3666 } else if (n < 0 || n > d->size - position)
3667 n = d->size - position;
3668 if (position == 0 && n == d->size)
3670 return QString((const QChar*) d->data() + position, n);
3674 Returns true if the string starts with \a s; otherwise returns
3677 If \a cs is Qt::CaseSensitive (default), the search is
3678 case sensitive; otherwise the search is case insensitive.
3680 \snippet qstring/main.cpp 65
3684 bool QString::startsWith(const QString& s, Qt::CaseSensitivity cs) const
3686 return qt_starts_with(isNull() ? 0 : unicode(), size(),
3687 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3691 \overload startsWith()
3693 bool QString::startsWith(QLatin1String s, Qt::CaseSensitivity cs) const
3695 return qt_starts_with(isNull() ? 0 : unicode(), size(), s, cs);
3699 \overload startsWith()
3701 Returns true if the string starts with \a c; otherwise returns
3704 bool QString::startsWith(QChar c, Qt::CaseSensitivity cs) const
3707 && (cs == Qt::CaseSensitive
3709 : foldCase(d->data()[0]) == foldCase(c.unicode()));
3715 Returns true if the string starts with the string reference \a s;
3716 otherwise returns false.
3718 If \a cs is Qt::CaseSensitive (default), the search is case
3719 sensitive; otherwise the search is case insensitive.
3723 bool QString::startsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
3725 return qt_starts_with(isNull() ? 0 : unicode(), size(),
3726 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3730 Returns true if the string ends with \a s; otherwise returns
3733 If \a cs is Qt::CaseSensitive (default), the search is case
3734 sensitive; otherwise the search is case insensitive.
3736 \snippet qstring/main.cpp 20
3740 bool QString::endsWith(const QString& s, Qt::CaseSensitivity cs) const
3742 return qt_ends_with(isNull() ? 0 : unicode(), size(),
3743 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3748 \overload endsWith()
3749 Returns true if the string ends with the string reference \a s;
3750 otherwise returns false.
3752 If \a cs is Qt::CaseSensitive (default), the search is case
3753 sensitive; otherwise the search is case insensitive.
3757 bool QString::endsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
3759 return qt_ends_with(isNull() ? 0 : unicode(), size(),
3760 s.isNull() ? 0 : s.unicode(), s.size(), cs);
3765 \overload endsWith()
3767 bool QString::endsWith(QLatin1String s, Qt::CaseSensitivity cs) const
3769 return qt_ends_with(isNull() ? 0 : unicode(), size(), s, cs);
3773 Returns true if the string ends with \a c; otherwise returns
3776 \overload endsWith()
3778 bool QString::endsWith(QChar c, Qt::CaseSensitivity cs) const
3781 && (cs == Qt::CaseSensitive
3782 ? d->data()[d->size - 1] == c
3783 : foldCase(d->data()[d->size - 1]) == foldCase(c.unicode()));
3787 #if defined(__SSE2__)
3788 static inline __m128i mergeQuestionMarks(__m128i chunk)
3790 const __m128i questionMark = _mm_set1_epi16('?');
3793 // compare the unsigned shorts for the range 0x0100-0xFFFF
3794 // note on the use of _mm_cmpestrm:
3795 // The MSDN documentation online (http://technet.microsoft.com/en-us/library/bb514080.aspx)
3796 // says for range search the following:
3797 // For each character c in a, determine whether b0 <= c <= b1 or b2 <= c <= b3
3799 // However, all examples on the Internet, including from Intel
3800 // (see http://software.intel.com/en-us/articles/xml-parsing-accelerator-with-intel-streaming-simd-extensions-4-intel-sse4/)
3801 // put the range to be searched first
3803 // Disassembly and instruction-level debugging with GCC and ICC show
3804 // that they are doing the right thing. Inverting the arguments in the
3805 // instruction does cause a bunch of test failures.
3807 const int mode = _SIDD_UWORD_OPS | _SIDD_CMP_RANGES | _SIDD_UNIT_MASK;
3808 const __m128i rangeMatch = _mm_cvtsi32_si128(0xffff0100);
3809 const __m128i offLimitMask = _mm_cmpestrm(rangeMatch, 2, chunk, 8, mode);
3811 // replace the non-Latin 1 characters in the chunk with question marks
3812 chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask);
3814 // SSE has no compare instruction for unsigned comparison.
3815 // The variables must be shiffted + 0x8000 to be compared
3816 const __m128i signedBitOffset = _mm_set1_epi16(0x8000);
3817 const __m128i thresholdMask = _mm_set1_epi16(0xff + 0x8000);
3819 const __m128i signedChunk = _mm_add_epi16(chunk, signedBitOffset);
3820 const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask);
3823 // replace the non-Latin 1 characters in the chunk with question marks
3824 chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask);
3826 // offLimitQuestionMark contains '?' for each 16 bits that was off-limit
3827 // the 16 bits that were correct contains zeros
3828 const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark);
3830 // correctBytes contains the bytes that were in limit
3831 // the 16 bits that were off limits contains zeros
3832 const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk);
3834 // merge offLimitQuestionMark and correctBytes to have the result
3835 chunk = _mm_or_si128(correctBytes, offLimitQuestionMark);
3842 static QByteArray toLatin1_helper(const QChar *data, int length)
3847 const ushort *src = reinterpret_cast<const ushort *>(data);
3848 uchar *dst = (uchar*) ba.data();
3849 #if defined(__SSE2__)
3851 const int chunkCount = length >> 4; // divided by 16
3853 for (int i = 0; i < chunkCount; ++i) {
3854 __m128i chunk1 = _mm_loadu_si128((__m128i*)src); // load
3855 chunk1 = mergeQuestionMarks(chunk1);
3858 __m128i chunk2 = _mm_loadu_si128((__m128i*)src); // load
3859 chunk2 = mergeQuestionMarks(chunk2);
3862 // pack the two vector to 16 x 8bits elements
3863 const __m128i result = _mm_packus_epi16(chunk1, chunk2);
3865 _mm_storeu_si128((__m128i*)dst, result); // store
3868 length = length % 16;
3870 #elif defined(__ARM_NEON__)
3871 // Refer to the documentation of the SSE2 implementation
3872 // this use eactly the same method as for SSE except:
3873 // 1) neon has unsigned comparison
3874 // 2) packing is done to 64 bits (8 x 8bits component).
3876 const int chunkCount = length >> 3; // divided by 8
3877 const uint16x8_t questionMark = vdupq_n_u16('?'); // set
3878 const uint16x8_t thresholdMask = vdupq_n_u16(0xff); // set
3879 for (int i = 0; i < chunkCount; ++i) {
3880 uint16x8_t chunk = vld1q_u16((uint16_t *)src); // load
3883 const uint16x8_t offLimitMask = vcgtq_u16(chunk, thresholdMask); // chunk > thresholdMask
3884 const uint16x8_t offLimitQuestionMark = vandq_u16(offLimitMask, questionMark); // offLimitMask & questionMark
3885 const uint16x8_t correctBytes = vbicq_u16(chunk, offLimitMask); // !offLimitMask & chunk
3886 chunk = vorrq_u16(correctBytes, offLimitQuestionMark); // correctBytes | offLimitQuestionMark
3887 const uint8x8_t result = vmovn_u16(chunk); // narrowing move->packing
3888 vst1_u8(dst, result); // store
3891 length = length % 8;
3895 *dst++ = (*src>0xff) ? '?' : (uchar) *src;
3903 Returns a Latin-1 representation of the string as a QByteArray.
3905 The returned byte array is undefined if the string contains non-Latin1
3906 characters. Those characters may be suppressed or replaced with a
3909 \sa fromLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
3911 QByteArray QString::toLatin1() const
3913 return toLatin1_helper(unicode(), length());
3917 \fn QByteArray QString::toAscii() const
3919 Returns an 8-bit representation of the string as a QByteArray.
3921 This function does the same as toLatin1().
3923 Note that, despite the name, this function does not necessarily return an US-ASCII
3924 (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
3926 \sa fromAscii(), toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
3929 #if !defined(Q_OS_MAC) && defined(Q_OS_UNIX)
3930 static QByteArray toLocal8Bit_helper(const QChar *data, int length)
3932 #ifndef QT_NO_TEXTCODEC
3933 if (QTextCodec::codecForLocale())
3934 return QTextCodec::codecForLocale()->fromUnicode(data, length);
3935 #endif // QT_NO_TEXTCODEC
3936 return toLatin1_helper(data, length);
3941 Returns the local 8-bit representation of the string as a
3942 QByteArray. The returned byte array is undefined if the string
3943 contains characters not supported by the local 8-bit encoding.
3945 QTextCodec::codecForLocale() is used to perform the conversion from
3946 Unicode. If the locale encoding could not be determined, this function
3947 does the same as toLatin1().
3949 If this string contains any characters that cannot be encoded in the
3950 locale, the returned byte array is undefined. Those characters may be
3951 suppressed or replaced by another.
3953 \sa fromLocal8Bit(), toLatin1(), toUtf8(), QTextCodec
3955 QByteArray QString::toLocal8Bit() const
3957 #ifndef QT_NO_TEXTCODEC
3958 if (QTextCodec::codecForLocale())
3959 return QTextCodec::codecForLocale()->fromUnicode(*this);
3960 #endif // QT_NO_TEXTCODEC
3965 Returns a UTF-8 representation of the string as a QByteArray.
3967 UTF-8 is a Unicode codec and can represent all characters in a Unicode
3968 string like QString.
3970 However, in the Unicode range, there are certain codepoints that are not
3971 considered characters. The Unicode standard reserves the last two
3972 codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
3973 U+2FFFE, etc.), as well as 32 codepoints in the range U+FDD0..U+FDEF,
3974 inclusive, as non-characters. If any of those appear in the string, they
3975 may be discarded and will not appear in the UTF-8 representation, or they
3976 may be replaced by one or more replacement characters.
3978 \sa fromUtf8(), toLatin1(), toLocal8Bit(), QTextCodec
3980 QByteArray QString::toUtf8() const
3983 return QByteArray();
3985 return QUtf8::convertFromUnicode(constData(), length(), 0);
3991 Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
3993 UCS-4 is a Unicode codec and is lossless. All characters from this string
3994 can be encoded in UCS-4. The vector is not null terminated.
3996 \sa fromUtf8(), toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
3998 QVector<uint> QString::toUcs4() const
4000 QVector<uint> v(length());
4002 int len = toUcs4_helper(d->data(), length(), a);
4007 QString::Data *QString::fromLatin1_helper(const char *str, int size)
4011 d = Data::sharedNull();
4012 } else if (size == 0 || (!*str && size < 0)) {
4013 d = Data::allocate(0);
4016 size = qstrlen(str);
4017 d = Data::allocate(size + 1);
4020 d->data()[size] = '\0';
4021 ushort *dst = d->data();
4023 * Unpacking with SSE has been shown to improve performance on recent CPUs
4024 * The same method gives no improvement with NEON.
4026 #if defined(__SSE2__)
4028 int chunkCount = size >> 4; // divided by 16
4029 const __m128i nullMask = _mm_set1_epi32(0);
4030 for (int i = 0; i < chunkCount; ++i) {
4031 const __m128i chunk = _mm_loadu_si128((__m128i*)str); // load
4034 // unpack the first 8 bytes, padding with zeros
4035 const __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullMask);
4036 _mm_storeu_si128((__m128i*)dst, firstHalf); // store
4039 // unpack the last 8 bytes, padding with zeros
4040 const __m128i secondHalf = _mm_unpackhi_epi8 (chunk, nullMask);
4041 _mm_storeu_si128((__m128i*)dst, secondHalf); // store
4048 *dst++ = (uchar)*str++;
4053 QString::Data *QString::fromAscii_helper(const char *str, int size)
4055 QString s = fromUtf8(str, size);
4060 /*! \fn QString QString::fromLatin1(const char *str, int size)
4061 Returns a QString initialized with the first \a size characters
4062 of the Latin-1 string \a str.
4064 If \a size is -1 (default), it is taken to be strlen(\a
4067 \sa toLatin1(), fromUtf8(), fromLocal8Bit()
4071 /*! \fn QString QString::fromLocal8Bit(const char *str, int size)
4072 Returns a QString initialized with the first \a size characters
4073 of the 8-bit string \a str.
4075 If \a size is -1 (default), it is taken to be strlen(\a
4078 QTextCodec::codecForLocale() is used to perform the conversion.
4080 \sa toLocal8Bit(), fromLatin1(), fromUtf8()
4082 QString QString::fromLocal8Bit_helper(const char *str, int size)
4086 if (size == 0 || (!*str && size < 0)) {
4087 QStringDataPtr empty = { Data::allocate(0) };
4088 return QString(empty);
4090 #if !defined(QT_NO_TEXTCODEC)
4092 size = qstrlen(str);
4093 QTextCodec *codec = QTextCodec::codecForLocale();
4095 return codec->toUnicode(str, size);
4096 #endif // !QT_NO_TEXTCODEC
4097 return fromLatin1(str, size);
4100 /*! \fn QString QString::fromAscii(const char *, int size);
4103 Returns a QString initialized with the first \a size characters
4104 from the string \a str.
4106 If \a size is -1 (default), it is taken to be strlen(\a
4109 This function does the same as fromLatin1().
4111 \sa toAscii(), fromLatin1(), fromUtf8(), fromLocal8Bit()
4114 /*! \fn QString QString::fromUtf8(const char *str, int size)
4115 Returns a QString initialized with the first \a size bytes
4116 of the UTF-8 string \a str.
4118 If \a size is -1 (default), it is taken to be strlen(\a
4121 UTF-8 is a Unicode codec and can represent all characters in a Unicode
4122 string like QString. However, invalid sequences are possible with UTF-8
4123 and, if any such are found, they will be replaced with one or more
4124 "replacement characters", or suppressed. These include non-Unicode
4125 sequences, non-characters, overlong sequences or surrogate codepoints
4128 Non-characters are codepoints that the Unicode standard reserves and must
4129 not be used in text interchange. They are the last two codepoints in each
4130 Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well
4131 as 32 codepoints in the range U+FDD0..U+FDEF, inclusive.
4133 \sa toUtf8(), fromLatin1(), fromLocal8Bit()
4135 QString QString::fromUtf8_helper(const char *str, int size)
4140 Q_ASSERT(size != -1);
4141 return QUtf8::convertToUnicode(str, size, 0);
4145 Returns a QString initialized with the first \a size characters
4146 of the Unicode string \a unicode (ISO-10646-UTF-16 encoded).
4148 If \a size is -1 (default), \a unicode must be terminated
4151 This function checks for a Byte Order Mark (BOM). If it is missing,
4152 host byte order is assumed.
4154 This function is slow compared to the other Unicode conversions.
4155 Use QString(const QChar *, int) or QString(const QChar *) if possible.
4157 QString makes a deep copy of the Unicode data.
4159 \sa utf16(), setUtf16()
4161 QString QString::fromUtf16(const ushort *unicode, int size)
4167 while (unicode[size] != 0)
4170 return QUtf16::convertToUnicode((const char *)unicode, size*2, 0);
4177 Returns a QString initialized with the first \a size characters
4178 of the Unicode string \a unicode (ISO-10646-UCS-4 encoded).
4180 If \a size is -1 (default), \a unicode must be terminated
4183 \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray()
4185 QString QString::fromUcs4(const uint *unicode, int size)
4191 while (unicode[size] != 0)
4194 return QUtf32::convertToUnicode((const char *)unicode, size*4, 0);
4198 Resizes the string to \a size characters and copies \a unicode
4201 If \a unicode is 0, nothing is copied, but the string is still
4204 \sa unicode(), setUtf16()
4206 QString& QString::setUnicode(const QChar *unicode, int size)
4209 if (unicode && size)
4210 memcpy(d->data(), unicode, size * sizeof(QChar));
4215 \fn QString &QString::setUtf16(const ushort *unicode, int size)
4217 Resizes the string to \a size characters and copies \a unicode
4220 If \a unicode is 0, nothing is copied, but the string is still
4223 Note that unlike fromUtf16(), this function does not consider BOMs and
4224 possibly differing byte ordering.
4226 \sa utf16(), setUnicode()
4230 Returns a string that has whitespace removed from the start
4231 and the end, and that has each sequence of internal whitespace
4232 replaced with a single space.
4234 Whitespace means any character for which QChar::isSpace() returns
4235 true. This includes the ASCII characters '\\t', '\\n', '\\v',
4236 '\\f', '\\r', and ' '.
4240 \snippet qstring/main.cpp 57
4244 QString QString::simplified() const
4249 const QChar * const start = reinterpret_cast<QChar *>(d->data());
4250 const QChar *from = start;
4251 const QChar *fromEnd = start + d->size;
4256 if (++from == fromEnd) {
4257 // All-whitespace string
4258 QStringDataPtr empty = { Data::allocate(0) };
4259 return QString(empty);
4262 // This loop needs no underflow check, as we already determined that
4263 // the string contains non-whitespace. If the string has exactly one
4264 // non-whitespace, it will be checked twice - we can live with that.
4265 while (fromEnd[-1].isSpace())
4267 // The rest of the function depends on the fact that we already know
4268 // that the last character in the source is no whitespace.
4269 const QChar *copyFrom = from;
4272 if (++from == fromEnd) {
4273 // Only leading and/or trailing whitespace, if any at all
4274 return mid(copyFrom - start, from - copyFrom);
4279 if (ch != QLatin1Char(' ')) {
4280 copyCount = from - copyFrom;
4285 copyCount = from - copyFrom - 1;
4289 // 'from' now points at the non-trailing whitespace which made the
4290 // string not simplified in the first place. 'copyCount' is the number
4291 // of already simplified characters - at least one, obviously -
4292 // without a trailing space.
4293 QString result((fromEnd - from) + copyCount, Qt::Uninitialized);
4294 QChar *to = reinterpret_cast<QChar *>(result.d->data());
4295 ::memcpy(to, copyFrom, copyCount * 2);
4300 *to++ = QLatin1Char(' ');
4303 } while (ch.isSpace());
4304 if (from == fromEnd)
4309 if (from == fromEnd)
4311 } while (!ch.isSpace());
4316 result.truncate(to - reinterpret_cast<QChar *>(result.d->data()));
4321 Returns a string that has whitespace removed from the start and
4324 Whitespace means any character for which QChar::isSpace() returns
4325 true. This includes the ASCII characters '\\t', '\\n', '\\v',
4326 '\\f', '\\r', and ' '.
4330 \snippet qstring/main.cpp 82
4332 Unlike simplified(), trimmed() leaves internal whitespace alone.
4336 QString QString::trimmed() const
4340 const QChar *s = (const QChar*)d->data();
4341 if (!s->isSpace() && !s[d->size-1].isSpace())
4344 int end = d->size - 1;
4345 while (start<=end && s[start].isSpace()) // skip white space from start
4347 if (start <= end) { // only white space
4348 while (end && s[end].isSpace()) // skip white space from end
4351 int l = end - start + 1;
4353 QStringDataPtr empty = { Data::allocate(0) };
4354 return QString(empty);
4356 return QString(s + start, l);
4359 /*! \fn const QChar QString::at(int position) const
4361 Returns the character at the given index \a position in the
4364 The \a position must be a valid index position in the string
4365 (i.e., 0 <= \a position < size()).
4371 \fn QCharRef QString::operator[](int position)
4373 Returns the character at the specified \a position in the string as a
4374 modifiable reference.
4378 \snippet qstring/main.cpp 85
4380 The return value is of type QCharRef, a helper class for QString.
4381 When you get an object of type QCharRef, you can use it as if it
4382 were a QChar &. If you assign to it, the assignment will apply to
4383 the character in the QString from which you got the reference.
4389 \fn const QChar QString::operator[](int position) const
4391 \overload operator[]()
4394 /*! \fn QCharRef QString::operator[](uint position)
4396 \overload operator[]()
4398 Returns the character at the specified \a position in the string as a
4399 modifiable reference. Equivalent to \c at(position).
4402 /*! \fn const QChar QString::operator[](uint position) const
4404 \overload operator[]()
4408 \fn void QString::truncate(int position)
4410 Truncates the string at the given \a position index.
4412 If the specified \a position index is beyond the end of the
4413 string, nothing happens.
4417 \snippet qstring/main.cpp 83
4419 If \a position is negative, it is equivalent to passing zero.
4421 \sa chop(), resize(), left()
4424 void QString::truncate(int pos)
4432 Removes \a n characters from the end of the string.
4434 If \a n is greater than size(), the result is an empty string.
4437 \snippet qstring/main.cpp 15
4439 If you want to remove characters from the \e beginning of the
4440 string, use remove() instead.
4442 \sa truncate(), resize(), remove()
4444 void QString::chop(int n)
4447 resize(d->size - n);
4451 Sets every character in the string to character \a ch. If \a size
4452 is different from -1 (default), the string is resized to \a
4457 \snippet qstring/main.cpp 21
4462 QString& QString::fill(QChar ch, int size)
4464 resize(size < 0 ? d->size : size);
4466 QChar *i = (QChar*)d->data() + d->size;
4467 QChar *b = (QChar*)d->data();
4475 \fn int QString::length() const
4477 Returns the number of characters in this string. Equivalent to
4484 \fn int QString::size() const
4486 Returns the number of characters in this string.
4488 The last character in the string is at position size() - 1. In
4489 addition, QString ensures that the character at position size()
4490 is always '\\0', so that you can use the return value of data()
4491 and constData() as arguments to functions that expect
4492 '\\0'-terminated strings.
4496 \snippet qstring/main.cpp 58
4498 \sa isEmpty(), resize()
4501 /*! \fn bool QString::isNull() const
4503 Returns true if this string is null; otherwise returns false.
4507 \snippet qstring/main.cpp 28
4509 Qt makes a distinction between null strings and empty strings for
4510 historical reasons. For most applications, what matters is
4511 whether or not a string contains any data, and this can be
4512 determined using the isEmpty() function.
4517 /*! \fn bool QString::isEmpty() const
4519 Returns true if the string has no characters; otherwise returns
4524 \snippet qstring/main.cpp 27
4529 /*! \fn QString &QString::operator+=(const QString &other)
4531 Appends the string \a other onto the end of this string and
4532 returns a reference to this string.
4536 \snippet qstring/main.cpp 84
4538 This operation is typically very fast (\l{constant time}),
4539 because QString preallocates extra space at the end of the string
4540 data so it can grow without reallocating the entire string each
4543 \sa append(), prepend()
4546 /*! \fn QString &QString::operator+=(QLatin1String str)
4548 \overload operator+=()
4550 Appends the Latin-1 string \a str to this string.
4553 /*! \fn QString &QString::operator+=(const QByteArray &ba)
4555 \overload operator+=()
4557 Appends the byte array \a ba to this string. The byte array is converted
4558 to Unicode using the fromUtf8() function. If any NUL characters ('\\0')
4559 are embedded in the \a ba byte array, they will be included in the
4562 You can disable this function by defining \c
4563 QT_NO_CAST_FROM_ASCII when you compile your applications. This
4564 can be useful if you want to ensure that all user-visible strings
4565 go through QObject::tr(), for example.
4568 /*! \fn QString &QString::operator+=(const char *str)
4570 \overload operator+=()
4572 Appends the string \a str to this string. The const char pointer
4573 is converted to Unicode using the fromUtf8() function.
4575 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4576 when you compile your applications. This can be useful if you want
4577 to ensure that all user-visible strings go through QObject::tr(),
4581 /*! \fn QString &QString::operator+=(const QStringRef &str)
4583 \overload operator+=()
4585 Appends the string section referenced by \a str to this string.
4588 /*! \fn QString &QString::operator+=(char ch)
4590 \overload operator+=()
4592 Appends the character \a ch to this string. Note that the character is
4593 converted to Unicode using the fromLatin1() function, unlike other 8-bit
4594 functions that operate on UTF-8 data.
4596 You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
4597 when you compile your applications. This can be useful if you want
4598 to ensure that all user-visible strings go through QObject::tr(),
4602 /*! \fn QString &QString::operator+=(QChar ch)
4604 \overload operator+=()
4606 Appends the character \a ch to the string.
4609 /*! \fn QString &QString::operator+=(QChar::SpecialCharacter c)
4611 \overload operator+=()
4617 \fn bool operator==(const char *s1, const QString &s2)
4619 \overload operator==()
4622 Returns true if \a s1 is equal to \a s2; otherwise returns false.
4623 Note that no string is equal to \a s1 being 0.
4625 Equivalent to \c {s1 != 0 && compare(s1, s2) == 0}.
4627 \sa QString::compare()
4631 \fn bool operator!=(const char *s1, const QString &s2)
4634 Returns true if \a s1 is not equal to \a s2; otherwise returns
4637 For \a s1 != 0, this is equivalent to \c {compare(} \a s1, \a s2
4638 \c {) != 0}. Note that no string is equal to \a s1 being 0.
4640 \sa QString::compare()
4644 \fn bool operator<(const char *s1, const QString &s2)
4647 Returns true if \a s1 is lexically less than \a s2; otherwise
4648 returns false. For \a s1 != 0, this is equivalent to \c
4649 {compare(s1, s2) < 0}.
4651 The comparison is based exclusively on the numeric Unicode values
4652 of the characters and is very fast, but is not what a human would
4653 expect. Consider sorting user-interface strings using the
4654 QString::localeAwareCompare() function.
4656 \sa QString::compare()
4660 \fn bool operator<=(const char *s1, const QString &s2)
4663 Returns true if \a s1 is lexically less than or equal to \a s2;
4664 otherwise returns false. For \a s1 != 0, this is equivalent to \c
4665 {compare(s1, s2) <= 0}.
4667 The comparison is based exclusively on the numeric Unicode values
4668 of the characters and is very fast, but is not what a human would
4669 expect. Consider sorting user-interface strings with
4670 QString::localeAwareCompare().
4672 \sa QString::compare()
4676 \fn bool operator>(const char *s1, const QString &s2)
4679 Returns true if \a s1 is lexically greater than \a s2; otherwise
4680 returns false. Equivalent to \c {compare(s1, s2) > 0}.
4682 The comparison is based exclusively on the numeric Unicode values
4683 of the characters and is very fast, but is not what a human would
4684 expect. Consider sorting user-interface strings using the
4685 QString::localeAwareCompare() function.
4687 \sa QString::compare()
4691 \fn bool operator>=(const char *s1, const QString &s2)
4694 Returns true if \a s1 is lexically greater than or equal to \a s2;
4695 otherwise returns false. For \a s1 != 0, this is equivalent to \c
4696 {compare(s1, s2) >= 0}.
4698 The comparison is based exclusively on the numeric Unicode values
4699 of the characters and is very fast, but is not what a human would
4700 expect. Consider sorting user-interface strings using the
4701 QString::localeAwareCompare() function.
4705 \fn const QString operator+(const QString &s1, const QString &s2)
4708 Returns a string which is the result of concatenating \a s1 and \a
4713 \fn const QString operator+(const QString &s1, const char *s2)
4716 Returns a string which is the result of concatenating \a s1 and \a
4717 s2 (\a s2 is converted to Unicode using the QString::fromUtf8()
4720 \sa QString::fromUtf8()
4724 \fn const QString operator+(const char *s1, const QString &s2)
4727 Returns a string which is the result of concatenating \a s1 and \a
4728 s2 (\a s1 is converted to Unicode using the QString::fromUtf8()
4731 \sa QString::fromUtf8()
4735 \fn const QString operator+(const QString &s, char ch)
4738 Returns a string which is the result of concatenating the string
4739 \a s and the character \a ch.
4743 \fn const QString operator+(char ch, const QString &s)
4746 Returns a string which is the result of concatenating the
4747 character \a ch and the string \a s.
4751 \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs)
4754 Compares \a s1 with \a s2 and returns an integer less than, equal
4755 to, or greater than zero if \a s1 is less than, equal to, or
4758 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
4759 otherwise the comparison is case insensitive.
4761 Case sensitive comparison is based exclusively on the numeric
4762 Unicode values of the characters and is very fast, but is not what
4763 a human would expect. Consider sorting user-visible strings with
4764 localeAwareCompare().
4766 \snippet qstring/main.cpp 16
4768 \sa operator==(), operator<(), operator>()
4772 \fn int QString::compare(const QString &s1, QLatin1String s2, Qt::CaseSensitivity cs)
4776 Performs a comparison of \a s1 and \a s2, using the case
4777 sensitivity setting \a cs.
4781 \fn int QString::compare(QLatin1String s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4786 Performs a comparison of \a s1 and \a s2, using the case
4787 sensitivity setting \a cs.
4795 Lexically compares this string with the \a other string and
4796 returns an integer less than, equal to, or greater than zero if
4797 this string is less than, equal to, or greater than the other
4800 Same as compare(*this, \a other, \a cs).
4802 int QString::compare(const QString &other, Qt::CaseSensitivity cs) const
4804 if (cs == Qt::CaseSensitive)
4805 return ucstrcmp(constData(), length(), other.constData(), other.length());
4806 return ucstricmp(d->data(), d->data() + d->size, other.d->data(), other.d->data() + other.d->size);
4813 int QString::compare_helper(const QChar *data1, int length1, const QChar *data2, int length2,
4814 Qt::CaseSensitivity cs)
4816 if (cs == Qt::CaseSensitive)
4817 return ucstrcmp(data1, length1, data2, length2);
4818 register const ushort *s1 = reinterpret_cast<const ushort *>(data1);
4819 register const ushort *s2 = reinterpret_cast<const ushort *>(data2);
4820 return ucstricmp(s1, s1 + length1, s2, s2 + length2);
4827 Same as compare(*this, \a other, \a cs).
4829 int QString::compare(QLatin1String other, Qt::CaseSensitivity cs) const
4831 return compare_helper(unicode(), length(), other, cs);
4835 \fn int QString::compare(const QStringRef &ref, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4838 Compares the string reference, \a ref, with the string and returns
4839 an integer less than, equal to, or greater than zero if the string
4840 is less than, equal to, or greater than \a ref.
4847 int QString::compare_helper(const QChar *data1, int length1, const char *data2, int length2,
4848 Qt::CaseSensitivity cs)
4851 const QString s2 = QString::fromUtf8(data2, length2 == -1 ? (data2 ? int(strlen(data2)) : -1) : length2);
4852 return compare_helper(data1, length1, s2.constData(), s2.size(), cs);
4856 \fn int QString::compare(const QString &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
4864 int QString::compare_helper(const QChar *data1, int length1, QLatin1String s2,
4865 Qt::CaseSensitivity cs)
4867 const ushort *uc = reinterpret_cast<const ushort *>(data1);
4868 const ushort *uce = uc + length1;
4869 const uchar *c = (uchar *)s2.latin1();
4874 if (cs == Qt::CaseSensitive) {
4875 const ushort *e = uc + length1;
4876 if (s2.size() < length1)
4879 int diff = *uc - *c;
4886 if (c == (const uchar *)s2.latin1() + s2.size())
4892 return ucstricmp(uc, uce, c, c + s2.size());
4897 \fn int QString::localeAwareCompare(const QString & s1, const QString & s2)
4899 Compares \a s1 with \a s2 and returns an integer less than, equal
4900 to, or greater than zero if \a s1 is less than, equal to, or
4903 The comparison is performed in a locale- and also
4904 platform-dependent manner. Use this function to present sorted
4905 lists of strings to the user.
4907 On Mac OS X since Qt 4.3, this function compares according the
4908 "Order for sorted lists" setting in the International prefereces panel.
4910 \sa compare(), QTextCodec::locale()
4914 \fn int QString::localeAwareCompare(const QStringRef &other) const
4916 \overload localeAwareCompare()
4918 Compares this string with the \a other string and returns an
4919 integer less than, equal to, or greater than zero if this string
4920 is less than, equal to, or greater than the \a other string.
4922 The comparison is performed in a locale- and also
4923 platform-dependent manner. Use this function to present sorted
4924 lists of strings to the user.
4926 Same as \c {localeAwareCompare(*this, other)}.
4930 \fn int QString::localeAwareCompare(const QString &s1, const QStringRef &s2)
4932 \overload localeAwareCompare()
4934 Compares \a s1 with \a s2 and returns an integer less than, equal
4935 to, or greater than zero if \a s1 is less than, equal to, or
4938 The comparison is performed in a locale- and also
4939 platform-dependent manner. Use this function to present sorted
4940 lists of strings to the user.
4944 #if !defined(CSTR_LESS_THAN)
4945 #define CSTR_LESS_THAN 1
4946 #define CSTR_EQUAL 2
4947 #define CSTR_GREATER_THAN 3
4951 \overload localeAwareCompare()
4953 Compares this string with the \a other string and returns an
4954 integer less than, equal to, or greater than zero if this string
4955 is less than, equal to, or greater than the \a other string.
4957 The comparison is performed in a locale- and also
4958 platform-dependent manner. Use this function to present sorted
4959 lists of strings to the user.
4961 Same as \c {localeAwareCompare(*this, other)}.
4963 int QString::localeAwareCompare(const QString &other) const
4965 return localeAwareCompare_helper(constData(), length(), other.constData(), other.length());
4972 int QString::localeAwareCompare_helper(const QChar *data1, int length1,
4973 const QChar *data2, int length2)
4975 // do the right thing for null and empty
4976 if (length1 == 0 || length2 == 0)
4977 return ucstrcmp(data1, length1, data2, length2);
4979 #if defined(Q_OS_WIN32) || defined(Q_OS_WINCE)
4980 int res = CompareString(GetUserDefaultLCID(), 0, (wchar_t*)data1, length1, (wchar_t*)data2, length2);
4983 case CSTR_LESS_THAN:
4985 case CSTR_GREATER_THAN:
4990 #elif defined (Q_OS_MAC)
4991 // Use CFStringCompare for comparing strings on Mac. This makes Qt order
4992 // strings the same way as native applications do, and also respects
4993 // the "Order for sorted lists" setting in the International preferences
4995 const CFStringRef thisString =
4996 CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
4997 reinterpret_cast<const UniChar *>(data1), length1, kCFAllocatorNull);
4998 const CFStringRef otherString =
4999 CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
5000 reinterpret_cast<const UniChar *>(data2), length2, kCFAllocatorNull);
5002 const int result = CFStringCompare(thisString, otherString, kCFCompareLocalized);
5003 CFRelease(thisString);
5004 CFRelease(otherString);
5006 #elif defined(Q_OS_UNIX)
5007 # if defined(QT_USE_ICU)
5010 if (QIcu::strcoll(locale.d.constData()->m_localeID, data1, length1, data2, length2, &res))
5012 // else fall through
5014 // declared in <string.h>
5015 int delta = strcoll(toLocal8Bit_helper(data1, length1).constData(), toLocal8Bit_helper(data2, length2).constData());
5017 delta = ucstrcmp(data1, length1, data2, length2);
5020 return ucstrcmp(data1, length1, data2, length2);
5026 \fn const QChar *QString::unicode() const
5028 Returns a '\\0'-terminated Unicode representation of the string.
5029 The result remains valid until the string is modified.
5035 \fn const ushort *QString::utf16() const
5037 Returns the QString as a '\\0\'-terminated array of unsigned
5038 shorts. The result remains valid until the string is modified.
5040 The returned string is in host byte order.
5045 const ushort *QString::utf16() const
5047 if (IS_RAW_DATA(d)) {
5048 // ensure '\0'-termination for ::fromRawData strings
5049 const_cast<QString*>(this)->reallocData(uint(d->size) + 1u);
5055 Returns a string of size \a width that contains this string
5056 padded by the \a fill character.
5058 If \a truncate is false and the size() of the string is more than
5059 \a width, then the returned string is a copy of the string.
5061 \snippet qstring/main.cpp 32
5063 If \a truncate is true and the size() of the string is more than
5064 \a width, then any characters in a copy of the string after
5065 position \a width are removed, and the copy is returned.
5067 \snippet qstring/main.cpp 33
5069 \sa rightJustified()
5072 QString QString::leftJustified(int width, QChar fill, bool truncate) const
5076 int padlen = width - len;
5078 result.resize(len+padlen);
5080 memcpy(result.d->data(), d->data(), sizeof(QChar)*len);
5081 QChar *uc = (QChar*)result.d->data() + len;
5086 result = left(width);
5094 Returns a string of size() \a width that contains the \a fill
5095 character followed by the string. For example:
5097 \snippet qstring/main.cpp 49
5099 If \a truncate is false and the size() of the string is more than
5100 \a width, then the returned string is a copy of the string.
5102 If \a truncate is true and the size() of the string is more than
5103 \a width, then the resulting string is truncated at position \a
5106 \snippet qstring/main.cpp 50
5111 QString QString::rightJustified(int width, QChar fill, bool truncate) const
5115 int padlen = width - len;
5117 result.resize(len+padlen);
5118 QChar *uc = (QChar*)result.d->data();
5122 memcpy(uc, d->data(), sizeof(QChar)*len);
5125 result = left(width);
5133 Returns a lowercase copy of the string.
5135 \snippet qstring/main.cpp 75
5137 The case conversion will always happen in the 'C' locale. For locale dependent
5138 case folding use QLocale::toLower()
5140 \sa toUpper(), QLocale::toLower()
5143 QString QString::toLower() const
5145 const ushort *p = d->data();
5149 const ushort *e = p + d->size;
5150 // this avoids out of bounds check in the loop
5151 while (e != p && QChar::isHighSurrogate(*(e - 1)))
5154 const QUnicodeTables::Properties *prop;
5156 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5158 prop = qGetProp(QChar::surrogateToUcs4(high, *p));
5160 prop = qGetProp(*p);
5162 if (prop->lowerCaseDiff) {
5163 if (QChar::isLowSurrogate(*p))
5164 --p; // safe; diff is 0 for surrogates
5165 QString s(d->size, Qt::Uninitialized);
5166 memcpy(s.d->data(), d->data(), (p - d->data())*sizeof(ushort));
5167 ushort *pp = s.d->data() + (p - d->data());
5169 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5171 prop = qGetProp(QChar::surrogateToUcs4(*pp++, *p));
5173 prop = qGetProp(*p);
5175 if (prop->lowerCaseSpecial) {
5176 const ushort *specialCase = specialCaseMap + prop->lowerCaseDiff;
5177 ushort length = *specialCase++;
5178 int pos = pp - s.d->data();
5179 s.resize(s.d->size + length - 1);
5180 pp = s.d->data() + pos;
5182 *pp++ = *specialCase++;
5184 *pp++ = *p + prop->lowerCaseDiff;
5189 // this restores high surrogate parts eaten above, if any
5190 while (e != d->data() + d->size)
5201 Returns the case folded equivalent of the string. For most Unicode
5202 characters this is the same as toLower().
5204 QString QString::toCaseFolded() const
5206 const ushort *p = d->data();
5210 const ushort *e = p + d->size;
5211 // this avoids out of bounds check in the loop
5212 while (e != p && QChar::isHighSurrogate(*(e - 1)))
5215 const QUnicodeTables::Properties *prop;
5217 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5219 prop = qGetProp(QChar::surrogateToUcs4(high, *p));
5221 prop = qGetProp(*p);
5223 if (prop->caseFoldDiff) {
5224 if (QChar::isLowSurrogate(*p))
5225 --p; // safe; diff is 0 for surrogates
5226 QString s(d->size, Qt::Uninitialized);
5227 memcpy(s.d->data(), d->data(), (p - d->data())*sizeof(ushort));
5228 ushort *pp = s.d->data() + (p - d->data());
5230 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5232 prop = qGetProp(QChar::surrogateToUcs4(*pp++, *p));
5234 prop = qGetProp(*p);
5236 if (prop->caseFoldSpecial) {
5237 const ushort *specialCase = specialCaseMap + prop->caseFoldDiff;
5238 ushort length = *specialCase++;
5240 int pos = pp - s.d->data;
5241 s.resize(s.d->size + length - 1);
5242 pp = s.d->data + pos;
5244 *pp++ = *specialCase++;
5246 //### we currently don't support full case foldings
5247 Q_ASSERT(length == 1);
5249 *pp++ = *specialCase;
5252 *pp++ = *p + prop->caseFoldDiff;
5257 // this restores high surrogate parts eaten above, if any
5258 while (e != d->data() + d->size)
5269 Returns an uppercase copy of the string.
5271 \snippet qstring/main.cpp 81
5273 The case conversion will always happen in the 'C' locale. For locale dependent
5274 case folding use QLocale::toUpper()
5276 \sa toLower(), QLocale::toLower()
5278 QString QString::toUpper() const
5280 const ushort *p = d->data();
5284 const ushort *e = p + d->size;
5285 // this avoids out of bounds check in the loop
5286 while (e != p && QChar::isHighSurrogate(*(e - 1)))
5289 const QUnicodeTables::Properties *prop;
5291 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5293 prop = qGetProp(QChar::surrogateToUcs4(high, *p));
5295 prop = qGetProp(*p);
5297 if (prop->upperCaseDiff) {
5298 if (QChar::isLowSurrogate(*p))
5299 --p; // safe; diff is 0 for surrogates
5300 QString s(d->size, Qt::Uninitialized);
5301 memcpy(s.d->data(), d->data(), (p - d->data())*sizeof(ushort));
5302 ushort *pp = s.d->data() + (p - d->data());
5304 if (QChar::isHighSurrogate(*p) && QChar::isLowSurrogate(p[1])) {
5306 prop = qGetProp(QChar::surrogateToUcs4(*pp++, *p));
5308 prop = qGetProp(*p);
5310 if (prop->upperCaseSpecial) {
5311 const ushort *specialCase = specialCaseMap + prop->upperCaseDiff;
5312 ushort length = *specialCase++;
5313 int pos = pp - s.d->data();
5314 s.resize(s.d->size + length - 1);
5315 pp = s.d->data() + pos;
5317 *pp++ = *specialCase++;
5319 *pp++ = *p + prop->upperCaseDiff;
5324 // this restores high surrogate parts eaten above, if any
5325 while (e != d->data() + d->size)
5335 // ### Qt 6: Consider whether this function shouldn't be removed See task 202871.
5337 Safely builds a formatted string from the format string \a cformat
5338 and an arbitrary list of arguments.
5340 The %lc escape sequence expects a unicode character of type ushort
5341 (as returned by QChar::unicode()). The %ls escape sequence expects
5342 a pointer to a zero-terminated array of unicode characters of type
5343 ushort (as returned by QString::utf16()).
5345 \note This function expects a UTF-8 string for %s and Latin-1 for
5348 The format string supports most of the conversion specifiers
5349 provided by printf() in the standard C++ library. It doesn't
5350 honor the length modifiers (e.g. \c h for \c short, \c ll for
5351 \c{long long}). If you need those, use the standard snprintf()
5354 \snippet qstring/main.cpp 63
5356 \warning We do not recommend using QString::sprintf() in new Qt
5357 code. Instead, consider using QTextStream or arg(), both of
5358 which support Unicode strings seamlessly and are type-safe.
5359 Here's an example that uses QTextStream:
5361 \snippet qstring/main.cpp 64
5363 For \l {QObject::tr()}{translations}, especially if the strings
5364 contains more than one escape sequence, you should consider using
5365 the arg() function instead. This allows the order of the
5366 replacements to be controlled by the translator.
5371 QString &QString::sprintf(const char *cformat, ...)
5374 va_start(ap, cformat);
5375 QString &s = vsprintf(cformat, ap);
5381 Equivalent method to sprintf(), but takes a va_list \a ap
5382 instead a list of variable arguments. See the sprintf()
5383 documentation for an explanation of \a cformat.
5385 This method does not call the va_end macro, the caller
5386 is responsible to call va_end on \a ap.
5391 QString &QString::vsprintf(const char* cformat, va_list ap)
5393 QLocale locale(QLocale::C);
5395 if (!cformat || !*cformat) {
5397 *this = fromLatin1("");
5404 const char *c = cformat;
5406 // Copy non-escape chars to result
5407 while (*c != '\0' && *c != '%')
5408 result.append(QLatin1Char(*c++));
5414 const char *escape_start = c;
5418 result.append(QLatin1Char('%')); // a % at the end of the string - treat as non-escape text
5422 result.append(QLatin1Char('%')); // %%
5427 // Parse flag characters
5429 bool no_more_flags = false;
5432 case '#': flags |= QLocalePrivate::Alternate; break;
5433 case '0': flags |= QLocalePrivate::ZeroPadded; break;
5434 case '-': flags |= QLocalePrivate::LeftAdjusted; break;
5435 case ' ': flags |= QLocalePrivate::BlankBeforePositive; break;
5436 case '+': flags |= QLocalePrivate::AlwaysShowSign; break;
5437 case '\'': flags |= QLocalePrivate::ThousandsGroup; break;
5438 default: no_more_flags = true; break;
5443 } while (!no_more_flags);
5446 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5450 // Parse field width
5451 int width = -1; // -1 means unspecified
5454 while (*c != '\0' && qIsDigit(*c))
5455 width_str.append(QLatin1Char(*c++));
5457 // can't be negative - started with a digit
5458 // contains at least one digit
5459 width = width_str.toInt();
5461 else if (*c == '*') {
5462 width = va_arg(ap, int);
5464 width = -1; // treat all negative numbers as unspecified
5469 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5474 int precision = -1; // -1 means unspecified
5478 QString precision_str;
5479 while (*c != '\0' && qIsDigit(*c))
5480 precision_str.append(QLatin1Char(*c++));
5482 // can't be negative - started with a digit
5483 // contains at least one digit
5484 precision = precision_str.toInt();
5486 else if (*c == '*') {
5487 precision = va_arg(ap, int);
5489 precision = -1; // treat all negative numbers as unspecified
5495 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5499 // Parse the length modifier
5500 enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t };
5501 LengthMod length_mod = lm_none;
5548 result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
5552 // Parse the conversion specifier and do the conversion
5558 switch (length_mod) {
5559 case lm_none: i = va_arg(ap, int); break;
5560 case lm_hh: i = va_arg(ap, int); break;
5561 case lm_h: i = va_arg(ap, int); break;
5562 case lm_l: i = va_arg(ap, long int); break;
5563 case lm_ll: i = va_arg(ap, qint64); break;
5564 case lm_j: i = va_arg(ap, long int); break;
5565 case lm_z: i = va_arg(ap, size_t); break;
5566 case lm_t: i = va_arg(ap, int); break;
5567 default: i = 0; break;
5569 subst = locale.d->longLongToString(i, precision, 10, width, flags);
5578 switch (length_mod) {
5579 case lm_none: u = va_arg(ap, uint); break;
5580 case lm_hh: u = va_arg(ap, uint); break;
5581 case lm_h: u = va_arg(ap, uint); break;
5582 case lm_l: u = va_arg(ap, ulong); break;
5583 case lm_ll: u = va_arg(ap, quint64); break;
5584 case lm_z: u = va_arg(ap, size_t); break;
5585 default: u = 0; break;
5589 flags |= QLocalePrivate::CapitalEorX;
5592 switch (qToLower(*c)) {
5601 subst = locale.d->unsLongLongToString(u, precision, base, width, flags);
5614 if (length_mod == lm_L)
5615 d = va_arg(ap, long double); // not supported - converted to a double
5617 d = va_arg(ap, double);
5620 flags |= QLocalePrivate::CapitalEorX;
5622 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5623 switch (qToLower(*c)) {
5624 case 'e': form = QLocalePrivate::DFExponent; break;
5625 case 'a': // not supported - decimal form used instead
5626 case 'f': form = QLocalePrivate::DFDecimal; break;
5627 case 'g': form = QLocalePrivate::DFSignificantDigits; break;
5630 subst = locale.d->doubleToString(d, precision, form, width, flags);
5635 if (length_mod == lm_l)
5636 subst = QChar((ushort) va_arg(ap, int));
5638 subst = QLatin1Char((uchar) va_arg(ap, int));
5643 if (length_mod == lm_l) {
5644 const ushort *buff = va_arg(ap, const ushort*);
5645 const ushort *ch = buff;
5648 subst.setUtf16(buff, ch - buff);
5650 subst = QString::fromUtf8(va_arg(ap, const char*));
5651 if (precision != -1)
5652 subst.truncate(precision);
5657 void *arg = va_arg(ap, void*);
5659 quint64 i = reinterpret_cast<quint64>(arg);
5661 quint64 i = reinterpret_cast<unsigned long>(arg);
5663 flags |= QLocalePrivate::Alternate;
5664 subst = locale.d->unsLongLongToString(i, precision, 16, width, flags);
5669 switch (length_mod) {
5671 signed char *n = va_arg(ap, signed char*);
5672 *n = result.length();
5676 short int *n = va_arg(ap, short int*);
5677 *n = result.length();
5681 long int *n = va_arg(ap, long int*);
5682 *n = result.length();
5686 qint64 *n = va_arg(ap, qint64*);
5687 volatile uint tmp = result.length(); // egcs-2.91.66 gets internal
5688 *n = tmp; // compiler error without volatile
5692 int *n = va_arg(ap, int*);
5693 *n = result.length();
5700 default: // bad escape, treat as non-escape text
5701 for (const char *cc = escape_start; cc != c; ++cc)
5702 result.append(QLatin1Char(*cc));
5706 if (flags & QLocalePrivate::LeftAdjusted)
5707 result.append(subst.leftJustified(width));
5709 result.append(subst.rightJustified(width));
5718 Returns the string converted to a \c{long long} using base \a
5719 base, which is 10 by default and must be between 2 and 36, or 0.
5720 Returns 0 if the conversion fails.
5722 If a conversion error occurs, *\a{ok} is set to false; otherwise
5723 *\a{ok} is set to true.
5725 If \a base is 0, the C language convention is used: If the string
5726 begins with "0x", base 16 is used; if the string begins with "0",
5727 base 8 is used; otherwise, base 10 is used.
5729 The string conversion will always happen in the 'C' locale. For locale
5730 dependent conversion use QLocale::toLongLong()
5734 \snippet qstring/main.cpp 74
5736 \sa number(), toULongLong(), toInt(), QLocale::toLongLong()
5739 qint64 QString::toLongLong(bool *ok, int base) const
5741 #if defined(QT_CHECK_RANGE)
5742 if (base != 0 && (base < 2 || base > 36)) {
5743 qWarning("QString::toLongLong: Invalid base (%d)", base);
5748 QLocale c_locale(QLocale::C);
5749 return c_locale.d->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5753 Returns the string converted to an \c{unsigned long long} using base \a
5754 base, which is 10 by default and must be between 2 and 36, or 0.
5755 Returns 0 if the conversion fails.
5757 If a conversion error occurs, *\a{ok} is set to false; otherwise
5758 *\a{ok} is set to true.
5760 If \a base is 0, the C language convention is used: If the string
5761 begins with "0x", base 16 is used; if the string begins with "0",
5762 base 8 is used; otherwise, base 10 is used.
5764 The string conversion will always happen in the 'C' locale. For locale
5765 dependent conversion use QLocale::toULongLong()
5769 \snippet qstring/main.cpp 79
5771 \sa number(), toLongLong(), QLocale::toULongLong()
5774 quint64 QString::toULongLong(bool *ok, int base) const
5776 #if defined(QT_CHECK_RANGE)
5777 if (base != 0 && (base < 2 || base > 36)) {
5778 qWarning("QString::toULongLong: Invalid base (%d)", base);
5783 QLocale c_locale(QLocale::C);
5784 return c_locale.d->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
5788 \fn long QString::toLong(bool *ok, int base) const
5790 Returns the string converted to a \c long using base \a
5791 base, which is 10 by default and must be between 2 and 36, or 0.
5792 Returns 0 if the conversion fails.
5794 If a conversion error occurs, *\a{ok} is set to false; otherwise
5795 *\a{ok} is set to true.
5797 If \a base is 0, the C language convention is used: If the string
5798 begins with "0x", base 16 is used; if the string begins with "0",
5799 base 8 is used; otherwise, base 10 is used.
5801 The string conversion will always happen in the 'C' locale. For locale
5802 dependent conversion use QLocale::toLong()
5806 \snippet qstring/main.cpp 73
5808 \sa number(), toULong(), toInt(), QLocale::toLong()
5811 long QString::toLong(bool *ok, int base) const
5813 qint64 v = toLongLong(ok, base);
5814 if (v < LONG_MIN || v > LONG_MAX) {
5823 \fn ulong QString::toULong(bool *ok, int base) const
5825 Returns the string converted to an \c{unsigned long} using base \a
5826 base, which is 10 by default and must be between 2 and 36, or 0.
5827 Returns 0 if the conversion fails.
5829 If a conversion error occurs, *\a{ok} is set to false; otherwise
5830 *\a{ok} is set to true.
5832 If \a base is 0, the C language convention is used: If the string
5833 begins with "0x", base 16 is used; if the string begins with "0",
5834 base 8 is used; otherwise, base 10 is used.
5836 The string conversion will always happen in the 'C' locale. For locale
5837 dependent conversion use QLocale::toULong()
5841 \snippet qstring/main.cpp 78
5843 \sa number(), QLocale::toULong()
5846 ulong QString::toULong(bool *ok, int base) const
5848 quint64 v = toULongLong(ok, base);
5849 if (v > ULONG_MAX) {
5859 Returns the string converted to an \c int using base \a
5860 base, which is 10 by default and must be between 2 and 36, or 0.
5861 Returns 0 if the conversion fails.
5863 If a conversion error occurs, *\a{ok} is set to false; otherwise
5864 *\a{ok} is set to true.
5866 If \a base is 0, the C language convention is used: If the string
5867 begins with "0x", base 16 is used; if the string begins with "0",
5868 base 8 is used; otherwise, base 10 is used.
5870 The string conversion will always happen in the 'C' locale. For locale
5871 dependent conversion use QLocale::toInt()
5875 \snippet qstring/main.cpp 72
5877 \sa number(), toUInt(), toDouble(), QLocale::toInt()
5880 int QString::toInt(bool *ok, int base) const
5882 qint64 v = toLongLong(ok, base);
5883 if (v < INT_MIN || v > INT_MAX) {
5892 Returns the string converted to an \c{unsigned int} using base \a
5893 base, which is 10 by default and must be between 2 and 36, or 0.
5894 Returns 0 if the conversion fails.
5896 If a conversion error occurs, *\a{ok} is set to false; otherwise
5897 *\a{ok} is set to true.
5899 If \a base is 0, the C language convention is used: If the string
5900 begins with "0x", base 16 is used; if the string begins with "0",
5901 base 8 is used; otherwise, base 10 is used.
5903 The string conversion will always happen in the 'C' locale. For locale
5904 dependent conversion use QLocale::toUInt()
5908 \snippet qstring/main.cpp 77
5910 \sa number(), toInt(), QLocale::toUInt()
5913 uint QString::toUInt(bool *ok, int base) const
5915 quint64 v = toULongLong(ok, base);
5925 Returns the string converted to a \c short using base \a
5926 base, which is 10 by default and must be between 2 and 36, or 0.
5927 Returns 0 if the conversion fails.
5929 If a conversion error occurs, *\a{ok} is set to false; otherwise
5930 *\a{ok} is set to true.
5932 If \a base is 0, the C language convention is used: If the string
5933 begins with "0x", base 16 is used; if the string begins with "0",
5934 base 8 is used; otherwise, base 10 is used.
5936 The string conversion will always happen in the 'C' locale. For locale
5937 dependent conversion use QLocale::toShort()
5941 \snippet qstring/main.cpp 76
5943 \sa number(), toUShort(), toInt(), QLocale::toShort()
5946 short QString::toShort(bool *ok, int base) const
5948 long v = toLongLong(ok, base);
5949 if (v < SHRT_MIN || v > SHRT_MAX) {
5958 Returns the string converted to an \c{unsigned short} using base \a
5959 base, which is 10 by default and must be between 2 and 36, or 0.
5960 Returns 0 if the conversion fails.
5962 If a conversion error occurs, *\a{ok} is set to false; otherwise
5963 *\a{ok} is set to true.
5965 If \a base is 0, the C language convention is used: If the string
5966 begins with "0x", base 16 is used; if the string begins with "0",
5967 base 8 is used; otherwise, base 10 is used.
5969 The string conversion will always happen in the 'C' locale. For locale
5970 dependent conversion use QLocale::toUShort()
5974 \snippet qstring/main.cpp 80
5976 \sa number(), toShort(), QLocale::toUShort()
5979 ushort QString::toUShort(bool *ok, int base) const
5981 ulong v = toULongLong(ok, base);
5982 if (v > USHRT_MAX) {
5992 Returns the string converted to a \c double value.
5994 Returns 0.0 if the conversion fails.
5996 If a conversion error occurs, \c{*}\a{ok} is set to false;
5997 otherwise \c{*}\a{ok} is set to true.
5999 \snippet qstring/main.cpp 66
6001 Various string formats for floating point numbers can be converted
6004 \snippet qstring/main.cpp 67
6006 The string conversion will always happen in the 'C' locale. For locale
6007 dependent conversion use QLocale::toDouble()
6009 \snippet qstring/main.cpp 68
6011 For historic reasons, this function does not handle
6012 thousands group separators. If you need to convert such numbers,
6013 use QLocale::toDouble().
6015 \snippet qstring/main.cpp 69
6017 \sa number(), QLocale::setDefault(), QLocale::toDouble(), trimmed()
6020 double QString::toDouble(bool *ok) const
6022 QLocale c_locale(QLocale::C);
6023 return c_locale.d->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators);
6027 Returns the string converted to a \c float value.
6029 If a conversion error occurs, *\a{ok} is set to false; otherwise
6030 *\a{ok} is set to true. Returns 0.0 if the conversion fails.
6032 The string conversion will always happen in the 'C' locale. For locale
6033 dependent conversion use QLocale::toFloat()
6037 \snippet qstring/main.cpp 71
6039 \sa number(), toDouble(), toInt(), QLocale::toFloat()
6042 #define QT_MAX_FLOAT 3.4028234663852886e+38
6044 float QString::toFloat(bool *ok) const
6047 double d = toDouble(&myOk);
6055 if (d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) {
6065 /*! \fn QString &QString::setNum(int n, int base)
6067 Sets the string to the printed value of \a n in the specified \a
6068 base, and returns a reference to the string.
6070 The base is 10 by default and must be between 2 and 36. For bases
6071 other than 10, \a n is treated as an unsigned integer.
6073 \snippet qstring/main.cpp 56
6075 The formatting always uses QLocale::C, i.e., English/UnitedStates.
6076 To get a localized string representation of a number, use
6077 QLocale::toString() with the appropriate locale.
6080 /*! \fn QString &QString::setNum(uint n, int base)
6085 /*! \fn QString &QString::setNum(long n, int base)
6090 /*! \fn QString &QString::setNum(ulong n, int base)
6098 QString &QString::setNum(qlonglong n, int base)
6100 #if defined(QT_CHECK_RANGE)
6101 if (base < 2 || base > 36) {
6102 qWarning("QString::setNum: Invalid base (%d)", base);
6106 QLocale locale(QLocale::C);
6107 *this = locale.d->longLongToString(n, -1, base);
6114 QString &QString::setNum(qulonglong n, int base)
6116 #if defined(QT_CHECK_RANGE)
6117 if (base < 2 || base > 36) {
6118 qWarning("QString::setNum: Invalid base (%d)", base);
6122 QLocale locale(QLocale::C);
6123 *this = locale.d->unsLongLongToString(n, -1, base);
6127 /*! \fn QString &QString::setNum(short n, int base)
6132 /*! \fn QString &QString::setNum(ushort n, int base)
6138 \fn QString &QString::setNum(double n, char format, int precision)
6141 Sets the string to the printed value of \a n, formatted according
6142 to the given \a format and \a precision, and returns a reference
6145 The \a format can be 'f', 'F', 'e', 'E', 'g' or 'G' (see the
6146 arg() function documentation for an explanation of the formats).
6148 The formatting always uses QLocale::C, i.e., English/UnitedStates.
6149 To get a localized string representation of a number, use
6150 QLocale::toString() with the appropriate locale.
6153 QString &QString::setNum(double n, char f, int prec)
6155 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
6159 flags = QLocalePrivate::CapitalEorX;
6164 form = QLocalePrivate::DFDecimal;
6167 form = QLocalePrivate::DFExponent;
6170 form = QLocalePrivate::DFSignificantDigits;
6173 #if defined(QT_CHECK_RANGE)
6174 qWarning("QString::setNum: Invalid format char '%c'", f);
6179 QLocale locale(QLocale::C);
6180 *this = locale.d->doubleToString(n, prec, form, -1, flags);
6185 \fn QString &QString::setNum(float n, char format, int precision)
6188 Sets the string to the printed value of \a n, formatted according
6189 to the given \a format and \a precision, and returns a reference
6192 The formatting always uses QLocale::C, i.e., English/UnitedStates.
6193 To get a localized string representation of a number, use
6194 QLocale::toString() with the appropriate locale.
6199 \fn QString QString::number(long n, int base)
6201 Returns a string equivalent of the number \a n according to the
6204 The base is 10 by default and must be between 2
6205 and 36. For bases other than 10, \a n is treated as an
6208 The formatting always uses QLocale::C, i.e., English/UnitedStates.
6209 To get a localized string representation of a number, use
6210 QLocale::toString() with the appropriate locale.
6212 \snippet qstring/main.cpp 35
6217 QString QString::number(long n, int base)
6225 \fn QString QString::number(ulong n, int base)
6229 QString QString::number(ulong n, int base)
6239 QString QString::number(int n, int base)
6249 QString QString::number(uint n, int base)
6259 QString QString::number(qlonglong n, int base)
6269 QString QString::number(qulonglong n, int base)
6278 \fn QString QString::number(double n, char format, int precision)
6280 Returns a string equivalent of the number \a n, formatted
6281 according to the specified \a format and \a precision. See
6282 \l{Argument Formats} for details.
6284 Unlike QLocale::toString(), this function does not honor the
6285 user's locale settings.
6287 \sa setNum(), QLocale::toString()
6289 QString QString::number(double n, char f, int prec)
6292 s.setNum(n, f, prec);
6297 Splits the string into substrings wherever \a sep occurs, and
6298 returns the list of those strings. If \a sep does not match
6299 anywhere in the string, split() returns a single-element list
6300 containing this string.
6302 \a cs specifies whether \a sep should be matched case
6303 sensitively or case insensitively.
6305 If \a behavior is QString::SkipEmptyParts, empty entries don't
6306 appear in the result. By default, empty entries are kept.
6310 \snippet qstring/main.cpp 62
6312 \sa QStringList::join(), section()
6314 QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6320 while ((end = indexOf(sep, start + extra, cs)) != -1) {
6321 if (start != end || behavior == KeepEmptyParts)
6322 list.append(mid(start, end - start));
6323 start = end + sep.size();
6324 extra = (sep.size() == 0 ? 1 : 0);
6326 if (start != size() || behavior == KeepEmptyParts)
6327 list.append(mid(start));
6334 QStringList QString::split(QChar sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
6339 while ((end = indexOf(sep, start, cs)) != -1) {
6340 if (start != end || behavior == KeepEmptyParts)
6341 list.append(mid(start, end - start));
6344 if (start != size() || behavior == KeepEmptyParts)
6345 list.append(mid(start));
6349 #ifndef QT_NO_REGEXP
6353 Splits the string into substrings wherever the regular expression
6354 \a rx matches, and returns the list of those strings. If \a rx
6355 does not match anywhere in the string, split() returns a
6356 single-element list containing this string.
6358 Here's an example where we extract the words in a sentence
6359 using one or more whitespace characters as the separator:
6361 \snippet qstring/main.cpp 59
6363 Here's a similar example, but this time we use any sequence of
6364 non-word characters as the separator:
6366 \snippet qstring/main.cpp 60
6368 Here's a third example where we use a zero-length assertion,
6369 \b{\\b} (word boundary), to split the string into an
6370 alternating sequence of non-word and word tokens:
6372 \snippet qstring/main.cpp 61
6374 \sa QStringList::join(), section()
6376 QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const
6383 while ((end = rx2.indexIn(*this, start + extra)) != -1) {
6384 int matchedLen = rx2.matchedLength();
6385 if (start != end || behavior == KeepEmptyParts)
6386 list.append(mid(start, end - start));
6387 start = end + matchedLen;
6388 extra = (matchedLen == 0) ? 1 : 0;
6390 if (start != size() || behavior == KeepEmptyParts)
6391 list.append(mid(start));
6396 #ifndef QT_NO_REGEXP
6397 #ifndef QT_BOOTSTRAPPED
6402 Splits the string into substrings wherever the regular expression
6403 \a re matches, and returns the list of those strings. If \a re
6404 does not match anywhere in the string, split() returns a
6405 single-element list containing this string.
6407 Here's an example where we extract the words in a sentence
6408 using one or more whitespace characters as the separator:
6410 \snippet qstring/main.cpp 90
6412 Here's a similar example, but this time we use any sequence of
6413 non-word characters as the separator:
6415 \snippet qstring/main.cpp 91
6417 Here's a third example where we use a zero-length assertion,
6418 \b{\\b} (word boundary), to split the string into an
6419 alternating sequence of non-word and word tokens:
6421 \snippet qstring/main.cpp 92
6423 \sa QStringList::join(), section()
6425 QStringList QString::split(const QRegularExpression &re, SplitBehavior behavior) const
6428 if (!re.isValid()) {
6429 qWarning("QString::split: invalid QRegularExpression object");
6435 QRegularExpressionMatchIterator iterator = re.globalMatch(*this);
6436 while (iterator.hasNext()) {
6437 QRegularExpressionMatch match = iterator.next();
6438 end = match.capturedStart();
6439 if (start != end || behavior == KeepEmptyParts)
6440 list.append(mid(start, end - start));
6441 start = match.capturedEnd();
6444 if (start != size() || behavior == KeepEmptyParts)
6445 list.append(mid(start));
6449 #endif // QT_BOOTSTRAPPED
6450 #endif // QT_NO_REGEXP
6453 \enum QString::NormalizationForm
6455 This enum describes the various normalized forms of Unicode text.
6457 \value NormalizationForm_D Canonical Decomposition
6458 \value NormalizationForm_C Canonical Decomposition followed by Canonical Composition
6459 \value NormalizationForm_KD Compatibility Decomposition
6460 \value NormalizationForm_KC Compatibility Decomposition followed by Canonical Composition
6463 {http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15}
6469 Returns a copy of this string repeated the specified number of \a times.
6471 If \a times is less than 1, an empty string is returned.
6477 str.repeated(4); // returns "abababab"
6480 QString QString::repeated(int times) const
6491 const int resultSize = times * d->size;
6494 result.reserve(resultSize);
6495 if (result.d->alloc != uint(resultSize) + 1u)
6496 return QString(); // not enough memory
6498 memcpy(result.d->data(), d->data(), d->size * sizeof(ushort));
6500 int sizeSoFar = d->size;
6501 ushort *end = result.d->data() + sizeSoFar;
6503 const int halfResultSize = resultSize >> 1;
6504 while (sizeSoFar <= halfResultSize) {
6505 memcpy(end, result.d->data(), sizeSoFar * sizeof(ushort));
6509 memcpy(end, result.d->data(), (resultSize - sizeSoFar) * sizeof(ushort));
6510 result.d->data()[resultSize] = '\0';
6511 result.d->size = resultSize;
6515 void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from)
6518 const QChar *p = data->constData();
6519 int len = data->length();
6520 for (int i = from; i < len; ++i) {
6521 if (p[i].unicode() >= 0x80) {
6529 if (version == QChar::Unicode_Unassigned) {
6530 version = QChar::currentUnicodeVersion();
6531 } else if (int(version) <= NormalizationCorrectionsVersionMax) {
6532 const QString &s = *data;
6534 for (int i = 0; i < NumNormalizationCorrections; ++i) {
6535 const NormalizationCorrection &n = uc_normalization_corrections[i];
6536 if (n.version > version) {
6538 if (QChar::requiresSurrogates(n.ucs4)) {
6539 ushort ucs4High = QChar::highSurrogate(n.ucs4);
6540 ushort ucs4Low = QChar::lowSurrogate(n.ucs4);
6541 ushort oldHigh = QChar::highSurrogate(n.old_mapping);
6542 ushort oldLow = QChar::lowSurrogate(n.old_mapping);
6543 while (pos < s.length() - 1) {
6544 if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) {
6547 d[pos] = QChar(oldHigh);
6548 d[++pos] = QChar(oldLow);
6553 while (pos < s.length()) {
6554 if (s.at(pos).unicode() == n.ucs4) {
6557 d[pos] = QChar(n.old_mapping);
6565 decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from);
6567 canonicalOrderHelper(data, version, from);
6569 if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD)
6572 composeHelper(data, version, from);
6576 Returns the string in the given Unicode normalization \a mode,
6577 according to the given \a version of the Unicode standard.
6579 QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const
6581 QString copy = *this;
6582 qt_string_normalize(©, mode, version, 0);
6587 struct ArgEscapeData
6589 int min_escape; // lowest escape sequence number
6590 int occurrences; // number of occurrences of the lowest escape sequence number
6591 int locale_occurrences; // number of occurrences of the lowest escape sequence number that
6593 int escape_len; // total length of escape sequences which will be replaced
6596 static ArgEscapeData findArgEscapes(const QString &s)
6598 const QChar *uc_begin = s.unicode();
6599 const QChar *uc_end = uc_begin + s.length();
6603 d.min_escape = INT_MAX;
6606 d.locale_occurrences = 0;
6608 const QChar *c = uc_begin;
6609 while (c != uc_end) {
6610 while (c != uc_end && c->unicode() != '%')
6615 const QChar *escape_start = c;
6619 bool locale_arg = false;
6620 if (c->unicode() == 'L') {
6626 if (c->digitValue() == -1)
6629 int escape = c->digitValue();
6632 if (c != uc_end && c->digitValue() != -1) {
6633 escape = (10 * escape) + c->digitValue();
6637 if (escape > d.min_escape)
6640 if (escape < d.min_escape) {
6641 d.min_escape = escape;
6644 d.locale_occurrences = 0;
6649 ++d.locale_occurrences;
6650 d.escape_len += c - escape_start;
6655 static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width,
6656 const QString &arg, const QString &larg, QChar fillChar = QLatin1Char(' '))
6658 const QChar *uc_begin = s.unicode();
6659 const QChar *uc_end = uc_begin + s.length();
6661 int abs_field_width = qAbs(field_width);
6662 int result_len = s.length()
6664 + (d.occurrences - d.locale_occurrences)
6665 *qMax(abs_field_width, arg.length())
6666 + d.locale_occurrences
6667 *qMax(abs_field_width, larg.length());
6669 QString result(result_len, Qt::Uninitialized);
6670 QChar *result_buff = (QChar*) result.unicode();
6672 QChar *rc = result_buff;
6673 const QChar *c = uc_begin;
6675 while (c != uc_end) {
6676 /* We don't have to check if we run off the end of the string with c,
6677 because as long as d.occurrences > 0 we KNOW there are valid escape
6680 const QChar *text_start = c;
6682 while (c->unicode() != '%')
6685 const QChar *escape_start = c++;
6687 bool locale_arg = false;
6688 if (c->unicode() == 'L') {
6693 int escape = c->digitValue();
6695 if (c + 1 != uc_end && (c + 1)->digitValue() != -1) {
6696 escape = (10 * escape) + (c + 1)->digitValue();
6701 if (escape != d.min_escape) {
6702 memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
6703 rc += c - text_start;
6708 memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
6709 rc += escape_start - text_start;
6713 pad_chars = qMax(abs_field_width, larg.length()) - larg.length();
6715 pad_chars = qMax(abs_field_width, arg.length()) - arg.length();
6717 if (field_width > 0) { // left padded
6718 for (uint i = 0; i < pad_chars; ++i)
6719 (rc++)->unicode() = fillChar.unicode();
6723 memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar));
6724 rc += larg.length();
6727 memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar));
6731 if (field_width < 0) { // right padded
6732 for (uint i = 0; i < pad_chars; ++i)
6733 (rc++)->unicode() = fillChar.unicode();
6736 if (++repl_cnt == d.occurrences) {
6737 memcpy(rc, c, (uc_end - c)*sizeof(QChar));
6739 Q_ASSERT(rc - result_buff == result_len);
6744 Q_ASSERT(rc == result_buff + result_len);
6750 Returns a copy of this string with the lowest numbered place marker
6751 replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
6753 \a fieldWidth specifies the minimum amount of space that argument \a
6754 a shall occupy. If \a a requires less space than \a fieldWidth, it
6755 is padded to \a fieldWidth with character \a fillChar. A positive
6756 \a fieldWidth produces right-aligned text. A negative \a fieldWidth
6757 produces left-aligned text.
6759 This example shows how we might create a \c status string for
6760 reporting progress while processing a list of files:
6762 \snippet qstring/main.cpp 11
6764 First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
6765 %2. Finally, \c arg(fileName) replaces \c %3.
6767 One advantage of using arg() over sprintf() is that the order of the
6768 numbered place markers can change, if the application's strings are
6769 translated into other languages, but each arg() will still replace
6770 the lowest numbered unreplaced place marker, no matter where it
6771 appears. Also, if place marker \c %i appears more than once in the
6772 string, the arg() replaces all of them.
6774 If there is no unreplaced place marker remaining, a warning message
6775 is output and the result is undefined. Place marker numbers must be
6776 in the range 1 to 99.
6778 QString QString::arg(const QString &a, int fieldWidth, QChar fillChar) const
6780 ArgEscapeData d = findArgEscapes(*this);
6782 if (d.occurrences == 0) {
6783 qWarning("QString::arg: Argument missing: %s, %s", toLocal8Bit().data(),
6784 a.toLocal8Bit().data());
6787 return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar);
6791 \fn QString QString::arg(const QString& a1, const QString& a2) const
6794 This is the same as \c {str.arg(a1).arg(a2)}, except that the
6795 strings \a a1 and \a a2 are replaced in one pass. This can make a
6796 difference if \a a1 contains e.g. \c{%1}:
6798 \snippet qstring/main.cpp 13
6802 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const
6805 This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except
6806 that the strings \a a1, \a a2 and \a a3 are replaced in one pass.
6810 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const
6813 This is the same as calling \c
6814 {str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a
6815 a1, \a a2, \a a3 and \a a4 are replaced in one pass.
6819 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const
6822 This is the same as calling \c
6823 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings
6824 \a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass.
6828 \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const
6831 This is the same as calling \c
6832 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that
6833 the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are
6834 replaced in one pass.
6838 \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
6841 This is the same as calling \c
6842 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)},
6843 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6,
6844 and \a a7 are replaced in one pass.
6848 \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
6851 This is the same as calling \c
6852 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)},
6853 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6854 a7, and \a a8 are replaced in one pass.
6858 \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
6861 This is the same as calling \c
6862 {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)},
6863 except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
6864 a7, \a a8, and \a a9 are replaced in one pass.
6867 /*! \fn QString QString::arg(int a, int fieldWidth, int base, QChar fillChar) const
6870 The \a a argument is expressed in base \a base, which is 10 by
6871 default and must be between 2 and 36. For bases other than 10, \a a
6872 is treated as an unsigned integer.
6874 \a fieldWidth specifies the minimum amount of space that \a a is
6875 padded to and filled with the character \a fillChar. A positive
6876 value produces right-aligned text; a negative value produces
6879 The '%' can be followed by an 'L', in which case the sequence is
6880 replaced with a localized representation of \a a. The conversion
6881 uses the default locale, set by QLocale::setDefault(). If no default
6882 locale was specified, the "C" locale is used. The 'L' flag is
6883 ignored if \a base is not 10.
6885 \snippet qstring/main.cpp 12
6886 \snippet qstring/main.cpp 14
6888 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6889 used. For negative numbers, zero padding might appear before the
6893 /*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const
6896 The \a base argument specifies the base to use when converting the
6897 integer \a a into a string. The base must be between 2 and 36.
6899 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6900 used. For negative numbers, zero padding might appear before the
6904 /*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const
6907 \a fieldWidth specifies the minimum amount of space that \a a is
6908 padded to and filled with the character \a fillChar. A positive
6909 value produces right-aligned text; a negative value produces
6912 The \a a argument is expressed in the given \a base, which is 10 by
6913 default and must be between 2 and 36.
6915 The '%' can be followed by an 'L', in which case the sequence is
6916 replaced with a localized representation of \a a. The conversion
6917 uses the default locale. The default locale is determined from the
6918 system's locale settings at application startup. It can be changed
6919 using QLocale::setDefault(). The 'L' flag is ignored if \a base is
6922 \snippet qstring/main.cpp 12
6923 \snippet qstring/main.cpp 14
6925 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6926 used. For negative numbers, zero padding might appear before the
6930 /*! \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
6933 \a fieldWidth specifies the minimum amount of space that \a a is
6934 padded to and filled with the character \a fillChar. A positive
6935 value produces right-aligned text; a negative value produces
6938 The \a base argument specifies the base to use when converting the
6939 integer \a a to a string. The base must be between 2 and 36, with 8
6940 giving octal, 10 decimal, and 16 hexadecimal numbers.
6942 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6943 used. For negative numbers, zero padding might appear before the
6950 \a fieldWidth specifies the minimum amount of space that \a a is
6951 padded to and filled with the character \a fillChar. A positive
6952 value produces right-aligned text; a negative value produces
6955 The \a base argument specifies the base to use when converting the
6956 integer \a a into a string. The base must be between 2 and 36, with
6957 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
6959 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
6960 used. For negative numbers, zero padding might appear before the
6963 QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const
6965 ArgEscapeData d = findArgEscapes(*this);
6967 if (d.occurrences == 0) {
6968 qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
6972 unsigned flags = QLocalePrivate::NoFlags;
6973 if (fillChar == QLatin1Char('0'))
6974 flags = QLocalePrivate::ZeroPadded;
6977 if (d.occurrences > d.locale_occurrences)
6978 arg = QLocale::c().d->longLongToString(a, -1, base, fieldWidth, flags);
6981 if (d.locale_occurrences > 0) {
6983 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
6984 flags |= QLocalePrivate::ThousandsGroup;
6985 locale_arg = locale.d->longLongToString(a, -1, base, fieldWidth, flags);
6988 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
6994 \a fieldWidth specifies the minimum amount of space that \a a is
6995 padded to and filled with the character \a fillChar. A positive
6996 value produces right-aligned text; a negative value produces
6999 The \a base argument specifies the base to use when converting the
7000 integer \a a into a string. \a base must be between 2 and 36, with 8
7001 giving octal, 10 decimal, and 16 hexadecimal numbers.
7003 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
7004 used. For negative numbers, zero padding might appear before the
7007 QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const
7009 ArgEscapeData d = findArgEscapes(*this);
7011 if (d.occurrences == 0) {
7012 qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
7016 unsigned flags = QLocalePrivate::NoFlags;
7017 if (fillChar == QLatin1Char('0'))
7018 flags = QLocalePrivate::ZeroPadded;
7021 if (d.occurrences > d.locale_occurrences)
7022 arg = QLocale::c().d->unsLongLongToString(a, -1, base, fieldWidth, flags);
7025 if (d.locale_occurrences > 0) {
7027 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
7028 flags |= QLocalePrivate::ThousandsGroup;
7029 locale_arg = locale.d->unsLongLongToString(a, -1, base, fieldWidth, flags);
7032 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
7038 \fn QString QString::arg(short a, int fieldWidth, int base, QChar fillChar) const
7040 \a fieldWidth specifies the minimum amount of space that \a a is
7041 padded to and filled with the character \a fillChar. A positive
7042 value produces right-aligned text; a negative value produces
7045 The \a base argument specifies the base to use when converting the
7046 integer \a a into a string. The base must be between 2 and 36, with
7047 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
7049 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
7050 used. For negative numbers, zero padding might appear before the
7055 \fn QString QString::arg(ushort a, int fieldWidth, int base, QChar fillChar) const
7058 \a fieldWidth specifies the minimum amount of space that \a a is
7059 padded to and filled with the character \a fillChar. A positive
7060 value produces right-aligned text; a negative value produces
7063 The \a base argument specifies the base to use when converting the
7064 integer \a a into a string. The base must be between 2 and 36, with
7065 8 giving octal, 10 decimal, and 16 hexadecimal numbers.
7067 If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
7068 used. For negative numbers, zero padding might appear before the
7075 QString QString::arg(QChar a, int fieldWidth, QChar fillChar) const
7079 return arg(c, fieldWidth, fillChar);
7085 The \a a argument is interpreted as a Latin-1 character.
7087 QString QString::arg(char a, int fieldWidth, QChar fillChar) const
7090 c += QLatin1Char(a);
7091 return arg(c, fieldWidth, fillChar);
7095 \fn QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
7098 Argument \a a is formatted according to the specified \a format and
7099 \a precision. See \l{Argument Formats} for details.
7101 \a fieldWidth specifies the minimum amount of space that \a a is
7102 padded to and filled with the character \a fillChar. A positive
7103 value produces right-aligned text; a negative value produces
7106 \snippet code/src_corelib_tools_qstring.cpp 2
7108 The '%' can be followed by an 'L', in which case the sequence is
7109 replaced with a localized representation of \a a. The conversion
7110 uses the default locale, set by QLocale::setDefaultLocale(). If no
7111 default locale was specified, the "C" locale is used.
7113 If \a fillChar is '0' (the number 0, ASCII 48), this function will
7114 use the locale's zero to pad. For negative numbers, the zero padding
7115 will probably appear before the minus sign.
7117 \sa QLocale::toString()
7119 QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillChar) const
7121 ArgEscapeData d = findArgEscapes(*this);
7123 if (d.occurrences == 0) {
7124 qWarning("QString::arg: Argument missing: %s, %g", toLocal8Bit().data(), a);
7128 unsigned flags = QLocalePrivate::NoFlags;
7129 if (fillChar == QLatin1Char('0'))
7130 flags = QLocalePrivate::ZeroPadded;
7133 flags |= QLocalePrivate::CapitalEorX;
7134 fmt = qToLower(fmt);
7136 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
7139 form = QLocalePrivate::DFDecimal;
7142 form = QLocalePrivate::DFExponent;
7145 form = QLocalePrivate::DFSignificantDigits;
7148 #if defined(QT_CHECK_RANGE)
7149 qWarning("QString::arg: Invalid format char '%c'", fmt);
7155 if (d.occurrences > d.locale_occurrences)
7156 arg = QLocale::c().d->doubleToString(a, prec, form, fieldWidth, flags);
7159 if (d.locale_occurrences > 0) {
7162 if (!locale.numberOptions() & QLocale::OmitGroupSeparator)
7163 flags |= QLocalePrivate::ThousandsGroup;
7164 locale_arg = locale.d->doubleToString(a, prec, form, fieldWidth, flags);
7167 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
7170 static int getEscape(const QChar *uc, int *pos, int len, int maxNumber = 999)
7174 if (i < len && uc[i] == QLatin1Char('L'))
7177 int escape = uc[i].unicode() - '0';
7178 if (uint(escape) >= 10U)
7182 int digit = uc[i].unicode() - '0';
7183 if (uint(digit) >= 10U)
7185 escape = (escape * 10) + digit;
7188 if (escape <= maxNumber) {
7196 QString QString::multiArg(int numArgs, const QString **args) const
7199 QMap<int, int> numbersUsed;
7200 const QChar *uc = (const QChar *) d->data();
7201 const int len = d->size;
7202 const int end = len - 1;
7203 int lastNumber = -1;
7206 // populate the numbersUsed map with the %n's that actually occur in the string
7208 if (uc[i] == QLatin1Char('%')) {
7209 int number = getEscape(uc, &i, len);
7211 numbersUsed.insert(number, -1);
7218 // assign an argument number to each of the %n's
7219 QMap<int, int>::iterator j = numbersUsed.begin();
7220 QMap<int, int>::iterator jend = numbersUsed.end();
7222 while (j != jend && arg < numArgs) {
7224 lastNumber = j.key();
7229 if (numArgs > arg) {
7230 qWarning("QString::arg: %d argument(s) missing in %s", numArgs - arg, toLocal8Bit().data());
7236 if (uc[i] == QLatin1Char('%') && i != end) {
7237 int number = getEscape(uc, &i, len, lastNumber);
7238 int arg = numbersUsed[number];
7239 if (number != -1 && arg != -1) {
7240 result += *args[arg];
7250 /*! \fn bool QString::isSimpleText() const
7254 bool QString::isSimpleText() const
7256 const ushort *p = d->data();
7257 const ushort * const end = p + d->size;
7260 // sort out regions of complex text formatting
7261 if (uc > 0x058f && (uc < 0x1100 || uc > 0xfb0f)) {
7270 /*! \fn bool QString::isRightToLeft() const
7272 Returns true if the string is read right to left.
7274 bool QString::isRightToLeft() const
7276 const ushort *p = d->data();
7277 const ushort * const end = p + d->size;
7280 if (QChar::isHighSurrogate(ucs4) && p < end - 1) {
7282 if (QChar::isLowSurrogate(low)) {
7283 ucs4 = QChar::surrogateToUcs4(ucs4, low);
7287 switch (QChar::direction(ucs4))
7302 /*! \fn QChar *QString::data()
7304 Returns a pointer to the data stored in the QString. The pointer
7305 can be used to access and modify the characters that compose the
7306 string. For convenience, the data is '\\0'-terminated.
7310 \snippet qstring/main.cpp 19
7312 Note that the pointer remains valid only as long as the string is
7313 not modified by other means. For read-only access, constData() is
7314 faster because it never causes a \l{deep copy} to occur.
7316 \sa constData(), operator[]()
7319 /*! \fn const QChar *QString::data() const
7324 /*! \fn const QChar *QString::constData() const
7326 Returns a pointer to the data stored in the QString. The pointer
7327 can be used to access the characters that compose the string. For
7328 convenience, the data is '\\0'-terminated.
7330 Note that the pointer remains valid only as long as the string is
7333 \sa data(), operator[]()
7336 /*! \fn void QString::push_front(const QString &other)
7338 This function is provided for STL compatibility, prepending the
7339 given \a other string to the beginning of this string. It is
7340 equivalent to \c prepend(other).
7345 /*! \fn void QString::push_front(QChar ch)
7349 Prepends the given \a ch character to the beginning of this string.
7352 /*! \fn void QString::push_back(const QString &other)
7354 This function is provided for STL compatibility, appending the
7355 given \a other string onto the end of this string. It is
7356 equivalent to \c append(other).
7361 /*! \fn void QString::push_back(QChar ch)
7365 Appends the given \a ch character onto the end of this string.
7369 \fn std::string QString::toStdString() const
7371 Returns a std::string object with the data contained in this
7372 QString. The Unicode data is converted into 8-bit characters using
7373 the toUtf8() function.
7375 This operator is mostly useful to pass a QString to a function
7376 that accepts a std::string object.
7378 If the QString contains non-Latin1 Unicode characters, using this
7379 can lead to loss of information.
7381 \sa toLatin1(), toUtf8(), toLocal8Bit()
7385 Constructs a QString that uses the first \a size Unicode characters
7386 in the array \a unicode. The data in \a unicode is \e not
7387 copied. The caller must be able to guarantee that \a unicode will
7388 not be deleted or modified as long as the QString (or an
7389 unmodified copy of it) exists.
7391 Any attempts to modify the QString or copies of it will cause it
7392 to create a deep copy of the data, ensuring that the raw data
7395 Here's an example of how we can use a QRegExp on raw data in
7396 memory without requiring to copy the data into a QString:
7398 \snippet qstring/main.cpp 22
7399 \snippet qstring/main.cpp 23
7401 \warning A string created with fromRawData() is \e not
7402 '\\0'-terminated, unless the raw data contains a '\\0' character
7403 at position \a size. This means unicode() will \e not return a
7404 '\\0'-terminated string (although utf16() does, at the cost of
7405 copying the raw data).
7407 \sa fromUtf16(), setRawData()
7409 QString QString::fromRawData(const QChar *unicode, int size)
7413 x = Data::sharedNull();
7415 x = Data::allocate(0);
7417 x = Data::fromRawData(reinterpret_cast<const ushort *>(unicode), size);
7420 QStringDataPtr dataPtr = { x };
7421 return QString(dataPtr);
7427 Resets the QString to use the first \a size Unicode characters
7428 in the array \a unicode. The data in \a unicode is \e not
7429 copied. The caller must be able to guarantee that \a unicode will
7430 not be deleted or modified as long as the QString (or an
7431 unmodified copy of it) exists.
7433 This function can be used instead of fromRawData() to re-use
7434 existings QString objects to save memory re-allocations.
7438 QString &QString::setRawData(const QChar *unicode, int size)
7440 if (d->ref.isShared() || d->alloc) {
7441 *this = fromRawData(unicode, size);
7445 d->offset = reinterpret_cast<const char *>(unicode) - reinterpret_cast<char *>(d);
7447 d->offset = sizeof(QStringData);
7454 /*! \class QLatin1String
7455 \brief The QLatin1String class provides a thin wrapper around an US-ASCII/Latin-1 encoded string literal.
7457 \ingroup string-processing
7460 Many of QString's member functions are overloaded to accept
7461 \c{const char *} instead of QString. This includes the copy
7462 constructor, the assignment operator, the comparison operators,
7463 and various other functions such as \l{QString::insert()}{insert()}, \l{QString::replace()}{replace()},
7464 and \l{QString::indexOf()}{indexOf()}. These functions
7465 are usually optimized to avoid constructing a QString object for
7466 the \c{const char *} data. For example, assuming \c str is a
7469 \snippet code/src_corelib_tools_qstring.cpp 3
7473 \snippet code/src_corelib_tools_qstring.cpp 4
7475 because it doesn't construct four temporary QString objects and
7476 make a deep copy of the character data.
7478 Applications that define \c QT_NO_CAST_FROM_ASCII (as explained
7479 in the QString documentation) don't have access to QString's
7480 \c{const char *} API. To provide an efficient way of specifying
7481 constant Latin-1 strings, Qt provides the QLatin1String, which is
7482 just a very thin wrapper around a \c{const char *}. Using
7483 QLatin1String, the example code above becomes
7485 \snippet code/src_corelib_tools_qstring.cpp 5
7487 This is a bit longer to type, but it provides exactly the same
7488 benefits as the first version of the code, and is faster than
7489 converting the Latin-1 strings using QString::fromLatin1().
7491 Thanks to the QString(QLatin1String) constructor,
7492 QLatin1String can be used everywhere a QString is expected. For
7495 \snippet code/src_corelib_tools_qstring.cpp 6
7497 \sa QString, QLatin1Char, QStringLiteral
7500 /*! \fn QLatin1String::QLatin1String(const char *str)
7502 Constructs a QLatin1String object that stores \a str. Note that if
7503 \a str is 0, an empty string is created; this case is handled by
7506 The string data is \e not copied. The caller must be able to
7507 guarantee that \a str will not be deleted or modified as long as
7508 the QLatin1String object exists.
7513 /*! \fn QLatin1String::QLatin1String(const char *str, int size)
7515 Constructs a QLatin1String object that stores \a str with \a size.
7516 Note that if \a str is 0, an empty string is created; this case
7517 is handled by QString.
7519 The string data is \e not copied. The caller must be able to
7520 guarantee that \a str will not be deleted or modified as long as
7521 the QLatin1String object exists.
7526 /*! \fn QLatin1String::QLatin1String(const QByteArray &str)
7528 Constructs a QLatin1String object that stores \a str.
7530 The string data is \e not copied. The caller must be able to
7531 guarantee that \a str will not be deleted or modified as long as
7532 the QLatin1String object exists.
7537 /*! \fn const char *QLatin1String::latin1() const
7539 Returns the Latin-1 string stored in this object.
7542 /*! \fn int QLatin1String::size() const
7544 Returns the size of the Latin-1 string stored in this object.
7547 /*! \fn bool QLatin1String::operator==(const QString &other) const
7549 Returns true if this string is equal to string \a other;
7550 otherwise returns false.
7552 The comparison is based exclusively on the numeric Unicode values
7553 of the characters and is very fast, but is not what a human would
7554 expect. Consider sorting user-interface strings with
7555 QString::localeAwareCompare().
7559 \fn bool QLatin1String::operator==(const char *other) const
7563 The \a other const char pointer is converted to a QString using
7564 the QString::fromUtf8() function.
7566 You can disable this operator by defining \c
7567 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7568 can be useful if you want to ensure that all user-visible strings
7569 go through QObject::tr(), for example.
7572 /*! \fn bool QLatin1String::operator!=(const QString &other) const
7574 Returns true if this string is not equal to string \a other;
7575 otherwise returns false.
7577 The comparison is based exclusively on the numeric Unicode values
7578 of the characters and is very fast, but is not what a human would
7579 expect. Consider sorting user-interface strings with
7580 QString::localeAwareCompare().
7584 \fn bool QLatin1String::operator!=(const char *other) const
7586 \overload operator!=()
7588 The \a other const char pointer is converted to a QString using
7589 the QString::fromUtf8() function.
7591 You can disable this operator by defining \c
7592 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7593 can be useful if you want to ensure that all user-visible strings
7594 go through QObject::tr(), for example.
7598 \fn bool QLatin1String::operator>(const QString &other) const
7600 Returns true if this string is lexically greater than string \a
7601 other; otherwise returns false.
7603 The comparison is based exclusively on the numeric Unicode values
7604 of the characters and is very fast, but is not what a human would
7605 expect. Consider sorting user-interface strings with
7606 QString::localeAwareCompare().
7610 \fn bool QLatin1String::operator>(const char *other) const
7614 The \a other const char pointer is converted to a QString using
7615 the QString::fromUtf8() function.
7617 You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
7618 when you compile your applications. This can be useful if you want
7619 to ensure that all user-visible strings go through QObject::tr(),
7624 \fn bool QLatin1String::operator<(const QString &other) const
7626 Returns true if this string is lexically less than the \a other
7627 string; otherwise returns false.
7629 The comparison is based exclusively on the numeric Unicode values
7630 of the characters and is very fast, but is not what a human would
7631 expect. Consider sorting user-interface strings using the
7632 QString::localeAwareCompare() function.
7636 \fn bool QLatin1String::operator<(const char *other) const
7640 The \a other const char pointer is converted to a QString using
7641 the QString::fromUtf8() function.
7643 You can disable this operator by defining \c
7644 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7645 can be useful if you want to ensure that all user-visible strings
7646 go through QObject::tr(), for example.
7650 \fn bool QLatin1String::operator>=(const QString &other) const
7652 Returns true if this string is lexically greater than or equal
7653 to string \a other; otherwise returns false.
7655 The comparison is based exclusively on the numeric Unicode values
7656 of the characters and is very fast, but is not what a human would
7657 expect. Consider sorting user-interface strings with
7658 QString::localeAwareCompare().
7662 \fn bool QLatin1String::operator>=(const char *other) const
7666 The \a other const char pointer is converted to a QString using
7667 the QString::fromUtf8() function.
7669 You can disable this operator by defining \c
7670 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7671 can be useful if you want to ensure that all user-visible strings
7672 go through QObject::tr(), for example.
7675 /*! \fn bool QLatin1String::operator<=(const QString &other) const
7677 Returns true if this string is lexically less than or equal
7678 to string \a other; otherwise returns false.
7680 The comparison is based exclusively on the numeric Unicode values
7681 of the characters and is very fast, but is not what a human would
7682 expect. Consider sorting user-interface strings with
7683 QString::localeAwareCompare().
7687 \fn bool QLatin1String::operator<=(const char *other) const
7691 The \a other const char pointer is converted to a QString using
7692 the QString::fromUtf8() function.
7694 You can disable this operator by defining \c
7695 QT_NO_CAST_FROM_ASCII when you compile your applications. This
7696 can be useful if you want to ensure that all user-visible strings
7697 go through QObject::tr(), for example.
7702 /*! \fn bool operator==(QLatin1String s1, QLatin1String s2)
7703 \relates QLatin1String
7705 Returns true if string \a s1 is lexically equal to string \a s2; otherwise
7708 /*! \fn bool operator!=(QLatin1String s1, QLatin1String s2)
7709 \relates QLatin1String
7711 Returns true if string \a s1 is lexically unequal to string \a s2; otherwise
7714 /*! \fn bool operator<(QLatin1String s1, QLatin1String s2)
7715 \relates QLatin1String
7717 Returns true if string \a s1 is lexically smaller than string \a s2; otherwise
7720 /*! \fn bool operator<=(QLatin1String s1, QLatin1String s2)
7721 \relates QLatin1String
7723 Returns true if string \a s1 is lexically smaller than or equal to string \a s2; otherwise
7726 /*! \fn bool operator>(QLatin1String s1, QLatin1String s2)
7727 \relates QLatin1String
7729 Returns true if string \a s1 is lexically greater than string \a s2; otherwise
7732 /*! \fn bool operator>=(QLatin1String s1, QLatin1String s2)
7733 \relates QLatin1String
7735 Returns true if string \a s1 is lexically greater than or equal to
7736 string \a s2; otherwise returns false.
7740 #if !defined(QT_NO_DATASTREAM) || (defined(QT_BOOTSTRAPPED) && !defined(QT_BUILD_QMAKE))
7742 \fn QDataStream &operator<<(QDataStream &stream, const QString &string)
7745 Writes the given \a string to the specified \a stream.
7747 \sa {Serializing Qt Data Types}
7750 QDataStream &operator<<(QDataStream &out, const QString &str)
7752 if (out.version() == 1) {
7753 out << str.toLatin1();
7755 if (!str.isNull() || out.version() < 3) {
7756 if ((out.byteOrder() == QDataStream::BigEndian) == (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7757 out.writeBytes(reinterpret_cast<const char *>(str.unicode()), sizeof(QChar) * str.length());
7759 QVarLengthArray<ushort> buffer(str.length());
7760 const ushort *data = reinterpret_cast<const ushort *>(str.constData());
7761 for (int i = 0; i < str.length(); i++) {
7762 buffer[i] = qbswap(*data);
7765 out.writeBytes(reinterpret_cast<const char *>(buffer.data()), sizeof(ushort) * buffer.size());
7768 // write null marker
7769 out << (quint32)0xffffffff;
7776 \fn QDataStream &operator>>(QDataStream &stream, QString &string)
7779 Reads a string from the specified \a stream into the given \a string.
7781 \sa {Serializing Qt Data Types}
7784 QDataStream &operator>>(QDataStream &in, QString &str)
7786 #ifdef QT_QSTRING_UCS_4
7787 #if defined(Q_CC_GNU)
7788 #warning "operator>> not working properly"
7792 if (in.version() == 1) {
7795 str = QString::fromLatin1(l);
7798 in >> bytes; // read size of string
7799 if (bytes == 0xffffffff) { // null string
7801 } else if (bytes > 0) { // not empty
7804 in.setStatus(QDataStream::ReadCorruptData);
7808 const quint32 Step = 1024 * 1024;
7809 quint32 len = bytes / 2;
7810 quint32 allocated = 0;
7812 while (allocated < len) {
7813 int blockSize = qMin(Step, len - allocated);
7814 str.resize(allocated + blockSize);
7815 if (in.readRawData(reinterpret_cast<char *>(str.data()) + allocated * 2,
7816 blockSize * 2) != blockSize * 2) {
7818 in.setStatus(QDataStream::ReadPastEnd);
7821 allocated += blockSize;
7824 if ((in.byteOrder() == QDataStream::BigEndian)
7825 != (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
7826 ushort *data = reinterpret_cast<ushort *>(str.data());
7828 *data = qbswap(*data);
7833 str = QString(QLatin1String(""));
7838 #endif // QT_NO_DATASTREAM
7846 \brief The QStringRef class provides a thin wrapper around QString substrings.
7849 \ingroup string-processing
7851 QStringRef provides a read-only subset of the QString API.
7853 A string reference explicitly references a portion of a string()
7854 with a given size(), starting at a specific position(). Calling
7855 toString() returns a copy of the data as a real QString instance.
7857 This class is designed to improve the performance of substring
7858 handling when manipulating substrings obtained from existing QString
7859 instances. QStringRef avoids the memory allocation and reference
7860 counting overhead of a standard QString by simply referencing a
7861 part of the original string. This can prove to be advantageous in
7862 low level code, such as that used in a parser, at the expense of
7863 potentially more complex code.
7865 For most users, there are no semantic benefits to using QStringRef
7866 instead of QString since QStringRef requires attention to be paid
7867 to memory management issues, potentially making code more complex
7868 to write and maintain.
7870 \warning A QStringRef is only valid as long as the referenced
7871 string exists. If the original string is deleted, the string
7872 reference points to an invalid memory location.
7874 We suggest that you only use this class in stable code where profiling
7875 has clearly identified that performance improvements can be made by
7876 replacing standard string operations with the optimized substring
7877 handling provided by this class.
7879 \sa {Implicitly Shared Classes}
7884 \fn QStringRef::QStringRef()
7886 Constructs an empty string reference.
7889 /*! \fn QStringRef::QStringRef(const QString *string, int position, int length)
7891 Constructs a string reference to the range of characters in the given
7892 \a string specified by the starting \a position and \a length in characters.
7894 \warning This function exists to improve performance as much as possible,
7895 and performs no bounds checking. For program correctness, \a position and
7896 \a length must describe a valid substring of \a string.
7898 This means that the starting \a position must be positive or 0 and smaller
7899 than \a string's length, and \a length must be positive or 0 but smaller than
7900 the string's length minus the starting \a position;
7901 i.e, 0 <= position < string->length() and
7902 0 <= length <= string->length() - position must both be satisfied.
7905 /*! \fn QStringRef::QStringRef(const QString *string)
7907 Constructs a string reference to the given \a string.
7910 /*! \fn QStringRef::QStringRef(const QStringRef &other)
7912 Constructs a copy of the \a other string reference.
7915 \fn QStringRef::~QStringRef()
7917 Destroys the string reference.
7919 Since this class is only used to refer to string data, and does not take
7920 ownership of it, no memory is freed when instances are destroyed.
7925 \fn int QStringRef::position() const
7927 Returns the starting position in the referenced string that is referred to
7928 by the string reference.
7930 \sa size(), string()
7934 \fn int QStringRef::size() const
7936 Returns the number of characters referred to by the string reference.
7937 Equivalent to length() and count().
7939 \sa position(), string()
7942 \fn int QStringRef::count() const
7943 Returns the number of characters referred to by the string reference.
7944 Equivalent to size() and length().
7946 \sa position(), string()
7949 \fn int QStringRef::length() const
7950 Returns the number of characters referred to by the string reference.
7951 Equivalent to size() and count().
7953 \sa position(), string()
7958 \fn bool QStringRef::isEmpty() const
7960 Returns true if the string reference has no characters; otherwise returns
7963 A string reference is empty if its size is zero.
7969 \fn bool QStringRef::isNull() const
7971 Returns true if string() returns a null pointer or a pointer to a
7972 null string; otherwise returns true.
7978 \fn const QString *QStringRef::string() const
7980 Returns a pointer to the string referred to by the string reference, or
7981 0 if it does not reference a string.
7988 \fn const QChar *QStringRef::unicode() const
7990 Returns a Unicode representation of the string reference. Since
7991 the data stems directly from the referenced string, it is not
7992 null-terminated unless the string reference includes the string's
7999 \fn const QChar *QStringRef::data() const
8005 \fn const QChar *QStringRef::constData() const
8011 Returns a copy of the string reference as a QString object.
8013 If the string reference is not a complete reference of the string
8014 (meaning that position() is 0 and size() equals string()->size()),
8015 this function will allocate a new string to return.
8020 QString QStringRef::toString() const {
8023 if (m_size && m_position == 0 && m_size == m_string->size())
8025 return QString(m_string->unicode() + m_position, m_size);
8029 /*! \relates QStringRef
8031 Returns true if string reference \a s1 is lexically equal to string reference \a s2; otherwise
8034 bool operator==(const QStringRef &s1,const QStringRef &s2)
8035 { return (s1.size() == s2.size() &&
8036 qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
8039 /*! \relates QStringRef
8041 Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
8044 bool operator==(const QString &s1,const QStringRef &s2)
8045 { return (s1.size() == s2.size() &&
8046 qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size()));
8049 /*! \relates QStringRef
8051 Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise
8054 bool operator==(QLatin1String s1, const QStringRef &s2)
8056 if (s1.size() != s2.size())
8059 const ushort *uc = reinterpret_cast<const ushort *>(s2.unicode());
8060 const ushort *e = uc + s2.size();
8061 const uchar *c = reinterpret_cast<const uchar *>(s1.latin1());
8063 return s2.isEmpty();
8066 if (uc == e || *uc != *c)
8077 Returns true if string reference \a s1 is lexically less than
8078 string reference \a s2; otherwise returns false.
8080 The comparison is based exclusively on the numeric Unicode values
8081 of the characters and is very fast, but is not what a human would
8082 expect. Consider sorting user-interface strings using the
8083 QString::localeAwareCompare() function.
8085 bool operator<(const QStringRef &s1,const QStringRef &s2)
8087 return ucstrcmp(s1.constData(), s1.length(), s2.constData(), s2.length()) < 0;
8090 /*!\fn bool operator<=(const QStringRef &s1,const QStringRef &s2)
8094 Returns true if string reference \a s1 is lexically less than
8095 or equal to string reference \a s2; otherwise returns false.
8097 The comparison is based exclusively on the numeric Unicode values
8098 of the characters and is very fast, but is not what a human would
8099 expect. Consider sorting user-interface strings using the
8100 QString::localeAwareCompare() function.
8103 /*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2)
8107 Returns true if string reference \a s1 is lexically greater than
8108 or equal to string reference \a s2; otherwise returns false.
8110 The comparison is based exclusively on the numeric Unicode values
8111 of the characters and is very fast, but is not what a human would
8112 expect. Consider sorting user-interface strings using the
8113 QString::localeAwareCompare() function.
8116 /*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2)
8120 Returns true if string reference \a s1 is lexically greater than
8121 string reference \a s2; otherwise returns false.
8123 The comparison is based exclusively on the numeric Unicode values
8124 of the characters and is very fast, but is not what a human would
8125 expect. Consider sorting user-interface strings using the
8126 QString::localeAwareCompare() function.
8131 \fn const QChar QStringRef::at(int position) const
8133 Returns the character at the given index \a position in the
8136 The \a position must be a valid index position in the string
8137 (i.e., 0 <= \a position < size()).
8141 \fn void QStringRef::clear()
8143 Clears the contents of the string reference by making it null and empty.
8145 \sa isEmpty(), isNull()
8149 \fn QStringRef &QStringRef::operator=(const QStringRef &other)
8151 Assigns the \a other string reference to this string reference, and
8156 \fn QStringRef &QStringRef::operator=(const QString *string)
8158 Constructs a string reference to the given \a string and assigns it to
8159 this string reference, returning the result.
8163 \typedef QString::DataPtr
8168 \fn DataPtr & QString::data_ptr()
8174 /*! Appends the string reference to \a string, and returns a new
8175 reference to the combined string data.
8177 QStringRef QStringRef::appendTo(QString *string) const
8180 return QStringRef();
8181 int pos = string->size();
8182 string->insert(pos, unicode(), size());
8183 return QStringRef(string, pos, size());
8187 \fn int QStringRef::compare(const QStringRef &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8190 Compares the string \a s1 with the string \a s2 and returns an
8191 integer less than, equal to, or greater than zero if \a s1
8192 is less than, equal to, or greater than \a s2.
8194 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8195 otherwise the comparison is case insensitive.
8199 \fn int QStringRef::compare(const QStringRef &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8203 Compares the string \a s1 with the string \a s2 and returns an
8204 integer less than, equal to, or greater than zero if \a s1
8205 is less than, equal to, or greater than \a s2.
8207 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8208 otherwise the comparison is case insensitive.
8212 \fn int QStringRef::compare(const QStringRef &s1, QLatin1String s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
8216 Compares the string \a s1 with the string \a s2 and returns an
8217 integer less than, equal to, or greater than zero if \a s1
8218 is less than, equal to, or greater than \a s2.
8220 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8221 otherwise the comparison is case insensitive.
8226 \fn int QStringRef::compare(const QString &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8229 Compares this string with the \a other string and returns an
8230 integer less than, equal to, or greater than zero if this string
8231 is less than, equal to, or greater than the \a other string.
8233 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8234 otherwise the comparison is case insensitive.
8236 Equivalent to \c {compare(*this, other, cs)}.
8238 \sa QString::compare()
8243 \fn int QStringRef::compare(const QStringRef &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8246 Compares this string with the \a other string and returns an
8247 integer less than, equal to, or greater than zero if this string
8248 is less than, equal to, or greater than the \a other string.
8250 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8251 otherwise the comparison is case insensitive.
8253 Equivalent to \c {compare(*this, other, cs)}.
8255 \sa QString::compare()
8260 \fn int QStringRef::compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8263 Compares this string with the \a other string and returns an
8264 integer less than, equal to, or greater than zero if this string
8265 is less than, equal to, or greater than the \a other string.
8267 If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
8268 otherwise the comparison is case insensitive.
8270 Equivalent to \c {compare(*this, other, cs)}.
8272 \sa QString::compare()
8276 \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QString & s2)
8279 Compares \a s1 with \a s2 and returns an integer less than, equal
8280 to, or greater than zero if \a s1 is less than, equal to, or
8283 The comparison is performed in a locale- and also
8284 platform-dependent manner. Use this function to present sorted
8285 lists of strings to the user.
8287 On Mac OS X, this function compares according the
8288 "Order for sorted lists" setting in the International prefereces panel.
8290 \sa compare(), QTextCodec::locale()
8294 \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QStringRef & s2)
8298 Compares \a s1 with \a s2 and returns an integer less than, equal
8299 to, or greater than zero if \a s1 is less than, equal to, or
8302 The comparison is performed in a locale- and also
8303 platform-dependent manner. Use this function to present sorted
8304 lists of strings to the user.
8309 \fn int QStringRef::localeAwareCompare(const QString &other) const
8313 Compares this string with the \a other string and returns an
8314 integer less than, equal to, or greater than zero if this string
8315 is less than, equal to, or greater than the \a other string.
8317 The comparison is performed in a locale- and also
8318 platform-dependent manner. Use this function to present sorted
8319 lists of strings to the user.
8323 \fn int QStringRef::localeAwareCompare(const QStringRef &other) const
8327 Compares this string with the \a other string and returns an
8328 integer less than, equal to, or greater than zero if this string
8329 is less than, equal to, or greater than the \a other string.
8331 The comparison is performed in a locale- and also
8332 platform-dependent manner. Use this function to present sorted
8333 lists of strings to the user.
8337 \fn QString &QString::append(const QStringRef &reference)
8340 Appends the given string \a reference to this string and returns the result.
8342 QString &QString::append(const QStringRef &str)
8344 if (str.string() == this) {
8346 } else if (str.string()) {
8347 int oldSize = size();
8348 resize(oldSize + str.size());
8349 memcpy(data() + oldSize, str.unicode(), str.size() * sizeof(QChar));
8357 Returns a substring reference to the \a n leftmost characters
8360 If \a n is greater than size() or less than zero, a reference to the entire
8363 \snippet qstring/main.cpp leftRef
8365 \sa left(), rightRef(), midRef(), startsWith()
8367 QStringRef QString::leftRef(int n) const
8369 if (n >= d->size || n < 0)
8371 return QStringRef(this, 0, n);
8377 Returns a substring reference to the \a n rightmost characters
8380 If \a n is greater than size() or less than zero, a reference to the entire
8383 \snippet qstring/main.cpp rightRef
8385 \sa right(), leftRef(), midRef(), endsWith()
8387 QStringRef QString::rightRef(int n) const
8389 if (n >= d->size || n < 0)
8391 return QStringRef(this, d->size - n, n);
8397 Returns a substring reference to \a n characters of this string,
8398 starting at the specified \a position.
8400 If the \a position exceeds the length of the string, a null
8401 reference is returned.
8403 If there are less than \a n characters available in the string,
8404 starting at the given \a position, or if \a n is -1 (default), the
8405 function returns all characters from the specified \a position
8410 \snippet qstring/main.cpp midRef
8412 \sa mid(), leftRef(), rightRef()
8415 QStringRef QString::midRef(int position, int n) const
8417 if (position > d->size)
8418 return QStringRef();
8420 if (n < 0 || n + position >= d->size)
8421 return QStringRef(this, 0, d->size);
8422 if (n + position <= 0)
8423 return QStringRef();
8427 } else if (n < 0 || n > d->size - position)
8428 n = d->size - position;
8429 return QStringRef(this, position, n);
8435 Returns the index position of the first occurrence of the string \a
8436 str in this string reference, searching forward from index position
8437 \a from. Returns -1 if \a str is not found.
8439 If \a cs is Qt::CaseSensitive (default), the search is case
8440 sensitive; otherwise the search is case insensitive.
8442 If \a from is -1, the search starts at the last character; if it is
8443 -2, at the next to last character and so on.
8445 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8447 int QStringRef::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8449 return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs);
8456 Returns the index position of the first occurrence of the
8457 character \a ch in the string reference, searching forward from
8458 index position \a from. Returns -1 if \a ch could not be found.
8460 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8462 int QStringRef::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8464 return findChar(unicode(), length(), ch, from, cs);
8470 Returns the index position of the first occurrence of the string \a
8471 str in this string reference, searching forward from index position
8472 \a from. Returns -1 if \a str is not found.
8474 If \a cs is Qt::CaseSensitive (default), the search is case
8475 sensitive; otherwise the search is case insensitive.
8477 If \a from is -1, the search starts at the last character; if it is
8478 -2, at the next to last character and so on.
8480 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8482 int QStringRef::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8484 return qt_find_latin1_string(unicode(), size(), str, from, cs);
8492 Returns the index position of the first occurrence of the string
8493 reference \a str in this string reference, searching forward from
8494 index position \a from. Returns -1 if \a str is not found.
8496 If \a cs is Qt::CaseSensitive (default), the search is case
8497 sensitive; otherwise the search is case insensitive.
8499 \sa QString::indexOf(), lastIndexOf(), contains(), count()
8501 int QStringRef::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8503 return qFindString(unicode(), size(), from, str.unicode(), str.size(), cs);
8509 Returns the index position of the last occurrence of the string \a
8510 str in this string reference, searching backward from index position
8511 \a from. If \a from is -1 (default), the search starts at the last
8512 character; if \a from is -2, at the next to last character and so
8513 on. Returns -1 if \a str is not found.
8515 If \a cs is Qt::CaseSensitive (default), the search is case
8516 sensitive; otherwise the search is case insensitive.
8518 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8520 int QStringRef::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
8522 const int sl = str.size();
8524 return lastIndexOf(str.at(0), from, cs);
8526 const int l = size();;
8530 if (from == l && sl == 0)
8532 if (from < 0 || from >= l || delta < 0)
8537 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8538 reinterpret_cast<const ushort*>(str.unicode()), str.size(), cs);
8543 \overload lastIndexOf()
8545 Returns the index position of the last occurrence of the character
8546 \a ch, searching backward from position \a from.
8548 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8550 int QStringRef::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
8552 return qt_last_index_of(unicode(), size(), ch, from, cs);
8557 \overload lastIndexOf()
8559 Returns the index position of the last occurrence of the string \a
8560 str in this string reference, searching backward from index position
8561 \a from. If \a from is -1 (default), the search starts at the last
8562 character; if \a from is -2, at the next to last character and so
8563 on. Returns -1 if \a str is not found.
8565 If \a cs is Qt::CaseSensitive (default), the search is case
8566 sensitive; otherwise the search is case insensitive.
8568 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8570 int QStringRef::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
8572 const int sl = str.size();
8574 return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs);
8576 const int l = size();
8580 if (from == l && sl == 0)
8582 if (from < 0 || from >= l || delta < 0)
8587 QVarLengthArray<ushort> s(sl);
8588 for (int i = 0; i < sl; ++i)
8589 s[i] = str.latin1()[i];
8591 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, s.data(), sl, cs);
8596 \overload lastIndexOf()
8598 Returns the index position of the last occurrence of the string
8599 reference \a str in this string reference, searching backward from
8600 index position \a from. If \a from is -1 (default), the search
8601 starts at the last character; if \a from is -2, at the next to last
8602 character and so on. Returns -1 if \a str is not found.
8604 If \a cs is Qt::CaseSensitive (default), the search is case
8605 sensitive; otherwise the search is case insensitive.
8607 \sa QString::lastIndexOf(), indexOf(), contains(), count()
8609 int QStringRef::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
8611 const int sl = str.size();
8613 return lastIndexOf(str.at(0), from, cs);
8615 const int l = size();
8619 if (from == l && sl == 0)
8621 if (from < 0 || from >= l || delta < 0)
8626 return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from,
8627 reinterpret_cast<const ushort*>(str.unicode()),
8633 Returns the number of (potentially overlapping) occurrences of
8634 the string \a str in this string reference.
8636 If \a cs is Qt::CaseSensitive (default), the search is
8637 case sensitive; otherwise the search is case insensitive.
8639 \sa QString::count(), contains(), indexOf()
8641 int QStringRef::count(const QString &str, Qt::CaseSensitivity cs) const
8643 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8650 Returns the number of occurrences of the character \a ch in the
8653 If \a cs is Qt::CaseSensitive (default), the search is
8654 case sensitive; otherwise the search is case insensitive.
8656 \sa QString::count(), contains(), indexOf()
8658 int QStringRef::count(QChar ch, Qt::CaseSensitivity cs) const
8660 return qt_string_count(unicode(), size(), ch, cs);
8667 Returns the number of (potentially overlapping) occurrences of the
8668 string reference \a str in this string reference.
8670 If \a cs is Qt::CaseSensitive (default), the search is
8671 case sensitive; otherwise the search is case insensitive.
8673 \sa QString::count(), contains(), indexOf()
8675 int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs) const
8677 return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs);
8683 Returns true if the string reference starts with \a str; otherwise
8686 If \a cs is Qt::CaseSensitive (default), the search is
8687 case sensitive; otherwise the search is case insensitive.
8689 \sa QString::startsWith(), endsWith()
8691 bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs) const
8693 return qt_starts_with(isNull() ? 0 : unicode(), size(),
8694 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8699 \overload startsWith()
8700 \sa QString::startsWith(), endsWith()
8702 bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8704 return qt_starts_with(isNull() ? 0 : unicode(), size(), str, cs);
8709 \overload startsWith()
8710 \sa QString::startsWith(), endsWith()
8712 bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8714 return qt_starts_with(isNull() ? 0 : unicode(), size(),
8715 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8720 \overload startsWith()
8722 Returns true if the string reference starts with \a ch; otherwise
8725 If \a cs is Qt::CaseSensitive (default), the search is case
8726 sensitive; otherwise the search is case insensitive.
8728 \sa QString::startsWith(), endsWith()
8730 bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs) const
8733 const ushort *data = reinterpret_cast<const ushort*>(unicode());
8734 return (cs == Qt::CaseSensitive
8736 : foldCase(data[0]) == foldCase(ch.unicode()));
8744 Returns true if the string reference ends with \a str; otherwise
8747 If \a cs is Qt::CaseSensitive (default), the search is case
8748 sensitive; otherwise the search is case insensitive.
8750 \sa QString::endsWith(), startsWith()
8752 bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs) const
8754 return qt_ends_with(isNull() ? 0 : unicode(), size(),
8755 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8760 \overload endsWith()
8762 Returns true if the string reference ends with \a ch; otherwise
8765 If \a cs is Qt::CaseSensitive (default), the search is case
8766 sensitive; otherwise the search is case insensitive.
8768 \sa QString::endsWith(), endsWith()
8770 bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs) const
8773 const ushort *data = reinterpret_cast<const ushort*>(unicode());
8774 const int size = length();
8775 return (cs == Qt::CaseSensitive
8776 ? data[size - 1] == ch
8777 : foldCase(data[size - 1]) == foldCase(ch.unicode()));
8785 \overload endsWith()
8786 \sa QString::endsWith(), endsWith()
8788 bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs) const
8790 return qt_ends_with(isNull() ? 0 : unicode(), size(), str, cs);
8795 \overload endsWith()
8796 \sa QString::endsWith(), endsWith()
8798 bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
8800 return qt_ends_with(isNull() ? 0 : unicode(), size(),
8801 str.isNull() ? 0 : str.unicode(), str.size(), cs);
8805 /*! \fn bool QStringRef::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8808 Returns true if this string reference contains an occurrence of
8809 the string \a str; otherwise returns false.
8811 If \a cs is Qt::CaseSensitive (default), the search is
8812 case sensitive; otherwise the search is case insensitive.
8814 \sa indexOf(), count()
8817 /*! \fn bool QStringRef::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8819 \overload contains()
8822 Returns true if this string contains an occurrence of the
8823 character \a ch; otherwise returns false.
8825 If \a cs is Qt::CaseSensitive (default), the search is
8826 case sensitive; otherwise the search is case insensitive.
8830 /*! \fn bool QStringRef::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
8831 \overload contains()
8834 Returns true if this string reference contains an occurrence of
8835 the string reference \a str; otherwise returns false.
8837 If \a cs is Qt::CaseSensitive (default), the search is
8838 case sensitive; otherwise the search is case insensitive.
8840 \sa indexOf(), count()
8843 /*! \fn bool QStringRef::contains(QLatin1String str, Qt::CaseSensitivity cs) const
8845 \overload contains()
8847 Returns true if this string reference contains an occurrence of
8848 the string \a str; otherwise returns false.
8850 If \a cs is Qt::CaseSensitive (default), the search is
8851 case sensitive; otherwise the search is case insensitive.
8853 \sa indexOf(), count()
8856 static inline int qt_last_index_of(const QChar *haystack, int haystackLen, QChar needle,
8857 int from, Qt::CaseSensitivity cs)
8859 ushort c = needle.unicode();
8861 from += haystackLen;
8862 if (from < 0 || from >= haystackLen)
8865 const ushort *b = reinterpret_cast<const ushort*>(haystack);
8866 const ushort *n = b + from;
8867 if (cs == Qt::CaseSensitive) {
8874 if (foldCase(*n) == c)
8883 static inline int qt_string_count(const QChar *haystack, int haystackLen,
8884 const QChar *needle, int needleLen,
8885 Qt::CaseSensitivity cs)
8889 if (haystackLen > 500 && needleLen > 5) {
8890 QStringMatcher matcher(needle, needleLen, cs);
8891 while ((i = matcher.indexIn(haystack, haystackLen, i + 1)) != -1)
8894 while ((i = qFindString(haystack, haystackLen, i + 1, needle, needleLen, cs)) != -1)
8900 static inline int qt_string_count(const QChar *unicode, int size, QChar ch,
8901 Qt::CaseSensitivity cs)
8903 ushort c = ch.unicode();
8905 const ushort *b = reinterpret_cast<const ushort*>(unicode);
8906 const ushort *i = b + size;
8907 if (cs == Qt::CaseSensitive) {
8914 if (foldCase(*(--i)) == c)
8920 static inline int qt_find_latin1_string(const QChar *haystack, int size,
8921 QLatin1String needle,
8922 int from, Qt::CaseSensitivity cs)
8924 const char *latin1 = needle.latin1();
8925 int len = needle.size();
8926 QVarLengthArray<ushort> s(len);
8927 for (int i = 0; i < len; ++i)
8930 return qFindString(haystack, size, from,
8931 reinterpret_cast<const QChar*>(s.constData()), len, cs);
8934 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8935 const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
8939 if (haystackLen == 0)
8940 return needleLen == 0;
8941 if (needleLen > haystackLen)
8944 const ushort *h = reinterpret_cast<const ushort*>(haystack);
8945 const ushort *n = reinterpret_cast<const ushort*>(needle);
8947 if (cs == Qt::CaseSensitive) {
8948 return qMemEquals(h, n, needleLen);
8952 for (int i = 0; i < needleLen; ++i)
8953 if (foldCase(h[i], last) != foldCase(n[i], olast))
8959 static inline bool qt_starts_with(const QChar *haystack, int haystackLen,
8960 QLatin1String needle, Qt::CaseSensitivity cs)
8963 return !needle.latin1();
8964 if (haystackLen == 0)
8965 return !needle.latin1() || *needle.latin1() == 0;
8966 const int slen = needle.size();
8967 if (slen > haystackLen)
8969 const ushort *data = reinterpret_cast<const ushort*>(haystack);
8970 const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
8971 if (cs == Qt::CaseSensitive) {
8972 for (int i = 0; i < slen; ++i)
8973 if (data[i] != latin[i])
8976 for (int i = 0; i < slen; ++i)
8977 if (foldCase(data[i]) != foldCase((ushort)latin[i]))
8983 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
8984 const QChar *needle, int needleLen, Qt::CaseSensitivity cs)
8988 if (haystackLen == 0)
8989 return needleLen == 0;
8990 const int pos = haystackLen - needleLen;
8994 const ushort *h = reinterpret_cast<const ushort*>(haystack);
8995 const ushort *n = reinterpret_cast<const ushort*>(needle);
8997 if (cs == Qt::CaseSensitive) {
8998 return qMemEquals(h + pos, n, needleLen);
9002 for (int i = 0; i < needleLen; i++)
9003 if (foldCase(h[pos+i], last) != foldCase(n[i], olast))
9010 static inline bool qt_ends_with(const QChar *haystack, int haystackLen,
9011 QLatin1String needle, Qt::CaseSensitivity cs)
9014 return !needle.latin1();
9015 if (haystackLen == 0)
9016 return !needle.latin1() || *needle.latin1() == 0;
9017 const int slen = needle.size();
9018 int pos = haystackLen - slen;
9021 const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1());
9022 const ushort *data = reinterpret_cast<const ushort*>(haystack);
9023 if (cs == Qt::CaseSensitive) {
9024 for (int i = 0; i < slen; i++)
9025 if (data[pos+i] != latin[i])
9028 for (int i = 0; i < slen; i++)
9029 if (foldCase(data[pos+i]) != foldCase((ushort)latin[i]))
9038 Returns a Latin-1 representation of the string as a QByteArray.
9040 The returned byte array is undefined if the string contains non-Latin1
9041 characters. Those characters may be suppressed or replaced with a
9044 \sa toUtf8(), toLocal8Bit(), QTextCodec
9046 QByteArray QStringRef::toLatin1() const
9048 return toLatin1_helper(unicode(), length());
9052 \fn QByteArray QStringRef::toAscii() const
9056 Returns an 8-bit representation of the string as a QByteArray.
9058 This function does the same as toLatin1().
9060 Note that, despite the name, this function does not necessarily return an US-ASCII
9061 (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
9063 \sa toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
9069 Returns the local 8-bit representation of the string as a
9070 QByteArray. The returned byte array is undefined if the string
9071 contains characters not supported by the local 8-bit encoding.
9073 QTextCodec::codecForLocale() is used to perform the conversion from
9074 Unicode. If the locale encoding could not be determined, this function
9075 does the same as toLatin1().
9077 If this string contains any characters that cannot be encoded in the
9078 locale, the returned byte array is undefined. Those characters may be
9079 suppressed or replaced by another.
9081 \sa toLatin1(), toUtf8(), QTextCodec
9083 QByteArray QStringRef::toLocal8Bit() const
9085 #ifndef QT_NO_TEXTCODEC
9086 if (QTextCodec::codecForLocale())
9087 return QTextCodec::codecForLocale()->fromUnicode(unicode(), length());
9088 #endif // QT_NO_TEXTCODEC
9095 Returns a UTF-8 representation of the string as a QByteArray.
9097 UTF-8 is a Unicode codec and can represent all characters in a Unicode
9098 string like QString.
9100 However, in the Unicode range, there are certain codepoints that are not
9101 considered characters. The Unicode standard reserves the last two
9102 codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF,
9103 U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF,
9104 inclusive, as non-characters. If any of those appear in the string, they
9105 may be discarded and will not appear in the UTF-8 representation, or they
9106 may be replaced by one or more replacement characters.
9108 \sa toLatin1(), toLocal8Bit(), QTextCodec
9110 QByteArray QStringRef::toUtf8() const
9113 return QByteArray();
9115 return QUtf8::convertFromUnicode(constData(), length(), 0);
9121 Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
9123 UCS-4 is a Unicode codec and is lossless. All characters from this string
9124 can be encoded in UCS-4.
9126 \sa toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec
9128 QVector<uint> QStringRef::toUcs4() const
9130 QVector<uint> v(length());
9132 int len = QString::toUcs4_helper(reinterpret_cast<const ushort *>(unicode()), length(), a);
9140 \fn QString Qt::escape(const QString &plain)
9142 \sa QString::toHtmlEscaped()
9146 Converts the plain text string \a plain to a HTML string with
9147 HTML metacharacters \c{<}, \c{>}, \c{&}, and \c{"} replaced by HTML
9152 \snippet code/src_corelib_tools_qstring.cpp 7
9154 QString QString::toHtmlEscaped() const
9157 const int len = length();
9158 rich.reserve(int(len * 1.1));
9159 for (int i = 0; i < len; ++i) {
9160 if (at(i) == QLatin1Char('<'))
9161 rich += QLatin1String("<");
9162 else if (at(i) == QLatin1Char('>'))
9163 rich += QLatin1String(">");
9164 else if (at(i) == QLatin1Char('&'))
9165 rich += QLatin1String("&");
9166 else if (at(i) == QLatin1Char('"'))
9167 rich += QLatin1String(""");
9176 \macro QStringLiteral(str)
9179 The macro generates the data for a QString out of \a str at compile time if the compiler supports it.
9180 Creating a QString from it is free in this case, and the generated string data is stored in
9181 the read-only segment of the compiled object file.
9183 For compilers not supporting the creation of compile time strings, QStringLiteral will fall back to
9186 The result of the QStringLiteral expression can be cast into a QString.
9188 If you have code looking like:
9190 if (node.hasAttribute("http-contents-length")) //...
9192 One temporary QString will be created to be passed as the hasAttribute function parameter.
9193 This can be quite expensive, as it involves a memory allocation and the copy and the conversion
9194 of the data into QString's internal encoding.
9196 This can be avoided by doing
9198 if (node.hasAttribute(QStringLiteral("http-contents-length"))) //...
9200 Then the QString's internal data will be generated at compile time and no conversion or allocation
9201 will occur at runtime
9203 Using QStringLiteral instead of a double quoted ascii literal can significantly speed up creation
9204 of QString's from data known at compile time.
9206 If the compiler is C++11 enabled the string \a str can actually contain unicode data.
9208 \note There are still a few cases in which QLatin1String is more efficient than QStringLiteral:
9209 If it is passed to a function that has an overload that takes the QLatin1String directly, without
9210 conversion to QString. For instance, this is the case of QString::operator==
9212 if (attribute.name() == QLatin1String("http-contents-length")) //...