1 /****************************************************************************
2 **
3 ** Copyright (C) 2020 The Qt Company Ltd.
4 ** Copyright (C) 2018 Intel Corporation.
5 ** Copyright (C) 2019 Mail.ru Group.
6 ** Contact: https://www.qt.io/licensing/
7 **
8 ** This file is part of the QtCore module of the Qt Toolkit.
9 **
10 ** $QT_BEGIN_LICENSE:LGPL$
11 ** Commercial License Usage
12 ** Licensees holding valid commercial Qt licenses may use this file in
13 ** accordance with the commercial license agreement provided with the
14 ** Software or, alternatively, in accordance with the terms contained in
15 ** a written agreement between you and The Qt Company. For licensing terms
16 ** and conditions see https://www.qt.io/terms-conditions. For further
17 ** information use the contact form at https://www.qt.io/contact-us.
18 **
19 ** GNU Lesser General Public License Usage
20 ** Alternatively, this file may be used under the terms of the GNU Lesser
21 ** General Public License version 3 as published by the Free Software
22 ** Foundation and appearing in the file LICENSE.LGPL3 included in the
23 ** packaging of this file. Please review the following information to
24 ** ensure the GNU Lesser General Public License version 3 requirements
25 ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
26 **
27 ** GNU General Public License Usage
28 ** Alternatively, this file may be used under the terms of the GNU
29 ** General Public License version 2.0 or (at your option) the GNU General
30 ** Public license version 3 or any later version approved by the KDE Free
31 ** Qt Foundation. The licenses are as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
33 ** included in the packaging of this file. Please review the following
34 ** information to ensure the GNU General Public License requirements will
35 ** be met: https://www.gnu.org/licenses/gpl-2.0.html and
36 ** https://www.gnu.org/licenses/gpl-3.0.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41 
42 #include "qstringlist.h"
43 #include "qregexp.h"
44 #if QT_CONFIG(regularexpression)
45 #include "qregularexpression.h"
46 #endif
47 #include "qunicodetables_p.h"
48 #if QT_CONFIG(textcodec)
49 #include <qtextcodec.h>
50 #endif
51 #include <private/qutfcodec_p.h>
52 #include "qlocale_tools_p.h"
53 #include "private/qsimd_p.h"
54 #include <qnumeric.h>
55 #include <qdatastream.h>
56 #include <qlist.h>
57 #include "qlocale.h"
58 #include "qlocale_p.h"
59 #include "qstringbuilder.h"
60 #include "qstringmatcher.h"
61 #include "qvarlengtharray.h"
62 #include "qdebug.h"
63 #include "qendian.h"
64 #include "qcollator.h"
65 
66 #ifdef Q_OS_MAC
67 #include <private/qcore_mac_p.h>
68 #endif
69 
70 #include <private/qfunctions_p.h>
71 
72 #include <limits.h>
73 #include <string.h>
74 #include <stdlib.h>
75 #include <stdio.h>
76 #include <stdarg.h>
77 #include <wchar.h>
78 
79 #include "qchar.cpp"
80 #include "qstringmatcher.cpp"
81 #include "qstringiterator_p.h"
82 #include "qstringalgorithms_p.h"
83 #include "qthreadstorage.h"
84 
85 #ifdef Q_OS_WIN
86 #  include <qt_windows.h>
87 #endif
88 
89 #ifdef truncate
90 #  undef truncate
91 #endif
92 
93 #ifndef LLONG_MAX
94 #define LLONG_MAX qint64_C(9223372036854775807)
95 #endif
96 #ifndef LLONG_MIN
97 #define LLONG_MIN (-LLONG_MAX - qint64_C(1))
98 #endif
99 #ifndef ULLONG_MAX
100 #define ULLONG_MAX quint64_C(18446744073709551615)
101 #endif
102 
103 #define IS_RAW_DATA(d) ((d)->offset != sizeof(QStringData))
104 
105 QT_BEGIN_NAMESPACE
106 
107 /*
108  * Note on the use of SIMD in qstring.cpp:
109  *
110  * Several operations with strings are improved with the use of SIMD code,
111  * since they are repetitive. For MIPS, we have hand-written assembly code
112  * outside of qstring.cpp targeting MIPS DSP and MIPS DSPr2. For ARM and for
113  * x86, we can only use intrinsics and therefore everything is contained in
114  * qstring.cpp. We need to use intrinsics only for those platforms due to the
115  * different compilers and toolchains used, which have different syntax for
116  * assembly sources.
117  *
118  * ** SSE notes: **
119  *
120  * Whenever multiple alternatives are equivalent or near so, we prefer the one
121  * using instructions from SSE2, since SSE2 is guaranteed to be enabled for all
122  * 64-bit builds and we enable it for 32-bit builds by default. Use of higher
123  * SSE versions should be done when there is a clear performance benefit and
124  * requires fallback code to SSE2, if it exists.
125  *
126  * Performance measurement in the past shows that most strings are short in
127  * size and, therefore, do not benefit from alignment prologues. That is,
128  * trying to find a 16-byte-aligned boundary to operate on is often more
129  * expensive than executing the unaligned operation directly. In addition, note
130  * that the QString private data is designed so that the data is stored on
131  * 16-byte boundaries if the system malloc() returns 16-byte aligned pointers
132  * on its own (64-bit glibc on Linux does; 32-bit glibc on Linux returns them
133  * 50% of the time), so skipping the alignment prologue is actually optimizing
134  * for the common case.
135  */
136 
137 #if defined(__mips_dsp)
138 // From qstring_mips_dsp_asm.S
139 extern "C" void qt_fromlatin1_mips_asm_unroll4 (ushort*, const char*, uint);
140 extern "C" void qt_fromlatin1_mips_asm_unroll8 (ushort*, const char*, uint);
141 extern "C" void qt_toLatin1_mips_dsp_asm(uchar *dst, const ushort *src, int length);
142 #endif
143 
144 // internal
145 qsizetype qFindStringBoyerMoore(QStringView haystack, qsizetype from, QStringView needle, Qt::CaseSensitivity cs);
146 static inline qsizetype qFindChar(QStringView str, QChar ch, qsizetype from, Qt::CaseSensitivity cs) noexcept;
147 template <typename Haystack>
148 static inline qsizetype qLastIndexOf(Haystack haystack, QChar needle, qsizetype from, Qt::CaseSensitivity cs) noexcept;
149 template <>
150 inline qsizetype qLastIndexOf(QString haystack, QChar needle,
151                               qsizetype from, Qt::CaseSensitivity cs) noexcept = delete; // unwanted, would detach
152 static inline qsizetype qt_string_count(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs);
153 static inline qsizetype qt_string_count(QStringView haystack, QChar needle, Qt::CaseSensitivity cs);
154 
155 static inline bool qt_starts_with(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs);
156 static inline bool qt_starts_with(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs);
157 static inline bool qt_starts_with(QStringView haystack, QChar needle, Qt::CaseSensitivity cs);
158 static inline bool qt_ends_with(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs);
159 static inline bool qt_ends_with(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs);
160 static inline bool qt_ends_with(QStringView haystack, QChar needle, Qt::CaseSensitivity cs);
161 
162 #if defined(__SSE2__) && defined(Q_CC_GNU) && !defined(Q_CC_INTEL)
163 #  if defined(__SANITIZE_ADDRESS__) && Q_CC_GNU < 800 && !defined(Q_CC_CLANG)
164 #     warning "The __attribute__ on below will likely cause a build failure with your GCC version. Your choices are:"
165 #     warning "1) disable ASan;"
166 #     warning "2) disable the optimized code in qustrlen (change __SSE2__ to anything else);"
167 #     warning "3) upgrade your compiler (preferred)."
168 #  endif
169 
170 // We may overrun the buffer, but that's a false positive:
171 // this won't crash nor produce incorrect results
172 __attribute__((__no_sanitize_address__))
173 #endif
qustrlen(const ushort * str)174 qsizetype QtPrivate::qustrlen(const ushort *str) noexcept
175 {
176     qsizetype result = 0;
177 
178 #ifdef __SSE2__
179     // find the 16-byte alignment immediately prior or equal to str
180     quintptr misalignment = quintptr(str) & 0xf;
181     Q_ASSERT((misalignment & 1) == 0);
182     const ushort *ptr = str - (misalignment / 2);
183 
184     // load 16 bytes and see if we have a null
185     // (aligned loads can never segfault)
186     const __m128i zeroes = _mm_setzero_si128();
187     __m128i data = _mm_load_si128(reinterpret_cast<const __m128i *>(ptr));
188     __m128i comparison = _mm_cmpeq_epi16(data, zeroes);
189     quint32 mask = _mm_movemask_epi8(comparison);
190 
191     // ignore the result prior to the beginning of str
192     mask >>= misalignment;
193 
194     // Have we found something in the first block? Need to handle it now
195     // because of the left shift above.
196     if (mask)
197         return qCountTrailingZeroBits(quint32(mask)) / 2;
198 
199     do {
200         ptr += 8;
201         data = _mm_load_si128(reinterpret_cast<const __m128i *>(ptr));
202 
203         comparison = _mm_cmpeq_epi16(data, zeroes);
204         mask = _mm_movemask_epi8(comparison);
205     } while (mask == 0);
206 
207     // found a null
208     uint idx = qCountTrailingZeroBits(quint32(mask));
209     return ptr - str + idx / 2;
210 #endif
211 
212     if (sizeof(wchar_t) == sizeof(ushort))
213         return wcslen(reinterpret_cast<const wchar_t *>(str));
214 
215     while (*str++)
216         ++result;
217     return result;
218 }
219 
220 #if !defined(__OPTIMIZE_SIZE__)
221 namespace {
222 template <uint MaxCount> struct UnrollTailLoop
223 {
224     template <typename RetType, typename Functor1, typename Functor2, typename Number>
exec__anon21da74bc0111::UnrollTailLoop225     static inline RetType exec(Number count, RetType returnIfExited, Functor1 loopCheck, Functor2 returnIfFailed, Number i = 0)
226     {
227         /* equivalent to:
228          *   while (count--) {
229          *       if (loopCheck(i))
230          *           return returnIfFailed(i);
231          *   }
232          *   return returnIfExited;
233          */
234 
235         if (!count)
236             return returnIfExited;
237 
238         bool check = loopCheck(i);
239         if (check)
240             return returnIfFailed(i);
241 
242         return UnrollTailLoop<MaxCount - 1>::exec(count - 1, returnIfExited, loopCheck, returnIfFailed, i + 1);
243     }
244 
245     template <typename Functor, typename Number>
exec__anon21da74bc0111::UnrollTailLoop246     static inline void exec(Number count, Functor code)
247     {
248         /* equivalent to:
249          *   for (Number i = 0; i < count; ++i)
250          *       code(i);
251          */
252         exec(count, 0, [=](Number i) -> bool { code(i); return false; }, [](Number) { return 0; });
253     }
254 };
255 template <> template <typename RetType, typename Functor1, typename Functor2, typename Number>
exec(Number,RetType returnIfExited,Functor1,Functor2,Number)256 inline RetType UnrollTailLoop<0>::exec(Number, RetType returnIfExited, Functor1, Functor2, Number)
257 {
258     return returnIfExited;
259 }
260 }
261 #endif
262 
263 /*!
264  * \internal
265  *
266  * Searches for character \a c in the string \a str and returns a pointer to
267  * it. Unlike strchr() and wcschr() (but like glibc's strchrnul()), if the
268  * character is not found, this function returns a pointer to the end of the
269  * string -- that is, \c{str.end()}.
270  */
qustrchr(QStringView str,ushort c)271 const ushort *QtPrivate::qustrchr(QStringView str, ushort c) noexcept
272 {
273     const ushort *n = reinterpret_cast<const ushort *>(str.begin());
274     const ushort *e = reinterpret_cast<const ushort *>(str.end());
275 
276 #ifdef __SSE2__
277     bool loops = true;
278     // Using the PMOVMSKB instruction, we get two bits for each character
279     // we compare.
280 #  if defined(__AVX2__) && !defined(__OPTIMIZE_SIZE__)
281     // we're going to read n[0..15] (32 bytes)
282     __m256i mch256 = _mm256_set1_epi32(c | (c << 16));
283     for (const ushort *next = n + 16; next <= e; n = next, next += 16) {
284         __m256i data = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(n));
285         __m256i result = _mm256_cmpeq_epi16(data, mch256);
286         uint mask = uint(_mm256_movemask_epi8(result));
287         if (mask) {
288             uint idx = qCountTrailingZeroBits(mask);
289             return n + idx / 2;
290         }
291     }
292     loops = false;
293     __m128i mch = _mm256_castsi256_si128(mch256);
294 #  else
295     __m128i mch = _mm_set1_epi32(c | (c << 16));
296 #  endif
297 
298     auto hasMatch = [mch, &n](__m128i data, ushort validityMask) {
299         __m128i result = _mm_cmpeq_epi16(data, mch);
300         uint mask = uint(_mm_movemask_epi8(result));
301         if ((mask & validityMask) == 0)
302             return false;
303         uint idx = qCountTrailingZeroBits(mask);
304         n += idx / 2;
305         return true;
306     };
307 
308     // we're going to read n[0..7] (16 bytes)
309     for (const ushort *next = n + 8; next <= e; n = next, next += 8) {
310         __m128i data = _mm_loadu_si128(reinterpret_cast<const __m128i *>(n));
311         if (hasMatch(data, 0xffff))
312             return n;
313 
314         if (!loops) {
315             n += 8;
316             break;
317         }
318     }
319 
320 #  if !defined(__OPTIMIZE_SIZE__)
321     // we're going to read n[0..3] (8 bytes)
322     if (e - n > 3) {
323         __m128i data = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(n));
324         if (hasMatch(data, 0xff))
325             return n;
326 
327         n += 4;
328     }
329 
330     return UnrollTailLoop<3>::exec(e - n, e,
331                                    [=](int i) { return n[i] == c; },
332                                    [=](int i) { return n + i; });
333 #  endif
334 #elif defined(__ARM_NEON__) && defined(Q_PROCESSOR_ARM_64) // vaddv is only available on Aarch64
335     const uint16x8_t vmask = { 1, 1 << 1, 1 << 2, 1 << 3, 1 << 4, 1 << 5, 1 << 6, 1 << 7 };
336     const uint16x8_t ch_vec = vdupq_n_u16(c);
337     for (const ushort *next = n + 8; next <= e; n = next, next += 8) {
338         uint16x8_t data = vld1q_u16(n);
339         uint mask = vaddvq_u16(vandq_u16(vceqq_u16(data, ch_vec), vmask));
340         if (ushort(mask)) {
341             // found a match
342             return n + qCountTrailingZeroBits(mask);
343         }
344     }
345 #endif // aarch64
346 
347     --n;
348     while (++n != e)
349         if (*n == c)
350             return n;
351 
352     return n;
353 }
354 
355 #ifdef __SSE2__
356 // Scans from \a ptr to \a end until \a maskval is non-zero. Returns true if
357 // the no non-zero was found. Returns false and updates \a ptr to point to the
358 // first 16-bit word that has any bit set (note: if the input is 8-bit, \a ptr
359 // may be updated to one byte short).
simdTestMask(const char * & ptr,const char * end,quint32 maskval)360 static bool simdTestMask(const char *&ptr, const char *end, quint32 maskval)
361 {
362     auto updatePtr = [&](uint result) {
363         // found a character matching the mask
364         uint idx = qCountTrailingZeroBits(~result);
365         ptr += idx;
366         return false;
367     };
368 
369 #  if defined(__SSE4_1__)
370     __m128i mask;
371     auto updatePtrSimd = [&](__m128i data) {
372         __m128i masked = _mm_and_si128(mask, data);
373         __m128i comparison = _mm_cmpeq_epi16(masked, _mm_setzero_si128());
374         uint result = _mm_movemask_epi8(comparison);
375         return updatePtr(result);
376     };
377 
378 #    if defined(__AVX2__)
379     // AVX2 implementation: test 32 bytes at a time
380     const __m256i mask256 = _mm256_broadcastd_epi32(_mm_cvtsi32_si128(maskval));
381     while (ptr + 32 <= end) {
382         __m256i data = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(ptr));
383         if (!_mm256_testz_si256(mask256, data)) {
384             // found a character matching the mask
385             __m256i masked256 = _mm256_and_si256(mask256, data);
386             __m256i comparison256 = _mm256_cmpeq_epi16(masked256, _mm256_setzero_si256());
387             return updatePtr(_mm256_movemask_epi8(comparison256));
388         }
389         ptr += 32;
390     }
391 
392     mask = _mm256_castsi256_si128(mask256);
393 #    else
394     // SSE 4.1 implementation: test 32 bytes at a time (two 16-byte
395     // comparisons, unrolled)
396     mask = _mm_set1_epi32(maskval);
397     while (ptr + 32 <= end) {
398         __m128i data1 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(ptr));
399         __m128i data2 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(ptr + 16));
400         if (!_mm_testz_si128(mask, data1))
401             return updatePtrSimd(data1);
402 
403         ptr += 16;
404         if (!_mm_testz_si128(mask, data2))
405             return updatePtrSimd(data2);
406         ptr += 16;
407     }
408 #    endif
409 
410     // AVX2 and SSE4.1: final 16-byte comparison
411     if (ptr + 16 <= end) {
412         __m128i data1 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(ptr));
413         if (!_mm_testz_si128(mask, data1))
414             return updatePtrSimd(data1);
415         ptr += 16;
416     }
417 
418     // and final 8-byte comparison
419     if (ptr + 8 <= end) {
420         __m128i data1 = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(ptr));
421         if (!_mm_testz_si128(mask, data1))
422             return updatePtrSimd(data1);
423         ptr += 8;
424     }
425 
426 #  else
427     // SSE2 implementation: test 16 bytes at a time.
428     const __m128i mask = _mm_set1_epi32(maskval);
429     while (ptr + 16 <= end) {
430         __m128i data = _mm_loadu_si128(reinterpret_cast<const __m128i *>(ptr));
431         __m128i masked = _mm_and_si128(mask, data);
432         __m128i comparison = _mm_cmpeq_epi16(masked, _mm_setzero_si128());
433         quint16 result = _mm_movemask_epi8(comparison);
434         if (result != 0xffff)
435             return updatePtr(result);
436         ptr += 16;
437     }
438 
439     // and one 8-byte comparison
440     if (ptr + 8 <= end) {
441         __m128i data = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(ptr));
442         __m128i masked = _mm_and_si128(mask, data);
443         __m128i comparison = _mm_cmpeq_epi16(masked, _mm_setzero_si128());
444         quint8 result = _mm_movemask_epi8(comparison);
445         if (result != 0xff)
446             return updatePtr(result);
447         ptr += 8;
448     }
449 #  endif
450 
451     return true;
452 }
453 
mm_load8_zero_extend(const void * ptr)454 static Q_ALWAYS_INLINE __m128i mm_load8_zero_extend(const void *ptr)
455 {
456     const __m128i *dataptr = static_cast<const __m128i *>(ptr);
457 #if defined(__SSE4_1__)
458     // use a MOVQ followed by PMOVZXBW
459     // if AVX2 is present, these should combine into a single VPMOVZXBW instruction
460     __m128i data = _mm_loadl_epi64(dataptr);
461     return _mm_cvtepu8_epi16(data);
462 #  else
463     // use MOVQ followed by PUNPCKLBW
464     __m128i data = _mm_loadl_epi64(dataptr);
465     return _mm_unpacklo_epi8(data, _mm_setzero_si128());
466 #  endif
467 }
468 #endif
469 
470 // Note: ptr on output may be off by one and point to a preceding US-ASCII
471 // character. Usually harmless.
qt_is_ascii(const char * & ptr,const char * end)472 bool qt_is_ascii(const char *&ptr, const char *end) noexcept
473 {
474 #if defined(__SSE2__)
475     // Testing for the high bit can be done efficiently with just PMOVMSKB
476 #  if defined(__AVX2__)
477     while (ptr + 32 <= end) {
478         __m256i data = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(ptr));
479         quint32 mask = _mm256_movemask_epi8(data);
480         if (mask) {
481             uint idx = qCountTrailingZeroBits(mask);
482             ptr += idx;
483             return false;
484         }
485         ptr += 32;
486     }
487 #  endif
488     while (ptr + 16 <= end) {
489         __m128i data = _mm_loadu_si128(reinterpret_cast<const __m128i *>(ptr));
490         quint32 mask = _mm_movemask_epi8(data);
491         if (mask) {
492             uint idx = qCountTrailingZeroBits(mask);
493             ptr += idx;
494             return false;
495         }
496         ptr += 16;
497     }
498     if (ptr + 8 <= end) {
499         __m128i data = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(ptr));
500         quint8 mask = _mm_movemask_epi8(data);
501         if (mask) {
502             uint idx = qCountTrailingZeroBits(mask);
503             ptr += idx;
504             return false;
505         }
506         ptr += 8;
507     }
508 #endif
509 
510     while (ptr + 4 <= end) {
511         quint32 data = qFromUnaligned<quint32>(ptr);
512         if (data &= 0x80808080U) {
513 #if Q_BYTE_ORDER == Q_BIG_ENDIAN
514             uint idx = qCountLeadingZeroBits(data);
515 #else
516             uint idx = qCountTrailingZeroBits(data);
517 #endif
518             ptr += idx / 8;
519             return false;
520         }
521         ptr += 4;
522     }
523 
524     while (ptr != end) {
525         if (quint8(*ptr) & 0x80)
526             return false;
527         ++ptr;
528     }
529     return true;
530 }
531 
isAscii(QLatin1String s)532 bool QtPrivate::isAscii(QLatin1String s) noexcept
533 {
534     const char *ptr = s.begin();
535     const char *end = s.end();
536 
537     return qt_is_ascii(ptr, end);
538 }
539 
isAscii(const QChar * & ptr,const QChar * end)540 static bool isAscii(const QChar *&ptr, const QChar *end)
541 {
542 #ifdef __SSE2__
543     const char *ptr8 = reinterpret_cast<const char *>(ptr);
544     const char *end8 = reinterpret_cast<const char *>(end);
545     bool ok = simdTestMask(ptr8, end8, 0xff80ff80);
546     ptr = reinterpret_cast<const QChar *>(ptr8);
547     if (!ok)
548         return false;
549 #endif
550 
551     while (ptr != end) {
552         if (ptr->unicode() & 0xff80)
553             return false;
554         ++ptr;
555     }
556     return true;
557 }
558 
isAscii(QStringView s)559 bool QtPrivate::isAscii(QStringView s) noexcept
560 {
561     const QChar *ptr = s.begin();
562     const QChar *end = s.end();
563 
564     return isAscii(ptr, end);
565 }
566 
isLatin1(QStringView s)567 bool QtPrivate::isLatin1(QStringView s) noexcept
568 {
569     const QChar *ptr = s.begin();
570     const QChar *end = s.end();
571 
572 #ifdef __SSE2__
573     const char *ptr8 = reinterpret_cast<const char *>(ptr);
574     const char *end8 = reinterpret_cast<const char *>(end);
575     if (!simdTestMask(ptr8, end8, 0xff00ff00))
576         return false;
577     ptr = reinterpret_cast<const QChar *>(ptr8);
578 #endif
579 
580     while (ptr != end) {
581         if ((*ptr++).unicode() > 0xff)
582             return false;
583     }
584     return true;
585 }
586 
isValidUtf16(QStringView s)587 bool QtPrivate::isValidUtf16(QStringView s) noexcept
588 {
589     Q_CONSTEXPR uint InvalidCodePoint = UINT_MAX;
590 
591     QStringIterator i(s);
592     while (i.hasNext()) {
593         uint c = i.next(InvalidCodePoint);
594         if (c == InvalidCodePoint)
595             return false;
596     }
597 
598     return true;
599 }
600 
601 // conversion between Latin 1 and UTF-16
qt_from_latin1(ushort * dst,const char * str,size_t size)602 void qt_from_latin1(ushort *dst, const char *str, size_t size) noexcept
603 {
604     /* SIMD:
605      * Unpacking with SSE has been shown to improve performance on recent CPUs
606      * The same method gives no improvement with NEON. On Aarch64, clang will do the vectorization
607      * itself in exactly the same way as one would do it with intrinsics.
608      */
609 #if defined(__SSE2__)
610     const char *e = str + size;
611     qptrdiff offset = 0;
612 
613     // we're going to read str[offset..offset+15] (16 bytes)
614     for ( ; str + offset + 15 < e; offset += 16) {
615         const __m128i chunk = _mm_loadu_si128((const __m128i*)(str + offset)); // load
616 #ifdef __AVX2__
617         // zero extend to an YMM register
618         const __m256i extended = _mm256_cvtepu8_epi16(chunk);
619 
620         // store
621         _mm256_storeu_si256((__m256i*)(dst + offset), extended);
622 #else
623         const __m128i nullMask = _mm_set1_epi32(0);
624 
625         // unpack the first 8 bytes, padding with zeros
626         const __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullMask);
627         _mm_storeu_si128((__m128i*)(dst + offset), firstHalf); // store
628 
629         // unpack the last 8 bytes, padding with zeros
630         const __m128i secondHalf = _mm_unpackhi_epi8 (chunk, nullMask);
631         _mm_storeu_si128((__m128i*)(dst + offset + 8), secondHalf); // store
632 #endif
633     }
634 
635     // we're going to read str[offset..offset+7] (8 bytes)
636     if (str + offset + 7 < e) {
637         const __m128i unpacked = mm_load8_zero_extend(str + offset);
638         _mm_storeu_si128(reinterpret_cast<__m128i *>(dst + offset), unpacked);
639         offset += 8;
640     }
641 
642     size = size % 8;
643     dst += offset;
644     str += offset;
645 #  if !defined(__OPTIMIZE_SIZE__)
646     return UnrollTailLoop<7>::exec(int(size), [=](int i) { dst[i] = (uchar)str[i]; });
647 #  endif
648 #endif
649 #if defined(__mips_dsp)
650     if (size > 20)
651         qt_fromlatin1_mips_asm_unroll8(dst, str, size);
652     else
653         qt_fromlatin1_mips_asm_unroll4(dst, str, size);
654 #else
655     while (size--)
656         *dst++ = (uchar)*str++;
657 #endif
658 }
659 
660 template <bool Checked>
qt_to_latin1_internal(uchar * dst,const ushort * src,qsizetype length)661 static void qt_to_latin1_internal(uchar *dst, const ushort *src, qsizetype length)
662 {
663 #if defined(__SSE2__)
664     uchar *e = dst + length;
665     qptrdiff offset = 0;
666 
667 #  ifdef __AVX2__
668     const __m256i questionMark256 = _mm256_broadcastw_epi16(_mm_cvtsi32_si128('?'));
669     const __m256i outOfRange256 = _mm256_broadcastw_epi16(_mm_cvtsi32_si128(0x100));
670     const __m128i questionMark = _mm256_castsi256_si128(questionMark256);
671     const __m128i outOfRange = _mm256_castsi256_si128(outOfRange256);
672 #  else
673     const __m128i questionMark = _mm_set1_epi16('?');
674     const __m128i outOfRange = _mm_set1_epi16(0x100);
675 #  endif
676 
677     auto mergeQuestionMarks = [=](__m128i chunk) {
678         // SSE has no compare instruction for unsigned comparison.
679 # ifdef __SSE4_1__
680         // We use an unsigned uc = qMin(uc, 0x100) and then compare for equality.
681         chunk = _mm_min_epu16(chunk, outOfRange);
682         const __m128i offLimitMask = _mm_cmpeq_epi16(chunk, outOfRange);
683         chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask);
684 # else
685         // The variables must be shiffted + 0x8000 to be compared
686         const __m128i signedBitOffset = _mm_set1_epi16(short(0x8000));
687         const __m128i thresholdMask = _mm_set1_epi16(short(0xff + 0x8000));
688 
689         const __m128i signedChunk = _mm_add_epi16(chunk, signedBitOffset);
690         const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask);
691 
692         // offLimitQuestionMark contains '?' for each 16 bits that was off-limit
693         // the 16 bits that were correct contains zeros
694         const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark);
695 
696         // correctBytes contains the bytes that were in limit
697         // the 16 bits that were off limits contains zeros
698         const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk);
699 
700         // merge offLimitQuestionMark and correctBytes to have the result
701         chunk = _mm_or_si128(correctBytes, offLimitQuestionMark);
702 
703         Q_UNUSED(outOfRange);
704 # endif
705         return chunk;
706     };
707 
708     // we're going to write to dst[offset..offset+15] (16 bytes)
709     for ( ; dst + offset + 15 < e; offset += 16) {
710 #  if defined(__AVX2__)
711         __m256i chunk = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(src + offset));
712         if (Checked) {
713             // See mergeQuestionMarks lambda above for details
714             chunk = _mm256_min_epu16(chunk, outOfRange256);
715             const __m256i offLimitMask = _mm256_cmpeq_epi16(chunk, outOfRange256);
716             chunk = _mm256_blendv_epi8(chunk, questionMark256, offLimitMask);
717         }
718 
719         const __m128i chunk2 = _mm256_extracti128_si256(chunk, 1);
720         const __m128i chunk1 = _mm256_castsi256_si128(chunk);
721 #  else
722         __m128i chunk1 = _mm_loadu_si128((const __m128i*)(src + offset)); // load
723         if (Checked)
724             chunk1 = mergeQuestionMarks(chunk1);
725 
726         __m128i chunk2 = _mm_loadu_si128((const __m128i*)(src + offset + 8)); // load
727         if (Checked)
728             chunk2 = mergeQuestionMarks(chunk2);
729 #  endif
730 
731         // pack the two vector to 16 x 8bits elements
732         const __m128i result = _mm_packus_epi16(chunk1, chunk2);
733         _mm_storeu_si128((__m128i*)(dst + offset), result); // store
734     }
735 
736 #  if !defined(__OPTIMIZE_SIZE__)
737     // we're going to write to dst[offset..offset+7] (8 bytes)
738     if (dst + offset + 7 < e) {
739         __m128i chunk = _mm_loadu_si128(reinterpret_cast<const __m128i *>(src + offset));
740         if (Checked)
741             chunk = mergeQuestionMarks(chunk);
742 
743         // pack, where the upper half is ignored
744         const __m128i result = _mm_packus_epi16(chunk, chunk);
745         _mm_storel_epi64(reinterpret_cast<__m128i *>(dst + offset), result);
746         offset += 8;
747     }
748 
749     // we're going to write to dst[offset..offset+3] (4 bytes)
750     if (dst + offset + 3 < e) {
751         __m128i chunk = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(src + offset));
752         if (Checked)
753             chunk = mergeQuestionMarks(chunk);
754 
755         // pack, we'll the upper three quarters
756         const __m128i result = _mm_packus_epi16(chunk, chunk);
757         qToUnaligned(_mm_cvtsi128_si32(result), dst + offset);
758         offset += 4;
759     }
760 
761     length = length % 4;
762 #  else
763     length = length % 16;
764 #  endif // optimize size
765 
766     // advance dst, src for tail processing
767     dst += offset;
768     src += offset;
769 
770 #  if !defined(__OPTIMIZE_SIZE__)
771     return UnrollTailLoop<3>::exec(length, [=](int i) {
772         if (Checked)
773             dst[i] = (src[i]>0xff) ? '?' : (uchar) src[i];
774         else
775             dst[i] = src[i];
776     });
777 #  endif
778 #elif defined(__ARM_NEON__)
779     // Refer to the documentation of the SSE2 implementation
780     // this use eactly the same method as for SSE except:
781     // 1) neon has unsigned comparison
782     // 2) packing is done to 64 bits (8 x 8bits component).
783     if (length >= 16) {
784         const int chunkCount = length >> 3; // divided by 8
785         const uint16x8_t questionMark = vdupq_n_u16('?'); // set
786         const uint16x8_t thresholdMask = vdupq_n_u16(0xff); // set
787         for (int i = 0; i < chunkCount; ++i) {
788             uint16x8_t chunk = vld1q_u16((uint16_t *)src); // load
789             src += 8;
790 
791             if (Checked) {
792                 const uint16x8_t offLimitMask = vcgtq_u16(chunk, thresholdMask); // chunk > thresholdMask
793                 const uint16x8_t offLimitQuestionMark = vandq_u16(offLimitMask, questionMark); // offLimitMask & questionMark
794                 const uint16x8_t correctBytes = vbicq_u16(chunk, offLimitMask); // !offLimitMask & chunk
795                 chunk = vorrq_u16(correctBytes, offLimitQuestionMark); // correctBytes | offLimitQuestionMark
796             }
797             const uint8x8_t result = vmovn_u16(chunk); // narrowing move->packing
798             vst1_u8(dst, result); // store
799             dst += 8;
800         }
801         length = length % 8;
802     }
803 #endif
804 #if defined(__mips_dsp)
805     qt_toLatin1_mips_dsp_asm(dst, src, length);
806 #else
807     while (length--) {
808         if (Checked)
809             *dst++ = (*src>0xff) ? '?' : (uchar) *src;
810         else
811             *dst++ = *src;
812         ++src;
813     }
814 #endif
815 }
816 
qt_to_latin1(uchar * dst,const ushort * src,qsizetype length)817 static void qt_to_latin1(uchar *dst, const ushort *src, qsizetype length)
818 {
819     qt_to_latin1_internal<true>(dst, src, length);
820 }
821 
qt_to_latin1_unchecked(uchar * dst,const ushort * src,qsizetype length)822 void qt_to_latin1_unchecked(uchar *dst, const ushort *src, qsizetype length)
823 {
824     qt_to_latin1_internal<false>(dst, src, length);
825 }
826 
827 // Unicode case-insensitive comparison
ucstricmp(const QChar * a,const QChar * ae,const QChar * b,const QChar * be)828 static int ucstricmp(const QChar *a, const QChar *ae, const QChar *b, const QChar *be)
829 {
830     if (a == b)
831         return (ae - be);
832 
833     const QChar *e = ae;
834     if (be - b < ae - a)
835         e = a + (be - b);
836 
837     uint alast = 0;
838     uint blast = 0;
839     while (a < e) {
840 //         qDebug() << Qt::hex << alast << blast;
841 //         qDebug() << Qt::hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast);
842 //         qDebug() << Qt::hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast);
843         int diff = foldCase(a->unicode(), alast) - foldCase(b->unicode(), blast);
844         if ((diff))
845             return diff;
846         ++a;
847         ++b;
848     }
849     if (a == ae) {
850         if (b == be)
851             return 0;
852         return -1;
853     }
854     return 1;
855 }
856 
857 // Case-insensitive comparison between a Unicode string and a QLatin1String
ucstricmp(const QChar * a,const QChar * ae,const char * b,const char * be)858 static int ucstricmp(const QChar *a, const QChar *ae, const char *b, const char *be)
859 {
860     auto e = ae;
861     if (be - b < ae - a)
862         e = a + (be - b);
863 
864     while (a < e) {
865         int diff = foldCase(a->unicode()) - foldCase(uchar(*b));
866         if ((diff))
867             return diff;
868         ++a;
869         ++b;
870     }
871     if (a == ae) {
872         if (b == be)
873             return 0;
874         return -1;
875     }
876     return 1;
877 }
878 
879 #if defined(__mips_dsp)
880 // From qstring_mips_dsp_asm.S
881 extern "C" int qt_ucstrncmp_mips_dsp_asm(const ushort *a,
882                                          const ushort *b,
883                                          unsigned len);
884 #endif
885 
886 // Unicode case-sensitive compare two same-sized strings
ucstrncmp(const QChar * a,const QChar * b,size_t l)887 static int ucstrncmp(const QChar *a, const QChar *b, size_t l)
888 {
889 #ifdef __OPTIMIZE_SIZE__
890     const QChar *end = a + l;
891     while (a < end) {
892         if (int diff = (int)a->unicode() - (int)b->unicode())
893             return diff;
894         ++a;
895         ++b;
896     }
897     return 0;
898 #else
899 #if defined(__mips_dsp)
900     Q_STATIC_ASSERT(sizeof(uint) == sizeof(size_t));
901     if (l >= 8) {
902         return qt_ucstrncmp_mips_dsp_asm(reinterpret_cast<const ushort*>(a),
903                                          reinterpret_cast<const ushort*>(b),
904                                          l);
905     }
906 #endif // __mips_dsp
907 #ifdef __SSE2__
908     const QChar *end = a + l;
909     qptrdiff offset = 0;
910 
911     // Using the PMOVMSKB instruction, we get two bits for each character
912     // we compare.
913     int retval;
914     auto isDifferent = [a, b, &offset, &retval](__m128i a_data, __m128i b_data) {
915         __m128i result = _mm_cmpeq_epi16(a_data, b_data);
916         uint mask = ~uint(_mm_movemask_epi8(result));
917         if (ushort(mask) == 0)
918             return false;
919         uint idx = qCountTrailingZeroBits(mask);
920         retval = a[offset + idx / 2].unicode() - b[offset + idx / 2].unicode();
921         return true;
922     };
923 
924     // we're going to read a[0..15] and b[0..15] (32 bytes)
925     for ( ; end - a >= offset + 16; offset += 16) {
926 #ifdef __AVX2__
927         __m256i a_data = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(a + offset));
928         __m256i b_data = _mm256_loadu_si256(reinterpret_cast<const __m256i *>(b + offset));
929         __m256i result = _mm256_cmpeq_epi16(a_data, b_data);
930         uint mask = _mm256_movemask_epi8(result);
931 #else
932         __m128i a_data1 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(a + offset));
933         __m128i a_data2 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(a + offset + 8));
934         __m128i b_data1 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(b + offset));
935         __m128i b_data2 = _mm_loadu_si128(reinterpret_cast<const __m128i *>(b + offset + 8));
936         __m128i result1 = _mm_cmpeq_epi16(a_data1, b_data1);
937         __m128i result2 = _mm_cmpeq_epi16(a_data2, b_data2);
938         uint mask = _mm_movemask_epi8(result1) | (_mm_movemask_epi8(result2) << 16);
939 #endif
940         mask = ~mask;
941         if (mask) {
942             // found a different character
943             uint idx = qCountTrailingZeroBits(mask);
944             return a[offset + idx / 2].unicode() - b[offset + idx / 2].unicode();
945         }
946     }
947 
948     // we're going to read a[0..7] and b[0..7] (16 bytes)
949     if (end - a >= offset + 8) {
950         __m128i a_data = _mm_loadu_si128(reinterpret_cast<const __m128i *>(a + offset));
951         __m128i b_data = _mm_loadu_si128(reinterpret_cast<const __m128i *>(b + offset));
952         if (isDifferent(a_data, b_data))
953             return retval;
954 
955         offset += 8;
956     }
957 
958     // we're going to read a[0..3] and b[0..3] (8 bytes)
959     if (end - a >= offset + 4) {
960         __m128i a_data = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(a + offset));
961         __m128i b_data = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(b + offset));
962         if (isDifferent(a_data, b_data))
963             return retval;
964 
965         offset += 4;
966     }
967 
968     // reset l
969     l &= 3;
970 
971     const auto lambda = [=](size_t i) -> int {
972         return a[offset + i].unicode() - b[offset + i].unicode();
973     };
974     return UnrollTailLoop<3>::exec(l, 0, lambda, lambda);
975 #endif
976 #if defined(__ARM_NEON__) && defined(Q_PROCESSOR_ARM_64) // vaddv is only available on Aarch64
977     if (l >= 8) {
978         const QChar *end = a + l;
979         const uint16x8_t mask = { 1, 1 << 1, 1 << 2, 1 << 3, 1 << 4, 1 << 5, 1 << 6, 1 << 7 };
980         while (end - a > 7) {
981             uint16x8_t da = vld1q_u16(reinterpret_cast<const uint16_t *>(a));
982             uint16x8_t db = vld1q_u16(reinterpret_cast<const uint16_t *>(b));
983 
984             uint8_t r = ~(uint8_t)vaddvq_u16(vandq_u16(vceqq_u16(da, db), mask));
985             if (r) {
986                 // found a different QChar
987                 uint idx = qCountTrailingZeroBits(r);
988                 return (int)a[idx].unicode() - (int)b[idx].unicode();
989             }
990             a += 8;
991             b += 8;
992         }
993         l &= 7;
994     }
995     const auto lambda = [=](size_t i) -> int {
996         return a[i].unicode() - b[i].unicode();
997     };
998     return UnrollTailLoop<7>::exec(l, 0, lambda, lambda);
999 #endif // __ARM_NEON__
1000     if (!l)
1001         return 0;
1002 
1003     // check alignment
1004     if ((reinterpret_cast<quintptr>(a) & 2) == (reinterpret_cast<quintptr>(b) & 2)) {
1005         // both addresses have the same alignment
1006         if (reinterpret_cast<quintptr>(a) & 2) {
1007             // both addresses are not aligned to 4-bytes boundaries
1008             // compare the first character
1009             if (*a != *b)
1010                 return a->unicode() - b->unicode();
1011             --l;
1012             ++a;
1013             ++b;
1014 
1015             // now both addresses are 4-bytes aligned
1016         }
1017 
1018         // both addresses are 4-bytes aligned
1019         // do a fast 32-bit comparison
1020         const quint32 *da = reinterpret_cast<const quint32 *>(a);
1021         const quint32 *db = reinterpret_cast<const quint32 *>(b);
1022         const quint32 *e = da + (l >> 1);
1023         for ( ; da != e; ++da, ++db) {
1024             if (*da != *db) {
1025                 a = reinterpret_cast<const QChar *>(da);
1026                 b = reinterpret_cast<const QChar *>(db);
1027                 if (*a != *b)
1028                     return a->unicode() - b->unicode();
1029                 return a[1].unicode() - b[1].unicode();
1030             }
1031         }
1032 
1033         // do we have a tail?
1034         a = reinterpret_cast<const QChar *>(da);
1035         b = reinterpret_cast<const QChar *>(db);
1036         return (l & 1) ? a->unicode() - b->unicode() : 0;
1037     } else {
1038         // one of the addresses isn't 4-byte aligned but the other is
1039         const QChar *e = a + l;
1040         for ( ; a != e; ++a, ++b) {
1041             if (*a != *b)
1042                 return a->unicode() - b->unicode();
1043         }
1044     }
1045     return 0;
1046 #endif
1047 }
1048 
ucstrncmp(const QChar * a,const uchar * c,size_t l)1049 static int ucstrncmp(const QChar *a, const uchar *c, size_t l)
1050 {
1051     const ushort *uc = reinterpret_cast<const ushort *>(a);
1052     const ushort *e = uc + l;
1053 
1054 #ifdef __SSE2__
1055     __m128i nullmask = _mm_setzero_si128();
1056     qptrdiff offset = 0;
1057 
1058 #  if !defined(__OPTIMIZE_SIZE__)
1059     // Using the PMOVMSKB instruction, we get two bits for each character
1060     // we compare.
1061     int retval;
1062     auto isDifferent = [uc, c, &offset, &retval](__m128i a_data, __m128i b_data) {
1063         __m128i result = _mm_cmpeq_epi16(a_data, b_data);
1064         uint mask = ~uint(_mm_movemask_epi8(result));
1065         if (ushort(mask) == 0)
1066             return false;
1067         uint idx = qCountTrailingZeroBits(mask);
1068         retval = uc[offset + idx / 2] - c[offset + idx / 2];
1069         return true;
1070     };
1071 #  endif
1072 
1073     // we're going to read uc[offset..offset+15] (32 bytes)
1074     // and c[offset..offset+15] (16 bytes)
1075     for ( ; uc + offset + 15 < e; offset += 16) {
1076         // similar to fromLatin1_helper:
1077         // load 16 bytes of Latin 1 data
1078         __m128i chunk = _mm_loadu_si128((const __m128i*)(c + offset));
1079 
1080 #  ifdef __AVX2__
1081         // expand Latin 1 data via zero extension
1082         __m256i ldata = _mm256_cvtepu8_epi16(chunk);
1083 
1084         // load UTF-16 data and compare
1085         __m256i ucdata = _mm256_loadu_si256((const __m256i*)(uc + offset));
1086         __m256i result = _mm256_cmpeq_epi16(ldata, ucdata);
1087 
1088         uint mask = ~_mm256_movemask_epi8(result);
1089 #  else
1090         // expand via unpacking
1091         __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullmask);
1092         __m128i secondHalf = _mm_unpackhi_epi8(chunk, nullmask);
1093 
1094         // load UTF-16 data and compare
1095         __m128i ucdata1 = _mm_loadu_si128((const __m128i*)(uc + offset));
1096         __m128i ucdata2 = _mm_loadu_si128((const __m128i*)(uc + offset + 8));
1097         __m128i result1 = _mm_cmpeq_epi16(firstHalf, ucdata1);
1098         __m128i result2 = _mm_cmpeq_epi16(secondHalf, ucdata2);
1099 
1100         uint mask = ~(_mm_movemask_epi8(result1) | _mm_movemask_epi8(result2) << 16);
1101 #  endif
1102         if (mask) {
1103             // found a different character
1104             uint idx = qCountTrailingZeroBits(mask);
1105             return uc[offset + idx / 2] - c[offset + idx / 2];
1106         }
1107     }
1108 
1109 #  if !defined(__OPTIMIZE_SIZE__)
1110     // we'll read uc[offset..offset+7] (16 bytes) and c[offset..offset+7] (8 bytes)
1111     if (uc + offset + 7 < e) {
1112         // same, but we're using an 8-byte load
1113         __m128i secondHalf = mm_load8_zero_extend(c + offset);
1114 
1115         __m128i ucdata = _mm_loadu_si128((const __m128i*)(uc + offset));
1116         if (isDifferent(ucdata, secondHalf))
1117             return retval;
1118 
1119         // still matched
1120         offset += 8;
1121     }
1122 
1123     enum { MaxTailLength = 3 };
1124     // we'll read uc[offset..offset+3] (8 bytes) and c[offset..offset+3] (4 bytes)
1125     if (uc + offset + 3 < e) {
1126         __m128i chunk = _mm_cvtsi32_si128(qFromUnaligned<int>(c + offset));
1127         __m128i secondHalf = _mm_unpacklo_epi8(chunk, nullmask);
1128 
1129         __m128i ucdata = _mm_loadl_epi64(reinterpret_cast<const __m128i *>(uc + offset));
1130         if (isDifferent(ucdata, secondHalf))
1131             return retval;
1132 
1133         // still matched
1134         offset += 4;
1135     }
1136 #  endif // optimize size
1137 
1138     // reset uc and c
1139     uc += offset;
1140     c += offset;
1141 
1142 #  if !defined(__OPTIMIZE_SIZE__)
1143     const auto lambda = [=](size_t i) { return uc[i] - ushort(c[i]); };
1144     return UnrollTailLoop<MaxTailLength>::exec(e - uc, 0, lambda, lambda);
1145 #  endif
1146 #endif
1147 
1148     while (uc < e) {
1149         int diff = *uc - *c;
1150         if (diff)
1151             return diff;
1152         uc++, c++;
1153     }
1154 
1155     return 0;
1156 }
1157 
1158 template <typename Number>
lencmp(Number lhs,Number rhs)1159 Q_DECL_CONSTEXPR int lencmp(Number lhs, Number rhs) noexcept
1160 {
1161     return lhs == rhs ? 0 :
1162            lhs >  rhs ? 1 :
1163            /* else */  -1 ;
1164 }
1165 
1166 // Unicode case-sensitive comparison
ucstrcmp(const QChar * a,size_t alen,const QChar * b,size_t blen)1167 static int ucstrcmp(const QChar *a, size_t alen, const QChar *b, size_t blen)
1168 {
1169     if (a == b && alen == blen)
1170         return 0;
1171     const size_t l = qMin(alen, blen);
1172     int cmp = ucstrncmp(a, b, l);
1173     return cmp ? cmp : lencmp(alen, blen);
1174 }
1175 
ucstrcmp(const QChar * a,size_t alen,const char * b,size_t blen)1176 static int ucstrcmp(const QChar *a, size_t alen, const char *b, size_t blen)
1177 {
1178     const size_t l = qMin(alen, blen);
1179     const int cmp = ucstrncmp(a, reinterpret_cast<const uchar*>(b), l);
1180     return cmp ? cmp : lencmp(alen, blen);
1181 }
1182 
qt_compare_strings(QStringView lhs,QStringView rhs,Qt::CaseSensitivity cs)1183 static int qt_compare_strings(QStringView lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
1184 {
1185     if (cs == Qt::CaseSensitive)
1186         return ucstrcmp(lhs.begin(), lhs.size(), rhs.begin(), rhs.size());
1187     else
1188         return ucstricmp(lhs.begin(), lhs.end(), rhs.begin(), rhs.end());
1189 }
1190 
qt_compare_strings(QStringView lhs,QLatin1String rhs,Qt::CaseSensitivity cs)1191 static int qt_compare_strings(QStringView lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
1192 {
1193     if (cs == Qt::CaseSensitive)
1194         return ucstrcmp(lhs.begin(), lhs.size(), rhs.begin(), rhs.size());
1195     else
1196         return ucstricmp(lhs.begin(), lhs.end(), rhs.begin(), rhs.end());
1197 }
1198 
qt_compare_strings(QLatin1String lhs,QStringView rhs,Qt::CaseSensitivity cs)1199 static int qt_compare_strings(QLatin1String lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
1200 {
1201     return -qt_compare_strings(rhs, lhs, cs);
1202 }
1203 
qt_compare_strings(QLatin1String lhs,QLatin1String rhs,Qt::CaseSensitivity cs)1204 static int qt_compare_strings(QLatin1String lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
1205 {
1206     if (lhs.isEmpty())
1207         return lencmp(0, rhs.size());
1208     if (cs == Qt::CaseInsensitive)
1209         return qstrnicmp(lhs.data(), lhs.size(), rhs.data(), rhs.size());
1210     const auto l = std::min(lhs.size(), rhs.size());
1211     int r = qstrncmp(lhs.data(), rhs.data(), l);
1212     return r ? r : lencmp(lhs.size(), rhs.size());
1213 }
1214 
1215 /*!
1216     \relates QStringView
1217     \internal
1218     \since 5.10
1219 
1220     Returns an integer that compares to 0 as \a lhs compares to \a rhs.
1221 
1222     If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive;
1223     otherwise the comparison is case-insensitive.
1224 
1225     Case-sensitive comparison is based exclusively on the numeric Unicode values
1226     of the characters and is very fast, but is not what a human would expect.
1227     Consider sorting user-visible strings with QString::localeAwareCompare().
1228 
1229     \sa {Comparing Strings}
1230 */
compareStrings(QStringView lhs,QStringView rhs,Qt::CaseSensitivity cs)1231 int QtPrivate::compareStrings(QStringView lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
1232 {
1233     return qt_compare_strings(lhs, rhs, cs);
1234 }
1235 
1236 /*!
1237     \relates QStringView
1238     \internal
1239     \since 5.10
1240     \overload
1241 
1242     Returns an integer that compares to 0 as \a lhs compares to \a rhs.
1243 
1244     If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive;
1245     otherwise the comparison is case-insensitive.
1246 
1247     Case-sensitive comparison is based exclusively on the numeric Unicode values
1248     of the characters and is very fast, but is not what a human would expect.
1249     Consider sorting user-visible strings with QString::localeAwareCompare().
1250 
1251     \sa {Comparing Strings}
1252 */
compareStrings(QStringView lhs,QLatin1String rhs,Qt::CaseSensitivity cs)1253 int QtPrivate::compareStrings(QStringView lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
1254 {
1255     return qt_compare_strings(lhs, rhs, cs);
1256 }
1257 
1258 /*!
1259     \relates QStringView
1260     \internal
1261     \since 5.10
1262     \overload
1263 
1264     Returns an integer that compares to 0 as \a lhs compares to \a rhs.
1265 
1266     If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive;
1267     otherwise the comparison is case-insensitive.
1268 
1269     Case-sensitive comparison is based exclusively on the numeric Unicode values
1270     of the characters and is very fast, but is not what a human would expect.
1271     Consider sorting user-visible strings with QString::localeAwareCompare().
1272 
1273     \sa {Comparing Strings}
1274 */
compareStrings(QLatin1String lhs,QStringView rhs,Qt::CaseSensitivity cs)1275 int QtPrivate::compareStrings(QLatin1String lhs, QStringView rhs, Qt::CaseSensitivity cs) noexcept
1276 {
1277     return qt_compare_strings(lhs, rhs, cs);
1278 }
1279 
1280 /*!
1281     \relates QStringView
1282     \internal
1283     \since 5.10
1284     \overload
1285 
1286     Returns an integer that compares to 0 as \a lhs compares to \a rhs.
1287 
1288     If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive;
1289     otherwise the comparison is case-insensitive.
1290 
1291     Case-sensitive comparison is based exclusively on the numeric Latin-1 values
1292     of the characters and is very fast, but is not what a human would expect.
1293     Consider sorting user-visible strings with QString::localeAwareCompare().
1294 
1295     \sa {Comparing Strings}
1296 */
compareStrings(QLatin1String lhs,QLatin1String rhs,Qt::CaseSensitivity cs)1297 int QtPrivate::compareStrings(QLatin1String lhs, QLatin1String rhs, Qt::CaseSensitivity cs) noexcept
1298 {
1299     return qt_compare_strings(lhs, rhs, cs);
1300 }
1301 
1302 #define REHASH(a) \
1303     if (sl_minus_1 < sizeof(std::size_t) * CHAR_BIT)  \
1304         hashHaystack -= std::size_t(a) << sl_minus_1; \
1305     hashHaystack <<= 1
1306 
qIsUpper(char ch)1307 inline bool qIsUpper(char ch)
1308 {
1309     return ch >= 'A' && ch <= 'Z';
1310 }
1311 
qIsDigit(char ch)1312 inline bool qIsDigit(char ch)
1313 {
1314     return ch >= '0' && ch <= '9';
1315 }
1316 
qToLower(char ch)1317 inline char qToLower(char ch)
1318 {
1319     if (ch >= 'A' && ch <= 'Z')
1320         return ch - 'A' + 'a';
1321     else
1322         return ch;
1323 }
1324 
1325 
1326 #if QT_DEPRECATED_SINCE(5, 9)
1327 const QString::Null QString::null = { };
1328 #endif
1329 
1330 /*!
1331   \macro QT_RESTRICTED_CAST_FROM_ASCII
1332   \relates QString
1333 
1334   Disables most automatic conversions from source literals and 8-bit data
1335   to unicode QStrings, but allows the use of
1336   the \c{QChar(char)} and \c{QString(const char (&ch)[N]} constructors,
1337   and the \c{QString::operator=(const char (&ch)[N])} assignment operator.
1338   This gives most of the type-safety benefits of \c QT_NO_CAST_FROM_ASCII
1339   but does not require user code to wrap character and string literals
1340   with QLatin1Char, QLatin1String or similar.
1341 
1342   Using this macro together with source strings outside the 7-bit range,
1343   non-literals, or literals with embedded NUL characters is undefined.
1344 
1345   \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_TO_ASCII
1346 */
1347 
1348 /*!
1349   \macro QT_NO_CAST_FROM_ASCII
1350   \relates QString
1351 
1352   Disables automatic conversions from 8-bit strings (char *) to unicode QStrings
1353 
1354   \sa QT_NO_CAST_TO_ASCII, QT_RESTRICTED_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
1355 */
1356 
1357 /*!
1358   \macro QT_NO_CAST_TO_ASCII
1359   \relates QString
1360 
1361   Disables automatic conversion from QString to 8-bit strings (char *).
1362 
1363   \sa QT_NO_CAST_FROM_ASCII, QT_RESTRICTED_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY
1364 */
1365 
1366 /*!
1367   \macro QT_ASCII_CAST_WARNINGS
1368   \internal
1369   \relates QString
1370 
1371   This macro can be defined to force a warning whenever a function is
1372   called that automatically converts between unicode and 8-bit encodings.
1373 
1374   Note: This only works for compilers that support warnings for
1375   deprecated API.
1376 
1377   \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII, QT_RESTRICTED_CAST_FROM_ASCII
1378 */
1379 
1380 /*!
1381     \class QCharRef
1382     \inmodule QtCore
1383     \reentrant
1384     \brief The QCharRef class is a helper class for QString.
1385 
1386     \internal
1387 
1388     \ingroup string-processing
1389 
1390     When you get an object of type QCharRef, if you can assign to it,
1391     the assignment will apply to the character in the string from
1392     which you got the reference. That is its whole purpose in life.
1393     The QCharRef becomes invalid once modifications are made to the
1394     string: if you want to keep the character, copy it into a QChar.
1395 
1396     Most of the QChar member functions also exist in QCharRef.
1397     However, they are not explicitly documented here.
1398 
1399     \sa QString::operator[](), QString::at(), QChar
1400 */
1401 
1402 /*!
1403     \class QString
1404     \inmodule QtCore
1405     \reentrant
1406 
1407     \brief The QString class provides a Unicode character string.
1408 
1409     \ingroup tools
1410     \ingroup shared
1411     \ingroup string-processing
1412 
1413     QString stores a string of 16-bit \l{QChar}s, where each QChar
1414     corresponds to one UTF-16 code unit. (Unicode characters
1415     with code values above 65535 are stored using surrogate pairs,
1416     i.e., two consecutive \l{QChar}s.)
1417 
1418     \l{Unicode} is an international standard that supports most of the
1419     writing systems in use today. It is a superset of US-ASCII (ANSI
1420     X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1
1421     characters are available at the same code positions.
1422 
1423     Behind the scenes, QString uses \l{implicit sharing}
1424     (copy-on-write) to reduce memory usage and to avoid the needless
1425     copying of data. This also helps reduce the inherent overhead of
1426     storing 16-bit characters instead of 8-bit characters.
1427 
1428     In addition to QString, Qt also provides the QByteArray class to
1429     store raw bytes and traditional 8-bit '\\0'-terminated strings.
1430     For most purposes, QString is the class you want to use. It is
1431     used throughout the Qt API, and the Unicode support ensures that
1432     your applications will be easy to translate if you want to expand
1433     your application's market at some point. The two main cases where
1434     QByteArray is appropriate are when you need to store raw binary
1435     data, and when memory conservation is critical (like in embedded
1436     systems).
1437 
1438     \tableofcontents
1439 
1440     \section1 Initializing a String
1441 
1442     One way to initialize a QString is simply to pass a \c{const char
1443     *} to its constructor. For example, the following code creates a
1444     QString of size 5 containing the data "Hello":
1445 
1446     \snippet qstring/main.cpp 0
1447 
1448     QString converts the \c{const char *} data into Unicode using the
1449     fromUtf8() function.
1450 
1451     In all of the QString functions that take \c{const char *}
1452     parameters, the \c{const char *} is interpreted as a classic
1453     C-style '\\0'-terminated string encoded in UTF-8. It is legal for
1454     the \c{const char *} parameter to be \nullptr.
1455 
1456     You can also provide string data as an array of \l{QChar}s:
1457 
1458     \snippet qstring/main.cpp 1
1459 
1460     QString makes a deep copy of the QChar data, so you can modify it
1461     later without experiencing side effects. (If for performance
1462     reasons you don't want to take a deep copy of the character data,
1463     use QString::fromRawData() instead.)
1464 
1465     Another approach is to set the size of the string using resize()
1466     and to initialize the data character per character. QString uses
1467     0-based indexes, just like C++ arrays. To access the character at
1468     a particular index position, you can use \l operator[](). On
1469     non-const strings, \l operator[]() returns a reference to a
1470     character that can be used on the left side of an assignment. For
1471     example:
1472 
1473     \snippet qstring/main.cpp 2
1474 
1475     For read-only access, an alternative syntax is to use the at()
1476     function:
1477 
1478     \snippet qstring/main.cpp 3
1479 
1480     The at() function can be faster than \l operator[](), because it
1481     never causes a \l{deep copy} to occur. Alternatively, use the
1482     left(), right(), or mid() functions to extract several characters
1483     at a time.
1484 
1485     A QString can embed '\\0' characters (QChar::Null). The size()
1486     function always returns the size of the whole string, including
1487     embedded '\\0' characters.
1488 
1489     After a call to the resize() function, newly allocated characters
1490     have undefined values. To set all the characters in the string to
1491     a particular value, use the fill() function.
1492 
1493     QString provides dozens of overloads designed to simplify string
1494     usage. For example, if you want to compare a QString with a string
1495     literal, you can write code like this and it will work as expected:
1496 
1497     \snippet qstring/main.cpp 4
1498 
1499     You can also pass string literals to functions that take QStrings
1500     as arguments, invoking the QString(const char *)
1501     constructor. Similarly, you can pass a QString to a function that
1502     takes a \c{const char *} argument using the \l qPrintable() macro
1503     which returns the given QString as a \c{const char *}. This is
1504     equivalent to calling <QString>.toLocal8Bit().constData().
1505 
1506     \section1 Manipulating String Data
1507 
1508     QString provides the following basic functions for modifying the
1509     character data: append(), prepend(), insert(), replace(), and
1510     remove(). For example:
1511 
1512     \snippet qstring/main.cpp 5
1513 
1514     If you are building a QString gradually and know in advance
1515     approximately how many characters the QString will contain, you
1516     can call reserve(), asking QString to preallocate a certain amount
1517     of memory. You can also call capacity() to find out how much
1518     memory QString actually allocated.
1519 
1520     The replace() and remove() functions' first two arguments are the
1521     position from which to start erasing and the number of characters
1522     that should be erased.  If you want to replace all occurrences of
1523     a particular substring with another, use one of the two-parameter
1524     replace() overloads.
1525 
1526     A frequent requirement is to remove whitespace characters from a
1527     string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace
1528     from both ends of a QString, use the trimmed() function. If you
1529     want to remove whitespace from both ends and replace multiple
1530     consecutive whitespaces with a single space character within the
1531     string, use simplified().
1532 
1533     If you want to find all occurrences of a particular character or
1534     substring in a QString, use the indexOf() or lastIndexOf()
1535     functions. The former searches forward starting from a given index
1536     position, the latter searches backward. Both return the index
1537     position of the character or substring if they find it; otherwise,
1538     they return -1.  For example, here is a typical loop that finds all
1539     occurrences of a particular substring:
1540 
1541     \snippet qstring/main.cpp 6
1542 
1543     QString provides many functions for converting numbers into
1544     strings and strings into numbers. See the arg() functions, the
1545     setNum() functions, the number() static functions, and the
1546     toInt(), toDouble(), and similar functions.
1547 
1548     To get an upper- or lowercase version of a string use toUpper() or
1549     toLower().
1550 
1551     Lists of strings are handled by the QStringList class. You can
1552     split a string into a list of strings using the split() function,
1553     and join a list of strings into a single string with an optional
1554     separator using QStringList::join(). You can obtain a list of
1555     strings from a string list that contain a particular substring or
1556     that match a particular QRegExp using the QStringList::filter()
1557     function.
1558 
1559     \section1 Querying String Data
1560 
1561     If you want to see if a QString starts or ends with a particular
1562     substring use startsWith() or endsWith(). If you simply want to
1563     check whether a QString contains a particular character or
1564     substring, use the contains() function. If you want to find out
1565     how many times a particular character or substring occurs in the
1566     string, use count().
1567 
1568     To obtain a pointer to the actual character data, call data() or
1569     constData(). These functions return a pointer to the beginning of
1570     the QChar data. The pointer is guaranteed to remain valid until a
1571     non-const function is called on the QString.
1572 
1573     \section2 Comparing Strings
1574 
1575     QStrings can be compared using overloaded operators such as \l
1576     operator<(), \l operator<=(), \l operator==(), \l operator>=(),
1577     and so on.  Note that the comparison is based exclusively on the
1578     numeric Unicode values of the characters. It is very fast, but is
1579     not what a human would expect; the QString::localeAwareCompare()
1580     function is usually a better choice for sorting user-interface
1581     strings, when such a comparison is available.
1582 
1583     On Unix-like platforms (including Linux, \macos and iOS), when Qt
1584     is linked with the ICU library (which it usually is), its
1585     locale-aware sorting is used.  Otherwise, on \macos and iOS, \l
1586     localeAwareCompare() compares according the "Order for sorted
1587     lists" setting in the International preferences panel. On other
1588     Unix-like systems without ICU, the comparison falls back to the
1589     system library's \c strcoll(), falling back when it considers
1590     strings equal to QString's (locale-unaware) comparison, described
1591     above,
1592 
1593     \section1 Converting Between 8-Bit Strings and Unicode Strings
1594 
1595     QString provides the following three functions that return a
1596     \c{const char *} version of the string as QByteArray: toUtf8(),
1597     toLatin1(), and toLocal8Bit().
1598 
1599     \list
1600     \li toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
1601     \li toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a
1602        superset of US-ASCII (ANSI X3.4-1986) that supports the entire
1603        Unicode character set through multibyte sequences.
1604     \li toLocal8Bit() returns an 8-bit string using the system's local
1605        encoding.
1606     \endlist
1607 
1608     To convert from one of these encodings, QString provides
1609     fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other
1610     encodings are supported through the QTextCodec class.
1611 
1612     As mentioned above, QString provides a lot of functions and
1613     operators that make it easy to interoperate with \c{const char *}
1614     strings. But this functionality is a double-edged sword: It makes
1615     QString more convenient to use if all strings are US-ASCII or
1616     Latin-1, but there is always the risk that an implicit conversion
1617     from or to \c{const char *} is done using the wrong 8-bit
1618     encoding. To minimize these risks, you can turn off these implicit
1619     conversions by defining some of the following preprocessor symbols:
1620 
1621     \list
1622     \li \l QT_NO_CAST_FROM_ASCII disables automatic conversions from
1623        C string literals and pointers to Unicode.
1624     \li \l QT_RESTRICTED_CAST_FROM_ASCII allows automatic conversions
1625        from C characters and character arrays, but disables automatic
1626        conversions from character pointers to Unicode.
1627     \li \l QT_NO_CAST_TO_ASCII disables automatic conversion from QString
1628        to C strings.
1629     \endlist
1630 
1631     You then need to explicitly call fromUtf8(), fromLatin1(),
1632     or fromLocal8Bit() to construct a QString from an
1633     8-bit string, or use the lightweight QLatin1String class, for
1634     example:
1635 
1636     \snippet code/src_corelib_tools_qstring.cpp 1
1637 
1638     Similarly, you must call toLatin1(), toUtf8(), or
1639     toLocal8Bit() explicitly to convert the QString to an 8-bit
1640     string.  (Other encodings are supported through the QTextCodec
1641     class.)
1642 
1643     \table 100 %
1644     \header
1645     \li Note for C Programmers
1646 
1647     \row
1648     \li
1649     Due to C++'s type system and the fact that QString is
1650     \l{implicitly shared}, QStrings may be treated like \c{int}s or
1651     other basic types. For example:
1652 
1653     \snippet qstring/main.cpp 7
1654 
1655     The \c result variable, is a normal variable allocated on the
1656     stack. When \c return is called, and because we're returning by
1657     value, the copy constructor is called and a copy of the string is
1658     returned. No actual copying takes place thanks to the implicit
1659     sharing.
1660 
1661     \endtable
1662 
1663     \section1 Distinction Between Null and Empty Strings
1664 
1665     For historical reasons, QString distinguishes between a null
1666     string and an empty string. A \e null string is a string that is
1667     initialized using QString's default constructor or by passing
1668     (const char *)0 to the constructor. An \e empty string is any
1669     string with size 0. A null string is always empty, but an empty
1670     string isn't necessarily null:
1671 
1672     \snippet qstring/main.cpp 8
1673 
1674     All functions except isNull() treat null strings the same as empty
1675     strings. For example, toUtf8().constData() returns a valid pointer
1676     (\e not nullptr) to a '\\0' character for a null string. We
1677     recommend that you always use the isEmpty() function and avoid isNull().
1678 
1679     \section1 Argument Formats
1680 
1681     In member functions where an argument \e format can be specified
1682     (e.g., arg(), number()), the argument \e format can be one of the
1683     following:
1684 
1685     \table
1686     \header \li Format \li Meaning
1687     \row \li \c e \li format as [-]9.9e[+|-]999
1688     \row \li \c E \li format as [-]9.9E[+|-]999
1689     \row \li \c f \li format as [-]9.9
1690     \row \li \c g \li use \c e or \c f format, whichever is the most concise
1691     \row \li \c G \li use \c E or \c f format, whichever is the most concise
1692     \endtable
1693 
1694     A \e precision is also specified with the argument \e format. For
1695     the 'e', 'E', and 'f' formats, the \e precision represents the
1696     number of digits \e after the decimal point. For the 'g' and 'G'
1697     formats, the \e precision represents the maximum number of
1698     significant digits (trailing zeroes are omitted).
1699 
1700     \section1 More Efficient String Construction
1701 
1702     Many strings are known at compile time. But the trivial
1703     constructor QString("Hello"), will copy the contents of the string,
1704     treating the contents as Latin-1. To avoid this one can use the
1705     QStringLiteral macro to directly create the required data at compile
1706     time. Constructing a QString out of the literal does then not cause
1707     any overhead at runtime.
1708 
1709     A slightly less efficient way is to use QLatin1String. This class wraps
1710     a C string literal, precalculates it length at compile time and can
1711     then be used for faster comparison with QStrings and conversion to
1712     QStrings than a regular C string literal.
1713 
1714     Using the QString \c{'+'} operator, it is easy to construct a
1715     complex string from multiple substrings. You will often write code
1716     like this:
1717 
1718     \snippet qstring/stringbuilder.cpp 0
1719 
1720     There is nothing wrong with either of these string constructions,
1721     but there are a few hidden inefficiencies. Beginning with Qt 4.6,
1722     you can eliminate them.
1723 
1724     First, multiple uses of the \c{'+'} operator usually means
1725     multiple memory allocations. When concatenating \e{n} substrings,
1726     where \e{n > 2}, there can be as many as \e{n - 1} calls to the
1727     memory allocator.
1728 
1729     In 4.6, an internal template class \c{QStringBuilder} has been
1730     added along with a few helper functions. This class is marked
1731     internal and does not appear in the documentation, because you
1732     aren't meant to instantiate it in your code. Its use will be
1733     automatic, as described below. The class is found in
1734     \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a
1735     look at it.
1736 
1737     \c{QStringBuilder} uses expression templates and reimplements the
1738     \c{'%'} operator so that when you use \c{'%'} for string
1739     concatenation instead of \c{'+'}, multiple substring
1740     concatenations will be postponed until the final result is about
1741     to be assigned to a QString. At this point, the amount of memory
1742     required for the final result is known. The memory allocator is
1743     then called \e{once} to get the required space, and the substrings
1744     are copied into it one by one.
1745 
1746     Additional efficiency is gained by inlining and reduced reference
1747     counting (the QString created from a \c{QStringBuilder} typically
1748     has a ref count of 1, whereas QString::append() needs an extra
1749     test).
1750 
1751     There are two ways you can access this improved method of string
1752     construction. The straightforward way is to include
1753     \c{QStringBuilder} wherever you want to use it, and use the
1754     \c{'%'} operator instead of \c{'+'} when concatenating strings:
1755 
1756     \snippet qstring/stringbuilder.cpp 5
1757 
1758     A more global approach which is the most convenient but
1759     not entirely source compatible, is to this define in your
1760     .pro file:
1761 
1762     \snippet qstring/stringbuilder.cpp 3
1763 
1764     and the \c{'+'} will automatically be performed as the
1765     \c{QStringBuilder} \c{'%'} everywhere.
1766 
1767     \section1 Maximum Size and Out-of-memory Conditions
1768 
1769     The current version of QString is limited to just under 2 GB (2^31 bytes)
1770     in size. The exact value is architecture-dependent, since it depends on the
1771     overhead required for managing the data block, but is no more than 32
1772     bytes. Raw data blocks are also limited by the use of \c int type in the
1773     current version to 2 GB minus 1 byte. Since QString uses two bytes per
1774     character, that translates to just under 2^30 characters in one QString.
1775 
1776     In case memory allocation fails, QString will throw a \c std::bad_alloc
1777     exception. Out of memory conditions in the Qt containers are the only case
1778     where Qt will throw exceptions.
1779 
1780     Note that the operating system may impose further limits on applications
1781     holding a lot of allocated memory, especially large, contiguous blocks.
1782     Such considerations, the configuration of such behavior or any mitigation
1783     are outside the scope of the Qt API.
1784 
1785     \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef
1786 */
1787 
1788 /*!
1789     \enum QString::SplitBehavior
1790 
1791     \obsolete
1792     Use Qt::SplitBehavior instead.
1793 
1794     This enum specifies how the split() function should behave with
1795     respect to empty strings.
1796 
1797     \value KeepEmptyParts  If a field is empty, keep it in the result.
1798     \value SkipEmptyParts  If a field is empty, don't include it in the result.
1799 
1800     \sa split()
1801 */
1802 
1803 /*! \typedef QString::ConstIterator
1804 
1805     Qt-style synonym for QString::const_iterator.
1806 */
1807 
1808 /*! \typedef QString::Iterator
1809 
1810     Qt-style synonym for QString::iterator.
1811 */
1812 
1813 /*! \typedef QString::const_iterator
1814 
1815     \sa QString::iterator
1816 */
1817 
1818 /*! \typedef QString::iterator
1819 
1820     \sa QString::const_iterator
1821 */
1822 
1823 /*! \typedef QString::const_reverse_iterator
1824     \since 5.6
1825 
1826     \sa QString::reverse_iterator, QString::const_iterator
1827 */
1828 
1829 /*! \typedef QString::reverse_iterator
1830     \since 5.6
1831 
1832     \sa QString::const_reverse_iterator, QString::iterator
1833 */
1834 
1835 /*!
1836     \typedef QString::size_type
1837 */
1838 
1839 /*!
1840     \typedef QString::difference_type
1841 */
1842 
1843 /*!
1844     \typedef QString::const_reference
1845 */
1846 /*!
1847     \typedef QString::reference
1848 */
1849 
1850 /*!
1851     \typedef QString::const_pointer
1852 
1853     The QString::const_pointer typedef provides an STL-style
1854     const pointer to a QString element (QChar).
1855 */
1856 /*!
1857     \typedef QString::pointer
1858 
1859     The QString::const_pointer typedef provides an STL-style
1860     pointer to a QString element (QChar).
1861 */
1862 
1863 /*!
1864     \typedef QString::value_type
1865 */
1866 
1867 /*! \fn QString::iterator QString::begin()
1868 
1869     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first character in
1870     the string.
1871 
1872     \sa constBegin(), end()
1873 */
1874 
1875 /*! \fn QString::const_iterator QString::begin() const
1876 
1877     \overload begin()
1878 */
1879 
1880 /*! \fn QString::const_iterator QString::cbegin() const
1881     \since 5.0
1882 
1883     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character
1884     in the string.
1885 
1886     \sa begin(), cend()
1887 */
1888 
1889 /*! \fn QString::const_iterator QString::constBegin() const
1890 
1891     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character
1892     in the string.
1893 
1894     \sa begin(), constEnd()
1895 */
1896 
1897 /*! \fn QString::iterator QString::end()
1898 
1899     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary character
1900     after the last character in the string.
1901 
1902     \sa begin(), constEnd()
1903 */
1904 
1905 /*! \fn QString::const_iterator QString::end() const
1906 
1907     \overload end()
1908 */
1909 
1910 /*! \fn QString::const_iterator QString::cend() const
1911     \since 5.0
1912 
1913     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
1914     character after the last character in the list.
1915 
1916     \sa cbegin(), end()
1917 */
1918 
1919 /*! \fn QString::const_iterator QString::constEnd() const
1920 
1921     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
1922     character after the last character in the list.
1923 
1924     \sa constBegin(), end()
1925 */
1926 
1927 /*! \fn QString::reverse_iterator QString::rbegin()
1928     \since 5.6
1929 
1930     Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
1931     character in the string, in reverse order.
1932 
1933     \sa begin(), crbegin(), rend()
1934 */
1935 
1936 /*! \fn QString::const_reverse_iterator QString::rbegin() const
1937     \since 5.6
1938     \overload
1939 */
1940 
1941 /*! \fn QString::const_reverse_iterator QString::crbegin() const
1942     \since 5.6
1943 
1944     Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
1945     character in the string, in reverse order.
1946 
1947     \sa begin(), rbegin(), rend()
1948 */
1949 
1950 /*! \fn QString::reverse_iterator QString::rend()
1951     \since 5.6
1952 
1953     Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
1954     the last character in the string, in reverse order.
1955 
1956     \sa end(), crend(), rbegin()
1957 */
1958 
1959 /*! \fn QString::const_reverse_iterator QString::rend() const
1960     \since 5.6
1961     \overload
1962 */
1963 
1964 /*! \fn QString::const_reverse_iterator QString::crend() const
1965     \since 5.6
1966 
1967     Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one
1968     past the last character in the string, in reverse order.
1969 
1970     \sa end(), rend(), rbegin()
1971 */
1972 
1973 /*!
1974     \fn QString::QString()
1975 
1976     Constructs a null string. Null strings are also empty.
1977 
1978     \sa isEmpty()
1979 */
1980 
1981 /*!
1982     \fn QString::QString(QString &&other)
1983 
1984     Move-constructs a QString instance, making it point at the same
1985     object that \a other was pointing to.
1986 
1987     \since 5.2
1988 */
1989 
1990 /*! \fn QString::QString(const char *str)
1991 
1992     Constructs a string initialized with the 8-bit string \a str. The
1993     given const char pointer is converted to Unicode using the
1994     fromUtf8() function.
1995 
1996     You can disable this constructor by defining \c
1997     QT_NO_CAST_FROM_ASCII when you compile your applications. This
1998     can be useful if you want to ensure that all user-visible strings
1999     go through QObject::tr(), for example.
2000 
2001     \note Defining \c QT_RESTRICTED_CAST_FROM_ASCII also disables
2002     this constructor, but enables a \c{QString(const char (&ch)[N])}
2003     constructor instead. Using non-literal input, or input with
2004     embedded NUL characters, or non-7-bit characters is undefined
2005     in this case.
2006 
2007     \sa fromLatin1(), fromLocal8Bit(), fromUtf8(), QT_NO_CAST_FROM_ASCII, QT_RESTRICTED_CAST_FROM_ASCII
2008 */
2009 
2010 /*! \fn QString QString::fromStdString(const std::string &str)
2011 
2012     Returns a copy of the \a str string. The given string is converted
2013     to Unicode using the fromUtf8() function.
2014 
2015     \sa fromLatin1(), fromLocal8Bit(), fromUtf8(), QByteArray::fromStdString()
2016 */
2017 
2018 /*! \fn QString QString::fromStdWString(const std::wstring &str)
2019 
2020     Returns a copy of the \a str string. The given string is assumed
2021     to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on
2022     windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix
2023     systems).
2024 
2025     \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdU16String(), fromStdU32String()
2026 */
2027 
2028 /*! \fn QString QString::fromWCharArray(const wchar_t *string, int size)
2029     \since 4.2
2030 
2031     Returns a copy of the \a string, where the encoding of \a string depends on
2032     the size of wchar. If wchar is 4 bytes, the \a string is interpreted as UCS-4,
2033     if wchar is 2 bytes it is interpreted as UTF-16.
2034 
2035     If \a size is -1 (default), the \a string has to be \\0'-terminated.
2036 
2037     \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString()
2038 */
2039 
2040 /*! \fn std::wstring QString::toStdWString() const
2041 
2042     Returns a std::wstring object with the data contained in this
2043     QString. The std::wstring is encoded in utf16 on platforms where
2044     wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms
2045     where wchar_t is 4 bytes wide (most Unix systems).
2046 
2047     This method is mostly useful to pass a QString to a function
2048     that accepts a std::wstring object.
2049 
2050     \sa utf16(), toLatin1(), toUtf8(), toLocal8Bit(), toStdU16String(), toStdU32String()
2051 */
2052 
toUcs4_helper(const ushort * uc,int length,uint * out)2053 int QString::toUcs4_helper(const ushort *uc, int length, uint *out)
2054 {
2055     int count = 0;
2056 
2057     QStringIterator i(QStringView(uc, length));
2058     while (i.hasNext())
2059         out[count++] = i.next();
2060 
2061     return count;
2062 }
2063 
2064 /*! \fn int QString::toWCharArray(wchar_t *array) const
2065   \since 4.2
2066 
2067   Fills the \a array with the data contained in this QString object.
2068   The array is encoded in UTF-16 on platforms where
2069   wchar_t is 2 bytes wide (e.g. windows) and in UCS-4 on platforms
2070   where wchar_t is 4 bytes wide (most Unix systems).
2071 
2072   \a array has to be allocated by the caller and contain enough space to
2073   hold the complete string (allocating the array with the same length as the
2074   string is always sufficient).
2075 
2076   This function returns the actual length of the string in \a array.
2077 
2078   \note This function does not append a null character to the array.
2079 
2080   \sa utf16(), toUcs4(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString(), QStringView::toWCharArray()
2081 */
2082 
2083 /*! \fn QString::QString(const QString &other)
2084 
2085     Constructs a copy of \a other.
2086 
2087     This operation takes \l{constant time}, because QString is
2088     \l{implicitly shared}. This makes returning a QString from a
2089     function very fast. If a shared instance is modified, it will be
2090     copied (copy-on-write), and that takes \l{linear time}.
2091 
2092     \sa operator=()
2093 */
2094 
2095 /*!
2096     Constructs a string initialized with the first \a size characters
2097     of the QChar array \a unicode.
2098 
2099     If \a unicode is 0, a null string is constructed.
2100 
2101     If \a size is negative, \a unicode is assumed to point to a \\0'-terminated
2102     array and its length is determined dynamically. The terminating
2103     null character is not considered part of the string.
2104 
2105     QString makes a deep copy of the string data. The unicode data is copied as
2106     is and the Byte Order Mark is preserved if present.
2107 
2108     \sa fromRawData()
2109 */
QString(const QChar * unicode,int size)2110 QString::QString(const QChar *unicode, int size)
2111 {
2112    if (!unicode) {
2113         d = Data::sharedNull();
2114     } else {
2115         if (size < 0) {
2116             size = 0;
2117             while (!unicode[size].isNull())
2118                 ++size;
2119         }
2120         if (!size) {
2121             d = Data::allocate(0);
2122         } else {
2123             d = Data::allocate(size + 1);
2124             Q_CHECK_PTR(d);
2125             d->size = size;
2126             memcpy(d->data(), unicode, size * sizeof(QChar));
2127             d->data()[size] = '\0';
2128         }
2129     }
2130 }
2131 
2132 /*!
2133     Constructs a string of the given \a size with every character set
2134     to \a ch.
2135 
2136     \sa fill()
2137 */
QString(int size,QChar ch)2138 QString::QString(int size, QChar ch)
2139 {
2140    if (size <= 0) {
2141         d = Data::allocate(0);
2142     } else {
2143         d = Data::allocate(size + 1);
2144         Q_CHECK_PTR(d);
2145         d->size = size;
2146         d->data()[size] = '\0';
2147         ushort *i = d->data() + size;
2148         ushort *b = d->data();
2149         const ushort value = ch.unicode();
2150         while (i != b)
2151            *--i = value;
2152     }
2153 }
2154 
2155 /*! \fn QString::QString(int size, Qt::Initialization)
2156   \internal
2157 
2158   Constructs a string of the given \a size without initializing the
2159   characters. This is only used in \c QStringBuilder::toString().
2160 */
QString(int size,Qt::Initialization)2161 QString::QString(int size, Qt::Initialization)
2162 {
2163     d = Data::allocate(size + 1);
2164     Q_CHECK_PTR(d);
2165     d->size = size;
2166     d->data()[size] = '\0';
2167 }
2168 
2169 /*! \fn QString::QString(QLatin1String str)
2170 
2171     Constructs a copy of the Latin-1 string \a str.
2172 
2173     \sa fromLatin1()
2174 */
2175 
2176 /*!
2177     Constructs a string of size 1 containing the character \a ch.
2178 */
QString(QChar ch)2179 QString::QString(QChar ch)
2180 {
2181     d = Data::allocate(2);
2182     Q_CHECK_PTR(d);
2183     d->size = 1;
2184     d->data()[0] = ch.unicode();
2185     d->data()[1] = '\0';
2186 }
2187 
2188 /*! \fn QString::QString(const QByteArray &ba)
2189 
2190     Constructs a string initialized with the byte array \a ba. The
2191     given byte array is converted to Unicode using fromUtf8(). Stops
2192     copying at the first 0 character, otherwise copies the entire byte
2193     array.
2194 
2195     You can disable this constructor by defining \c
2196     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2197     can be useful if you want to ensure that all user-visible strings
2198     go through QObject::tr(), for example.
2199 
2200     \sa fromLatin1(), fromLocal8Bit(), fromUtf8(), QT_NO_CAST_FROM_ASCII
2201 */
2202 
2203 /*! \fn QString::QString(const Null &)
2204     \internal
2205 */
2206 
2207 /*! \fn QString::QString(QStringDataPtr)
2208     \internal
2209 */
2210 
2211 /*! \fn QString &QString::operator=(const QString::Null &)
2212     \internal
2213 */
2214 
2215 /*!
2216   \fn QString::~QString()
2217 
2218     Destroys the string.
2219 */
2220 
2221 
2222 /*! \fn void QString::swap(QString &other)
2223     \since 4.8
2224 
2225     Swaps string \a other with this string. This operation is very fast and
2226     never fails.
2227 */
2228 
2229 /*! \fn void QString::detach()
2230 
2231     \internal
2232 */
2233 
2234 /*! \fn bool QString::isDetached() const
2235 
2236     \internal
2237 */
2238 
2239 /*! \fn bool QString::isSharedWith(const QString &other) const
2240 
2241     \internal
2242 */
2243 
2244 /*!
2245     Sets the size of the string to \a size characters.
2246 
2247     If \a size is greater than the current size, the string is
2248     extended to make it \a size characters long with the extra
2249     characters added to the end. The new characters are uninitialized.
2250 
2251     If \a size is less than the current size, characters are removed
2252     from the end.
2253 
2254     Example:
2255 
2256     \snippet qstring/main.cpp 45
2257 
2258     If you want to append a certain number of identical characters to
2259     the string, use the \l {QString::}{resize(int, QChar)} overload.
2260 
2261     If you want to expand the string so that it reaches a certain
2262     width and fill the new positions with a particular character, use
2263     the leftJustified() function:
2264 
2265     If \a size is negative, it is equivalent to passing zero.
2266 
2267     \snippet qstring/main.cpp 47
2268 
2269     \sa truncate(), reserve()
2270 */
2271 
resize(int size)2272 void QString::resize(int size)
2273 {
2274     if (size < 0)
2275         size = 0;
2276 
2277     if (IS_RAW_DATA(d) && !d->ref.isShared() && size < d->size) {
2278         d->size = size;
2279         return;
2280     }
2281 
2282     if (d->ref.isShared() || uint(size) + 1u > d->alloc)
2283         reallocData(uint(size) + 1u, true);
2284     if (d->alloc) {
2285         d->size = size;
2286         d->data()[size] = '\0';
2287     }
2288 }
2289 
2290 /*!
2291     \overload
2292     \since 5.7
2293 
2294     Unlike \l {QString::}{resize(int)}, this overload
2295     initializes the new characters to \a fillChar:
2296 
2297     \snippet qstring/main.cpp 46
2298 */
2299 
resize(int size,QChar fillChar)2300 void QString::resize(int size, QChar fillChar)
2301 {
2302     const int oldSize = length();
2303     resize(size);
2304     const int difference = length() - oldSize;
2305     if (difference > 0)
2306         std::fill_n(d->begin() + oldSize, difference, fillChar.unicode());
2307 }
2308 
2309 /*! \fn int QString::capacity() const
2310 
2311     Returns the maximum number of characters that can be stored in
2312     the string without forcing a reallocation.
2313 
2314     The sole purpose of this function is to provide a means of fine
2315     tuning QString's memory usage. In general, you will rarely ever
2316     need to call this function. If you want to know how many
2317     characters are in the string, call size().
2318 
2319     \sa reserve(), squeeze()
2320 */
2321 
2322 /*!
2323     \fn void QString::reserve(int size)
2324 
2325     Attempts to allocate memory for at least \a size characters. If
2326     you know in advance how large the string will be, you can call
2327     this function, and if you resize the string often you are likely
2328     to get better performance. If \a size is an underestimate, the
2329     worst that will happen is that the QString will be a bit slower.
2330 
2331     The sole purpose of this function is to provide a means of fine
2332     tuning QString's memory usage. In general, you will rarely ever
2333     need to call this function. If you want to change the size of the
2334     string, call resize().
2335 
2336     This function is useful for code that needs to build up a long
2337     string and wants to avoid repeated reallocation. In this example,
2338     we want to add to the string until some condition is \c true, and
2339     we're fairly sure that size is large enough to make a call to
2340     reserve() worthwhile:
2341 
2342     \snippet qstring/main.cpp 44
2343 
2344     \sa squeeze(), capacity()
2345 */
2346 
2347 /*!
2348     \fn void QString::squeeze()
2349 
2350     Releases any memory not required to store the character data.
2351 
2352     The sole purpose of this function is to provide a means of fine
2353     tuning QString's memory usage. In general, you will rarely ever
2354     need to call this function.
2355 
2356     \sa reserve(), capacity()
2357 */
2358 
reallocData(uint alloc,bool grow)2359 void QString::reallocData(uint alloc, bool grow)
2360 {
2361     auto allocOptions = d->detachFlags();
2362     if (grow)
2363         allocOptions |= QArrayData::Grow;
2364 
2365     if (d->ref.isShared() || IS_RAW_DATA(d)) {
2366         Data *x = Data::allocate(alloc, allocOptions);
2367         Q_CHECK_PTR(x);
2368         x->size = qMin(int(alloc) - 1, d->size);
2369         ::memcpy(x->data(), d->data(), x->size * sizeof(QChar));
2370         x->data()[x->size] = 0;
2371         if (!d->ref.deref())
2372             Data::deallocate(d);
2373         d = x;
2374     } else {
2375         Data *p = Data::reallocateUnaligned(d, alloc, allocOptions);
2376         Q_CHECK_PTR(p);
2377         d = p;
2378     }
2379 }
2380 
2381 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
expand(int i)2382 void QString::expand(int i)
2383 {
2384     resize(qMax(i + 1, d->size), QLatin1Char(' '));
2385 }
2386 #endif
2387 
2388 /*! \fn void QString::clear()
2389 
2390     Clears the contents of the string and makes it null.
2391 
2392     \sa resize(), isNull()
2393 */
2394 
2395 /*! \fn QString &QString::operator=(const QString &other)
2396 
2397     Assigns \a other to this string and returns a reference to this
2398     string.
2399 */
2400 
operator =(const QString & other)2401 QString &QString::operator=(const QString &other) noexcept
2402 {
2403     other.d->ref.ref();
2404     if (!d->ref.deref())
2405         Data::deallocate(d);
2406     d = other.d;
2407     return *this;
2408 }
2409 
2410 /*!
2411     \fn QString &QString::operator=(QString &&other)
2412 
2413     Move-assigns \a other to this QString instance.
2414 
2415     \since 5.2
2416 */
2417 
2418 /*! \fn QString &QString::operator=(QLatin1String str)
2419 
2420     \overload operator=()
2421 
2422     Assigns the Latin-1 string \a str to this string.
2423 */
operator =(QLatin1String other)2424 QString &QString::operator=(QLatin1String other)
2425 {
2426     if (isDetached() && other.size() <= capacity()) { // assumes d->alloc == 0 -> !isDetached() (sharedNull)
2427         d->size = other.size();
2428         d->data()[other.size()] = 0;
2429         qt_from_latin1(d->data(), other.latin1(), other.size());
2430     } else {
2431         *this = fromLatin1(other.latin1(), other.size());
2432     }
2433     return *this;
2434 }
2435 
2436 /*! \fn QString &QString::operator=(const QByteArray &ba)
2437 
2438     \overload operator=()
2439 
2440     Assigns \a ba to this string. The byte array is converted to Unicode
2441     using the fromUtf8() function. This function stops conversion at the
2442     first NUL character found, or the end of the \a ba byte array.
2443 
2444     You can disable this operator by defining \c
2445     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2446     can be useful if you want to ensure that all user-visible strings
2447     go through QObject::tr(), for example.
2448 
2449     \sa QT_NO_CAST_FROM_ASCII
2450 */
2451 
2452 /*! \fn QString &QString::operator=(const char *str)
2453 
2454     \overload operator=()
2455 
2456     Assigns \a str to this string. The const char pointer is converted
2457     to Unicode using the fromUtf8() function.
2458 
2459     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
2460     or \c QT_RESTRICTED_CAST_FROM_ASCII when you compile your applications.
2461     This can be useful if you want to ensure that all user-visible strings
2462     go through QObject::tr(), for example.
2463 
2464     \sa QT_NO_CAST_FROM_ASCII, QT_RESTRICTED_CAST_FROM_ASCII
2465 */
2466 
2467 /*! \fn QString &QString::operator=(char ch)
2468 
2469     \overload operator=()
2470 
2471     Assigns character \a ch to this string. Note that the character is
2472     converted to Unicode using the fromLatin1() function, unlike other 8-bit
2473     functions that operate on UTF-8 data.
2474 
2475     You can disable this operator by defining \c
2476     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2477     can be useful if you want to ensure that all user-visible strings
2478     go through QObject::tr(), for example.
2479 
2480     \sa QT_NO_CAST_FROM_ASCII
2481 */
2482 
2483 /*!
2484     \overload operator=()
2485 
2486     Sets the string to contain the single character \a ch.
2487 */
operator =(QChar ch)2488 QString &QString::operator=(QChar ch)
2489 {
2490     if (isDetached() && capacity() >= 1) { // assumes d->alloc == 0 -> !isDetached() (sharedNull)
2491         // re-use existing capacity:
2492         ushort *dat = d->data();
2493         dat[0] = ch.unicode();
2494         dat[1] = 0;
2495         d->size = 1;
2496     } else {
2497         operator=(QString(ch));
2498     }
2499     return *this;
2500 }
2501 
2502 /*!
2503      \fn QString& QString::insert(int position, const QString &str)
2504 
2505     Inserts the string \a str at the given index \a position and
2506     returns a reference to this string.
2507 
2508     Example:
2509 
2510     \snippet qstring/main.cpp 26
2511 
2512     If the given \a position is greater than size(), the array is
2513     first extended using resize().
2514 
2515     \sa append(), prepend(), replace(), remove()
2516 */
2517 
2518 
2519 /*!
2520     \fn QString& QString::insert(int position, const QStringRef &str)
2521     \since 5.5
2522     \overload insert()
2523 
2524     Inserts the string reference \a str at the given index \a position and
2525     returns a reference to this string.
2526 
2527     If the given \a position is greater than size(), the array is
2528     first extended using resize().
2529 */
2530 
2531 /*!
2532     \fn QString& QString::insert(int position, QStringView str)
2533     \since 5.15.2
2534     \overload insert()
2535 
2536     Inserts the string reference \a str at the given index \a position and
2537     returns a reference to this string.
2538 
2539     If the given \a position is greater than size(), the array is
2540     first extended using resize().
2541 
2542     \note This method has been added in 5.15.2 to simplify writing code that is portable
2543     between Qt 5.15 and Qt 6.
2544 */
2545 
2546 
2547 /*!
2548     \fn QString& QString::insert(int position, const char *str)
2549     \since 5.5
2550     \overload insert()
2551 
2552     Inserts the C string \a str at the given index \a position and
2553     returns a reference to this string.
2554 
2555     If the given \a position is greater than size(), the array is
2556     first extended using resize().
2557 
2558     This function is not available when \c QT_NO_CAST_FROM_ASCII is
2559     defined.
2560 
2561     \sa QT_NO_CAST_FROM_ASCII
2562 */
2563 
2564 
2565 /*!
2566     \fn QString& QString::insert(int position, const QByteArray &str)
2567     \since 5.5
2568     \overload insert()
2569 
2570     Inserts the byte array \a str at the given index \a position and
2571     returns a reference to this string.
2572 
2573     If the given \a position is greater than size(), the array is
2574     first extended using resize().
2575 
2576     This function is not available when \c QT_NO_CAST_FROM_ASCII is
2577     defined.
2578 
2579     \sa QT_NO_CAST_FROM_ASCII
2580 */
2581 
2582 
2583 /*!
2584     \fn QString &QString::insert(int position, QLatin1String str)
2585     \overload insert()
2586 
2587     Inserts the Latin-1 string \a str at the given index \a position.
2588 */
insert(int i,QLatin1String str)2589 QString &QString::insert(int i, QLatin1String str)
2590 {
2591     const char *s = str.latin1();
2592     if (i < 0 || !s || !(*s))
2593         return *this;
2594 
2595     int len = str.size();
2596     if (Q_UNLIKELY(i > d->size))
2597         resize(i + len, QLatin1Char(' '));
2598     else
2599         resize(d->size + len);
2600 
2601     ::memmove(d->data() + i + len, d->data() + i, (d->size - i - len) * sizeof(QChar));
2602     qt_from_latin1(d->data() + i, s, uint(len));
2603     return *this;
2604 }
2605 
2606 /*!
2607     \fn QString& QString::insert(int position, const QChar *unicode, int size)
2608     \overload insert()
2609 
2610     Inserts the first \a size characters of the QChar array \a unicode
2611     at the given index \a position in the string.
2612 */
insert(int i,const QChar * unicode,int size)2613 QString& QString::insert(int i, const QChar *unicode, int size)
2614 {
2615     if (i < 0 || size <= 0)
2616         return *this;
2617 
2618     const ushort *s = (const ushort *)unicode;
2619     const std::less<const ushort*> less = {};
2620     if (!less(s, d->data()) && less(s, d->data() + d->alloc)) {
2621         // Part of me - take a copy
2622         const QVarLengthArray<ushort> copy(s, s + size);
2623         insert(i, reinterpret_cast<const QChar *>(copy.data()), size);
2624         return *this;
2625     }
2626 
2627     if (Q_UNLIKELY(i > d->size))
2628         resize(i + size, QLatin1Char(' '));
2629     else
2630         resize(d->size + size);
2631 
2632     ::memmove(d->data() + i + size, d->data() + i, (d->size - i - size) * sizeof(QChar));
2633     memcpy(d->data() + i, s, size * sizeof(QChar));
2634     return *this;
2635 }
2636 
2637 /*!
2638     \fn QString& QString::insert(int position, QChar ch)
2639     \overload insert()
2640 
2641     Inserts \a ch at the given index \a position in the string.
2642 */
2643 
insert(int i,QChar ch)2644 QString& QString::insert(int i, QChar ch)
2645 {
2646     if (i < 0)
2647         i += d->size;
2648     if (i < 0)
2649         return *this;
2650     if (Q_UNLIKELY(i > d->size))
2651         resize(i + 1, QLatin1Char(' '));
2652     else
2653         resize(d->size + 1);
2654     ::memmove(d->data() + i + 1, d->data() + i, (d->size - i - 1) * sizeof(QChar));
2655     d->data()[i] = ch.unicode();
2656     return *this;
2657 }
2658 
2659 /*!
2660     Appends the string \a str onto the end of this string.
2661 
2662     Example:
2663 
2664     \snippet qstring/main.cpp 9
2665 
2666     This is the same as using the insert() function:
2667 
2668     \snippet qstring/main.cpp 10
2669 
2670     The append() function is typically very fast (\l{constant time}),
2671     because QString preallocates extra space at the end of the string
2672     data so it can grow without reallocating the entire string each
2673     time.
2674 
2675     \sa operator+=(), prepend(), insert()
2676 */
append(const QString & str)2677 QString &QString::append(const QString &str)
2678 {
2679     if (str.d != Data::sharedNull()) {
2680         if (d == Data::sharedNull()) {
2681             operator=(str);
2682         } else {
2683             if (d->ref.isShared() || uint(d->size + str.d->size) + 1u > d->alloc)
2684                 reallocData(uint(d->size + str.d->size) + 1u, true);
2685             memcpy(d->data() + d->size, str.d->data(), str.d->size * sizeof(QChar));
2686             d->size += str.d->size;
2687             d->data()[d->size] = '\0';
2688         }
2689     }
2690     return *this;
2691 }
2692 
2693 /*!
2694   \overload append()
2695   \since 5.0
2696 
2697   Appends \a len characters from the QChar array \a str to this string.
2698 */
append(const QChar * str,int len)2699 QString &QString::append(const QChar *str, int len)
2700 {
2701     if (str && len > 0) {
2702         if (d->ref.isShared() || uint(d->size + len) + 1u > d->alloc)
2703             reallocData(uint(d->size + len) + 1u, true);
2704         memcpy(d->data() + d->size, str, len * sizeof(QChar));
2705         d->size += len;
2706         d->data()[d->size] = '\0';
2707     }
2708     return *this;
2709 }
2710 
2711 /*!
2712   \overload append()
2713 
2714   Appends the Latin-1 string \a str to this string.
2715 */
append(QLatin1String str)2716 QString &QString::append(QLatin1String str)
2717 {
2718     const char *s = str.latin1();
2719     if (s) {
2720         int len = str.size();
2721         if (d->ref.isShared() || uint(d->size + len) + 1u > d->alloc)
2722             reallocData(uint(d->size + len) + 1u, true);
2723         ushort *i = d->data() + d->size;
2724         qt_from_latin1(i, s, uint(len));
2725         i[len] = '\0';
2726         d->size += len;
2727     }
2728     return *this;
2729 }
2730 
2731 /*! \fn QString &QString::append(const QByteArray &ba)
2732 
2733     \overload append()
2734 
2735     Appends the byte array \a ba to this string. The given byte array
2736     is converted to Unicode using the fromUtf8() function.
2737 
2738     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
2739     when you compile your applications. This can be useful if you want
2740     to ensure that all user-visible strings go through QObject::tr(),
2741     for example.
2742 
2743     \sa QT_NO_CAST_FROM_ASCII
2744 */
2745 
2746 /*! \fn QString &QString::append(const char *str)
2747 
2748     \overload append()
2749 
2750     Appends the string \a str to this string. The given const char
2751     pointer is converted to Unicode using the fromUtf8() function.
2752 
2753     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
2754     when you compile your applications. This can be useful if you want
2755     to ensure that all user-visible strings go through QObject::tr(),
2756     for example.
2757 
2758     \sa QT_NO_CAST_FROM_ASCII
2759 */
2760 
2761 /*!
2762     \overload append()
2763 
2764     Appends the character \a ch to this string.
2765 */
append(QChar ch)2766 QString &QString::append(QChar ch)
2767 {
2768     if (d->ref.isShared() || uint(d->size) + 2u > d->alloc)
2769         reallocData(uint(d->size) + 2u, true);
2770     d->data()[d->size++] = ch.unicode();
2771     d->data()[d->size] = '\0';
2772     return *this;
2773 }
2774 
2775 /*! \fn QString &QString::prepend(const QString &str)
2776 
2777     Prepends the string \a str to the beginning of this string and
2778     returns a reference to this string.
2779 
2780     Example:
2781 
2782     \snippet qstring/main.cpp 36
2783 
2784     \sa append(), insert()
2785 */
2786 
2787 /*! \fn QString &QString::prepend(QLatin1String str)
2788 
2789     \overload prepend()
2790 
2791     Prepends the Latin-1 string \a str to this string.
2792 */
2793 
2794 /*! \fn QString &QString::prepend(const QChar *str, int len)
2795     \since 5.5
2796     \overload prepend()
2797 
2798     Prepends \a len characters from the QChar array \a str to this string and
2799     returns a reference to this string.
2800 */
2801 
2802 /*! \fn QString &QString::prepend(const QStringRef &str)
2803     \since 5.5
2804     \overload prepend()
2805 
2806     Prepends the string reference \a str to the beginning of this string and
2807     returns a reference to this string.
2808 */
2809 
2810 /*!
2811     \fn QString &QString::prepend(QStringView str)
2812     \since 5.15.2
2813 
2814     Prepends the given string \a str to this string and returns the result.
2815 
2816     \note This method has been added in 5.15.2 to simplify writing code that is portable
2817     between Qt 5.15 and Qt 6.
2818 */
2819 
2820 /*! \fn QString &QString::prepend(const QByteArray &ba)
2821 
2822     \overload prepend()
2823 
2824     Prepends the byte array \a ba to this string. The byte array is
2825     converted to Unicode using the fromUtf8() function.
2826 
2827     You can disable this function by defining \c
2828     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2829     can be useful if you want to ensure that all user-visible strings
2830     go through QObject::tr(), for example.
2831 
2832     \sa QT_NO_CAST_FROM_ASCII
2833 */
2834 
2835 /*! \fn QString &QString::prepend(const char *str)
2836 
2837     \overload prepend()
2838 
2839     Prepends the string \a str to this string. The const char pointer
2840     is converted to Unicode using the fromUtf8() function.
2841 
2842     You can disable this function by defining \c
2843     QT_NO_CAST_FROM_ASCII when you compile your applications. This
2844     can be useful if you want to ensure that all user-visible strings
2845     go through QObject::tr(), for example.
2846 
2847     \sa QT_NO_CAST_FROM_ASCII
2848 */
2849 
2850 /*! \fn QString &QString::prepend(QChar ch)
2851 
2852     \overload prepend()
2853 
2854     Prepends the character \a ch to this string.
2855 */
2856 
2857 /*!
2858   \fn QString &QString::remove(int position, int n)
2859 
2860   Removes \a n characters from the string, starting at the given \a
2861   position index, and returns a reference to the string.
2862 
2863   If the specified \a position index is within the string, but \a
2864   position + \a n is beyond the end of the string, the string is
2865   truncated at the specified \a position.
2866 
2867   \snippet qstring/main.cpp 37
2868 
2869   \sa insert(), replace()
2870 */
remove(int pos,int len)2871 QString &QString::remove(int pos, int len)
2872 {
2873     if (pos < 0)  // count from end of string
2874         pos += d->size;
2875     if (uint(pos) >= uint(d->size)) {
2876         // range problems
2877     } else if (len >= d->size - pos) {
2878         resize(pos); // truncate
2879     } else if (len > 0) {
2880         detach();
2881         memmove(d->data() + pos, d->data() + pos + len,
2882                 (d->size - pos - len + 1) * sizeof(ushort));
2883         d->size -= len;
2884     }
2885     return *this;
2886 }
2887 
2888 template<typename T>
removeStringImpl(QString & s,const T & needle,Qt::CaseSensitivity cs)2889 static void removeStringImpl(QString &s, const T &needle, Qt::CaseSensitivity cs)
2890 {
2891     const auto needleSize = needle.size();
2892     if (!needleSize)
2893         return;
2894 
2895     // avoid detach if nothing to do:
2896     int i = s.indexOf(needle, 0, cs);
2897     if (i < 0)
2898         return;
2899 
2900     const auto beg = s.begin(); // detaches
2901     auto dst = beg + i;
2902     auto src = beg + i + needleSize;
2903     const auto end = s.end();
2904     // loop invariant: [beg, dst[ is partial result
2905     //                 [src, end[ still to be checked for needles
2906     while (src < end) {
2907         const auto i = s.indexOf(needle, src - beg, cs);
2908         const auto hit = i == -1 ? end : beg + i;
2909         const auto skipped = hit - src;
2910         memmove(dst, src, skipped * sizeof(QChar));
2911         dst += skipped;
2912         src = hit + needleSize;
2913     }
2914     s.truncate(dst - beg);
2915 }
2916 
2917 /*!
2918   Removes every occurrence of the given \a str string in this
2919   string, and returns a reference to this string.
2920 
2921   If \a cs is Qt::CaseSensitive (default), the search is
2922   case sensitive; otherwise the search is case insensitive.
2923 
2924   This is the same as \c replace(str, "", cs).
2925 
2926   \sa replace()
2927 */
remove(const QString & str,Qt::CaseSensitivity cs)2928 QString &QString::remove(const QString &str, Qt::CaseSensitivity cs)
2929 {
2930     const auto s = reinterpret_cast<const ushort *>(str.data());
2931     const std::less<const ushort *> less = {};
2932     if (!less(s, d->data()) && less(s, d->data() + d->alloc)) {
2933         // Part of me - take a copy
2934         const QVarLengthArray<ushort> copy(s, s + str.size());
2935         removeStringImpl(*this, QStringView{copy.data(), copy.size()}, cs);
2936     } else {
2937         removeStringImpl(*this, qToStringViewIgnoringNull(str), cs);
2938     }
2939     return *this;
2940 }
2941 
2942 /*!
2943   \since 5.11
2944   \overload
2945 
2946   Removes every occurrence of the given \a str string in this
2947   string, and returns a reference to this string.
2948 
2949   If \a cs is Qt::CaseSensitive (default), the search is
2950   case sensitive; otherwise the search is case insensitive.
2951 
2952   This is the same as \c replace(str, "", cs).
2953 
2954   \sa replace()
2955 */
remove(QLatin1String str,Qt::CaseSensitivity cs)2956 QString &QString::remove(QLatin1String str, Qt::CaseSensitivity cs)
2957 {
2958     removeStringImpl(*this, str, cs);
2959     return *this;
2960 }
2961 
2962 /*!
2963   Removes every occurrence of the character \a ch in this string, and
2964   returns a reference to this string.
2965 
2966   If \a cs is Qt::CaseSensitive (default), the search is case
2967   sensitive; otherwise the search is case insensitive.
2968 
2969   Example:
2970 
2971   \snippet qstring/main.cpp 38
2972 
2973   This is the same as \c replace(ch, "", cs).
2974 
2975   \sa replace()
2976 */
remove(QChar ch,Qt::CaseSensitivity cs)2977 QString &QString::remove(QChar ch, Qt::CaseSensitivity cs)
2978 {
2979     const int idx = indexOf(ch, 0, cs);
2980     if (idx != -1) {
2981         const auto first = begin(); // implicit detach()
2982         auto last = end();
2983         if (cs == Qt::CaseSensitive) {
2984             last = std::remove(first + idx, last, ch);
2985         } else {
2986             const QChar c = ch.toCaseFolded();
2987             auto caseInsensEqual = [c](QChar x) {
2988                 return c == x.toCaseFolded();
2989             };
2990             last = std::remove_if(first + idx, last, caseInsensEqual);
2991         }
2992         resize(last - first);
2993     }
2994     return *this;
2995 }
2996 
2997 /*!
2998   \fn QString &QString::remove(const QRegExp &rx)
2999 
3000   Removes every occurrence of the regular expression \a rx in the
3001   string, and returns a reference to the string. For example:
3002 
3003   \snippet qstring/main.cpp 39
3004 
3005   \sa indexOf(), lastIndexOf(), replace()
3006 */
3007 
3008 /*!
3009   \fn QString &QString::remove(const QRegularExpression &re)
3010   \since 5.0
3011 
3012   Removes every occurrence of the regular expression \a re in the
3013   string, and returns a reference to the string. For example:
3014 
3015   \snippet qstring/main.cpp 96
3016 
3017   \sa indexOf(), lastIndexOf(), replace()
3018 */
3019 
3020 /*!
3021   \fn QString &QString::replace(int position, int n, const QString &after)
3022 
3023   Replaces \a n characters beginning at index \a position with
3024   the string \a after and returns a reference to this string.
3025 
3026   \note If the specified \a position index is within the string,
3027   but \a position + \a n goes outside the strings range,
3028   then \a n will be adjusted to stop at the end of the string.
3029 
3030   Example:
3031 
3032   \snippet qstring/main.cpp 40
3033 
3034   \sa insert(), remove()
3035 */
replace(int pos,int len,const QString & after)3036 QString &QString::replace(int pos, int len, const QString &after)
3037 {
3038     return replace(pos, len, after.constData(), after.length());
3039 }
3040 
3041 /*!
3042   \fn QString &QString::replace(int position, int n, const QChar *unicode, int size)
3043   \overload replace()
3044   Replaces \a n characters beginning at index \a position with the
3045   first \a size characters of the QChar array \a unicode and returns a
3046   reference to this string.
3047 */
replace(int pos,int len,const QChar * unicode,int size)3048 QString &QString::replace(int pos, int len, const QChar *unicode, int size)
3049 {
3050     if (uint(pos) > uint(d->size))
3051         return *this;
3052     if (len > d->size - pos)
3053         len = d->size - pos;
3054 
3055     uint index = pos;
3056     replace_helper(&index, 1, len, unicode, size);
3057     return *this;
3058 }
3059 
3060 /*!
3061   \fn QString &QString::replace(int position, int n, QChar after)
3062   \overload replace()
3063 
3064   Replaces \a n characters beginning at index \a position with the
3065   character \a after and returns a reference to this string.
3066 */
replace(int pos,int len,QChar after)3067 QString &QString::replace(int pos, int len, QChar after)
3068 {
3069     return replace(pos, len, &after, 1);
3070 }
3071 
3072 /*!
3073   \overload replace()
3074   Replaces every occurrence of the string \a before with the string \a
3075   after and returns a reference to this string.
3076 
3077   If \a cs is Qt::CaseSensitive (default), the search is case
3078   sensitive; otherwise the search is case insensitive.
3079 
3080   Example:
3081 
3082   \snippet qstring/main.cpp 41
3083 
3084   \note The replacement text is not rescanned after it is inserted.
3085 
3086   Example:
3087 
3088   \snippet qstring/main.cpp 86
3089 */
replace(const QString & before,const QString & after,Qt::CaseSensitivity cs)3090 QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs)
3091 {
3092     return replace(before.constData(), before.size(), after.constData(), after.size(), cs);
3093 }
3094 
3095 namespace { // helpers for replace and its helper:
textCopy(const QChar * start,int len)3096 QChar *textCopy(const QChar *start, int len)
3097 {
3098     const size_t size = len * sizeof(QChar);
3099     QChar *const copy = static_cast<QChar *>(::malloc(size));
3100     Q_CHECK_PTR(copy);
3101     ::memcpy(copy, start, size);
3102     return copy;
3103 }
3104 
pointsIntoRange(const QChar * ptr,const ushort * base,int len)3105 bool pointsIntoRange(const QChar *ptr, const ushort *base, int len)
3106 {
3107     const QChar *const start = reinterpret_cast<const QChar *>(base);
3108     const std::less<const QChar *> less = {};
3109     return !less(ptr, start) && less(ptr, start + len);
3110 }
3111 } // end namespace
3112 
3113 /*!
3114   \internal
3115  */
replace_helper(uint * indices,int nIndices,int blen,const QChar * after,int alen)3116 void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen)
3117 {
3118     // Copy after if it lies inside our own d->data() area (which we could
3119     // possibly invalidate via a realloc or modify by replacement).
3120     QChar *afterBuffer = nullptr;
3121     if (pointsIntoRange(after, d->data(), d->size)) // Use copy in place of vulnerable original:
3122         after = afterBuffer = textCopy(after, alen);
3123 
3124     QT_TRY {
3125         if (blen == alen) {
3126             // replace in place
3127             detach();
3128             for (int i = 0; i < nIndices; ++i)
3129                 memcpy(d->data() + indices[i], after, alen * sizeof(QChar));
3130         } else if (alen < blen) {
3131             // replace from front
3132             detach();
3133             uint to = indices[0];
3134             if (alen)
3135                 memcpy(d->data()+to, after, alen*sizeof(QChar));
3136             to += alen;
3137             uint movestart = indices[0] + blen;
3138             for (int i = 1; i < nIndices; ++i) {
3139                 int msize = indices[i] - movestart;
3140                 if (msize > 0) {
3141                     memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
3142                     to += msize;
3143                 }
3144                 if (alen) {
3145                     memcpy(d->data() + to, after, alen * sizeof(QChar));
3146                     to += alen;
3147                 }
3148                 movestart = indices[i] + blen;
3149             }
3150             int msize = d->size - movestart;
3151             if (msize > 0)
3152                 memmove(d->data() + to, d->data() + movestart, msize * sizeof(QChar));
3153             resize(d->size - nIndices*(blen-alen));
3154         } else {
3155             // replace from back
3156             int adjust = nIndices*(alen-blen);
3157             int newLen = d->size + adjust;
3158             int moveend = d->size;
3159             resize(newLen);
3160 
3161             while (nIndices) {
3162                 --nIndices;
3163                 int movestart = indices[nIndices] + blen;
3164                 int insertstart = indices[nIndices] + nIndices*(alen-blen);
3165                 int moveto = insertstart + alen;
3166                 memmove(d->data() + moveto, d->data() + movestart,
3167                         (moveend - movestart)*sizeof(QChar));
3168                 memcpy(d->data() + insertstart, after, alen * sizeof(QChar));
3169                 moveend = movestart-blen;
3170             }
3171         }
3172     } QT_CATCH(const std::bad_alloc &) {
3173         ::free(afterBuffer);
3174         QT_RETHROW;
3175     }
3176     ::free(afterBuffer);
3177 }
3178 
3179 /*!
3180   \since 4.5
3181   \overload replace()
3182 
3183   Replaces each occurrence in this string of the first \a blen
3184   characters of \a before with the first \a alen characters of \a
3185   after and returns a reference to this string.
3186 
3187   If \a cs is Qt::CaseSensitive (default), the search is case
3188   sensitive; otherwise the search is case insensitive.
3189 */
replace(const QChar * before,int blen,const QChar * after,int alen,Qt::CaseSensitivity cs)3190 QString &QString::replace(const QChar *before, int blen,
3191                           const QChar *after, int alen,
3192                           Qt::CaseSensitivity cs)
3193 {
3194     if (d->size == 0) {
3195         if (blen)
3196             return *this;
3197     } else {
3198         if (cs == Qt::CaseSensitive && before == after && blen == alen)
3199             return *this;
3200     }
3201     if (alen == 0 && blen == 0)
3202         return *this;
3203 
3204     QStringMatcher matcher(before, blen, cs);
3205     QChar *beforeBuffer = nullptr, *afterBuffer = nullptr;
3206 
3207     int index = 0;
3208     while (1) {
3209         uint indices[1024];
3210         uint pos = 0;
3211         while (pos < 1024) {
3212             index = matcher.indexIn(*this, index);
3213             if (index == -1)
3214                 break;
3215             indices[pos++] = index;
3216             if (blen) // Step over before:
3217                 index += blen;
3218             else // Only count one instance of empty between any two characters:
3219                 index++;
3220         }
3221         if (!pos) // Nothing to replace
3222             break;
3223 
3224         if (Q_UNLIKELY(index != -1)) {
3225             /*
3226               We're about to change data, that before and after might point
3227               into, and we'll need that data for our next batch of indices.
3228             */
3229             if (!afterBuffer && pointsIntoRange(after, d->data(), d->size))
3230                 after = afterBuffer = textCopy(after, alen);
3231 
3232             if (!beforeBuffer && pointsIntoRange(before, d->data(), d->size)) {
3233                 beforeBuffer = textCopy(before, blen);
3234                 matcher = QStringMatcher(beforeBuffer, blen, cs);
3235             }
3236         }
3237 
3238         replace_helper(indices, pos, blen, after, alen);
3239 
3240         if (Q_LIKELY(index == -1)) // Nothing left to replace
3241             break;
3242         // The call to replace_helper just moved what index points at:
3243         index += pos*(alen-blen);
3244     }
3245     ::free(afterBuffer);
3246     ::free(beforeBuffer);
3247 
3248     return *this;
3249 }
3250 
3251 /*!
3252   \overload replace()
3253   Replaces every occurrence of the character \a ch in the string with
3254   \a after and returns a reference to this string.
3255 
3256   If \a cs is Qt::CaseSensitive (default), the search is case
3257   sensitive; otherwise the search is case insensitive.
3258 */
replace(QChar ch,const QString & after,Qt::CaseSensitivity cs)3259 QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs)
3260 {
3261     if (after.d->size == 0)
3262         return remove(ch, cs);
3263 
3264     if (after.d->size == 1)
3265         return replace(ch, after.front(), cs);
3266 
3267     if (d->size == 0)
3268         return *this;
3269 
3270     ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode());
3271 
3272     int index = 0;
3273     while (1) {
3274         uint indices[1024];
3275         uint pos = 0;
3276         if (cs == Qt::CaseSensitive) {
3277             while (pos < 1024 && index < d->size) {
3278                 if (d->data()[index] == cc)
3279                     indices[pos++] = index;
3280                 index++;
3281             }
3282         } else {
3283             while (pos < 1024 && index < d->size) {
3284                 if (QChar::toCaseFolded(d->data()[index]) == cc)
3285                     indices[pos++] = index;
3286                 index++;
3287             }
3288         }
3289         if (!pos) // Nothing to replace
3290             break;
3291 
3292         replace_helper(indices, pos, 1, after.constData(), after.d->size);
3293 
3294         if (Q_LIKELY(index == size())) // Nothing left to replace
3295             break;
3296         // The call to replace_helper just moved what index points at:
3297         index += pos*(after.d->size - 1);
3298     }
3299     return *this;
3300 }
3301 
3302 /*!
3303   \overload replace()
3304   Replaces every occurrence of the character \a before with the
3305   character \a after and returns a reference to this string.
3306 
3307   If \a cs is Qt::CaseSensitive (default), the search is case
3308   sensitive; otherwise the search is case insensitive.
3309 */
replace(QChar before,QChar after,Qt::CaseSensitivity cs)3310 QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs)
3311 {
3312     if (d->size) {
3313         const int idx = indexOf(before, 0, cs);
3314         if (idx != -1) {
3315             detach();
3316             const ushort a = after.unicode();
3317             ushort *i = d->data();
3318             const ushort *e = i + d->size;
3319             i += idx;
3320             *i = a;
3321             if (cs == Qt::CaseSensitive) {
3322                 const ushort b = before.unicode();
3323                 while (++i != e) {
3324                     if (*i == b)
3325                         *i = a;
3326                 }
3327             } else {
3328                 const ushort b = foldCase(before.unicode());
3329                 while (++i != e) {
3330                     if (foldCase(*i) == b)
3331                         *i = a;
3332                 }
3333             }
3334         }
3335     }
3336     return *this;
3337 }
3338 
3339 /*!
3340   \since 4.5
3341   \overload replace()
3342 
3343   Replaces every occurrence of the string \a before with the string \a
3344   after and returns a reference to this string.
3345 
3346   If \a cs is Qt::CaseSensitive (default), the search is case
3347   sensitive; otherwise the search is case insensitive.
3348 
3349   \note The text is not rescanned after a replacement.
3350 */
replace(QLatin1String before,QLatin1String after,Qt::CaseSensitivity cs)3351 QString &QString::replace(QLatin1String before, QLatin1String after, Qt::CaseSensitivity cs)
3352 {
3353     int alen = after.size();
3354     int blen = before.size();
3355     QVarLengthArray<ushort> a(alen);
3356     QVarLengthArray<ushort> b(blen);
3357     qt_from_latin1(a.data(), after.latin1(), alen);
3358     qt_from_latin1(b.data(), before.latin1(), blen);
3359     return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs);
3360 }
3361 
3362 /*!
3363   \since 4.5
3364   \overload replace()
3365 
3366   Replaces every occurrence of the string \a before with the string \a
3367   after and returns a reference to this string.
3368 
3369   If \a cs is Qt::CaseSensitive (default), the search is case
3370   sensitive; otherwise the search is case insensitive.
3371 
3372   \note The text is not rescanned after a replacement.
3373 */
replace(QLatin1String before,const QString & after,Qt::CaseSensitivity cs)3374 QString &QString::replace(QLatin1String before, const QString &after, Qt::CaseSensitivity cs)
3375 {
3376     int blen = before.size();
3377     QVarLengthArray<ushort> b(blen);
3378     qt_from_latin1(b.data(), before.latin1(), blen);
3379     return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs);
3380 }
3381 
3382 /*!
3383   \since 4.5
3384   \overload replace()
3385 
3386   Replaces every occurrence of the string \a before with the string \a
3387   after and returns a reference to this string.
3388 
3389   If \a cs is Qt::CaseSensitive (default), the search is case
3390   sensitive; otherwise the search is case insensitive.
3391 
3392   \note The text is not rescanned after a replacement.
3393 */
replace(const QString & before,QLatin1String after,Qt::CaseSensitivity cs)3394 QString &QString::replace(const QString &before, QLatin1String after, Qt::CaseSensitivity cs)
3395 {
3396     int alen = after.size();
3397     QVarLengthArray<ushort> a(alen);
3398     qt_from_latin1(a.data(), after.latin1(), alen);
3399     return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs);
3400 }
3401 
3402 /*!
3403   \since 4.5
3404   \overload replace()
3405 
3406   Replaces every occurrence of the character \a c with the string \a
3407   after and returns a reference to this string.
3408 
3409   If \a cs is Qt::CaseSensitive (default), the search is case
3410   sensitive; otherwise the search is case insensitive.
3411 
3412   \note The text is not rescanned after a replacement.
3413 */
replace(QChar c,QLatin1String after,Qt::CaseSensitivity cs)3414 QString &QString::replace(QChar c, QLatin1String after, Qt::CaseSensitivity cs)
3415 {
3416     int alen = after.size();
3417     QVarLengthArray<ushort> a(alen);
3418     qt_from_latin1(a.data(), after.latin1(), alen);
3419     return replace(&c, 1, (const QChar *)a.data(), alen, cs);
3420 }
3421 
3422 
3423 /*!
3424   \relates QString
3425   Returns \c true if string \a s1 is equal to string \a s2; otherwise
3426   returns \c false.
3427 
3428   \sa {Comparing Strings}
3429 */
operator ==(const QString & s1,const QString & s2)3430 bool operator==(const QString &s1, const QString &s2) noexcept
3431 {
3432     if (s1.d->size != s2.d->size)
3433         return false;
3434 
3435     return qt_compare_strings(s1, s2, Qt::CaseSensitive) == 0;
3436 }
3437 
3438 /*!
3439     \overload operator==()
3440     Returns \c true if this string is equal to \a other; otherwise
3441     returns \c false.
3442 */
operator ==(QLatin1String other) const3443 bool QString::operator==(QLatin1String other) const noexcept
3444 {
3445     if (d->size != other.size())
3446         return false;
3447 
3448     return qt_compare_strings(*this, other, Qt::CaseSensitive) == 0;
3449 }
3450 
3451 /*! \fn bool QString::operator==(const QByteArray &other) const
3452 
3453     \overload operator==()
3454 
3455     The \a other byte array is converted to a QString using the
3456     fromUtf8() function. This function stops conversion at the
3457     first NUL character found, or the end of the byte array.
3458 
3459     You can disable this operator by defining \c
3460     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3461     can be useful if you want to ensure that all user-visible strings
3462     go through QObject::tr(), for example.
3463 
3464     Returns \c true if this string is lexically equal to the parameter
3465     string \a other. Otherwise returns \c false.
3466 
3467     \sa QT_NO_CAST_FROM_ASCII
3468 */
3469 
3470 /*! \fn bool QString::operator==(const char *other) const
3471 
3472     \overload operator==()
3473 
3474     The \a other const char pointer is converted to a QString using
3475     the fromUtf8() function.
3476 
3477     You can disable this operator by defining \c
3478     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3479     can be useful if you want to ensure that all user-visible strings
3480     go through QObject::tr(), for example.
3481 
3482     \sa QT_NO_CAST_FROM_ASCII
3483 */
3484 
3485 /*!
3486    \relates QString
3487     Returns \c true if string \a s1 is lexically less than string
3488     \a s2; otherwise returns \c false.
3489 
3490     \sa {Comparing Strings}
3491 */
operator <(const QString & s1,const QString & s2)3492 bool operator<(const QString &s1, const QString &s2) noexcept
3493 {
3494     return qt_compare_strings(s1, s2, Qt::CaseSensitive) < 0;
3495 }
3496 
3497 /*!
3498    \overload operator<()
3499 
3500     Returns \c true if this string is lexically less than the parameter
3501     string called \a other; otherwise returns \c false.
3502 */
operator <(QLatin1String other) const3503 bool QString::operator<(QLatin1String other) const noexcept
3504 {
3505     return qt_compare_strings(*this, other, Qt::CaseSensitive) < 0;
3506 }
3507 
3508 /*! \fn bool QString::operator<(const QByteArray &other) const
3509 
3510     \overload operator<()
3511 
3512     The \a other byte array is converted to a QString using the
3513     fromUtf8() function. If any NUL characters ('\\0') are embedded
3514     in the byte array, they will be included in the transformation.
3515 
3516     You can disable this operator by defining \c
3517     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3518     can be useful if you want to ensure that all user-visible strings
3519     go through QObject::tr(), for example.
3520 
3521     \sa QT_NO_CAST_FROM_ASCII
3522 */
3523 
3524 /*! \fn bool QString::operator<(const char *other) const
3525 
3526     Returns \c true if this string is lexically less than string \a other.
3527     Otherwise returns \c false.
3528 
3529     \overload operator<()
3530 
3531     The \a other const char pointer is converted to a QString using
3532     the fromUtf8() function.
3533 
3534     You can disable this operator by defining \c
3535     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3536     can be useful if you want to ensure that all user-visible strings
3537     go through QObject::tr(), for example.
3538 
3539     \sa QT_NO_CAST_FROM_ASCII
3540 */
3541 
3542 /*! \fn bool operator<=(const QString &s1, const QString &s2)
3543 
3544     \relates QString
3545 
3546     Returns \c true if string \a s1 is lexically less than or equal to
3547     string \a s2; otherwise returns \c false.
3548 
3549     \sa {Comparing Strings}
3550 */
3551 
3552 /*! \fn bool QString::operator<=(QLatin1String other) const
3553 
3554     Returns \c true if this string is lexically less than or equal to
3555     parameter string \a other. Otherwise returns \c false.
3556 
3557     \overload operator<=()
3558 */
3559 
3560 /*! \fn bool QString::operator<=(const QByteArray &other) const
3561 
3562     \overload operator<=()
3563 
3564     The \a other byte array is converted to a QString using the
3565     fromUtf8() function. If any NUL characters ('\\0') are embedded
3566     in the byte array, they will be included in the transformation.
3567 
3568     You can disable this operator by defining \c
3569     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3570     can be useful if you want to ensure that all user-visible strings
3571     go through QObject::tr(), for example.
3572 
3573     \sa QT_NO_CAST_FROM_ASCII
3574 */
3575 
3576 /*! \fn bool QString::operator<=(const char *other) const
3577 
3578     \overload operator<=()
3579 
3580     The \a other const char pointer is converted to a QString using
3581     the fromUtf8() function.
3582 
3583     You can disable this operator by defining \c
3584     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3585     can be useful if you want to ensure that all user-visible strings
3586     go through QObject::tr(), for example.
3587 
3588     \sa QT_NO_CAST_FROM_ASCII
3589 */
3590 
3591 /*! \fn bool operator>(const QString &s1, const QString &s2)
3592     \relates QString
3593 
3594     Returns \c true if string \a s1 is lexically greater than string \a s2;
3595     otherwise returns \c false.
3596 
3597     \sa {Comparing Strings}
3598 */
3599 
3600 /*!
3601    \overload operator>()
3602 
3603     Returns \c true if this string is lexically greater than the parameter
3604     string \a other; otherwise returns \c false.
3605 */
operator >(QLatin1String other) const3606 bool QString::operator>(QLatin1String other) const noexcept
3607 {
3608     return qt_compare_strings(*this, other, Qt::CaseSensitive) > 0;
3609 }
3610 
3611 /*! \fn bool QString::operator>(const QByteArray &other) const
3612 
3613     \overload operator>()
3614 
3615     The \a other byte array is converted to a QString using the
3616     fromUtf8() function. If any NUL characters ('\\0') are embedded
3617     in the byte array, they will be included in the transformation.
3618 
3619     You can disable this operator by defining \c
3620     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3621     can be useful if you want to ensure that all user-visible strings
3622     go through QObject::tr(), for example.
3623 
3624     \sa QT_NO_CAST_FROM_ASCII
3625 */
3626 
3627 /*! \fn bool QString::operator>(const char *other) const
3628 
3629     \overload operator>()
3630 
3631     The \a other const char pointer is converted to a QString using
3632     the fromUtf8() function.
3633 
3634     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
3635     when you compile your applications. This can be useful if you want
3636     to ensure that all user-visible strings go through QObject::tr(),
3637     for example.
3638 
3639     \sa QT_NO_CAST_FROM_ASCII
3640 */
3641 
3642 /*! \fn bool operator>=(const QString &s1, const QString &s2)
3643     \relates QString
3644 
3645     Returns \c true if string \a s1 is lexically greater than or equal to
3646     string \a s2; otherwise returns \c false.
3647 
3648     \sa {Comparing Strings}
3649 */
3650 
3651 /*! \fn bool QString::operator>=(QLatin1String other) const
3652 
3653     Returns \c true if this string is lexically greater than or equal to parameter
3654     string \a other. Otherwise returns \c false.
3655 
3656     \overload operator>=()
3657 */
3658 
3659 /*! \fn bool QString::operator>=(const QByteArray &other) const
3660 
3661     \overload operator>=()
3662 
3663     The \a other byte array is converted to a QString using the
3664     fromUtf8() function. If any NUL characters ('\\0') are embedded in
3665     the byte array, they will be included in the transformation.
3666 
3667     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
3668     when you compile your applications. This can be useful if you want
3669     to ensure that all user-visible strings go through QObject::tr(),
3670     for example.
3671 
3672     \sa QT_NO_CAST_FROM_ASCII
3673 */
3674 
3675 /*! \fn bool QString::operator>=(const char *other) const
3676 
3677     \overload operator>=()
3678 
3679     The \a other const char pointer is converted to a QString using
3680     the fromUtf8() function.
3681 
3682     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
3683     when you compile your applications. This can be useful if you want
3684     to ensure that all user-visible strings go through QObject::tr(),
3685     for example.
3686 
3687     \sa QT_NO_CAST_FROM_ASCII
3688 */
3689 
3690 /*! \fn bool operator!=(const QString &s1, const QString &s2)
3691     \relates QString
3692 
3693     Returns \c true if string \a s1 is not equal to string \a s2;
3694     otherwise returns \c false.
3695 
3696     \sa {Comparing Strings}
3697 */
3698 
3699 /*! \fn bool QString::operator!=(QLatin1String other) const
3700 
3701     Returns \c true if this string is not equal to parameter string \a other.
3702     Otherwise returns \c false.
3703 
3704     \overload operator!=()
3705 */
3706 
3707 /*! \fn bool QString::operator!=(const QByteArray &other) const
3708 
3709     \overload operator!=()
3710 
3711     The \a other byte array is converted to a QString using the
3712     fromUtf8() function. If any NUL characters ('\\0') are embedded
3713     in the byte array, they will be included in the transformation.
3714 
3715     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
3716     when you compile your applications. This can be useful if you want
3717     to ensure that all user-visible strings go through QObject::tr(),
3718     for example.
3719 
3720     \sa QT_NO_CAST_FROM_ASCII
3721 */
3722 
3723 /*! \fn bool QString::operator!=(const char *other) const
3724 
3725     \overload operator!=()
3726 
3727     The \a other const char pointer is converted to a QString using
3728     the fromUtf8() function.
3729 
3730     You can disable this operator by defining \c
3731     QT_NO_CAST_FROM_ASCII when you compile your applications. This
3732     can be useful if you want to ensure that all user-visible strings
3733     go through QObject::tr(), for example.
3734 
3735     \sa QT_NO_CAST_FROM_ASCII
3736 */
3737 
3738 #if QT_STRINGVIEW_LEVEL < 2
3739 /*!
3740   Returns the index position of the first occurrence of the string \a
3741   str in this string, searching forward from index position \a
3742   from. Returns -1 if \a str is not found.
3743 
3744   If \a cs is Qt::CaseSensitive (default), the search is case
3745   sensitive; otherwise the search is case insensitive.
3746 
3747   Example:
3748 
3749   \snippet qstring/main.cpp 24
3750 
3751   If \a from is -1, the search starts at the last character; if it is
3752   -2, at the next to last character and so on.
3753 
3754   \sa lastIndexOf(), contains(), count()
3755 */
indexOf(const QString & str,int from,Qt::CaseSensitivity cs) const3756 int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
3757 {
3758     // ### Qt6: qsizetype
3759     return int(QtPrivate::findString(QStringView(unicode(), length()), from, QStringView(str.unicode(), str.length()), cs));
3760 }
3761 #endif  // QT_STRINGVIEW_LEVEL < 2
3762 
3763 /*!
3764     \fn int QString::indexOf(QStringView str, int from, Qt::CaseSensitivity cs) const
3765     \since 5.14
3766     \overload indexOf()
3767 
3768     Returns the index position of the first occurrence of the string view \a str
3769     in this string, searching forward from index position \a from.
3770     Returns -1 if \a str is not found.
3771 
3772     If \a cs is Qt::CaseSensitive (default), the search is case
3773     sensitive; otherwise the search is case insensitive.
3774 
3775     If \a from is -1, the search starts at the last character; if it is
3776     -2, at the next to last character and so on.
3777 
3778     \sa QStringView::indexOf(), lastIndexOf(), contains(), count()
3779 */
3780 
3781 /*!
3782   \since 4.5
3783   Returns the index position of the first occurrence of the string \a
3784   str in this string, searching forward from index position \a
3785   from. Returns -1 if \a str is not found.
3786 
3787   If \a cs is Qt::CaseSensitive (default), the search is case
3788   sensitive; otherwise the search is case insensitive.
3789 
3790   Example:
3791 
3792   \snippet qstring/main.cpp 24
3793 
3794   If \a from is -1, the search starts at the last character; if it is
3795   -2, at the next to last character and so on.
3796 
3797   \sa lastIndexOf(), contains(), count()
3798 */
3799 
indexOf(QLatin1String str,int from,Qt::CaseSensitivity cs) const3800 int QString::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
3801 {
3802     // ### Qt6: qsizetype
3803     return int(QtPrivate::findString(QStringView(unicode(), size()), from, str, cs));
3804 }
3805 
3806 /*!
3807     \overload indexOf()
3808 
3809     Returns the index position of the first occurrence of the
3810     character \a ch in the string, searching forward from index
3811     position \a from. Returns -1 if \a ch could not be found.
3812 */
indexOf(QChar ch,int from,Qt::CaseSensitivity cs) const3813 int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
3814 {
3815     // ### Qt6: qsizetype
3816     return int(qFindChar(QStringView(unicode(), length()), ch, from, cs));
3817 }
3818 
3819 #if QT_STRINGVIEW_LEVEL < 2
3820 /*!
3821     \since 4.8
3822 
3823     \overload indexOf()
3824 
3825     Returns the index position of the first occurrence of the string
3826     reference \a str in this string, searching forward from index
3827     position \a from. Returns -1 if \a str is not found.
3828 
3829     If \a cs is Qt::CaseSensitive (default), the search is case
3830     sensitive; otherwise the search is case insensitive.
3831 */
indexOf(const QStringRef & str,int from,Qt::CaseSensitivity cs) const3832 int QString::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
3833 {
3834     // ### Qt6: qsizetype
3835     return int(QtPrivate::findString(QStringView(unicode(), length()), from, QStringView(str.unicode(), str.length()), cs));
3836 }
3837 
3838 /*!
3839   Returns the index position of the last occurrence of the string \a
3840   str in this string, searching backward from index position \a
3841   from. If \a from is -1 (default), the search starts at the last
3842   character; if \a from is -2, at the next to last character and so
3843   on. Returns -1 if \a str is not found.
3844 
3845   If \a cs is Qt::CaseSensitive (default), the search is case
3846   sensitive; otherwise the search is case insensitive.
3847 
3848   Example:
3849 
3850   \snippet qstring/main.cpp 29
3851 
3852   \sa indexOf(), contains(), count()
3853 */
lastIndexOf(const QString & str,int from,Qt::CaseSensitivity cs) const3854 int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
3855 {
3856     // ### Qt6: qsizetype
3857     return int(QtPrivate::lastIndexOf(QStringView(*this), from, str, cs));
3858 }
3859 
3860 #endif // QT_STRINGVIEW_LEVEL < 2
3861 
3862 /*!
3863   \since 4.5
3864   \overload lastIndexOf()
3865 
3866   Returns the index position of the last occurrence of the string \a
3867   str in this string, searching backward from index position \a
3868   from. If \a from is -1 (default), the search starts at the last
3869   character; if \a from is -2, at the next to last character and so
3870   on. Returns -1 if \a str is not found.
3871 
3872   If \a cs is Qt::CaseSensitive (default), the search is case
3873   sensitive; otherwise the search is case insensitive.
3874 
3875   Example:
3876 
3877   \snippet qstring/main.cpp 29
3878 
3879   \sa indexOf(), contains(), count()
3880 */
lastIndexOf(QLatin1String str,int from,Qt::CaseSensitivity cs) const3881 int QString::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
3882 {
3883     // ### Qt6: qsizetype
3884     return int(QtPrivate::lastIndexOf(*this, from, str, cs));
3885 }
3886 
3887 /*!
3888   \overload lastIndexOf()
3889 
3890   Returns the index position of the last occurrence of the character
3891   \a ch, searching backward from position \a from.
3892 */
lastIndexOf(QChar ch,int from,Qt::CaseSensitivity cs) const3893 int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
3894 {
3895     // ### Qt6: qsizetype
3896     return int(qLastIndexOf(QStringView(*this), ch, from, cs));
3897 }
3898 
3899 #if QT_STRINGVIEW_LEVEL < 2
3900 /*!
3901   \since 4.8
3902   \overload lastIndexOf()
3903 
3904   Returns the index position of the last occurrence of the string
3905   reference \a str in this string, searching backward from index
3906   position \a from. If \a from is -1 (default), the search starts at
3907   the last character; if \a from is -2, at the next to last character
3908   and so on. Returns -1 if \a str is not found.
3909 
3910   If \a cs is Qt::CaseSensitive (default), the search is case
3911   sensitive; otherwise the search is case insensitive.
3912 
3913   \sa indexOf(), contains(), count()
3914 */
lastIndexOf(const QStringRef & str,int from,Qt::CaseSensitivity cs) const3915 int QString::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
3916 {
3917     // ### Qt6: qsizetype
3918     return int(QtPrivate::lastIndexOf(*this, from, str, cs));
3919 }
3920 #endif // QT_STRINGVIEW_LEVEL < 2
3921 
3922 /*!
3923   \fn int QString::lastIndexOf(QStringView str, int from, Qt::CaseSensitivity cs) const
3924   \since 5.14
3925   \overload lastIndexOf()
3926 
3927   Returns the index position of the last occurrence of the string view \a
3928   str in this string, searching backward from index position \a
3929   from. If \a from is -1 (default), the search starts at the last
3930   character; if \a from is -2, at the next to last character and so
3931   on. Returns -1 if \a str is not found.
3932 
3933   If \a cs is Qt::CaseSensitive (default), the search is case
3934   sensitive; otherwise the search is case insensitive.
3935 
3936   \sa indexOf(), contains(), count()
3937 */
3938 
3939 
3940 #if !(defined(QT_NO_REGEXP) && !QT_CONFIG(regularexpression))
3941 struct QStringCapture
3942 {
3943     int pos;
3944     int len;
3945     int no;
3946 };
3947 Q_DECLARE_TYPEINFO(QStringCapture, Q_PRIMITIVE_TYPE);
3948 #endif
3949 
3950 #ifndef QT_NO_REGEXP
3951 
3952 /*!
3953   \overload replace()
3954 
3955   Replaces every occurrence of the regular expression \a rx in the
3956   string with \a after. Returns a reference to the string. For
3957   example:
3958 
3959   \snippet qstring/main.cpp 42
3960 
3961   For regular expressions containing \l{capturing parentheses},
3962   occurrences of \b{\\1}, \b{\\2}, ..., in \a after are replaced
3963   with \a{rx}.cap(1), cap(2), ...
3964 
3965   \snippet qstring/main.cpp 43
3966 
3967   \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap()
3968 */
replace(const QRegExp & rx,const QString & after)3969 QString& QString::replace(const QRegExp &rx, const QString &after)
3970 {
3971     QRegExp rx2(rx);
3972 
3973     if (isEmpty() && rx2.indexIn(*this) == -1)
3974         return *this;
3975 
3976     reallocData(uint(d->size) + 1u);
3977 
3978     int index = 0;
3979     int numCaptures = rx2.captureCount();
3980     int al = after.length();
3981     QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
3982 
3983     if (numCaptures > 0) {
3984         const QChar *uc = after.unicode();
3985         int numBackRefs = 0;
3986 
3987         for (int i = 0; i < al - 1; i++) {
3988             if (uc[i] == QLatin1Char('\\')) {
3989                 int no = uc[i + 1].digitValue();
3990                 if (no > 0 && no <= numCaptures)
3991                     numBackRefs++;
3992             }
3993         }
3994 
3995         /*
3996             This is the harder case where we have back-references.
3997         */
3998         if (numBackRefs > 0) {
3999             QVarLengthArray<QStringCapture, 16> captures(numBackRefs);
4000             int j = 0;
4001 
4002             for (int i = 0; i < al - 1; i++) {
4003                 if (uc[i] == QLatin1Char('\\')) {
4004                     int no = uc[i + 1].digitValue();
4005                     if (no > 0 && no <= numCaptures) {
4006                         QStringCapture capture;
4007                         capture.pos = i;
4008                         capture.len = 2;
4009 
4010                         if (i < al - 2) {
4011                             int secondDigit = uc[i + 2].digitValue();
4012                             if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
4013                                 no = (no * 10) + secondDigit;
4014                                 ++capture.len;
4015                             }
4016                         }
4017 
4018                         capture.no = no;
4019                         captures[j++] = capture;
4020                     }
4021                 }
4022             }
4023 
4024             while (index <= length()) {
4025                 index = rx2.indexIn(*this, index, caretMode);
4026                 if (index == -1)
4027                     break;
4028 
4029                 QString after2(after);
4030                 for (j = numBackRefs - 1; j >= 0; j--) {
4031                     const QStringCapture &capture = captures[j];
4032                     after2.replace(capture.pos, capture.len, rx2.cap(capture.no));
4033                 }
4034 
4035                 replace(index, rx2.matchedLength(), after2);
4036                 index += after2.length();
4037 
4038                 // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*"))
4039                 if (rx2.matchedLength() == 0)
4040                     ++index;
4041 
4042                 caretMode = QRegExp::CaretWontMatch;
4043             }
4044             return *this;
4045         }
4046     }
4047 
4048     /*
4049         This is the simple and optimized case where we don't have
4050         back-references.
4051     */
4052     while (index != -1) {
4053         struct {
4054             int pos;
4055             int length;
4056         } replacements[2048];
4057 
4058         int pos = 0;
4059         int adjust = 0;
4060         while (pos < 2047) {
4061             index = rx2.indexIn(*this, index, caretMode);
4062             if (index == -1)
4063                 break;
4064             int ml = rx2.matchedLength();
4065             replacements[pos].pos = index;
4066             replacements[pos++].length = ml;
4067             index += ml;
4068             adjust += al - ml;
4069             // avoid infinite loop
4070             if (!ml)
4071                 index++;
4072         }
4073         if (!pos)
4074             break;
4075         replacements[pos].pos = d->size;
4076         int newlen = d->size + adjust;
4077 
4078         // to continue searching at the right position after we did
4079         // the first round of replacements
4080         if (index != -1)
4081             index += adjust;
4082         QString newstring;
4083         newstring.reserve(newlen + 1);
4084         QChar *newuc = newstring.data();
4085         QChar *uc = newuc;
4086         int copystart = 0;
4087         int i = 0;
4088         while (i < pos) {
4089             int copyend = replacements[i].pos;
4090             int size = copyend - copystart;
4091             memcpy(static_cast<void*>(uc), static_cast<const void *>(d->data() + copystart), size * sizeof(QChar));
4092             uc += size;
4093             memcpy(static_cast<void *>(uc), static_cast<const void *>(after.d->data()), al * sizeof(QChar));
4094             uc += al;
4095             copystart = copyend + replacements[i].length;
4096             i++;
4097         }
4098         memcpy(static_cast<void *>(uc), static_cast<const void *>(d->data() + copystart), (d->size - copystart) * sizeof(QChar));
4099         newstring.resize(newlen);
4100         *this = newstring;
4101         caretMode = QRegExp::CaretWontMatch;
4102     }
4103     return *this;
4104 }
4105 #endif
4106 
4107 #if QT_CONFIG(regularexpression)
4108 /*!
4109   \overload replace()
4110   \since 5.0
4111 
4112   Replaces every occurrence of the regular expression \a re in the
4113   string with \a after. Returns a reference to the string. For
4114   example:
4115 
4116   \snippet qstring/main.cpp 87
4117 
4118   For regular expressions containing capturing groups,
4119   occurrences of \b{\\1}, \b{\\2}, ..., in \a after are replaced
4120   with the string captured by the corresponding capturing group.
4121 
4122   \snippet qstring/main.cpp 88
4123 
4124   \sa indexOf(), lastIndexOf(), remove(), QRegularExpression, QRegularExpressionMatch
4125 */
replace(const QRegularExpression & re,const QString & after)4126 QString &QString::replace(const QRegularExpression &re, const QString &after)
4127 {
4128     if (!re.isValid()) {
4129         qWarning("QString::replace: invalid QRegularExpression object");
4130         return *this;
4131     }
4132 
4133     const QString copy(*this);
4134     QRegularExpressionMatchIterator iterator = re.globalMatch(copy);
4135     if (!iterator.hasNext()) // no matches at all
4136         return *this;
4137 
4138     reallocData(uint(d->size) + 1u);
4139 
4140     int numCaptures = re.captureCount();
4141 
4142     // 1. build the backreferences vector, holding where the backreferences
4143     // are in the replacement string
4144     QVector<QStringCapture> backReferences;
4145     const int al = after.length();
4146     const QChar *ac = after.unicode();
4147 
4148     for (int i = 0; i < al - 1; i++) {
4149         if (ac[i] == QLatin1Char('\\')) {
4150             int no = ac[i + 1].digitValue();
4151             if (no > 0 && no <= numCaptures) {
4152                 QStringCapture backReference;
4153                 backReference.pos = i;
4154                 backReference.len = 2;
4155 
4156                 if (i < al - 2) {
4157                     int secondDigit = ac[i + 2].digitValue();
4158                     if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) {
4159                         no = (no * 10) + secondDigit;
4160                         ++backReference.len;
4161                     }
4162                 }
4163 
4164                 backReference.no = no;
4165                 backReferences.append(backReference);
4166             }
4167         }
4168     }
4169 
4170     // 2. iterate on the matches. For every match, copy in chunks
4171     // - the part before the match
4172     // - the after string, with the proper replacements for the backreferences
4173 
4174     int newLength = 0; // length of the new string, with all the replacements
4175     int lastEnd = 0;
4176     QVector<QStringRef> chunks;
4177     while (iterator.hasNext()) {
4178         QRegularExpressionMatch match = iterator.next();
4179         int len;
4180         // add the part before the match
4181         len = match.capturedStart() - lastEnd;
4182         if (len > 0) {
4183             chunks << copy.midRef(lastEnd, len);
4184             newLength += len;
4185         }
4186 
4187         lastEnd = 0;
4188         // add the after string, with replacements for the backreferences
4189         for (const QStringCapture &backReference : qAsConst(backReferences)) {
4190             // part of "after" before the backreference
4191             len = backReference.pos - lastEnd;
4192             if (len > 0) {
4193                 chunks << after.midRef(lastEnd, len);
4194                 newLength += len;
4195             }
4196 
4197             // backreference itself
4198             len = match.capturedLength(backReference.no);
4199             if (len > 0) {
4200                 chunks << copy.midRef(match.capturedStart(backReference.no), len);
4201                 newLength += len;
4202             }
4203 
4204             lastEnd = backReference.pos + backReference.len;
4205         }
4206 
4207         // add the last part of the after string
4208         len = after.length() - lastEnd;
4209         if (len > 0) {
4210             chunks << after.midRef(lastEnd, len);
4211             newLength += len;
4212         }
4213 
4214         lastEnd = match.capturedEnd();
4215     }
4216 
4217     // 3. trailing string after the last match
4218     if (copy.length() > lastEnd) {
4219         chunks << copy.midRef(lastEnd);
4220         newLength += copy.length() - lastEnd;
4221     }
4222 
4223     // 4. assemble the chunks together
4224     resize(newLength);
4225     int i = 0;
4226     QChar *uc = data();
4227     for (const QStringRef &chunk : qAsConst(chunks)) {
4228         int len = chunk.length();
4229         memcpy(uc + i, chunk.unicode(), len * sizeof(QChar));
4230         i += len;
4231     }
4232 
4233     return *this;
4234 }
4235 #endif // QT_CONFIG(regularexpression)
4236 
4237 /*!
4238     Returns the number of (potentially overlapping) occurrences of
4239     the string \a str in this string.
4240 
4241     If \a cs is Qt::CaseSensitive (default), the search is
4242     case sensitive; otherwise the search is case insensitive.
4243 
4244     \sa contains(), indexOf()
4245 */
4246 
count(const QString & str,Qt::CaseSensitivity cs) const4247 int QString::count(const QString &str, Qt::CaseSensitivity cs) const
4248 {
4249     // ### Qt6: qsizetype
4250     return int(qt_string_count(QStringView(unicode(), size()), QStringView(str.unicode(), str.size()), cs));
4251 }
4252 
4253 /*!
4254     \overload count()
4255 
4256     Returns the number of occurrences of character \a ch in the string.
4257 
4258     If \a cs is Qt::CaseSensitive (default), the search is
4259     case sensitive; otherwise the search is case insensitive.
4260 
4261     \sa contains(), indexOf()
4262 */
4263 
count(QChar ch,Qt::CaseSensitivity cs) const4264 int QString::count(QChar ch, Qt::CaseSensitivity cs) const
4265 {
4266     // ### Qt6: qsizetype
4267     return int(qt_string_count(QStringView(unicode(), size()), ch, cs));
4268 }
4269 
4270 /*!
4271     \since 4.8
4272     \overload count()
4273     Returns the number of (potentially overlapping) occurrences of the
4274     string reference \a str in this string.
4275 
4276     If \a cs is Qt::CaseSensitive (default), the search is
4277     case sensitive; otherwise the search is case insensitive.
4278 
4279     \sa contains(), indexOf()
4280 */
count(const QStringRef & str,Qt::CaseSensitivity cs) const4281 int QString::count(const QStringRef &str, Qt::CaseSensitivity cs) const
4282 {
4283     // ### Qt6: qsizetype
4284     return int(qt_string_count(QStringView(unicode(), size()), QStringView(str.unicode(), str.size()), cs));
4285 }
4286 
4287 #if QT_STRINGVIEW_LEVEL < 2
4288 /*! \fn bool QString::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4289 
4290     Returns \c true if this string contains an occurrence of the string
4291     \a str; otherwise returns \c false.
4292 
4293     If \a cs is Qt::CaseSensitive (default), the search is
4294     case sensitive; otherwise the search is case insensitive.
4295 
4296     Example:
4297     \snippet qstring/main.cpp 17
4298 
4299     \sa indexOf(), count()
4300 */
4301 #endif // QT_STRINGVIEW_LEVEL < 2
4302 
4303 /*! \fn bool QString::contains(QLatin1String str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4304     \since 5.3
4305 
4306     \overload contains()
4307 
4308     Returns \c true if this string contains an occurrence of the latin-1 string
4309     \a str; otherwise returns \c false.
4310 */
4311 
4312 /*! \fn bool QString::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4313 
4314     \overload contains()
4315 
4316     Returns \c true if this string contains an occurrence of the
4317     character \a ch; otherwise returns \c false.
4318 */
4319 
4320 #if QT_STRINGVIEW_LEVEL < 2
4321 /*! \fn bool QString::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4322     \since 4.8
4323 
4324     Returns \c true if this string contains an occurrence of the string
4325     reference \a str; otherwise returns \c false.
4326 
4327     If \a cs is Qt::CaseSensitive (default), the search is
4328     case sensitive; otherwise the search is case insensitive.
4329 
4330     \sa indexOf(), count()
4331 */
4332 #endif // QT_STRINGVIEW_LEVEL < 2
4333 
4334 /*! \fn bool QString::contains(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
4335     \since 5.14
4336     \overload contains()
4337 
4338     Returns \c true if this string contains an occurrence of the string view
4339     \a str; otherwise returns \c false.
4340 
4341     If \a cs is Qt::CaseSensitive (default), the search is
4342     case sensitive; otherwise the search is case insensitive.
4343 
4344     \sa indexOf(), count()
4345 */
4346 
4347 /*! \fn bool QString::contains(const QRegExp &rx) const
4348 
4349     \overload contains()
4350 
4351     Returns \c true if the regular expression \a rx matches somewhere in
4352     this string; otherwise returns \c false.
4353 */
4354 
4355 /*! \fn bool QString::contains(QRegExp &rx) const
4356     \overload contains()
4357     \since 4.5
4358 
4359     Returns \c true if the regular expression \a rx matches somewhere in
4360     this string; otherwise returns \c false.
4361 
4362     If there is a match, the \a rx regular expression will contain the
4363     matched captures (see QRegExp::matchedLength, QRegExp::cap).
4364 */
4365 
4366 #ifndef QT_NO_REGEXP
4367 /*!
4368     \overload indexOf()
4369 
4370     Returns the index position of the first match of the regular
4371     expression \a rx in the string, searching forward from index
4372     position \a from. Returns -1 if \a rx didn't match anywhere.
4373 
4374     Example:
4375 
4376     \snippet qstring/main.cpp 25
4377 */
indexOf(const QRegExp & rx,int from) const4378 int QString::indexOf(const QRegExp& rx, int from) const
4379 {
4380     QRegExp rx2(rx);
4381     return rx2.indexIn(*this, from);
4382 }
4383 
4384 /*!
4385     \overload indexOf()
4386     \since 4.5
4387 
4388     Returns the index position of the first match of the regular
4389     expression \a rx in the string, searching forward from index
4390     position \a from. Returns -1 if \a rx didn't match anywhere.
4391 
4392     If there is a match, the \a rx regular expression will contain the
4393     matched captures (see QRegExp::matchedLength, QRegExp::cap).
4394 
4395     Example:
4396 
4397     \snippet qstring/main.cpp 25
4398 */
indexOf(QRegExp & rx,int from) const4399 int QString::indexOf(QRegExp& rx, int from) const
4400 {
4401     return rx.indexIn(*this, from);
4402 }
4403 
4404 /*!
4405     \overload lastIndexOf()
4406 
4407     Returns the index position of the last match of the regular
4408     expression \a rx in the string, searching backward from index
4409     position \a from. Returns -1 if \a rx didn't match anywhere.
4410 
4411     Example:
4412 
4413     \snippet qstring/main.cpp 30
4414 */
lastIndexOf(const QRegExp & rx,int from) const4415 int QString::lastIndexOf(const QRegExp& rx, int from) const
4416 {
4417     QRegExp rx2(rx);
4418     return rx2.lastIndexIn(*this, from);
4419 }
4420 
4421 /*!
4422     \overload lastIndexOf()
4423     \since 4.5
4424 
4425     Returns the index position of the last match of the regular
4426     expression \a rx in the string, searching backward from index
4427     position \a from. Returns -1 if \a rx didn't match anywhere.
4428 
4429     If there is a match, the \a rx regular expression will contain the
4430     matched captures (see QRegExp::matchedLength, QRegExp::cap).
4431 
4432     Example:
4433 
4434     \snippet qstring/main.cpp 30
4435 */
lastIndexOf(QRegExp & rx,int from) const4436 int QString::lastIndexOf(QRegExp& rx, int from) const
4437 {
4438     return rx.lastIndexIn(*this, from);
4439 }
4440 
4441 /*!
4442     \overload count()
4443 
4444     Returns the number of times the regular expression \a rx matches
4445     in the string.
4446 
4447     This function counts overlapping matches, so in the example
4448     below, there are four instances of "ana" or "ama":
4449 
4450     \snippet qstring/main.cpp 18
4451 
4452 */
count(const QRegExp & rx) const4453 int QString::count(const QRegExp& rx) const
4454 {
4455     QRegExp rx2(rx);
4456     int count = 0;
4457     int index = -1;
4458     int len = length();
4459     while (index < len - 1) {                 // count overlapping matches
4460         index = rx2.indexIn(*this, index + 1);
4461         if (index == -1)
4462             break;
4463         count++;
4464     }
4465     return count;
4466 }
4467 #endif // QT_NO_REGEXP
4468 
4469 #if QT_CONFIG(regularexpression)
4470 /*!
4471     \overload indexOf()
4472     \since 5.0
4473 
4474     Returns the index position of the first match of the regular
4475     expression \a re in the string, searching forward from index
4476     position \a from. Returns -1 if \a re didn't match anywhere.
4477 
4478     Example:
4479 
4480     \snippet qstring/main.cpp 93
4481 */
indexOf(const QRegularExpression & re,int from) const4482 int QString::indexOf(const QRegularExpression& re, int from) const
4483 {
4484     return indexOf(re, from, nullptr);
4485 }
4486 
4487 /*!
4488     \overload
4489     \since 5.5
4490 
4491     Returns the index position of the first match of the regular
4492     expression \a re in the string, searching forward from index
4493     position \a from. Returns -1 if \a re didn't match anywhere.
4494 
4495     If the match is successful and \a rmatch is not \nullptr, it also
4496     writes the results of the match into the QRegularExpressionMatch object
4497     pointed to by \a rmatch.
4498 
4499     Example:
4500 
4501     \snippet qstring/main.cpp 99
4502 */
indexOf(const QRegularExpression & re,int from,QRegularExpressionMatch * rmatch) const4503 int QString::indexOf(const QRegularExpression &re, int from, QRegularExpressionMatch *rmatch) const
4504 {
4505     if (!re.isValid()) {
4506         qWarning("QString::indexOf: invalid QRegularExpression object");
4507         return -1;
4508     }
4509 
4510     QRegularExpressionMatch match = re.match(*this, from);
4511     if (match.hasMatch()) {
4512         const int ret = match.capturedStart();
4513         if (rmatch)
4514             *rmatch = std::move(match);
4515         return ret;
4516     }
4517 
4518     return -1;
4519 }
4520 
4521 /*!
4522     \overload lastIndexOf()
4523     \since 5.0
4524 
4525     Returns the index position of the last match of the regular
4526     expression \a re in the string, which starts before the index
4527     position \a from. Returns -1 if \a re didn't match anywhere.
4528 
4529     Example:
4530 
4531     \snippet qstring/main.cpp 94
4532 */
lastIndexOf(const QRegularExpression & re,int from) const4533 int QString::lastIndexOf(const QRegularExpression &re, int from) const
4534 {
4535     return lastIndexOf(re, from, nullptr);
4536 }
4537 
4538 /*!
4539     \overload
4540     \since 5.5
4541 
4542     Returns the index position of the last match of the regular
4543     expression \a re in the string, which starts before the index
4544     position \a from. Returns -1 if \a re didn't match anywhere.
4545 
4546     If the match is successful and \a rmatch is not \nullptr, it also
4547     writes the results of the match into the QRegularExpressionMatch object
4548     pointed to by \a rmatch.
4549 
4550     Example:
4551 
4552     \snippet qstring/main.cpp 100
4553 */
lastIndexOf(const QRegularExpression & re,int from,QRegularExpressionMatch * rmatch) const4554 int QString::lastIndexOf(const QRegularExpression &re, int from, QRegularExpressionMatch *rmatch) const
4555 {
4556     if (!re.isValid()) {
4557         qWarning("QString::lastIndexOf: invalid QRegularExpression object");
4558         return -1;
4559     }
4560 
4561     int endpos = (from < 0) ? (size() + from + 1) : (from + 1);
4562     QRegularExpressionMatchIterator iterator = re.globalMatch(*this);
4563     int lastIndex = -1;
4564     while (iterator.hasNext()) {
4565         QRegularExpressionMatch match = iterator.next();
4566         int start = match.capturedStart();
4567         if (start < endpos) {
4568             lastIndex = start;
4569             if (rmatch)
4570                 *rmatch = std::move(match);
4571         } else {
4572             break;
4573         }
4574     }
4575 
4576     return lastIndex;
4577 }
4578 
4579 /*! \overload contains()
4580     \since 5.0
4581 
4582     Returns \c true if the regular expression \a re matches somewhere in
4583     this string; otherwise returns \c false.
4584 */
contains(const QRegularExpression & re) const4585 bool QString::contains(const QRegularExpression &re) const
4586 {
4587     return contains(re, nullptr);
4588 }
4589 
4590 /*!
4591     \overload contains()
4592     \since 5.1
4593 
4594     Returns \c true if the regular expression \a re matches somewhere in this
4595     string; otherwise returns \c false.
4596 
4597     If the match is successful and \a rmatch is not \nullptr, it also
4598     writes the results of the match into the QRegularExpressionMatch object
4599     pointed to by \a rmatch.
4600 
4601     \sa QRegularExpression::match()
4602 */
4603 
contains(const QRegularExpression & re,QRegularExpressionMatch * rmatch) const4604 bool QString::contains(const QRegularExpression &re, QRegularExpressionMatch *rmatch) const
4605 {
4606     if (!re.isValid()) {
4607         qWarning("QString::contains: invalid QRegularExpression object");
4608         return false;
4609     }
4610     QRegularExpressionMatch m = re.match(*this);
4611     bool hasMatch = m.hasMatch();
4612     if (hasMatch && rmatch)
4613         *rmatch = std::move(m);
4614     return hasMatch;
4615 }
4616 
4617 /*!
4618     \overload count()
4619     \since 5.0
4620 
4621     Returns the number of times the regular expression \a re matches
4622     in the string.
4623 
4624     For historical reasons, this function counts overlapping matches,
4625     so in the example below, there are four instances of "ana" or
4626     "ama":
4627 
4628     \snippet qstring/main.cpp 95
4629 
4630     This behavior is different from simply iterating over the matches
4631     in the string using QRegularExpressionMatchIterator.
4632 
4633     \sa QRegularExpression::globalMatch()
4634 */
count(const QRegularExpression & re) const4635 int QString::count(const QRegularExpression &re) const
4636 {
4637     if (!re.isValid()) {
4638         qWarning("QString::count: invalid QRegularExpression object");
4639         return 0;
4640     }
4641     int count = 0;
4642     int index = -1;
4643     int len = length();
4644     while (index <= len - 1) {
4645         QRegularExpressionMatch match = re.match(*this, index + 1);
4646         if (!match.hasMatch())
4647             break;
4648         index = match.capturedStart();
4649         count++;
4650     }
4651     return count;
4652 }
4653 #endif // QT_CONFIG(regularexpression)
4654 
4655 /*! \fn int QString::count() const
4656 
4657     \overload count()
4658 
4659     Same as size().
4660 */
4661 
4662 
4663 /*!
4664     \enum QString::SectionFlag
4665 
4666     This enum specifies flags that can be used to affect various
4667     aspects of the section() function's behavior with respect to
4668     separators and empty fields.
4669 
4670     \value SectionDefault Empty fields are counted, leading and
4671     trailing separators are not included, and the separator is
4672     compared case sensitively.
4673 
4674     \value SectionSkipEmpty Treat empty fields as if they don't exist,
4675     i.e. they are not considered as far as \e start and \e end are
4676     concerned.
4677 
4678     \value SectionIncludeLeadingSep Include the leading separator (if
4679     any) in the result string.
4680 
4681     \value SectionIncludeTrailingSep Include the trailing separator
4682     (if any) in the result string.
4683 
4684     \value SectionCaseInsensitiveSeps Compare the separator
4685     case-insensitively.
4686 
4687     \sa section()
4688 */
4689 
4690 /*!
4691     \fn QString QString::section(QChar sep, int start, int end = -1, SectionFlags flags) const
4692 
4693     This function returns a section of the string.
4694 
4695     This string is treated as a sequence of fields separated by the
4696     character, \a sep. The returned string consists of the fields from
4697     position \a start to position \a end inclusive. If \a end is not
4698     specified, all fields from position \a start to the end of the
4699     string are included. Fields are numbered 0, 1, 2, etc., counting
4700     from the left, and -1, -2, etc., counting from right to left.
4701 
4702     The \a flags argument can be used to affect some aspects of the
4703     function's behavior, e.g. whether to be case sensitive, whether
4704     to skip empty fields and how to deal with leading and trailing
4705     separators; see \l{SectionFlags}.
4706 
4707     \snippet qstring/main.cpp 52
4708 
4709     If \a start or \a end is negative, we count fields from the right
4710     of the string, the right-most field being -1, the one from
4711     right-most field being -2, and so on.
4712 
4713     \snippet qstring/main.cpp 53
4714 
4715     \sa split()
4716 */
4717 
4718 /*!
4719     \overload section()
4720 
4721     \snippet qstring/main.cpp 51
4722     \snippet qstring/main.cpp 54
4723 
4724     \sa split()
4725 */
4726 
section(const QString & sep,int start,int end,SectionFlags flags) const4727 QString QString::section(const QString &sep, int start, int end, SectionFlags flags) const
4728 {
4729     const QVector<QStringRef> sections = splitRef(sep, Qt::KeepEmptyParts,
4730                                                   (flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive : Qt::CaseSensitive);
4731     const int sectionsSize = sections.size();
4732     if (!(flags & SectionSkipEmpty)) {
4733         if (start < 0)
4734             start += sectionsSize;
4735         if (end < 0)
4736             end += sectionsSize;
4737     } else {
4738         int skip = 0;
4739         for (int k = 0; k < sectionsSize; ++k) {
4740             if (sections.at(k).isEmpty())
4741                 skip++;
4742         }
4743         if (start < 0)
4744             start += sectionsSize - skip;
4745         if (end < 0)
4746             end += sectionsSize - skip;
4747     }
4748     if (start >= sectionsSize || end < 0 || start > end)
4749         return QString();
4750 
4751     QString ret;
4752     int first_i = start, last_i = end;
4753     for (int x = 0, i = 0; x <= end && i < sectionsSize; ++i) {
4754         const QStringRef &section = sections.at(i);
4755         const bool empty = section.isEmpty();
4756         if (x >= start) {
4757             if(x == start)
4758                 first_i = i;
4759             if(x == end)
4760                 last_i = i;
4761             if (x > start && i > 0)
4762                 ret += sep;
4763             ret += section;
4764         }
4765         if (!empty || !(flags & SectionSkipEmpty))
4766             x++;
4767     }
4768     if ((flags & SectionIncludeLeadingSep) && first_i > 0)
4769         ret.prepend(sep);
4770     if ((flags & SectionIncludeTrailingSep) && last_i < sectionsSize - 1)
4771         ret += sep;
4772     return ret;
4773 }
4774 
4775 #if !(defined(QT_NO_REGEXP) && !QT_CONFIG(regularexpression))
4776 class qt_section_chunk {
4777 public:
qt_section_chunk()4778     qt_section_chunk() {}
qt_section_chunk(int l,QStringRef s)4779     qt_section_chunk(int l, QStringRef s) : length(l), string(std::move(s)) {}
4780     int length;
4781     QStringRef string;
4782 };
4783 Q_DECLARE_TYPEINFO(qt_section_chunk, Q_MOVABLE_TYPE);
4784 
extractSections(const QVector<qt_section_chunk> & sections,int start,int end,QString::SectionFlags flags)4785 static QString extractSections(const QVector<qt_section_chunk> &sections,
4786                                int start,
4787                                int end,
4788                                QString::SectionFlags flags)
4789 {
4790     const int sectionsSize = sections.size();
4791 
4792     if (!(flags & QString::SectionSkipEmpty)) {
4793         if (start < 0)
4794             start += sectionsSize;
4795         if (end < 0)
4796             end += sectionsSize;
4797     } else {
4798         int skip = 0;
4799         for (int k = 0; k < sectionsSize; ++k) {
4800             const qt_section_chunk &section = sections.at(k);
4801             if (section.length == section.string.length())
4802                 skip++;
4803         }
4804         if (start < 0)
4805             start += sectionsSize - skip;
4806         if (end < 0)
4807             end += sectionsSize - skip;
4808     }
4809     if (start >= sectionsSize || end < 0 || start > end)
4810         return QString();
4811 
4812     QString ret;
4813     int x = 0;
4814     int first_i = start, last_i = end;
4815     for (int i = 0; x <= end && i < sectionsSize; ++i) {
4816         const qt_section_chunk &section = sections.at(i);
4817         const bool empty = (section.length == section.string.length());
4818         if (x >= start) {
4819             if (x == start)
4820                 first_i = i;
4821             if (x == end)
4822                 last_i = i;
4823             if (x != start)
4824                 ret += section.string;
4825             else
4826                 ret += section.string.mid(section.length);
4827         }
4828         if (!empty || !(flags & QString::SectionSkipEmpty))
4829             x++;
4830     }
4831 
4832     if ((flags & QString::SectionIncludeLeadingSep) && first_i >= 0) {
4833         const qt_section_chunk &section = sections.at(first_i);
4834         ret.prepend(section.string.left(section.length));
4835     }
4836 
4837     if ((flags & QString::SectionIncludeTrailingSep)
4838         && last_i < sectionsSize - 1) {
4839         const qt_section_chunk &section = sections.at(last_i+1);
4840         ret += section.string.left(section.length);
4841     }
4842 
4843     return ret;
4844 }
4845 #endif
4846 
4847 #ifndef QT_NO_REGEXP
4848 /*!
4849     \overload section()
4850 
4851     This string is treated as a sequence of fields separated by the
4852     regular expression, \a reg.
4853 
4854     \snippet qstring/main.cpp 55
4855 
4856     \warning Using this QRegExp version is much more expensive than
4857     the overloaded string and character versions.
4858 
4859     \sa split(), simplified()
4860 */
section(const QRegExp & reg,int start,int end,SectionFlags flags) const4861 QString QString::section(const QRegExp &reg, int start, int end, SectionFlags flags) const
4862 {
4863     const QChar *uc = unicode();
4864     if(!uc)
4865         return QString();
4866 
4867     QRegExp sep(reg);
4868     sep.setCaseSensitivity((flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive
4869                                                                 : Qt::CaseSensitive);
4870 
4871     QVector<qt_section_chunk> sections;
4872     int n = length(), m = 0, last_m = 0, last_len = 0;
4873     while ((m = sep.indexIn(*this, m)) != -1) {
4874         sections.append(qt_section_chunk(last_len, QStringRef(this, last_m, m - last_m)));
4875         last_m = m;
4876         last_len = sep.matchedLength();
4877         m += qMax(sep.matchedLength(), 1);
4878     }
4879     sections.append(qt_section_chunk(last_len, QStringRef(this, last_m, n - last_m)));
4880 
4881     return extractSections(sections, start, end, flags);
4882 }
4883 #endif
4884 
4885 #if QT_CONFIG(regularexpression)
4886 /*!
4887     \overload section()
4888     \since 5.0
4889 
4890     This string is treated as a sequence of fields separated by the
4891     regular expression, \a re.
4892 
4893     \snippet qstring/main.cpp 89
4894 
4895     \warning Using this QRegularExpression version is much more expensive than
4896     the overloaded string and character versions.
4897 
4898     \sa split(), simplified()
4899 */
section(const QRegularExpression & re,int start,int end,SectionFlags flags) const4900 QString QString::section(const QRegularExpression &re, int start, int end, SectionFlags flags) const
4901 {
4902     if (!re.isValid()) {
4903         qWarning("QString::section: invalid QRegularExpression object");
4904         return QString();
4905     }
4906 
4907     const QChar *uc = unicode();
4908     if (!uc)
4909         return QString();
4910 
4911     QRegularExpression sep(re);
4912     if (flags & SectionCaseInsensitiveSeps)
4913         sep.setPatternOptions(sep.patternOptions() | QRegularExpression::CaseInsensitiveOption);
4914 
4915     QVector<qt_section_chunk> sections;
4916     int n = length(), m = 0, last_m = 0, last_len = 0;
4917     QRegularExpressionMatchIterator iterator = sep.globalMatch(*this);
4918     while (iterator.hasNext()) {
4919         QRegularExpressionMatch match = iterator.next();
4920         m = match.capturedStart();
4921         sections.append(qt_section_chunk(last_len, QStringRef(this, last_m, m - last_m)));
4922         last_m = m;
4923         last_len = match.capturedLength();
4924     }
4925     sections.append(qt_section_chunk(last_len, QStringRef(this, last_m, n - last_m)));
4926 
4927     return extractSections(sections, start, end, flags);
4928 }
4929 #endif // QT_CONFIG(regularexpression)
4930 
4931 /*!
4932     Returns a substring that contains the \a n leftmost characters
4933     of the string.
4934 
4935     The entire string is returned if \a n is greater than or equal
4936     to size(), or less than zero.
4937 
4938     \snippet qstring/main.cpp 31
4939 
4940     \sa right(), mid(), startsWith(), chopped(), chop(), truncate()
4941 */
left(int n) const4942 QString QString::left(int n)  const
4943 {
4944     if (uint(n) >= uint(d->size))
4945         return *this;
4946     return QString((const QChar*) d->data(), n);
4947 }
4948 
4949 /*!
4950     Returns a substring that contains the \a n rightmost characters
4951     of the string.
4952 
4953     The entire string is returned if \a n is greater than or equal
4954     to size(), or less than zero.
4955 
4956     \snippet qstring/main.cpp 48
4957 
4958     \sa left(), mid(), endsWith(), chopped(), chop(), truncate()
4959 */
right(int n) const4960 QString QString::right(int n) const
4961 {
4962     if (uint(n) >= uint(d->size))
4963         return *this;
4964     return QString((const QChar*) d->data() + d->size - n, n);
4965 }
4966 
4967 /*!
4968     Returns a string that contains \a n characters of this string,
4969     starting at the specified \a position index.
4970 
4971     Returns a null string if the \a position index exceeds the
4972     length of the string. If there are less than \a n characters
4973     available in the string starting at the given \a position, or if
4974     \a n is -1 (default), the function returns all characters that
4975     are available from the specified \a position.
4976 
4977     Example:
4978 
4979     \snippet qstring/main.cpp 34
4980 
4981     \sa left(), right(), chopped(), chop(), truncate()
4982 */
4983 
mid(int position,int n) const4984 QString QString::mid(int position, int n) const
4985 {
4986     using namespace QtPrivate;
4987     switch (QContainerImplHelper::mid(d->size, &position, &n)) {
4988     case QContainerImplHelper::Null:
4989         return QString();
4990     case QContainerImplHelper::Empty:
4991     {
4992         QStringDataPtr empty = { Data::allocate(0) };
4993         return QString(empty);
4994     }
4995     case QContainerImplHelper::Full:
4996         return *this;
4997     case QContainerImplHelper::Subset:
4998         return QString((const QChar*)d->data() + position, n);
4999     }
5000     Q_UNREACHABLE();
5001     return QString();
5002 }
5003 
5004 /*!
5005     \fn QString QString::chopped(int len) const
5006     \since 5.10
5007 
5008     Returns a substring that contains the size() - \a len leftmost characters
5009     of this string.
5010 
5011     \note The behavior is undefined if \a len is negative or greater than size().
5012 
5013     \sa endsWith(), left(), right(), mid(), chop(), truncate()
5014 */
5015 
5016 #if QT_STRINGVIEW_LEVEL < 2
5017 /*!
5018     Returns \c true if the string starts with \a s; otherwise returns
5019     \c false.
5020 
5021     If \a cs is Qt::CaseSensitive (default), the search is
5022     case sensitive; otherwise the search is case insensitive.
5023 
5024     \snippet qstring/main.cpp 65
5025 
5026     \sa endsWith()
5027 */
startsWith(const QString & s,Qt::CaseSensitivity cs) const5028 bool QString::startsWith(const QString& s, Qt::CaseSensitivity cs) const
5029 {
5030     return qt_starts_with(*this, s, cs);
5031 }
5032 #endif
5033 
5034 /*!
5035   \overload startsWith()
5036  */
startsWith(QLatin1String s,Qt::CaseSensitivity cs) const5037 bool QString::startsWith(QLatin1String s, Qt::CaseSensitivity cs) const
5038 {
5039     return qt_starts_with(*this, s, cs);
5040 }
5041 
5042 /*!
5043   \overload startsWith()
5044 
5045   Returns \c true if the string starts with \a c; otherwise returns
5046   \c false.
5047 */
startsWith(QChar c,Qt::CaseSensitivity cs) const5048 bool QString::startsWith(QChar c, Qt::CaseSensitivity cs) const
5049 {
5050     return qt_starts_with(*this, c, cs);
5051 }
5052 
5053 #if QT_STRINGVIEW_LEVEL < 2
5054 /*!
5055     \since 4.8
5056     \overload
5057     Returns \c true if the string starts with the string reference \a s;
5058     otherwise returns \c false.
5059 
5060     If \a cs is Qt::CaseSensitive (default), the search is case
5061     sensitive; otherwise the search is case insensitive.
5062 
5063     \sa endsWith()
5064 */
startsWith(const QStringRef & s,Qt::CaseSensitivity cs) const5065 bool QString::startsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
5066 {
5067     return qt_starts_with(*this, s, cs);
5068 }
5069 #endif
5070 
5071 /*!
5072     \fn bool QString::startsWith(QStringView str, Qt::CaseSensitivity cs) const
5073     \since 5.10
5074     \overload
5075 
5076     Returns \c true if the string starts with the string-view \a str;
5077     otherwise returns \c false.
5078 
5079     If \a cs is Qt::CaseSensitive (default), the search is case-sensitive;
5080     otherwise the search is case insensitive.
5081 
5082     \sa endsWith()
5083 */
5084 
5085 #if QT_STRINGVIEW_LEVEL < 2
5086 /*!
5087     Returns \c true if the string ends with \a s; otherwise returns
5088     \c false.
5089 
5090     If \a cs is Qt::CaseSensitive (default), the search is case
5091     sensitive; otherwise the search is case insensitive.
5092 
5093     \snippet qstring/main.cpp 20
5094 
5095     \sa startsWith()
5096 */
endsWith(const QString & s,Qt::CaseSensitivity cs) const5097 bool QString::endsWith(const QString &s, Qt::CaseSensitivity cs) const
5098 {
5099     return qt_ends_with(*this, s, cs);
5100 }
5101 
5102 /*!
5103     \since 4.8
5104     \overload endsWith()
5105     Returns \c true if the string ends with the string reference \a s;
5106     otherwise returns \c false.
5107 
5108     If \a cs is Qt::CaseSensitive (default), the search is case
5109     sensitive; otherwise the search is case insensitive.
5110 
5111     \sa startsWith()
5112 */
endsWith(const QStringRef & s,Qt::CaseSensitivity cs) const5113 bool QString::endsWith(const QStringRef &s, Qt::CaseSensitivity cs) const
5114 {
5115     return qt_ends_with(*this, s, cs);
5116 }
5117 #endif // QT_STRINGVIEW_LEVEL < 2
5118 
5119 /*!
5120     \fn bool QString::endsWith(QStringView str, Qt::CaseSensitivity cs) const
5121     \since 5.10
5122     \overload endsWith()
5123     Returns \c true if the string ends with the string view \a str;
5124     otherwise returns \c false.
5125 
5126     If \a cs is Qt::CaseSensitive (default), the search is case
5127     sensitive; otherwise the search is case insensitive.
5128 
5129     \sa startsWith()
5130 */
5131 
5132 /*!
5133     \overload endsWith()
5134 */
endsWith(QLatin1String s,Qt::CaseSensitivity cs) const5135 bool QString::endsWith(QLatin1String s, Qt::CaseSensitivity cs) const
5136 {
5137     return qt_ends_with(*this, s, cs);
5138 }
5139 
5140 /*!
5141   Returns \c true if the string ends with \a c; otherwise returns
5142   \c false.
5143 
5144   \overload endsWith()
5145  */
endsWith(QChar c,Qt::CaseSensitivity cs) const5146 bool QString::endsWith(QChar c, Qt::CaseSensitivity cs) const
5147 {
5148     return qt_ends_with(*this, c, cs);
5149 }
5150 
5151 /*!
5152     Returns \c true if the string is uppercase, that is, it's identical
5153     to its toUpper() folding.
5154 
5155     Note that this does \e not mean that the string does not contain
5156     lowercase letters (some lowercase letters do not have a uppercase
5157     folding; they are left unchanged by toUpper()).
5158     For more information, refer to the Unicode standard, section 3.13.
5159 
5160     \since 5.12
5161 
5162     \sa QChar::toUpper(), isLower()
5163 */
isUpper() const5164 bool QString::isUpper() const
5165 {
5166     QStringIterator it(*this);
5167 
5168     while (it.hasNext()) {
5169         uint uc = it.nextUnchecked();
5170         if (qGetProp(uc)->cases[QUnicodeTables::UpperCase].diff)
5171             return false;
5172     }
5173 
5174     return true;
5175 }
5176 
5177 /*!
5178     Returns \c true if the string is lowercase, that is, it's identical
5179     to its toLower() folding.
5180 
5181     Note that this does \e not mean that the string does not contain
5182     uppercase letters (some uppercase letters do not have a lowercase
5183     folding; they are left unchanged by toLower()).
5184     For more information, refer to the Unicode standard, section 3.13.
5185 
5186     \since 5.12
5187 
5188     \sa QChar::toLower(), isUpper()
5189  */
isLower() const5190 bool QString::isLower() const
5191 {
5192     QStringIterator it(*this);
5193 
5194     while (it.hasNext()) {
5195         uint uc = it.nextUnchecked();
5196         if (qGetProp(uc)->cases[QUnicodeTables::LowerCase].diff)
5197             return false;
5198     }
5199 
5200     return true;
5201 }
5202 
5203 static QByteArray qt_convert_to_latin1(QStringView string);
5204 
toLatin1_helper(const QString & string)5205 QByteArray QString::toLatin1_helper(const QString &string)
5206 {
5207     return qt_convert_to_latin1(string);
5208 }
5209 
5210 /*!
5211     \since 5.10
5212     \internal
5213     \relates QStringView
5214 
5215     Returns a Latin-1 representation of \a string as a QByteArray.
5216 
5217     The behavior is undefined if \a string contains non-Latin1 characters.
5218 
5219     \sa QString::toLatin1(), QStringView::toLatin1(), QtPrivate::convertToUtf8(),
5220     QtPrivate::convertToLocal8Bit(), QtPrivate::convertToUcs4()
5221 */
convertToLatin1(QStringView string)5222 QByteArray QtPrivate::convertToLatin1(QStringView string)
5223 {
5224     return qt_convert_to_latin1(string);
5225 }
5226 
qt_convert_to_latin1(QStringView string)5227 static QByteArray qt_convert_to_latin1(QStringView string)
5228 {
5229     if (Q_UNLIKELY(string.isNull()))
5230         return QByteArray();
5231 
5232     QByteArray ba(string.length(), Qt::Uninitialized);
5233 
5234     // since we own the only copy, we're going to const_cast the constData;
5235     // that avoids an unnecessary call to detach() and expansion code that will never get used
5236     qt_to_latin1(reinterpret_cast<uchar *>(const_cast<char *>(ba.constData())),
5237                  reinterpret_cast<const ushort *>(string.data()), string.length());
5238     return ba;
5239 }
5240 
toLatin1_helper_inplace(QString & s)5241 QByteArray QString::toLatin1_helper_inplace(QString &s)
5242 {
5243     if (!s.isDetached())
5244         return qt_convert_to_latin1(s);
5245 
5246     // We can return our own buffer to the caller.
5247     // Conversion to Latin-1 always shrinks the buffer by half.
5248     const ushort *data = reinterpret_cast<const ushort *>(s.constData());
5249     uint length = s.size();
5250 
5251     // Swap the d pointers.
5252     // Kids, avert your eyes. Don't try this at home.
5253     QArrayData *ba_d = s.d;
5254 
5255     // multiply the allocated capacity by sizeof(ushort)
5256     ba_d->alloc *= sizeof(ushort);
5257 
5258     // reset ourselves to QString()
5259     s.d = QString().d;
5260 
5261     // do the in-place conversion
5262     uchar *dst = reinterpret_cast<uchar *>(ba_d->data());
5263     qt_to_latin1(dst, data, length);
5264     dst[length] = '\0';
5265 
5266     QByteArrayDataPtr badptr = { ba_d };
5267     return QByteArray(badptr);
5268 }
5269 
5270 
5271 /*!
5272     \fn QByteArray QString::toLatin1() const
5273 
5274     Returns a Latin-1 representation of the string as a QByteArray.
5275 
5276     The returned byte array is undefined if the string contains non-Latin1
5277     characters. Those characters may be suppressed or replaced with a
5278     question mark.
5279 
5280     \sa fromLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
5281 */
5282 
5283 /*!
5284     \fn QByteArray QString::toAscii() const
5285     \deprecated
5286     Returns an 8-bit representation of the string as a QByteArray.
5287 
5288     This function does the same as toLatin1().
5289 
5290     Note that, despite the name, this function does not necessarily return an US-ASCII
5291     (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
5292 
5293     \sa fromAscii(), toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
5294 */
5295 
5296 static QByteArray qt_convert_to_local_8bit(QStringView string);
5297 
5298 /*!
5299     \fn QByteArray QString::toLocal8Bit() const
5300 
5301     Returns the local 8-bit representation of the string as a
5302     QByteArray. The returned byte array is undefined if the string
5303     contains characters not supported by the local 8-bit encoding.
5304 
5305     QTextCodec::codecForLocale() is used to perform the conversion from
5306     Unicode. If the locale encoding could not be determined, this function
5307     does the same as toLatin1().
5308 
5309     If this string contains any characters that cannot be encoded in the
5310     locale, the returned byte array is undefined. Those characters may be
5311     suppressed or replaced by another.
5312 
5313     \sa fromLocal8Bit(), toLatin1(), toUtf8(), QTextCodec
5314 */
5315 
toLocal8Bit_helper(const QChar * data,int size)5316 QByteArray QString::toLocal8Bit_helper(const QChar *data, int size)
5317 {
5318     return qt_convert_to_local_8bit(QStringView(data, size));
5319 }
5320 
qt_convert_to_local_8bit(QStringView string)5321 static QByteArray qt_convert_to_local_8bit(QStringView string)
5322 {
5323     if (string.isNull())
5324         return QByteArray();
5325 #if QT_CONFIG(textcodec)
5326     QTextCodec *localeCodec = QTextCodec::codecForLocale();
5327     if (localeCodec)
5328         return localeCodec->fromUnicode(string);
5329 #endif // textcodec
5330     return qt_convert_to_latin1(string);
5331 }
5332 
5333 /*!
5334     \since 5.10
5335     \internal
5336     \relates QStringView
5337 
5338     Returns a local 8-bit representation of \a string as a QByteArray.
5339 
5340     QTextCodec::codecForLocale() is used to perform the conversion from
5341     Unicode.
5342 
5343     The behavior is undefined if \a string contains characters not
5344     supported by the locale's 8-bit encoding.
5345 
5346     \sa QString::toLocal8Bit(), QStringView::toLocal8Bit()
5347 */
convertToLocal8Bit(QStringView string)5348 QByteArray QtPrivate::convertToLocal8Bit(QStringView string)
5349 {
5350     return qt_convert_to_local_8bit(string);
5351 }
5352 
5353 static QByteArray qt_convert_to_utf8(QStringView str);
5354 
5355 /*!
5356     \fn QByteArray QString::toUtf8() const
5357 
5358     Returns a UTF-8 representation of the string as a QByteArray.
5359 
5360     UTF-8 is a Unicode codec and can represent all characters in a Unicode
5361     string like QString.
5362 
5363     \sa fromUtf8(), toLatin1(), toLocal8Bit(), QTextCodec
5364 */
5365 
toUtf8_helper(const QString & str)5366 QByteArray QString::toUtf8_helper(const QString &str)
5367 {
5368     return qt_convert_to_utf8(str);
5369 }
5370 
qt_convert_to_utf8(QStringView str)5371 static QByteArray qt_convert_to_utf8(QStringView str)
5372 {
5373     if (str.isNull())
5374         return QByteArray();
5375 
5376     return QUtf8::convertFromUnicode(str.data(), str.length());
5377 }
5378 
5379 /*!
5380     \since 5.10
5381     \internal
5382     \relates QStringView
5383 
5384     Returns a UTF-8 representation of \a string as a QByteArray.
5385 
5386     UTF-8 is a Unicode codec and can represent all characters in a Unicode
5387     string like QStringView.
5388 
5389     \sa QString::toUtf8(), QStringView::toUtf8()
5390 */
convertToUtf8(QStringView string)5391 QByteArray QtPrivate::convertToUtf8(QStringView string)
5392 {
5393     return qt_convert_to_utf8(string);
5394 }
5395 
5396 static QVector<uint> qt_convert_to_ucs4(QStringView string);
5397 
5398 /*!
5399     \since 4.2
5400 
5401     Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
5402 
5403     UCS-4 is a Unicode codec and therefore it is lossless. All characters from
5404     this string will be encoded in UCS-4. Any invalid sequence of code units in
5405     this string is replaced by the Unicode's replacement character
5406     (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}).
5407 
5408     The returned vector is not \\0'-terminated.
5409 
5410     \sa fromUtf8(), toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
5411 */
toUcs4() const5412 QVector<uint> QString::toUcs4() const
5413 {
5414     return qt_convert_to_ucs4(*this);
5415 }
5416 
qt_convert_to_ucs4(QStringView string)5417 static QVector<uint> qt_convert_to_ucs4(QStringView string)
5418 {
5419     QVector<uint> v(string.length());
5420     uint *a = const_cast<uint*>(v.constData());
5421     QStringIterator it(string);
5422     while (it.hasNext())
5423         *a++ = it.next();
5424     v.resize(a - v.constData());
5425     return v;
5426 }
5427 
5428 /*!
5429     \since 5.10
5430     \internal
5431     \relates QStringView
5432 
5433     Returns a UCS-4/UTF-32 representation of \a string as a QVector<uint>.
5434 
5435     UCS-4 is a Unicode codec and therefore it is lossless. All characters from
5436     this string will be encoded in UCS-4. Any invalid sequence of code units in
5437     this string is replaced by the Unicode's replacement character
5438     (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}).
5439 
5440     The returned vector is not \\0'-terminated.
5441 
5442     \sa QString::toUcs4(), QStringView::toUcs4(), QtPrivate::convertToLatin1(),
5443     QtPrivate::convertToLocal8Bit(), QtPrivate::convertToUtf8()
5444 */
convertToUcs4(QStringView string)5445 QVector<uint> QtPrivate::convertToUcs4(QStringView string)
5446 {
5447     return qt_convert_to_ucs4(string);
5448 }
5449 
fromLatin1_helper(const char * str,int size)5450 QString::Data *QString::fromLatin1_helper(const char *str, int size)
5451 {
5452     Data *d;
5453     if (!str) {
5454         d = Data::sharedNull();
5455     } else if (size == 0 || (!*str && size < 0)) {
5456         d = Data::allocate(0);
5457     } else {
5458         if (size < 0)
5459             size = qstrlen(str);
5460         d = Data::allocate(size + 1);
5461         Q_CHECK_PTR(d);
5462         d->size = size;
5463         d->data()[size] = '\0';
5464         ushort *dst = d->data();
5465 
5466         qt_from_latin1(dst, str, uint(size));
5467     }
5468     return d;
5469 }
5470 
fromAscii_helper(const char * str,int size)5471 QString::Data *QString::fromAscii_helper(const char *str, int size)
5472 {
5473     QString s = fromUtf8(str, size);
5474     s.d->ref.ref();
5475     return s.d;
5476 }
5477 
5478 /*! \fn QString QString::fromLatin1(const char *str, int size)
5479     Returns a QString initialized with the first \a size characters
5480     of the Latin-1 string \a str.
5481 
5482     If \a size is -1 (default), it is taken to be strlen(\a
5483     str).
5484 
5485     \sa toLatin1(), fromUtf8(), fromLocal8Bit()
5486 */
5487 
5488 /*!
5489     \fn QString QString::fromLatin1(const QByteArray &str)
5490     \overload
5491     \since 5.0
5492 
5493     Returns a QString initialized with the Latin-1 string \a str.
5494 */
5495 
5496 /*! \fn QString QString::fromLocal8Bit(const char *str, int size)
5497     Returns a QString initialized with the first \a size characters
5498     of the 8-bit string \a str.
5499 
5500     If \a size is -1 (default), it is taken to be strlen(\a
5501     str).
5502 
5503     QTextCodec::codecForLocale() is used to perform the conversion.
5504 
5505     \sa toLocal8Bit(), fromLatin1(), fromUtf8()
5506 */
5507 
5508 /*!
5509     \fn QString QString::fromLocal8Bit(const QByteArray &str)
5510     \overload
5511     \since 5.0
5512 
5513     Returns a QString initialized with the 8-bit string \a str.
5514 */
fromLocal8Bit_helper(const char * str,int size)5515 QString QString::fromLocal8Bit_helper(const char *str, int size)
5516 {
5517     if (!str)
5518         return QString();
5519     if (size == 0 || (!*str && size < 0)) {
5520         QStringDataPtr empty = { Data::allocate(0) };
5521         return QString(empty);
5522     }
5523 #if QT_CONFIG(textcodec)
5524     if (size < 0)
5525         size = qstrlen(str);
5526     QTextCodec *codec = QTextCodec::codecForLocale();
5527     if (codec)
5528         return codec->toUnicode(str, size);
5529 #endif // textcodec
5530     return fromLatin1(str, size);
5531 }
5532 
5533 /*! \fn QString QString::fromAscii(const char *, int size);
5534     \deprecated
5535 
5536     Returns a QString initialized with the first \a size characters
5537     from the string \a str.
5538 
5539     If \a size is -1 (default), it is taken to be strlen(\a
5540     str).
5541 
5542     This function does the same as fromLatin1().
5543 
5544     \sa toAscii(), fromLatin1(), fromUtf8(), fromLocal8Bit()
5545 */
5546 
5547 /*!
5548     \fn QString QString::fromAscii(const QByteArray &str)
5549     \deprecated
5550     \overload
5551     \since 5.0
5552 
5553     Returns a QString initialized with the string \a str.
5554 */
5555 
5556 /*! \fn QString QString::fromUtf8(const char *str, int size)
5557     Returns a QString initialized with the first \a size bytes
5558     of the UTF-8 string \a str.
5559 
5560     If \a size is -1 (default), it is taken to be strlen(\a
5561     str).
5562 
5563     UTF-8 is a Unicode codec and can represent all characters in a Unicode
5564     string like QString. However, invalid sequences are possible with UTF-8
5565     and, if any such are found, they will be replaced with one or more
5566     "replacement characters", or suppressed. These include non-Unicode
5567     sequences, non-characters, overlong sequences or surrogate codepoints
5568     encoded into UTF-8.
5569 
5570     This function can be used to process incoming data incrementally as long as
5571     all UTF-8 characters are terminated within the incoming data. Any
5572     unterminated characters at the end of the string will be replaced or
5573     suppressed. In order to do stateful decoding, please use \l QTextDecoder.
5574 
5575     \sa toUtf8(), fromLatin1(), fromLocal8Bit()
5576 */
5577 
5578 /*!
5579     \fn QString QString::fromUtf8(const QByteArray &str)
5580     \overload
5581     \since 5.0
5582 
5583     Returns a QString initialized with the UTF-8 string \a str.
5584 */
fromUtf8_helper(const char * str,int size)5585 QString QString::fromUtf8_helper(const char *str, int size)
5586 {
5587     if (!str)
5588         return QString();
5589 
5590     Q_ASSERT(size != -1);
5591     return QUtf8::convertToUnicode(str, size);
5592 }
5593 
5594 /*!
5595     Returns a QString initialized with the first \a size characters
5596     of the Unicode string \a unicode (ISO-10646-UTF-16 encoded).
5597 
5598     If \a size is -1 (default), \a unicode must be \\0'-terminated.
5599 
5600     This function checks for a Byte Order Mark (BOM). If it is missing,
5601     host byte order is assumed.
5602 
5603     This function is slow compared to the other Unicode conversions.
5604     Use QString(const QChar *, int) or QString(const QChar *) if possible.
5605 
5606     QString makes a deep copy of the Unicode data.
5607 
5608     \sa utf16(), setUtf16(), fromStdU16String()
5609 */
fromUtf16(const ushort * unicode,int size)5610 QString QString::fromUtf16(const ushort *unicode, int size)
5611 {
5612     if (!unicode)
5613         return QString();
5614     if (size < 0) {
5615         size = 0;
5616         while (unicode[size] != 0)
5617             ++size;
5618     }
5619     return QUtf16::convertToUnicode((const char *)unicode, size*2, nullptr);
5620 }
5621 
5622 /*!
5623    \fn QString QString::fromUtf16(const char16_t *str, int size)
5624    \since 5.3
5625 
5626     Returns a QString initialized with the first \a size characters
5627     of the Unicode string \a str (ISO-10646-UTF-16 encoded).
5628 
5629     If \a size is -1 (default), \a str must be \\0'-terminated.
5630 
5631     This function checks for a Byte Order Mark (BOM). If it is missing,
5632     host byte order is assumed.
5633 
5634     This function is slow compared to the other Unicode conversions.
5635     Use QString(const QChar *, int) or QString(const QChar *) if possible.
5636 
5637     QString makes a deep copy of the Unicode data.
5638 
5639     \sa utf16(), setUtf16(), fromStdU16String()
5640 */
5641 
5642 /*!
5643     \fn QString QString::fromUcs4(const char32_t *str, int size)
5644     \since 5.3
5645 
5646     Returns a QString initialized with the first \a size characters
5647     of the Unicode string \a str (ISO-10646-UCS-4 encoded).
5648 
5649     If \a size is -1 (default), \a str must be \\0'-terminated.
5650 
5651     \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String()
5652 */
5653 
5654 /*!
5655     \since 4.2
5656 
5657     Returns a QString initialized with the first \a size characters
5658     of the Unicode string \a unicode (ISO-10646-UCS-4 encoded).
5659 
5660     If \a size is -1 (default), \a unicode must be \\0'-terminated.
5661 
5662     \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray(), fromStdU32String()
5663 */
fromUcs4(const uint * unicode,int size)5664 QString QString::fromUcs4(const uint *unicode, int size)
5665 {
5666     if (!unicode)
5667         return QString();
5668     if (size < 0) {
5669         size = 0;
5670         while (unicode[size] != 0)
5671             ++size;
5672     }
5673     return QUtf32::convertToUnicode((const char *)unicode, size*4, nullptr);
5674 }
5675 
5676 
5677 /*!
5678     Resizes the string to \a size characters and copies \a unicode
5679     into the string.
5680 
5681     If \a unicode is 0, nothing is copied, but the string is still
5682     resized to \a size.
5683 
5684     \sa unicode(), setUtf16()
5685 */
setUnicode(const QChar * unicode,int size)5686 QString& QString::setUnicode(const QChar *unicode, int size)
5687 {
5688      resize(size);
5689      if (unicode && size)
5690          memcpy(d->data(), unicode, size * sizeof(QChar));
5691      return *this;
5692 }
5693 
5694 /*!
5695     \fn QString &QString::setUtf16(const ushort *unicode, int size)
5696 
5697     Resizes the string to \a size characters and copies \a unicode
5698     into the string.
5699 
5700     If \a unicode is 0, nothing is copied, but the string is still
5701     resized to \a size.
5702 
5703     Note that unlike fromUtf16(), this function does not consider BOMs and
5704     possibly differing byte ordering.
5705 
5706     \sa utf16(), setUnicode()
5707 */
5708 
5709 /*!
5710     \fn QString QString::simplified() const
5711 
5712     Returns a string that has whitespace removed from the start
5713     and the end, and that has each sequence of internal whitespace
5714     replaced with a single space.
5715 
5716     Whitespace means any character for which QChar::isSpace() returns
5717     \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
5718     '\\f', '\\r', and ' '.
5719 
5720     Example:
5721 
5722     \snippet qstring/main.cpp 57
5723 
5724     \sa trimmed()
5725 */
simplified_helper(const QString & str)5726 QString QString::simplified_helper(const QString &str)
5727 {
5728     return QStringAlgorithms<const QString>::simplified_helper(str);
5729 }
5730 
simplified_helper(QString & str)5731 QString QString::simplified_helper(QString &str)
5732 {
5733     return QStringAlgorithms<QString>::simplified_helper(str);
5734 }
5735 
5736 namespace {
5737     template <typename StringView>
qt_trimmed(StringView s)5738     StringView qt_trimmed(StringView s) noexcept
5739     {
5740         auto begin = s.begin();
5741         auto end = s.end();
5742         QStringAlgorithms<const StringView>::trimmed_helper_positions(begin, end);
5743         return StringView{begin, end};
5744     }
5745 }
5746 
5747 /*!
5748     \fn QStringView QtPrivate::trimmed(QStringView s)
5749     \fn QLatin1String QtPrivate::trimmed(QLatin1String s)
5750     \internal
5751     \relates QStringView
5752     \since 5.10
5753 
5754     Returns \a s with whitespace removed from the start and the end.
5755 
5756     Whitespace means any character for which QChar::isSpace() returns
5757     \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
5758     '\\f', '\\r', and ' '.
5759 
5760     \sa QString::trimmed(), QStringView::trimmed(), QLatin1String::trimmed()
5761 */
trimmed(QStringView s)5762 QStringView QtPrivate::trimmed(QStringView s) noexcept
5763 {
5764     return qt_trimmed(s);
5765 }
5766 
trimmed(QLatin1String s)5767 QLatin1String QtPrivate::trimmed(QLatin1String s) noexcept
5768 {
5769     return qt_trimmed(s);
5770 }
5771 
5772 /*!
5773     \fn QString QString::trimmed() const
5774 
5775     Returns a string that has whitespace removed from the start and
5776     the end.
5777 
5778     Whitespace means any character for which QChar::isSpace() returns
5779     \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
5780     '\\f', '\\r', and ' '.
5781 
5782     Example:
5783 
5784     \snippet qstring/main.cpp 82
5785 
5786     Unlike simplified(), trimmed() leaves internal whitespace alone.
5787 
5788     \sa simplified()
5789 */
trimmed_helper(const QString & str)5790 QString QString::trimmed_helper(const QString &str)
5791 {
5792     return QStringAlgorithms<const QString>::trimmed_helper(str);
5793 }
5794 
trimmed_helper(QString & str)5795 QString QString::trimmed_helper(QString &str)
5796 {
5797     return QStringAlgorithms<QString>::trimmed_helper(str);
5798 }
5799 
5800 /*! \fn const QChar QString::at(int position) const
5801 
5802     Returns the character at the given index \a position in the
5803     string.
5804 
5805     The \a position must be a valid index position in the string
5806     (i.e., 0 <= \a position < size()).
5807 
5808     \sa operator[]()
5809 */
5810 
5811 /*!
5812     \fn QCharRef QString::operator[](int position)
5813 
5814     Returns the character at the specified \a position in the string as a
5815     modifiable reference.
5816 
5817     Example:
5818 
5819     \snippet qstring/main.cpp 85
5820 
5821     The return value is of type QCharRef, a helper class for QString.
5822     When you get an object of type QCharRef, you can use it as if it
5823     were a reference to a QChar. If you assign to it, the assignment will apply to
5824     the character in the QString from which you got the reference.
5825 
5826     \note Before Qt 5.14 it was possible to use this operator to access
5827     a character at an out-of-bounds position in the string, and
5828     then assign to such a position, causing the string to be
5829     automatically resized. Furthermore, assigning a value to the
5830     returned QCharRef would cause a detach of the string, even if the
5831     string has been copied in the meanwhile (and the QCharRef kept
5832     alive while the copy was taken). These behaviors are deprecated,
5833     and will be changed in a future version of Qt.
5834 
5835     \sa at()
5836 */
5837 
5838 /*!
5839     \fn const QChar QString::operator[](int position) const
5840 
5841     \overload operator[]()
5842 */
5843 
5844 /*! \fn QCharRef QString::operator[](uint position)
5845 
5846 \overload operator[]()
5847 
5848 Returns the character at the specified \a position in the string as a
5849 modifiable reference.
5850 */
5851 
5852 /*! \fn const QChar QString::operator[](uint position) const
5853     Equivalent to \c at(position).
5854 \overload operator[]()
5855 */
5856 
5857 /*!
5858     \fn QChar QString::front() const
5859     \since 5.10
5860 
5861     Returns the first character in the string.
5862     Same as \c{at(0)}.
5863 
5864     This function is provided for STL compatibility.
5865 
5866     \warning Calling this function on an empty string constitutes
5867     undefined behavior.
5868 
5869     \sa back(), at(), operator[]()
5870 */
5871 
5872 /*!
5873     \fn QChar QString::back() const
5874     \since 5.10
5875 
5876     Returns the last character in the string.
5877     Same as \c{at(size() - 1)}.
5878 
5879     This function is provided for STL compatibility.
5880 
5881     \warning Calling this function on an empty string constitutes
5882     undefined behavior.
5883 
5884     \sa front(), at(), operator[]()
5885 */
5886 
5887 /*!
5888     \fn QCharRef QString::front()
5889     \since 5.10
5890 
5891     Returns a reference to the first character in the string.
5892     Same as \c{operator[](0)}.
5893 
5894     This function is provided for STL compatibility.
5895 
5896     \warning Calling this function on an empty string constitutes
5897     undefined behavior.
5898 
5899     \sa back(), at(), operator[]()
5900 */
5901 
5902 /*!
5903     \fn QCharRef QString::back()
5904     \since 5.10
5905 
5906     Returns a reference to the last character in the string.
5907     Same as \c{operator[](size() - 1)}.
5908 
5909     This function is provided for STL compatibility.
5910 
5911     \warning Calling this function on an empty string constitutes
5912     undefined behavior.
5913 
5914     \sa front(), at(), operator[]()
5915 */
5916 
5917 /*!
5918     \fn void QString::truncate(int position)
5919 
5920     Truncates the string at the given \a position index.
5921 
5922     If the specified \a position index is beyond the end of the
5923     string, nothing happens.
5924 
5925     Example:
5926 
5927     \snippet qstring/main.cpp 83
5928 
5929     If \a position is negative, it is equivalent to passing zero.
5930 
5931     \sa chop(), resize(), left(), QStringRef::truncate()
5932 */
5933 
truncate(int pos)5934 void QString::truncate(int pos)
5935 {
5936     if (pos < d->size)
5937         resize(pos);
5938 }
5939 
5940 
5941 /*!
5942     Removes \a n characters from the end of the string.
5943 
5944     If \a n is greater than or equal to size(), the result is an
5945     empty string; if \a n is negative, it is equivalent to passing zero.
5946 
5947     Example:
5948     \snippet qstring/main.cpp 15
5949 
5950     If you want to remove characters from the \e beginning of the
5951     string, use remove() instead.
5952 
5953     \sa truncate(), resize(), remove(), QStringRef::chop()
5954 */
chop(int n)5955 void QString::chop(int n)
5956 {
5957     if (n > 0)
5958         resize(d->size - n);
5959 }
5960 
5961 /*!
5962     Sets every character in the string to character \a ch. If \a size
5963     is different from -1 (default), the string is resized to \a
5964     size beforehand.
5965 
5966     Example:
5967 
5968     \snippet qstring/main.cpp 21
5969 
5970     \sa resize()
5971 */
5972 
fill(QChar ch,int size)5973 QString& QString::fill(QChar ch, int size)
5974 {
5975     resize(size < 0 ? d->size : size);
5976     if (d->size) {
5977         QChar *i = (QChar*)d->data() + d->size;
5978         QChar *b = (QChar*)d->data();
5979         while (i != b)
5980            *--i = ch;
5981     }
5982     return *this;
5983 }
5984 
5985 /*!
5986     \fn int QString::length() const
5987 
5988     Returns the number of characters in this string.  Equivalent to
5989     size().
5990 
5991     \sa resize()
5992 */
5993 
5994 /*!
5995     \fn int QString::size() const
5996 
5997     Returns the number of characters in this string.
5998 
5999     The last character in the string is at position size() - 1.
6000 
6001     Example:
6002     \snippet qstring/main.cpp 58
6003 
6004     \sa isEmpty(), resize()
6005 */
6006 
6007 /*! \fn bool QString::isNull() const
6008 
6009     Returns \c true if this string is null; otherwise returns \c false.
6010 
6011     Example:
6012 
6013     \snippet qstring/main.cpp 28
6014 
6015     Qt makes a distinction between null strings and empty strings for
6016     historical reasons. For most applications, what matters is
6017     whether or not a string contains any data, and this can be
6018     determined using the isEmpty() function.
6019 
6020     \sa isEmpty()
6021 */
6022 
6023 /*! \fn bool QString::isEmpty() const
6024 
6025     Returns \c true if the string has no characters; otherwise returns
6026     \c false.
6027 
6028     Example:
6029 
6030     \snippet qstring/main.cpp 27
6031 
6032     \sa size()
6033 */
6034 
6035 /*! \fn QString &QString::operator+=(const QString &other)
6036 
6037     Appends the string \a other onto the end of this string and
6038     returns a reference to this string.
6039 
6040     Example:
6041 
6042     \snippet qstring/main.cpp 84
6043 
6044     This operation is typically very fast (\l{constant time}),
6045     because QString preallocates extra space at the end of the string
6046     data so it can grow without reallocating the entire string each
6047     time.
6048 
6049     \sa append(), prepend()
6050 */
6051 
6052 /*! \fn QString &QString::operator+=(QLatin1String str)
6053 
6054     \overload operator+=()
6055 
6056     Appends the Latin-1 string \a str to this string.
6057 */
6058 
6059 /*! \fn QString &QString::operator+=(const QByteArray &ba)
6060 
6061     \overload operator+=()
6062 
6063     Appends the byte array \a ba to this string. The byte array is converted
6064     to Unicode using the fromUtf8() function. If any NUL characters ('\\0')
6065     are embedded in the \a ba byte array, they will be included in the
6066     transformation.
6067 
6068     You can disable this function by defining \c
6069     QT_NO_CAST_FROM_ASCII when you compile your applications. This
6070     can be useful if you want to ensure that all user-visible strings
6071     go through QObject::tr(), for example.
6072 
6073     \sa QT_NO_CAST_FROM_ASCII
6074 */
6075 
6076 /*! \fn QString &QString::operator+=(const char *str)
6077 
6078     \overload operator+=()
6079 
6080     Appends the string \a str to this string. The const char pointer
6081     is converted to Unicode using the fromUtf8() function.
6082 
6083     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
6084     when you compile your applications. This can be useful if you want
6085     to ensure that all user-visible strings go through QObject::tr(),
6086     for example.
6087 
6088     \sa QT_NO_CAST_FROM_ASCII
6089 */
6090 
6091 /*! \fn QString &QString::operator+=(const QStringRef &str)
6092 
6093     \overload operator+=()
6094 
6095     Appends the string section referenced by \a str to this string.
6096 */
6097 
6098 /*! \fn QString &QString::operator+=(QStringView str)
6099     \since 5.15.2
6100     \overload operator+=()
6101 
6102     Appends the string section referenced by \a str to this string.
6103 
6104     \note This method has been added in 5.15.2 to simplify writing code that is portable
6105     between Qt 5.15 and Qt 6.
6106 */
6107 
6108 /*! \fn QString &QString::operator+=(char ch)
6109 
6110     \overload operator+=()
6111 
6112     Appends the character \a ch to this string. Note that the character is
6113     converted to Unicode using the fromLatin1() function, unlike other 8-bit
6114     functions that operate on UTF-8 data.
6115 
6116     You can disable this function by defining \c QT_NO_CAST_FROM_ASCII
6117     when you compile your applications. This can be useful if you want
6118     to ensure that all user-visible strings go through QObject::tr(),
6119     for example.
6120 
6121     \sa QT_NO_CAST_FROM_ASCII
6122 */
6123 
6124 /*! \fn QString &QString::operator+=(QChar ch)
6125 
6126     \overload operator+=()
6127 
6128     Appends the character \a ch to the string.
6129 */
6130 
6131 /*! \fn QString &QString::operator+=(QChar::SpecialCharacter c)
6132 
6133     \overload operator+=()
6134 
6135     \internal
6136 */
6137 
6138 /*!
6139     \fn bool operator==(const char *s1, const QString &s2)
6140 
6141     \overload  operator==()
6142     \relates QString
6143 
6144     Returns \c true if \a s1 is equal to \a s2; otherwise returns \c false.
6145     Note that no string is equal to \a s1 being 0.
6146 
6147     Equivalent to \c {s1 != 0 && compare(s1, s2) == 0}.
6148 */
6149 
6150 /*!
6151     \fn bool operator!=(const char *s1, const QString &s2)
6152     \relates QString
6153 
6154     Returns \c true if \a s1 is not equal to \a s2; otherwise returns
6155     \c false.
6156 
6157     For \a s1 != 0, this is equivalent to \c {compare(} \a s1, \a s2
6158     \c {) != 0}. Note that no string is equal to \a s1 being 0.
6159 */
6160 
6161 /*!
6162     \fn bool operator<(const char *s1, const QString &s2)
6163     \relates QString
6164 
6165     Returns \c true if \a s1 is lexically less than \a s2; otherwise
6166     returns \c false.  For \a s1 != 0, this is equivalent to \c
6167     {compare(s1, s2) < 0}.
6168 
6169     \sa {Comparing Strings}
6170 */
6171 
6172 /*!
6173     \fn bool operator<=(const char *s1, const QString &s2)
6174     \relates QString
6175 
6176     Returns \c true if \a s1 is lexically less than or equal to \a s2;
6177     otherwise returns \c false.  For \a s1 != 0, this is equivalent to \c
6178     {compare(s1, s2) <= 0}.
6179 
6180     \sa {Comparing Strings}
6181 */
6182 
6183 /*!
6184     \fn bool operator>(const char *s1, const QString &s2)
6185     \relates QString
6186 
6187     Returns \c true if \a s1 is lexically greater than \a s2; otherwise
6188     returns \c false.  Equivalent to \c {compare(s1, s2) > 0}.
6189 
6190     \sa {Comparing Strings}
6191 */
6192 
6193 /*!
6194     \fn bool operator>=(const char *s1, const QString &s2)
6195     \relates QString
6196 
6197     Returns \c true if \a s1 is lexically greater than or equal to \a s2;
6198     otherwise returns \c false.  For \a s1 != 0, this is equivalent to \c
6199     {compare(s1, s2) >= 0}.
6200 
6201     \sa {Comparing Strings}
6202 */
6203 
6204 /*!
6205     \fn const QString operator+(const QString &s1, const QString &s2)
6206     \relates QString
6207 
6208     Returns a string which is the result of concatenating \a s1 and \a
6209     s2.
6210 */
6211 
6212 /*!
6213     \fn const QString operator+(const QString &s1, const char *s2)
6214     \relates QString
6215 
6216     Returns a string which is the result of concatenating \a s1 and \a
6217     s2 (\a s2 is converted to Unicode using the QString::fromUtf8()
6218     function).
6219 
6220     \sa QString::fromUtf8()
6221 */
6222 
6223 /*!
6224     \fn const QString operator+(const char *s1, const QString &s2)
6225     \relates QString
6226 
6227     Returns a string which is the result of concatenating \a s1 and \a
6228     s2 (\a s1 is converted to Unicode using the QString::fromUtf8()
6229     function).
6230 
6231     \sa QString::fromUtf8()
6232 */
6233 
6234 /*!
6235     \fn const QString operator+(const QString &s, char ch)
6236     \relates QString
6237 
6238     Returns a string which is the result of concatenating the string
6239     \a s and the character \a ch.
6240 */
6241 
6242 /*!
6243     \fn const QString operator+(char ch, const QString &s)
6244     \relates QString
6245 
6246     Returns a string which is the result of concatenating the
6247     character \a ch and the string \a s.
6248 */
6249 
6250 /*!
6251     \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs)
6252     \since 4.2
6253 
6254     Compares \a s1 with \a s2 and returns an integer less than, equal
6255     to, or greater than zero if \a s1 is less than, equal to, or
6256     greater than \a s2.
6257 
6258     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
6259     otherwise the comparison is case insensitive.
6260 
6261     Case sensitive comparison is based exclusively on the numeric
6262     Unicode values of the characters and is very fast, but is not what
6263     a human would expect.  Consider sorting user-visible strings with
6264     localeAwareCompare().
6265 
6266     \snippet qstring/main.cpp 16
6267 
6268     \sa operator==(), operator<(), operator>(), {Comparing Strings}
6269 */
6270 
6271 /*!
6272     \fn int QString::compare(const QString &s1, QLatin1String s2, Qt::CaseSensitivity cs)
6273     \since 4.2
6274     \overload compare()
6275 
6276     Performs a comparison of \a s1 and \a s2, using the case
6277     sensitivity setting \a cs.
6278 */
6279 
6280 /*!
6281     \fn int QString::compare(QLatin1String s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
6282 
6283     \since 4.2
6284     \overload compare()
6285 
6286     Performs a comparison of \a s1 and \a s2, using the case
6287     sensitivity setting \a cs.
6288 */
6289 
6290 /*!
6291     \fn int QString::compare(QStringView s, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
6292 
6293     \since 5.12
6294     \overload compare()
6295 
6296     Performs a comparison of this with \a s, using the case
6297     sensitivity setting \a cs.
6298 */
6299 
6300 /*!
6301     \fn int QString::compare(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
6302 
6303     \since 5.14
6304     \overload compare()
6305 
6306     Performs a comparison of this with \a ch, using the case
6307     sensitivity setting \a cs.
6308 */
6309 
6310 #if QT_STRINGVIEW_LEVEL < 2
6311 /*!
6312     \overload compare()
6313     \since 4.2
6314 
6315     Lexically compares this string with the \a other string and
6316     returns an integer less than, equal to, or greater than zero if
6317     this string is less than, equal to, or greater than the other
6318     string.
6319 
6320     Same as compare(*this, \a other, \a cs).
6321 */
compare(const QString & other,Qt::CaseSensitivity cs) const6322 int QString::compare(const QString &other, Qt::CaseSensitivity cs) const noexcept
6323 {
6324     return qt_compare_strings(*this, other, cs);
6325 }
6326 #endif
6327 
6328 /*!
6329     \internal
6330     \since 4.5
6331 */
compare_helper(const QChar * data1,int length1,const QChar * data2,int length2,Qt::CaseSensitivity cs)6332 int QString::compare_helper(const QChar *data1, int length1, const QChar *data2, int length2,
6333                             Qt::CaseSensitivity cs) noexcept
6334 {
6335     Q_ASSERT(length1 >= 0);
6336     Q_ASSERT(length2 >= 0);
6337     Q_ASSERT(data1 || length1 == 0);
6338     Q_ASSERT(data2 || length2 == 0);
6339     return qt_compare_strings(QStringView(data1, length1), QStringView(data2, length2), cs);
6340 }
6341 
6342 /*!
6343     \overload compare()
6344     \since 4.2
6345 
6346     Same as compare(*this, \a other, \a cs).
6347 */
compare(QLatin1String other,Qt::CaseSensitivity cs) const6348 int QString::compare(QLatin1String other, Qt::CaseSensitivity cs) const noexcept
6349 {
6350     return qt_compare_strings(*this, other, cs);
6351 }
6352 
6353 #if QT_STRINGVIEW_LEVEL < 2
6354 /*!
6355   \fn int QString::compare(const QStringRef &ref, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
6356   \overload compare()
6357 
6358   Compares the string reference, \a ref, with the string and returns
6359   an integer less than, equal to, or greater than zero if the string
6360   is less than, equal to, or greater than \a ref.
6361 */
6362 #endif
6363 
6364 /*!
6365     \internal
6366     \since 5.0
6367 */
compare_helper(const QChar * data1,int length1,const char * data2,int length2,Qt::CaseSensitivity cs)6368 int QString::compare_helper(const QChar *data1, int length1, const char *data2, int length2,
6369                             Qt::CaseSensitivity cs)
6370 {
6371     Q_ASSERT(length1 >= 0);
6372     Q_ASSERT(data1 || length1 == 0);
6373     if (!data2)
6374         return length1;
6375     if (Q_UNLIKELY(length2 < 0))
6376         length2 = int(strlen(data2));
6377     // ### make me nothrow in all cases
6378     QVarLengthArray<ushort> s2(length2);
6379     const auto beg = reinterpret_cast<QChar *>(s2.data());
6380     const auto end = QUtf8::convertToUnicode(beg, data2, length2);
6381     return qt_compare_strings(QStringView(data1, length1), QStringView(beg, end - beg), cs);
6382 }
6383 
6384 /*!
6385   \fn int QString::compare(const QString &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
6386   \overload compare()
6387 */
6388 
6389 /*!
6390     \internal
6391     \since 4.5
6392 */
compare_helper(const QChar * data1,int length1,QLatin1String s2,Qt::CaseSensitivity cs)6393 int QString::compare_helper(const QChar *data1, int length1, QLatin1String s2,
6394                             Qt::CaseSensitivity cs) noexcept
6395 {
6396     Q_ASSERT(length1 >= 0);
6397     Q_ASSERT(data1 || length1 == 0);
6398     return qt_compare_strings(QStringView(data1, length1), s2, cs);
6399 }
6400 
6401 /*!
6402     \fn int QString::localeAwareCompare(const QString & s1, const QString & s2)
6403 
6404     Compares \a s1 with \a s2 and returns an integer less than, equal
6405     to, or greater than zero if \a s1 is less than, equal to, or
6406     greater than \a s2.
6407 
6408     The comparison is performed in a locale- and also
6409     platform-dependent manner. Use this function to present sorted
6410     lists of strings to the user.
6411 
6412     \sa compare(), QLocale, {Comparing Strings}
6413 */
6414 
6415 /*!
6416     \fn int QString::localeAwareCompare(const QStringRef &other) const
6417     \since 4.5
6418     \overload localeAwareCompare()
6419 
6420     Compares this string with the \a other string and returns an
6421     integer less than, equal to, or greater than zero if this string
6422     is less than, equal to, or greater than the \a other string.
6423 
6424     The comparison is performed in a locale- and also
6425     platform-dependent manner. Use this function to present sorted
6426     lists of strings to the user.
6427 
6428     Same as \c {localeAwareCompare(*this, other)}.
6429 
6430     \sa {Comparing Strings}
6431 */
6432 
6433 /*!
6434     \fn int QString::localeAwareCompare(QStringView other) const
6435     \since 5.15.2
6436     \overload localeAwareCompare()
6437 
6438     Compares this string with the \a other string and returns an
6439     integer less than, equal to, or greater than zero if this string
6440     is less than, equal to, or greater than the \a other string.
6441 
6442     The comparison is performed in a locale- and also
6443     platform-dependent manner. Use this function to present sorted
6444     lists of strings to the user.
6445 
6446     Same as \c {localeAwareCompare(*this, other)}.
6447 
6448     \note This method has been added in 5.15.2 to simplify writing code that is portable
6449     between Qt 5.15 and Qt 6.
6450 
6451     \sa {Comparing Strings}
6452 */
6453 
6454 /*!
6455     \fn int QString::localeAwareCompare(const QString &s1, const QStringRef &s2)
6456     \since 4.5
6457     \overload localeAwareCompare()
6458 
6459     Compares \a s1 with \a s2 and returns an integer less than, equal
6460     to, or greater than zero if \a s1 is less than, equal to, or
6461     greater than \a s2.
6462 
6463     The comparison is performed in a locale- and also
6464     platform-dependent manner. Use this function to present sorted
6465     lists of strings to the user.
6466 
6467     \sa {Comparing Strings}
6468 */
6469 
6470 /*!
6471     \fn int QString::localeAwareCompare(QStringView s1, QStringView s2)
6472     \since 5.15.2
6473     \overload localeAwareCompare()
6474 
6475     Compares \a s1 with \a s2 and returns an integer less than, equal
6476     to, or greater than zero if \a s1 is less than, equal to, or
6477     greater than \a s2.
6478 
6479     The comparison is performed in a locale- and also
6480     platform-dependent manner. Use this function to present sorted
6481     lists of strings to the user.
6482 
6483     \note This method has been added in 5.15.2 to simplify writing code that is portable
6484     between Qt 5.15 and Qt 6.
6485 
6486     \sa {Comparing Strings}
6487 */
6488 
6489 #if !defined(CSTR_LESS_THAN)
6490 #define CSTR_LESS_THAN    1
6491 #define CSTR_EQUAL        2
6492 #define CSTR_GREATER_THAN 3
6493 #endif
6494 
6495 /*!
6496     \overload localeAwareCompare()
6497 
6498     Compares this string with the \a other string and returns an
6499     integer less than, equal to, or greater than zero if this string
6500     is less than, equal to, or greater than the \a other string.
6501 
6502     The comparison is performed in a locale- and also
6503     platform-dependent manner. Use this function to present sorted
6504     lists of strings to the user.
6505 
6506     Same as \c {localeAwareCompare(*this, other)}.
6507 
6508     \sa {Comparing Strings}
6509 */
localeAwareCompare(const QString & other) const6510 int QString::localeAwareCompare(const QString &other) const
6511 {
6512     return localeAwareCompare_helper(constData(), length(), other.constData(), other.length());
6513 }
6514 
6515 #if QT_CONFIG(icu)
Q_GLOBAL_STATIC(QThreadStorage<QCollator>,defaultCollator)6516 Q_GLOBAL_STATIC(QThreadStorage<QCollator>, defaultCollator)
6517 #endif
6518 
6519 /*!
6520     \internal
6521     \since 4.5
6522 */
6523 int QString::localeAwareCompare_helper(const QChar *data1, int length1,
6524                                        const QChar *data2, int length2)
6525 {
6526     Q_ASSERT(length1 >= 0);
6527     Q_ASSERT(data1 || length1 == 0);
6528     Q_ASSERT(length2 >= 0);
6529     Q_ASSERT(data2 || length2 == 0);
6530 
6531     // do the right thing for null and empty
6532     if (length1 == 0 || length2 == 0)
6533         return qt_compare_strings(QStringView(data1, length1), QStringView(data2, length2),
6534                                Qt::CaseSensitive);
6535 
6536 #if QT_CONFIG(icu)
6537     if (!defaultCollator()->hasLocalData())
6538         defaultCollator()->setLocalData(QCollator());
6539     return defaultCollator()->localData().compare(data1, length1, data2, length2);
6540 #else
6541     const QString lhs = QString::fromRawData(data1, length1).normalized(QString::NormalizationForm_C);
6542     const QString rhs = QString::fromRawData(data2, length2).normalized(QString::NormalizationForm_C);
6543 #  if defined(Q_OS_WIN)
6544     int res = CompareStringEx(LOCALE_NAME_USER_DEFAULT, 0, (LPWSTR)lhs.constData(), lhs.length(), (LPWSTR)rhs.constData(), rhs.length(), NULL, NULL, 0);
6545 
6546     switch (res) {
6547     case CSTR_LESS_THAN:
6548         return -1;
6549     case CSTR_GREATER_THAN:
6550         return 1;
6551     default:
6552         return 0;
6553     }
6554 #  elif defined (Q_OS_DARWIN)
6555     // Use CFStringCompare for comparing strings on Mac. This makes Qt order
6556     // strings the same way as native applications do, and also respects
6557     // the "Order for sorted lists" setting in the International preferences
6558     // panel.
6559     const CFStringRef thisString =
6560         CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
6561             reinterpret_cast<const UniChar *>(lhs.constData()), lhs.length(), kCFAllocatorNull);
6562     const CFStringRef otherString =
6563         CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault,
6564             reinterpret_cast<const UniChar *>(rhs.constData()), rhs.length(), kCFAllocatorNull);
6565 
6566     const int result = CFStringCompare(thisString, otherString, kCFCompareLocalized);
6567     CFRelease(thisString);
6568     CFRelease(otherString);
6569     return result;
6570 #  elif defined(Q_OS_UNIX)
6571     // declared in <string.h>
6572     int delta = strcoll(lhs.toLocal8Bit().constData(), rhs.toLocal8Bit().constData());
6573     if (delta == 0)
6574         delta = qt_compare_strings(lhs, rhs, Qt::CaseSensitive);
6575     return delta;
6576 #  else
6577 #     error "This case shouldn't happen"
6578     return qt_compare_strings(lhs, rhs, Qt::CaseSensitive);
6579 #  endif
6580 #endif // !QT_CONFIG(icu)
6581 }
6582 
6583 
6584 /*!
6585     \fn const QChar *QString::unicode() const
6586 
6587     Returns a Unicode representation of the string.
6588     The result remains valid until the string is modified.
6589 
6590     \note The returned string may not be '\\0'-terminated.
6591     Use size() to determine the length of the array.
6592 
6593     \sa utf16(), fromRawData()
6594 */
6595 
6596 /*!
6597     \fn const ushort *QString::utf16() const
6598 
6599     Returns the QString as a '\\0\'-terminated array of unsigned
6600     shorts. The result remains valid until the string is modified.
6601 
6602     The returned string is in host byte order.
6603 
6604     \sa unicode()
6605 */
6606 
utf16() const6607 const ushort *QString::utf16() const
6608 {
6609     if (IS_RAW_DATA(d)) {
6610         // ensure '\0'-termination for ::fromRawData strings
6611         const_cast<QString*>(this)->reallocData(uint(d->size) + 1u);
6612     }
6613     return d->data();
6614 }
6615 
6616 /*!
6617     Returns a string of size \a width that contains this string
6618     padded by the \a fill character.
6619 
6620     If \a truncate is \c false and the size() of the string is more than
6621     \a width, then the returned string is a copy of the string.
6622 
6623     \snippet qstring/main.cpp 32
6624 
6625     If \a truncate is \c true and the size() of the string is more than
6626     \a width, then any characters in a copy of the string after
6627     position \a width are removed, and the copy is returned.
6628 
6629     \snippet qstring/main.cpp 33
6630 
6631     \sa rightJustified()
6632 */
6633 
leftJustified(int width,QChar fill,bool truncate) const6634 QString QString::leftJustified(int width, QChar fill, bool truncate) const
6635 {
6636     QString result;
6637     int len = length();
6638     int padlen = width - len;
6639     if (padlen > 0) {
6640         result.resize(len+padlen);
6641         if (len)
6642             memcpy(result.d->data(), d->data(), sizeof(QChar)*len);
6643         QChar *uc = (QChar*)result.d->data() + len;
6644         while (padlen--)
6645            * uc++ = fill;
6646     } else {
6647         if (truncate)
6648             result = left(width);
6649         else
6650             result = *this;
6651     }
6652     return result;
6653 }
6654 
6655 /*!
6656     Returns a string of size() \a width that contains the \a fill
6657     character followed by the string. For example:
6658 
6659     \snippet qstring/main.cpp 49
6660 
6661     If \a truncate is \c false and the size() of the string is more than
6662     \a width, then the returned string is a copy of the string.
6663 
6664     If \a truncate is true and the size() of the string is more than
6665     \a width, then the resulting string is truncated at position \a
6666     width.
6667 
6668     \snippet qstring/main.cpp 50
6669 
6670     \sa leftJustified()
6671 */
6672 
rightJustified(int width,QChar fill,bool truncate) const6673 QString QString::rightJustified(int width, QChar fill, bool truncate) const
6674 {
6675     QString result;
6676     int len = length();
6677     int padlen = width - len;
6678     if (padlen > 0) {
6679         result.resize(len+padlen);
6680         QChar *uc = (QChar*)result.d->data();
6681         while (padlen--)
6682            * uc++ = fill;
6683         if (len)
6684           memcpy(static_cast<void *>(uc), static_cast<const void *>(d->data()), sizeof(QChar)*len);
6685     } else {
6686         if (truncate)
6687             result = left(width);
6688         else
6689             result = *this;
6690     }
6691     return result;
6692 }
6693 
6694 /*!
6695     \fn QString QString::toLower() const
6696 
6697     Returns a lowercase copy of the string.
6698 
6699     \snippet qstring/main.cpp 75
6700 
6701     The case conversion will always happen in the 'C' locale. For locale dependent
6702     case folding use QLocale::toLower()
6703 
6704     \sa toUpper(), QLocale::toLower()
6705 */
6706 
6707 namespace QUnicodeTables {
6708 /*
6709     \internal
6710     Converts the \a str string starting from the position pointed to by the \a
6711     it iterator, using the Unicode case traits \c Traits, and returns the
6712     result. The input string must not be empty (the convertCase function below
6713     guarantees that).
6714 
6715     The string type \c{T} is also a template and is either \c{const QString} or
6716     \c{QString}. This function can do both copy-conversion and in-place
6717     conversion depending on the state of the \a str parameter:
6718     \list
6719        \li \c{T} is \c{const QString}: copy-convert
6720        \li \c{T} is \c{QString} and its refcount != 1: copy-convert
6721        \li \c{T} is \c{QString} and its refcount == 1: in-place convert
6722     \endlist
6723 
6724     In copy-convert mode, the local variable \c{s} is detached from the input
6725     \a str. In the in-place convert mode, \a str is in moved-from state (which
6726     this function requires to be a valid, empty string) and \c{s} contains the
6727     only copy of the string, without reallocation (thus, \a it is still valid).
6728 
6729     There is one pathological case left: when the in-place conversion needs to
6730     reallocate memory to grow the buffer. In that case, we need to adjust the \a
6731     it pointer.
6732  */
6733 template <typename T>
6734 Q_NEVER_INLINE
detachAndConvertCase(T & str,QStringIterator it,QUnicodeTables::Case which)6735 static QString detachAndConvertCase(T &str, QStringIterator it, QUnicodeTables::Case which)
6736 {
6737     Q_ASSERT(!str.isEmpty());
6738     QString s = std::move(str);             // will copy if T is const QString
6739     QChar *pp = s.begin() + it.index(); // will detach if necessary
6740 
6741     do {
6742         uint uc = it.nextUnchecked();
6743 
6744         const auto fold = qGetProp(uc)->cases[which];
6745         signed short caseDiff = fold.diff;
6746 
6747         if (Q_UNLIKELY(fold.special)) {
6748             const ushort *specialCase = specialCaseMap + caseDiff;
6749             ushort length = *specialCase++;
6750 
6751             if (Q_LIKELY(length == 1)) {
6752                 *pp++ = QChar(*specialCase);
6753             } else {
6754                 // slow path: the string is growing
6755                 int inpos = it.index() - 1;
6756                 int outpos = pp - s.constBegin();
6757 
6758                 s.replace(outpos, 1, reinterpret_cast<const QChar *>(specialCase), length);
6759                 pp = const_cast<QChar *>(s.constBegin()) + outpos + length;
6760 
6761                 // do we need to adjust the input iterator too?
6762                 // if it is pointing to s's data, str is empty
6763                 if (str.isEmpty())
6764                     it = QStringIterator(s.constBegin(), inpos + length, s.constEnd());
6765             }
6766         } else if (Q_UNLIKELY(QChar::requiresSurrogates(uc))) {
6767             // so far, case convertion never changes planes (guaranteed by the qunicodetables generator)
6768             pp++;
6769             *pp++ = QChar(QChar::lowSurrogate(uc + caseDiff));
6770         } else {
6771             *pp++ = QChar(uc + caseDiff);
6772         }
6773     } while (it.hasNext());
6774 
6775     return s;
6776 }
6777 
6778 template <typename T>
convertCase(T & str,QUnicodeTables::Case which)6779 static QString convertCase(T &str, QUnicodeTables::Case which)
6780 {
6781     const QChar *p = str.constBegin();
6782     const QChar *e = p + str.size();
6783 
6784     // this avoids out of bounds check in the loop
6785     while (e != p && e[-1].isHighSurrogate())
6786         --e;
6787 
6788     QStringIterator it(p, e);
6789     while (it.hasNext()) {
6790         uint uc = it.nextUnchecked();
6791         if (qGetProp(uc)->cases[which].diff) {
6792             it.recedeUnchecked();
6793             return detachAndConvertCase(str, it, which);
6794         }
6795     }
6796     return std::move(str);
6797 }
6798 } // namespace QUnicodeTables
6799 
toLower_helper(const QString & str)6800 QString QString::toLower_helper(const QString &str)
6801 {
6802     return QUnicodeTables::convertCase(str, QUnicodeTables::LowerCase);
6803 }
6804 
toLower_helper(QString & str)6805 QString QString::toLower_helper(QString &str)
6806 {
6807     return QUnicodeTables::convertCase(str, QUnicodeTables::LowerCase);
6808 }
6809 
6810 /*!
6811     \fn QString QString::toCaseFolded() const
6812 
6813     Returns the case folded equivalent of the string. For most Unicode
6814     characters this is the same as toLower().
6815 */
6816 
toCaseFolded_helper(const QString & str)6817 QString QString::toCaseFolded_helper(const QString &str)
6818 {
6819     return QUnicodeTables::convertCase(str, QUnicodeTables::CaseFold);
6820 }
6821 
toCaseFolded_helper(QString & str)6822 QString QString::toCaseFolded_helper(QString &str)
6823 {
6824     return QUnicodeTables::convertCase(str, QUnicodeTables::CaseFold);
6825 }
6826 
6827 /*!
6828     \fn QString QString::toUpper() const
6829 
6830     Returns an uppercase copy of the string.
6831 
6832     \snippet qstring/main.cpp 81
6833 
6834     The case conversion will always happen in the 'C' locale. For locale dependent
6835     case folding use QLocale::toUpper()
6836 
6837     \sa toLower(), QLocale::toLower()
6838 */
6839 
toUpper_helper(const QString & str)6840 QString QString::toUpper_helper(const QString &str)
6841 {
6842     return QUnicodeTables::convertCase(str, QUnicodeTables::UpperCase);
6843 }
6844 
toUpper_helper(QString & str)6845 QString QString::toUpper_helper(QString &str)
6846 {
6847     return QUnicodeTables::convertCase(str, QUnicodeTables::UpperCase);
6848 }
6849 
6850 #if QT_DEPRECATED_SINCE(5, 14)
6851 /*!
6852     \obsolete
6853 
6854     Use asprintf(), arg() or QTextStream instead.
6855 */
sprintf(const char * cformat,...)6856 QString &QString::sprintf(const char *cformat, ...)
6857 {
6858     va_list ap;
6859     va_start(ap, cformat);
6860     *this = vasprintf(cformat, ap);
6861     va_end(ap);
6862     return *this;
6863 }
6864 #endif
6865 
6866 // ### Qt 6: Consider whether this function shouldn't be removed See task 202871.
6867 /*!
6868     \since 5.5
6869 
6870     Safely builds a formatted string from the format string \a cformat
6871     and an arbitrary list of arguments.
6872 
6873     The format string supports the conversion specifiers, length modifiers,
6874     and flags provided by printf() in the standard C++ library. The \a cformat
6875     string and \c{%s} arguments must be UTF-8 encoded.
6876 
6877     \note The \c{%lc} escape sequence expects a unicode character of type
6878     \c char16_t, or \c ushort (as returned by QChar::unicode()).
6879     The \c{%ls} escape sequence expects a pointer to a zero-terminated array
6880     of unicode characters of type \c char16_t, or ushort (as returned by
6881     QString::utf16()). This is at odds with the printf() in the standard C++
6882     library, which defines \c {%lc} to print a wchar_t and \c{%ls} to print
6883     a \c{wchar_t*}, and might also produce compiler warnings on platforms
6884     where the size of \c {wchar_t} is not 16 bits.
6885 
6886     \warning We do not recommend using QString::asprintf() in new Qt
6887     code. Instead, consider using QTextStream or arg(), both of
6888     which support Unicode strings seamlessly and are type-safe.
6889     Here is an example that uses QTextStream:
6890 
6891     \snippet qstring/main.cpp 64
6892 
6893     For \l {QObject::tr()}{translations}, especially if the strings
6894     contains more than one escape sequence, you should consider using
6895     the arg() function instead. This allows the order of the
6896     replacements to be controlled by the translator.
6897 
6898     \sa arg()
6899 */
6900 
asprintf(const char * cformat,...)6901 QString QString::asprintf(const char *cformat, ...)
6902 {
6903     va_list ap;
6904     va_start(ap, cformat);
6905     const QString s = vasprintf(cformat, ap);
6906     va_end(ap);
6907     return s;
6908 }
6909 
6910 #if QT_DEPRECATED_SINCE(5, 14)
6911 /*!
6912     \obsolete
6913 
6914     Use vasprintf(), arg() or QTextStream instead.
6915 */
vsprintf(const char * cformat,va_list ap)6916 QString &QString::vsprintf(const char *cformat, va_list ap)
6917 {
6918     return *this = vasprintf(cformat, ap);
6919 }
6920 #endif
6921 
append_utf8(QString & qs,const char * cs,int len)6922 static void append_utf8(QString &qs, const char *cs, int len)
6923 {
6924     const int oldSize = qs.size();
6925     qs.resize(oldSize + len);
6926     const QChar *newEnd = QUtf8::convertToUnicode(qs.data() + oldSize, cs, len);
6927     qs.resize(newEnd - qs.constData());
6928 }
6929 
parse_flag_characters(const char * & c)6930 static uint parse_flag_characters(const char * &c) noexcept
6931 {
6932     uint flags = QLocaleData::ZeroPadExponent;
6933     while (true) {
6934         switch (*c) {
6935         case '#':
6936             flags |= QLocaleData::ShowBase | QLocaleData::AddTrailingZeroes
6937                     | QLocaleData::ForcePoint;
6938             break;
6939         case '0': flags |= QLocaleData::ZeroPadded; break;
6940         case '-': flags |= QLocaleData::LeftAdjusted; break;
6941         case ' ': flags |= QLocaleData::BlankBeforePositive; break;
6942         case '+': flags |= QLocaleData::AlwaysShowSign; break;
6943         case '\'': flags |= QLocaleData::ThousandsGroup; break;
6944         default: return flags;
6945         }
6946         ++c;
6947     }
6948 }
6949 
parse_field_width(const char * & c)6950 static int parse_field_width(const char * &c)
6951 {
6952     Q_ASSERT(qIsDigit(*c));
6953 
6954     // can't be negative - started with a digit
6955     // contains at least one digit
6956     const char *endp;
6957     bool ok;
6958     const qulonglong result = qstrtoull(c, &endp, 10, &ok);
6959     c = endp;
6960     while (qIsDigit(*c)) // preserve Qt 5.5 behavior of consuming all digits, no matter how many
6961         ++c;
6962     return ok && result < qulonglong(std::numeric_limits<int>::max()) ? int(result) : 0;
6963 }
6964 
6965 enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t };
6966 
can_consume(const char * & c,char ch)6967 static inline bool can_consume(const char * &c, char ch) noexcept
6968 {
6969     if (*c == ch) {
6970         ++c;
6971         return true;
6972     }
6973     return false;
6974 }
6975 
parse_length_modifier(const char * & c)6976 static LengthMod parse_length_modifier(const char * &c) noexcept
6977 {
6978     switch (*c++) {
6979     case 'h': return can_consume(c, 'h') ? lm_hh : lm_h;
6980     case 'l': return can_consume(c, 'l') ? lm_ll : lm_l;
6981     case 'L': return lm_L;
6982     case 'j': return lm_j;
6983     case 'z':
6984     case 'Z': return lm_z;
6985     case 't': return lm_t;
6986     }
6987     --c; // don't consume *c - it wasn't a flag
6988     return lm_none;
6989 }
6990 
6991 /*!
6992     \fn QString QString::vasprintf(const char *cformat, va_list ap)
6993     \since 5.5
6994 
6995     Equivalent method to asprintf(), but takes a va_list \a ap
6996     instead a list of variable arguments. See the asprintf()
6997     documentation for an explanation of \a cformat.
6998 
6999     This method does not call the va_end macro, the caller
7000     is responsible to call va_end on \a ap.
7001 
7002     \sa asprintf()
7003 */
7004 
vasprintf(const char * cformat,va_list ap)7005 QString QString::vasprintf(const char *cformat, va_list ap)
7006 {
7007     if (!cformat || !*cformat) {
7008         // Qt 1.x compat
7009         return fromLatin1("");
7010     }
7011 
7012     // Parse cformat
7013 
7014     QString result;
7015     const char *c = cformat;
7016     for (;;) {
7017         // Copy non-escape chars to result
7018         const char *cb = c;
7019         while (*c != '\0' && *c != '%')
7020             c++;
7021         append_utf8(result, cb, int(c - cb));
7022 
7023         if (*c == '\0')
7024             break;
7025 
7026         // Found '%'
7027         const char *escape_start = c;
7028         ++c;
7029 
7030         if (*c == '\0') {
7031             result.append(QLatin1Char('%')); // a % at the end of the string - treat as non-escape text
7032             break;
7033         }
7034         if (*c == '%') {
7035             result.append(QLatin1Char('%')); // %%
7036             ++c;
7037             continue;
7038         }
7039 
7040         uint flags = parse_flag_characters(c);
7041 
7042         if (*c == '\0') {
7043             result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
7044             break;
7045         }
7046 
7047         // Parse field width
7048         int width = -1; // -1 means unspecified
7049         if (qIsDigit(*c)) {
7050             width = parse_field_width(c);
7051         } else if (*c == '*') { // can't parse this in another function, not portably, at least
7052             width = va_arg(ap, int);
7053             if (width < 0)
7054                 width = -1; // treat all negative numbers as unspecified
7055             ++c;
7056         }
7057 
7058         if (*c == '\0') {
7059             result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
7060             break;
7061         }
7062 
7063         // Parse precision
7064         int precision = -1; // -1 means unspecified
7065         if (*c == '.') {
7066             ++c;
7067             if (qIsDigit(*c)) {
7068                 precision = parse_field_width(c);
7069             } else if (*c == '*') { // can't parse this in another function, not portably, at least
7070                 precision = va_arg(ap, int);
7071                 if (precision < 0)
7072                     precision = -1; // treat all negative numbers as unspecified
7073                 ++c;
7074             }
7075         }
7076 
7077         if (*c == '\0') {
7078             result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
7079             break;
7080         }
7081 
7082         const LengthMod length_mod = parse_length_modifier(c);
7083 
7084         if (*c == '\0') {
7085             result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text
7086             break;
7087         }
7088 
7089         // Parse the conversion specifier and do the conversion
7090         QString subst;
7091         switch (*c) {
7092             case 'd':
7093             case 'i': {
7094                 qint64 i;
7095                 switch (length_mod) {
7096                     case lm_none: i = va_arg(ap, int); break;
7097                     case lm_hh: i = va_arg(ap, int); break;
7098                     case lm_h: i = va_arg(ap, int); break;
7099                     case lm_l: i = va_arg(ap, long int); break;
7100                     case lm_ll: i = va_arg(ap, qint64); break;
7101                     case lm_j: i = va_arg(ap, long int); break;
7102                     case lm_z: i = va_arg(ap, size_t); break;
7103                     case lm_t: i = va_arg(ap, int); break;
7104                     default: i = 0; break;
7105                 }
7106                 subst = QLocaleData::c()->longLongToString(i, precision, 10, width, flags);
7107                 ++c;
7108                 break;
7109             }
7110             case 'o':
7111             case 'u':
7112             case 'x':
7113             case 'X': {
7114                 quint64 u;
7115                 switch (length_mod) {
7116                     case lm_none: u = va_arg(ap, uint); break;
7117                     case lm_hh: u = va_arg(ap, uint); break;
7118                     case lm_h: u = va_arg(ap, uint); break;
7119                     case lm_l: u = va_arg(ap, ulong); break;
7120                     case lm_ll: u = va_arg(ap, quint64); break;
7121                     case lm_z: u = va_arg(ap, size_t); break;
7122                     default: u = 0; break;
7123                 }
7124 
7125                 if (qIsUpper(*c))
7126                     flags |= QLocaleData::CapitalEorX;
7127 
7128                 int base = 10;
7129                 switch (qToLower(*c)) {
7130                     case 'o':
7131                         base = 8; break;
7132                     case 'u':
7133                         base = 10; break;
7134                     case 'x':
7135                         base = 16; break;
7136                     default: break;
7137                 }
7138                 subst = QLocaleData::c()->unsLongLongToString(u, precision, base, width, flags);
7139                 ++c;
7140                 break;
7141             }
7142             case 'E':
7143             case 'e':
7144             case 'F':
7145             case 'f':
7146             case 'G':
7147             case 'g':
7148             case 'A':
7149             case 'a': {
7150                 double d;
7151                 if (length_mod == lm_L)
7152                     d = va_arg(ap, long double); // not supported - converted to a double
7153                 else
7154                     d = va_arg(ap, double);
7155 
7156                 if (qIsUpper(*c))
7157                     flags |= QLocaleData::CapitalEorX;
7158 
7159                 QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
7160                 switch (qToLower(*c)) {
7161                     case 'e': form = QLocaleData::DFExponent; break;
7162                     case 'a':                             // not supported - decimal form used instead
7163                     case 'f': form = QLocaleData::DFDecimal; break;
7164                     case 'g': form = QLocaleData::DFSignificantDigits; break;
7165                     default: break;
7166                 }
7167                 subst = QLocaleData::c()->doubleToString(d, precision, form, width, flags);
7168                 ++c;
7169                 break;
7170             }
7171             case 'c': {
7172                 if (length_mod == lm_l)
7173                     subst = QChar((ushort) va_arg(ap, int));
7174                 else
7175                     subst = QLatin1Char((uchar) va_arg(ap, int));
7176                 ++c;
7177                 break;
7178             }
7179             case 's': {
7180                 if (length_mod == lm_l) {
7181                     const ushort *buff = va_arg(ap, const ushort*);
7182                     const ushort *ch = buff;
7183                     while (*ch != 0)
7184                         ++ch;
7185                     subst.setUtf16(buff, ch - buff);
7186                 } else
7187                     subst = QString::fromUtf8(va_arg(ap, const char*));
7188                 if (precision != -1)
7189                     subst.truncate(precision);
7190                 ++c;
7191                 break;
7192             }
7193             case 'p': {
7194                 void *arg = va_arg(ap, void*);
7195                 const quint64 i = reinterpret_cast<quintptr>(arg);
7196                 flags |= QLocaleData::ShowBase;
7197                 subst = QLocaleData::c()->unsLongLongToString(i, precision, 16, width, flags);
7198                 ++c;
7199                 break;
7200             }
7201             case 'n':
7202                 switch (length_mod) {
7203                     case lm_hh: {
7204                         signed char *n = va_arg(ap, signed char*);
7205                         *n = result.length();
7206                         break;
7207                     }
7208                     case lm_h: {
7209                         short int *n = va_arg(ap, short int*);
7210                         *n = result.length();
7211                             break;
7212                     }
7213                     case lm_l: {
7214                         long int *n = va_arg(ap, long int*);
7215                         *n = result.length();
7216                         break;
7217                     }
7218                     case lm_ll: {
7219                         qint64 *n = va_arg(ap, qint64*);
7220                         *n = result.length();
7221                         break;
7222                     }
7223                     default: {
7224                         int *n = va_arg(ap, int*);
7225                         *n = result.length();
7226                         break;
7227                     }
7228                 }
7229                 ++c;
7230                 break;
7231 
7232             default: // bad escape, treat as non-escape text
7233                 for (const char *cc = escape_start; cc != c; ++cc)
7234                     result.append(QLatin1Char(*cc));
7235                 continue;
7236         }
7237 
7238         if (flags & QLocaleData::LeftAdjusted)
7239             result.append(subst.leftJustified(width));
7240         else
7241             result.append(subst.rightJustified(width));
7242     }
7243 
7244     return result;
7245 }
7246 
7247 /*!
7248     Returns the string converted to a \c{long long} using base \a
7249     base, which is 10 by default and must be between 2 and 36, or 0.
7250     Returns 0 if the conversion fails.
7251 
7252     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7253     to \c false, and success by setting *\a{ok} to \c true.
7254 
7255     If \a base is 0, the C language convention is used: If the string
7256     begins with "0x", base 16 is used; if the string begins with "0",
7257     base 8 is used; otherwise, base 10 is used.
7258 
7259     The string conversion will always happen in the 'C' locale. For locale
7260     dependent conversion use QLocale::toLongLong()
7261 
7262     Example:
7263 
7264     \snippet qstring/main.cpp 74
7265 
7266     This function ignores leading and trailing whitespace.
7267 
7268     \sa number(), toULongLong(), toInt(), QLocale::toLongLong()
7269 */
7270 
toLongLong(bool * ok,int base) const7271 qint64 QString::toLongLong(bool *ok, int base) const
7272 {
7273     return toIntegral_helper<qlonglong>(constData(), size(), ok, base);
7274 }
7275 
toIntegral_helper(const QChar * data,int len,bool * ok,int base)7276 qlonglong QString::toIntegral_helper(const QChar *data, int len, bool *ok, int base)
7277 {
7278 #if defined(QT_CHECK_RANGE)
7279     if (base != 0 && (base < 2 || base > 36)) {
7280         qWarning("QString::toULongLong: Invalid base (%d)", base);
7281         base = 10;
7282     }
7283 #endif
7284 
7285     return QLocaleData::c()->stringToLongLong(QStringView(data, len), base, ok, QLocale::RejectGroupSeparator);
7286 }
7287 
7288 
7289 /*!
7290     Returns the string converted to an \c{unsigned long long} using base \a
7291     base, which is 10 by default and must be between 2 and 36, or 0.
7292     Returns 0 if the conversion fails.
7293 
7294     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7295     to \c false, and success by setting *\a{ok} to \c true.
7296 
7297     If \a base is 0, the C language convention is used: If the string
7298     begins with "0x", base 16 is used; if the string begins with "0",
7299     base 8 is used; otherwise, base 10 is used.
7300 
7301     The string conversion will always happen in the 'C' locale. For locale
7302     dependent conversion use QLocale::toULongLong()
7303 
7304     Example:
7305 
7306     \snippet qstring/main.cpp 79
7307 
7308     This function ignores leading and trailing whitespace.
7309 
7310     \sa number(), toLongLong(), QLocale::toULongLong()
7311 */
7312 
toULongLong(bool * ok,int base) const7313 quint64 QString::toULongLong(bool *ok, int base) const
7314 {
7315     return toIntegral_helper<qulonglong>(constData(), size(), ok, base);
7316 }
7317 
toIntegral_helper(const QChar * data,uint len,bool * ok,int base)7318 qulonglong QString::toIntegral_helper(const QChar *data, uint len, bool *ok, int base)
7319 {
7320 #if defined(QT_CHECK_RANGE)
7321     if (base != 0 && (base < 2 || base > 36)) {
7322         qWarning("QString::toULongLong: Invalid base (%d)", base);
7323         base = 10;
7324     }
7325 #endif
7326 
7327     return QLocaleData::c()->stringToUnsLongLong(QStringView(data, len), base, ok,
7328                                                  QLocale::RejectGroupSeparator);
7329 }
7330 
7331 /*!
7332     \fn long QString::toLong(bool *ok, int base) const
7333 
7334     Returns the string converted to a \c long using base \a
7335     base, which is 10 by default and must be between 2 and 36, or 0.
7336     Returns 0 if the conversion fails.
7337 
7338     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7339     to \c false, and success by setting *\a{ok} to \c true.
7340 
7341     If \a base is 0, the C language convention is used: If the string
7342     begins with "0x", base 16 is used; if the string begins with "0",
7343     base 8 is used; otherwise, base 10 is used.
7344 
7345     The string conversion will always happen in the 'C' locale. For locale
7346     dependent conversion use QLocale::toLongLong()
7347 
7348     Example:
7349 
7350     \snippet qstring/main.cpp 73
7351 
7352     This function ignores leading and trailing whitespace.
7353 
7354     \sa number(), toULong(), toInt(), QLocale::toInt()
7355 */
7356 
toLong(bool * ok,int base) const7357 long QString::toLong(bool *ok, int base) const
7358 {
7359     return toIntegral_helper<long>(constData(), size(), ok, base);
7360 }
7361 
7362 /*!
7363     \fn ulong QString::toULong(bool *ok, int base) const
7364 
7365     Returns the string converted to an \c{unsigned long} using base \a
7366     base, which is 10 by default and must be between 2 and 36, or 0.
7367     Returns 0 if the conversion fails.
7368 
7369     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7370     to \c false, and success by setting *\a{ok} to \c true.
7371 
7372     If \a base is 0, the C language convention is used: If the string
7373     begins with "0x", base 16 is used; if the string begins with "0",
7374     base 8 is used; otherwise, base 10 is used.
7375 
7376     The string conversion will always happen in the 'C' locale. For locale
7377     dependent conversion use QLocale::toULongLong()
7378 
7379     Example:
7380 
7381     \snippet qstring/main.cpp 78
7382 
7383     This function ignores leading and trailing whitespace.
7384 
7385     \sa number(), QLocale::toUInt()
7386 */
7387 
toULong(bool * ok,int base) const7388 ulong QString::toULong(bool *ok, int base) const
7389 {
7390     return toIntegral_helper<ulong>(constData(), size(), ok, base);
7391 }
7392 
7393 
7394 /*!
7395     Returns the string converted to an \c int using base \a
7396     base, which is 10 by default and must be between 2 and 36, or 0.
7397     Returns 0 if the conversion fails.
7398 
7399     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7400     to \c false, and success by setting *\a{ok} to \c true.
7401 
7402     If \a base is 0, the C language convention is used: If the string
7403     begins with "0x", base 16 is used; if the string begins with "0",
7404     base 8 is used; otherwise, base 10 is used.
7405 
7406     The string conversion will always happen in the 'C' locale. For locale
7407     dependent conversion use QLocale::toInt()
7408 
7409     Example:
7410 
7411     \snippet qstring/main.cpp 72
7412 
7413     This function ignores leading and trailing whitespace.
7414 
7415     \sa number(), toUInt(), toDouble(), QLocale::toInt()
7416 */
7417 
toInt(bool * ok,int base) const7418 int QString::toInt(bool *ok, int base) const
7419 {
7420     return toIntegral_helper<int>(constData(), size(), ok, base);
7421 }
7422 
7423 /*!
7424     Returns the string converted to an \c{unsigned int} using base \a
7425     base, which is 10 by default and must be between 2 and 36, or 0.
7426     Returns 0 if the conversion fails.
7427 
7428     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7429     to \c false, and success by setting *\a{ok} to \c true.
7430 
7431     If \a base is 0, the C language convention is used: If the string
7432     begins with "0x", base 16 is used; if the string begins with "0",
7433     base 8 is used; otherwise, base 10 is used.
7434 
7435     The string conversion will always happen in the 'C' locale. For locale
7436     dependent conversion use QLocale::toUInt()
7437 
7438     Example:
7439 
7440     \snippet qstring/main.cpp 77
7441 
7442     This function ignores leading and trailing whitespace.
7443 
7444     \sa number(), toInt(), QLocale::toUInt()
7445 */
7446 
toUInt(bool * ok,int base) const7447 uint QString::toUInt(bool *ok, int base) const
7448 {
7449     return toIntegral_helper<uint>(constData(), size(), ok, base);
7450 }
7451 
7452 /*!
7453     Returns the string converted to a \c short using base \a
7454     base, which is 10 by default and must be between 2 and 36, or 0.
7455     Returns 0 if the conversion fails.
7456 
7457     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7458     to \c false, and success by setting *\a{ok} to \c true.
7459 
7460     If \a base is 0, the C language convention is used: If the string
7461     begins with "0x", base 16 is used; if the string begins with "0",
7462     base 8 is used; otherwise, base 10 is used.
7463 
7464     The string conversion will always happen in the 'C' locale. For locale
7465     dependent conversion use QLocale::toShort()
7466 
7467     Example:
7468 
7469     \snippet qstring/main.cpp 76
7470 
7471     This function ignores leading and trailing whitespace.
7472 
7473     \sa number(), toUShort(), toInt(), QLocale::toShort()
7474 */
7475 
toShort(bool * ok,int base) const7476 short QString::toShort(bool *ok, int base) const
7477 {
7478     return toIntegral_helper<short>(constData(), size(), ok, base);
7479 }
7480 
7481 /*!
7482     Returns the string converted to an \c{unsigned short} using base \a
7483     base, which is 10 by default and must be between 2 and 36, or 0.
7484     Returns 0 if the conversion fails.
7485 
7486     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7487     to \c false, and success by setting *\a{ok} to \c true.
7488 
7489     If \a base is 0, the C language convention is used: If the string
7490     begins with "0x", base 16 is used; if the string begins with "0",
7491     base 8 is used; otherwise, base 10 is used.
7492 
7493     The string conversion will always happen in the 'C' locale. For locale
7494     dependent conversion use QLocale::toUShort()
7495 
7496     Example:
7497 
7498     \snippet qstring/main.cpp 80
7499 
7500     This function ignores leading and trailing whitespace.
7501 
7502     \sa number(), toShort(), QLocale::toUShort()
7503 */
7504 
toUShort(bool * ok,int base) const7505 ushort QString::toUShort(bool *ok, int base) const
7506 {
7507     return toIntegral_helper<ushort>(constData(), size(), ok, base);
7508 }
7509 
7510 
7511 /*!
7512     Returns the string converted to a \c double value.
7513 
7514     Returns an infinity if the conversion overflows or 0.0 if the
7515     conversion fails for other reasons (e.g. underflow).
7516 
7517     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7518     to \c false, and success by setting *\a{ok} to \c true.
7519 
7520     \snippet qstring/main.cpp 66
7521 
7522     \warning The QString content may only contain valid numerical characters
7523     which includes the plus/minus sign, the character e used in scientific
7524     notation, and the decimal point. Including the unit or additional characters
7525     leads to a conversion error.
7526 
7527     \snippet qstring/main.cpp 67
7528 
7529     The string conversion will always happen in the 'C' locale. For locale
7530     dependent conversion use QLocale::toDouble()
7531 
7532     \snippet qstring/main.cpp 68
7533 
7534     For historical reasons, this function does not handle
7535     thousands group separators. If you need to convert such numbers,
7536     use QLocale::toDouble().
7537 
7538     \snippet qstring/main.cpp 69
7539 
7540     This function ignores leading and trailing whitespace.
7541 
7542     \sa number(), QLocale::setDefault(), QLocale::toDouble(), trimmed()
7543 */
7544 
toDouble(bool * ok) const7545 double QString::toDouble(bool *ok) const
7546 {
7547     return QLocaleData::c()->stringToDouble(*this, ok, QLocale::RejectGroupSeparator);
7548 }
7549 
7550 /*!
7551     Returns the string converted to a \c float value.
7552 
7553     Returns an infinity if the conversion overflows or 0.0 if the
7554     conversion fails for other reasons (e.g. underflow).
7555 
7556     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
7557     to \c false, and success by setting *\a{ok} to \c true.
7558 
7559     \warning The QString content may only contain valid numerical characters
7560     which includes the plus/minus sign, the character e used in scientific
7561     notation, and the decimal point. Including the unit or additional characters
7562     leads to a conversion error.
7563 
7564     The string conversion will always happen in the 'C' locale. For locale
7565     dependent conversion use QLocale::toFloat()
7566 
7567     For historical reasons, this function does not handle
7568     thousands group separators. If you need to convert such numbers,
7569     use QLocale::toFloat().
7570 
7571     Example:
7572 
7573     \snippet qstring/main.cpp 71
7574 
7575     This function ignores leading and trailing whitespace.
7576 
7577     \sa number(), toDouble(), toInt(), QLocale::toFloat(), trimmed()
7578 */
7579 
toFloat(bool * ok) const7580 float QString::toFloat(bool *ok) const
7581 {
7582     return QLocaleData::convertDoubleToFloat(toDouble(ok), ok);
7583 }
7584 
7585 /*! \fn QString &QString::setNum(int n, int base)
7586 
7587     Sets the string to the printed value of \a n in the specified \a
7588     base, and returns a reference to the string.
7589 
7590     The base is 10 by default and must be between 2 and 36. For bases
7591     other than 10, \a n is treated as an unsigned integer.
7592 
7593     \snippet qstring/main.cpp 56
7594 
7595    The formatting always uses QLocale::C, i.e., English/UnitedStates.
7596    To get a localized string representation of a number, use
7597    QLocale::toString() with the appropriate locale.
7598 
7599    \sa number()
7600 */
7601 
7602 /*! \fn QString &QString::setNum(uint n, int base)
7603 
7604     \overload
7605 */
7606 
7607 /*! \fn QString &QString::setNum(long n, int base)
7608 
7609     \overload
7610 */
7611 
7612 /*! \fn QString &QString::setNum(ulong n, int base)
7613 
7614     \overload
7615 */
7616 
7617 /*!
7618     \overload
7619 */
setNum(qlonglong n,int base)7620 QString &QString::setNum(qlonglong n, int base)
7621 {
7622     return *this = number(n, base);
7623 }
7624 
7625 /*!
7626     \overload
7627 */
setNum(qulonglong n,int base)7628 QString &QString::setNum(qulonglong n, int base)
7629 {
7630     return *this = number(n, base);
7631 }
7632 
7633 /*! \fn QString &QString::setNum(short n, int base)
7634 
7635     \overload
7636 */
7637 
7638 /*! \fn QString &QString::setNum(ushort n, int base)
7639 
7640     \overload
7641 */
7642 
7643 /*!
7644     \fn QString &QString::setNum(double n, char format, int precision)
7645     \overload
7646 
7647     Sets the string to the printed value of \a n, formatted according
7648     to the given \a format and \a precision, and returns a reference
7649     to the string.
7650 
7651     The \a format can be 'e', 'E', 'f', 'g' or 'G' (see
7652     \l{Argument Formats} for an explanation of the formats).
7653 
7654     The formatting always uses QLocale::C, i.e., English/UnitedStates.
7655     To get a localized string representation of a number, use
7656     QLocale::toString() with the appropriate locale.
7657 
7658     \sa number()
7659 */
7660 
setNum(double n,char f,int prec)7661 QString &QString::setNum(double n, char f, int prec)
7662 {
7663     return *this = number(n, f, prec);
7664 }
7665 
7666 /*!
7667     \fn QString &QString::setNum(float n, char format, int precision)
7668     \overload
7669 
7670     Sets the string to the printed value of \a n, formatted according
7671     to the given \a format and \a precision, and returns a reference
7672     to the string.
7673 
7674     The formatting always uses QLocale::C, i.e., English/UnitedStates.
7675     To get a localized string representation of a number, use
7676     QLocale::toString() with the appropriate locale.
7677 
7678     \sa number()
7679 */
7680 
7681 
7682 /*!
7683     \fn QString QString::number(long n, int base)
7684 
7685     Returns a string equivalent of the number \a n according to the
7686     specified \a base.
7687 
7688     The base is 10 by default and must be between 2
7689     and 36. For bases other than 10, \a n is treated as an
7690     unsigned integer.
7691 
7692     The formatting always uses QLocale::C, i.e., English/UnitedStates.
7693     To get a localized string representation of a number, use
7694     QLocale::toString() with the appropriate locale.
7695 
7696     \snippet qstring/main.cpp 35
7697 
7698     \sa setNum()
7699 */
7700 
number(long n,int base)7701 QString QString::number(long n, int base)
7702 {
7703     return number(qlonglong(n), base);
7704 }
7705 
7706 /*!
7707   \fn QString QString::number(ulong n, int base)
7708 
7709     \overload
7710 */
number(ulong n,int base)7711 QString QString::number(ulong n, int base)
7712 {
7713     return number(qulonglong(n), base);
7714 }
7715 
7716 /*!
7717     \overload
7718 */
number(int n,int base)7719 QString QString::number(int n, int base)
7720 {
7721     return number(qlonglong(n), base);
7722 }
7723 
7724 /*!
7725     \overload
7726 */
number(uint n,int base)7727 QString QString::number(uint n, int base)
7728 {
7729     return number(qulonglong(n), base);
7730 }
7731 
7732 /*!
7733     \overload
7734 */
number(qlonglong n,int base)7735 QString QString::number(qlonglong n, int base)
7736 {
7737 #if defined(QT_CHECK_RANGE)
7738     if (base < 2 || base > 36) {
7739         qWarning("QString::setNum: Invalid base (%d)", base);
7740         base = 10;
7741     }
7742 #endif
7743     return QLocaleData::c()->longLongToString(n, -1, base);
7744 }
7745 
7746 /*!
7747     \overload
7748 */
number(qulonglong n,int base)7749 QString QString::number(qulonglong n, int base)
7750 {
7751 #if defined(QT_CHECK_RANGE)
7752     if (base < 2 || base > 36) {
7753         qWarning("QString::setNum: Invalid base (%d)", base);
7754         base = 10;
7755     }
7756 #endif
7757     return QLocaleData::c()->unsLongLongToString(n, -1, base);
7758 }
7759 
7760 
7761 /*!
7762     \fn QString QString::number(double n, char format, int precision)
7763 
7764     Returns a string equivalent of the number \a n, formatted
7765     according to the specified \a format and \a precision. See
7766     \l{Argument Formats} for details.
7767 
7768     Unlike QLocale::toString(), this function does not honor the
7769     user's locale settings.
7770 
7771     \sa setNum(), QLocale::toString()
7772 */
number(double n,char f,int prec)7773 QString QString::number(double n, char f, int prec)
7774 {
7775     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
7776     uint flags = QLocaleData::ZeroPadExponent;
7777 
7778     if (qIsUpper(f))
7779         flags |= QLocaleData::CapitalEorX;
7780 
7781     switch (qToLower(f)) {
7782         case 'f':
7783             form = QLocaleData::DFDecimal;
7784             break;
7785         case 'e':
7786             form = QLocaleData::DFExponent;
7787             break;
7788         case 'g':
7789             form = QLocaleData::DFSignificantDigits;
7790             break;
7791         default:
7792 #if defined(QT_CHECK_RANGE)
7793             qWarning("QString::setNum: Invalid format char '%c'", f);
7794 #endif
7795             break;
7796     }
7797 
7798     return QLocaleData::c()->doubleToString(n, prec, form, -1, flags);
7799 }
7800 
7801 namespace {
7802 template<class ResultList, class StringSource>
splitString(const StringSource & source,const QChar * sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs,const int separatorSize)7803 static ResultList splitString(const StringSource &source, const QChar *sep,
7804                               Qt::SplitBehavior behavior, Qt::CaseSensitivity cs, const int separatorSize)
7805 {
7806     ResultList list;
7807     typename StringSource::size_type start = 0;
7808     typename StringSource::size_type end;
7809     typename StringSource::size_type extra = 0;
7810     while ((end = QtPrivate::findString(QStringView(source.constData(), source.size()), start + extra, QStringView(sep, separatorSize), cs)) != -1) {
7811         if (start != end || behavior == Qt::KeepEmptyParts)
7812             list.append(source.mid(start, end - start));
7813         start = end + separatorSize;
7814         extra = (separatorSize == 0 ? 1 : 0);
7815     }
7816     if (start != source.size() || behavior == Qt::KeepEmptyParts)
7817         list.append(source.mid(start, -1));
7818     return list;
7819 }
7820 
7821 #if QT_DEPRECATED_SINCE(5, 15)
mapSplitBehavior(QString::SplitBehavior sb)7822 Qt::SplitBehavior mapSplitBehavior(QString::SplitBehavior sb)
7823 {
7824 QT_WARNING_PUSH
7825 QT_WARNING_DISABLE_DEPRECATED
7826     return sb & QString::SkipEmptyParts ? Qt::SkipEmptyParts : Qt::KeepEmptyParts;
7827 QT_WARNING_POP
7828 }
7829 #endif
7830 
7831 } // namespace
7832 
7833 /*!
7834     Splits the string into substrings wherever \a sep occurs, and
7835     returns the list of those strings. If \a sep does not match
7836     anywhere in the string, split() returns a single-element list
7837     containing this string.
7838 
7839     \a cs specifies whether \a sep should be matched case
7840     sensitively or case insensitively.
7841 
7842     If \a behavior is Qt::SkipEmptyParts, empty entries don't
7843     appear in the result. By default, empty entries are kept.
7844 
7845     Example:
7846 
7847     \snippet qstring/main.cpp 62
7848 
7849     If \a sep is empty, split() returns an empty string, followed
7850     by each of the string's characters, followed by another empty string:
7851 
7852     \snippet qstring/main.cpp 62-empty
7853 
7854     To understand this behavior, recall that the empty string matches
7855     everywhere, so the above is qualitatively the same as:
7856 
7857     \snippet qstring/main.cpp 62-slashes
7858 
7859     \sa QStringList::join(), section()
7860 
7861     \since 5.14
7862 */
split(const QString & sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7863 QStringList QString::split(const QString &sep, Qt::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7864 {
7865     return splitString<QStringList>(*this, sep.constData(), behavior, cs, sep.size());
7866 }
7867 
7868 #if QT_DEPRECATED_SINCE(5, 15)
7869 /*!
7870     \overload
7871     \obsolete
7872 */
split(const QString & sep,SplitBehavior behavior,Qt::CaseSensitivity cs) const7873 QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
7874 {
7875     return split(sep, mapSplitBehavior(behavior), cs);
7876 }
7877 #endif
7878 
7879 /*!
7880     Splits the string into substring references wherever \a sep occurs, and
7881     returns the list of those strings.
7882 
7883     See QString::split() for how \a sep, \a behavior and \a cs interact to form
7884     the result.
7885 
7886     \note All references are valid as long this string is alive. Destroying this
7887     string will cause all references to be dangling pointers.
7888 
7889     \since 5.14
7890     \sa QStringRef split()
7891 */
splitRef(const QString & sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7892 QVector<QStringRef> QString::splitRef(const QString &sep, Qt::SplitBehavior behavior,
7893                                       Qt::CaseSensitivity cs) const
7894 {
7895     return splitString<QVector<QStringRef>>(QStringRef(this), sep.constData(), behavior,
7896                                             cs, sep.size());
7897 }
7898 
7899 #if QT_DEPRECATED_SINCE(5, 15)
7900 /*!
7901     \overload
7902     \obsolete
7903     \since 5.4
7904 */
splitRef(const QString & sep,SplitBehavior behavior,Qt::CaseSensitivity cs) const7905 QVector<QStringRef> QString::splitRef(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
7906 {
7907     return splitRef(sep, mapSplitBehavior(behavior), cs);
7908 }
7909 #endif
7910 
7911 /*!
7912     \overload
7913     \since 5.14
7914 */
split(QChar sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7915 QStringList QString::split(QChar sep, Qt::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7916 {
7917     return splitString<QStringList>(*this, &sep, behavior, cs, 1);
7918 }
7919 
7920 #if QT_DEPRECATED_SINCE(5, 15)
7921 /*!
7922     \overload
7923     \obsolete
7924 */
split(QChar sep,SplitBehavior behavior,Qt::CaseSensitivity cs) const7925 QStringList QString::split(QChar sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
7926 {
7927     return split(sep, mapSplitBehavior(behavior), cs);
7928 }
7929 #endif
7930 
7931 /*!
7932     \overload
7933     \since 5.14
7934 */
splitRef(QChar sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7935 QVector<QStringRef> QString::splitRef(QChar sep, Qt::SplitBehavior behavior,
7936                                       Qt::CaseSensitivity cs) const
7937 {
7938     return splitString<QVector<QStringRef> >(QStringRef(this), &sep, behavior, cs, 1);
7939 }
7940 
7941 #if QT_DEPRECATED_SINCE(5, 15)
7942 /*!
7943     \overload
7944     \since 5.4
7945 */
splitRef(QChar sep,SplitBehavior behavior,Qt::CaseSensitivity cs) const7946 QVector<QStringRef> QString::splitRef(QChar sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const
7947 {
7948     return splitRef(sep, mapSplitBehavior(behavior), cs);
7949 }
7950 #endif
7951 
7952 /*!
7953     Splits the string into substrings references wherever \a sep occurs, and
7954     returns the list of those strings.
7955 
7956     See QString::split() for how \a sep, \a behavior and \a cs interact to form
7957     the result.
7958 
7959     \note All references are valid as long this string is alive. Destroying this
7960     string will cause all references to be dangling pointers.
7961 
7962     \since 5.14
7963 */
split(const QString & sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7964 QVector<QStringRef> QStringRef::split(const QString &sep, Qt::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7965 {
7966     return splitString<QVector<QStringRef> >(*this, sep.constData(), behavior, cs, sep.size());
7967 }
7968 
7969 #if QT_DEPRECATED_SINCE(5, 15)
7970 /*!
7971     \overload
7972     \since 5.4
7973     \obsolete
7974 */
split(const QString & sep,QString::SplitBehavior behavior,Qt::CaseSensitivity cs) const7975 QVector<QStringRef> QStringRef::split(const QString &sep, QString::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7976 {
7977     return split(sep, mapSplitBehavior(behavior), cs);
7978 }
7979 #endif
7980 
7981 /*!
7982     \overload
7983     \since 5.14
7984 */
split(QChar sep,Qt::SplitBehavior behavior,Qt::CaseSensitivity cs) const7985 QVector<QStringRef> QStringRef::split(QChar sep, Qt::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7986 {
7987     return splitString<QVector<QStringRef> >(*this, &sep, behavior, cs, 1);
7988 }
7989 
7990 #if QT_DEPRECATED_SINCE(5, 15)
7991 /*!
7992     \overload
7993     \since 5.4
7994     \obsolete
7995 */
split(QChar sep,QString::SplitBehavior behavior,Qt::CaseSensitivity cs) const7996 QVector<QStringRef> QStringRef::split(QChar sep, QString::SplitBehavior behavior, Qt::CaseSensitivity cs) const
7997 {
7998     return split(sep, mapSplitBehavior(behavior), cs);
7999 }
8000 #endif
8001 
8002 #ifndef QT_NO_REGEXP
8003 namespace {
8004 template<class ResultList, typename MidMethod>
splitString(const QString & source,MidMethod mid,const QRegExp & rx,Qt::SplitBehavior behavior)8005 static ResultList splitString(const QString &source, MidMethod mid, const QRegExp &rx, Qt::SplitBehavior behavior)
8006 {
8007     QRegExp rx2(rx);
8008     ResultList list;
8009     int start = 0;
8010     int extra = 0;
8011     int end;
8012     while ((end = rx2.indexIn(source, start + extra)) != -1) {
8013         int matchedLen = rx2.matchedLength();
8014         if (start != end || behavior == Qt::KeepEmptyParts)
8015             list.append((source.*mid)(start, end - start));
8016         start = end + matchedLen;
8017         extra = (matchedLen == 0) ? 1 : 0;
8018     }
8019     if (start != source.size() || behavior == Qt::KeepEmptyParts)
8020         list.append((source.*mid)(start, -1));
8021     return list;
8022 }
8023 } // namespace
8024 
8025 /*!
8026     \overload
8027     \since 5.14
8028 
8029     Splits the string into substrings wherever the regular expression
8030     \a rx matches, and returns the list of those strings. If \a rx
8031     does not match anywhere in the string, split() returns a
8032     single-element list containing this string.
8033 
8034     Here is an example where we extract the words in a sentence
8035     using one or more whitespace characters as the separator:
8036 
8037     \snippet qstring/main.cpp 59
8038 
8039     Here is a similar example, but this time we use any sequence of
8040     non-word characters as the separator:
8041 
8042     \snippet qstring/main.cpp 60
8043 
8044     Here is a third example where we use a zero-length assertion,
8045     \b{\\b} (word boundary), to split the string into an
8046     alternating sequence of non-word and word tokens:
8047 
8048     \snippet qstring/main.cpp 61
8049 
8050     \sa QStringList::join(), section()
8051 */
split(const QRegExp & rx,Qt::SplitBehavior behavior) const8052 QStringList QString::split(const QRegExp &rx, Qt::SplitBehavior behavior) const
8053 {
8054     return splitString<QStringList>(*this, &QString::mid, rx, behavior);
8055 }
8056 
8057 #  if QT_DEPRECATED_SINCE(5, 15)
8058 /*!
8059     \overload
8060     \obsolete
8061 */
split(const QRegExp & rx,SplitBehavior behavior) const8062 QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const
8063 {
8064     return split(rx, mapSplitBehavior(behavior));
8065 }
8066 #  endif
8067 
8068 /*!
8069     \overload
8070     \since 5.14
8071 
8072     Splits the string into substring references wherever the regular expression
8073     \a rx matches, and returns the list of those strings. If \a rx
8074     does not match anywhere in the string, splitRef() returns a
8075     single-element vector containing this string reference.
8076 
8077     \note All references are valid as long this string is alive. Destroying this
8078     string will cause all references to be dangling pointers.
8079 
8080     \sa QStringRef split()
8081 */
splitRef(const QRegExp & rx,Qt::SplitBehavior behavior) const8082 QVector<QStringRef> QString::splitRef(const QRegExp &rx, Qt::SplitBehavior behavior) const
8083 {
8084     return splitString<QVector<QStringRef> >(*this, &QString::midRef, rx, behavior);
8085 }
8086 
8087 #  if QT_DEPRECATED_SINCE(5, 15)
8088 /*!
8089     \overload
8090     \since 5.4
8091     \obsolete
8092 */
splitRef(const QRegExp & rx,SplitBehavior behavior) const8093 QVector<QStringRef> QString::splitRef(const QRegExp &rx, SplitBehavior behavior) const
8094 {
8095     return splitRef(rx, mapSplitBehavior(behavior));
8096 }
8097 #  endif
8098 #endif // QT_NO_REGEXP
8099 
8100 #if QT_CONFIG(regularexpression)
8101 namespace {
8102 template<class ResultList, typename MidMethod>
splitString(const QString & source,MidMethod mid,const QRegularExpression & re,Qt::SplitBehavior behavior)8103 static ResultList splitString(const QString &source, MidMethod mid, const QRegularExpression &re,
8104                               Qt::SplitBehavior behavior)
8105 {
8106     ResultList list;
8107     if (!re.isValid()) {
8108         qWarning("QString::split: invalid QRegularExpression object");
8109         return list;
8110     }
8111 
8112     int start = 0;
8113     int end = 0;
8114     QRegularExpressionMatchIterator iterator = re.globalMatch(source);
8115     while (iterator.hasNext()) {
8116         QRegularExpressionMatch match = iterator.next();
8117         end = match.capturedStart();
8118         if (start != end || behavior == Qt::KeepEmptyParts)
8119             list.append((source.*mid)(start, end - start));
8120         start = match.capturedEnd();
8121     }
8122 
8123     if (start != source.size() || behavior == Qt::KeepEmptyParts)
8124         list.append((source.*mid)(start, -1));
8125 
8126     return list;
8127 }
8128 } // namespace
8129 
8130 /*!
8131     \overload
8132     \since 5.14
8133 
8134     Splits the string into substrings wherever the regular expression
8135     \a re matches, and returns the list of those strings. If \a re
8136     does not match anywhere in the string, split() returns a
8137     single-element list containing this string.
8138 
8139     Here is an example where we extract the words in a sentence
8140     using one or more whitespace characters as the separator:
8141 
8142     \snippet qstring/main.cpp 90
8143 
8144     Here is a similar example, but this time we use any sequence of
8145     non-word characters as the separator:
8146 
8147     \snippet qstring/main.cpp 91
8148 
8149     Here is a third example where we use a zero-length assertion,
8150     \b{\\b} (word boundary), to split the string into an
8151     alternating sequence of non-word and word tokens:
8152 
8153     \snippet qstring/main.cpp 92
8154 
8155     \sa QStringList::join(), section()
8156 */
split(const QRegularExpression & re,Qt::SplitBehavior behavior) const8157 QStringList QString::split(const QRegularExpression &re, Qt::SplitBehavior behavior) const
8158 {
8159     return splitString<QStringList>(*this, &QString::mid, re, behavior);
8160 }
8161 
8162 #  if QT_DEPRECATED_SINCE(5, 15)
8163 /*!
8164     \overload
8165     \since 5.0
8166     \obsolete
8167 */
split(const QRegularExpression & re,SplitBehavior behavior) const8168 QStringList QString::split(const QRegularExpression &re, SplitBehavior behavior) const
8169 {
8170     return split(re, mapSplitBehavior(behavior));
8171 }
8172 #  endif
8173 
8174 /*!
8175     \overload
8176     \since 5.14
8177 
8178     Splits the string into substring references wherever the regular expression
8179     \a re matches, and returns the list of those strings. If \a re
8180     does not match anywhere in the string, splitRef() returns a
8181     single-element vector containing this string reference.
8182 
8183     \note All references are valid as long this string is alive. Destroying this
8184     string will cause all references to be dangling pointers.
8185 
8186     \sa split() QStringRef
8187 */
splitRef(const QRegularExpression & re,Qt::SplitBehavior behavior) const8188 QVector<QStringRef> QString::splitRef(const QRegularExpression &re, Qt::SplitBehavior behavior) const
8189 {
8190     return splitString<QVector<QStringRef> >(*this, &QString::midRef, re, behavior);
8191 }
8192 
8193 #  if QT_DEPRECATED_SINCE(5, 15)
8194 /*!
8195     \overload
8196     \since 5.4
8197     \obsolete
8198 */
splitRef(const QRegularExpression & re,SplitBehavior behavior) const8199 QVector<QStringRef> QString::splitRef(const QRegularExpression &re, SplitBehavior behavior) const
8200 {
8201     return splitRef(re, mapSplitBehavior(behavior));
8202 }
8203 #  endif
8204 #endif // QT_CONFIG(regularexpression)
8205 
8206 /*!
8207     \enum QString::NormalizationForm
8208 
8209     This enum describes the various normalized forms of Unicode text.
8210 
8211     \value NormalizationForm_D  Canonical Decomposition
8212     \value NormalizationForm_C  Canonical Decomposition followed by Canonical Composition
8213     \value NormalizationForm_KD  Compatibility Decomposition
8214     \value NormalizationForm_KC  Compatibility Decomposition followed by Canonical Composition
8215 
8216     \sa normalized(),
8217         {http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15}
8218 */
8219 
8220 /*!
8221     \since 4.5
8222 
8223     Returns a copy of this string repeated the specified number of \a times.
8224 
8225     If \a times is less than 1, an empty string is returned.
8226 
8227     Example:
8228 
8229     \snippet code/src_corelib_tools_qstring.cpp 8
8230 */
repeated(int times) const8231 QString QString::repeated(int times) const
8232 {
8233     if (d->size == 0)
8234         return *this;
8235 
8236     if (times <= 1) {
8237         if (times == 1)
8238             return *this;
8239         return QString();
8240     }
8241 
8242     const int resultSize = times * d->size;
8243 
8244     QString result;
8245     result.reserve(resultSize);
8246     if (result.d->alloc != uint(resultSize) + 1u)
8247         return QString(); // not enough memory
8248 
8249     memcpy(result.d->data(), d->data(), d->size * sizeof(ushort));
8250 
8251     int sizeSoFar = d->size;
8252     ushort *end = result.d->data() + sizeSoFar;
8253 
8254     const int halfResultSize = resultSize >> 1;
8255     while (sizeSoFar <= halfResultSize) {
8256         memcpy(end, result.d->data(), sizeSoFar * sizeof(ushort));
8257         end += sizeSoFar;
8258         sizeSoFar <<= 1;
8259     }
8260     memcpy(end, result.d->data(), (resultSize - sizeSoFar) * sizeof(ushort));
8261     result.d->data()[resultSize] = '\0';
8262     result.d->size = resultSize;
8263     return result;
8264 }
8265 
qt_string_normalize(QString * data,QString::NormalizationForm mode,QChar::UnicodeVersion version,int from)8266 void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from)
8267 {
8268     const QChar *p = data->constData() + from;
8269     if (isAscii(p, p + data->length() - from))
8270         return;
8271     if (p > data->constData() + from)
8272         from = p - data->constData() - 1;   // need one before the non-ASCII to perform NFC
8273 
8274     if (version == QChar::Unicode_Unassigned) {
8275         version = QChar::currentUnicodeVersion();
8276     } else if (int(version) <= NormalizationCorrectionsVersionMax) {
8277         const QString &s = *data;
8278         QChar *d = nullptr;
8279         for (int i = 0; i < NumNormalizationCorrections; ++i) {
8280             const NormalizationCorrection &n = uc_normalization_corrections[i];
8281             if (n.version > version) {
8282                 int pos = from;
8283                 if (QChar::requiresSurrogates(n.ucs4)) {
8284                     ushort ucs4High = QChar::highSurrogate(n.ucs4);
8285                     ushort ucs4Low = QChar::lowSurrogate(n.ucs4);
8286                     ushort oldHigh = QChar::highSurrogate(n.old_mapping);
8287                     ushort oldLow = QChar::lowSurrogate(n.old_mapping);
8288                     while (pos < s.length() - 1) {
8289                         if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) {
8290                             if (!d)
8291                                 d = data->data();
8292                             d[pos] = QChar(oldHigh);
8293                             d[++pos] = QChar(oldLow);
8294                         }
8295                         ++pos;
8296                     }
8297                 } else {
8298                     while (pos < s.length()) {
8299                         if (s.at(pos).unicode() == n.ucs4) {
8300                             if (!d)
8301                                 d = data->data();
8302                             d[pos] = QChar(n.old_mapping);
8303                         }
8304                         ++pos;
8305                     }
8306                 }
8307             }
8308         }
8309     }
8310 
8311     if (normalizationQuickCheckHelper(data, mode, from, &from))
8312         return;
8313 
8314     decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from);
8315 
8316     canonicalOrderHelper(data, version, from);
8317 
8318     if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD)
8319         return;
8320 
8321     composeHelper(data, version, from);
8322 }
8323 
8324 /*!
8325     Returns the string in the given Unicode normalization \a mode,
8326     according to the given \a version of the Unicode standard.
8327 */
normalized(QString::NormalizationForm mode,QChar::UnicodeVersion version) const8328 QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const
8329 {
8330     QString copy = *this;
8331     qt_string_normalize(&copy, mode, version, 0);
8332     return copy;
8333 }
8334 
8335 
8336 struct ArgEscapeData
8337 {
8338     int min_escape;            // lowest escape sequence number
8339     int occurrences;           // number of occurrences of the lowest escape sequence number
8340     int locale_occurrences;    // number of occurrences of the lowest escape sequence number that
8341                                // contain 'L'
8342     int escape_len;            // total length of escape sequences which will be replaced
8343 };
8344 
findArgEscapes(QStringView s)8345 static ArgEscapeData findArgEscapes(QStringView s)
8346 {
8347     const QChar *uc_begin = s.begin();
8348     const QChar *uc_end = s.end();
8349 
8350     ArgEscapeData d;
8351 
8352     d.min_escape = INT_MAX;
8353     d.occurrences = 0;
8354     d.escape_len = 0;
8355     d.locale_occurrences = 0;
8356 
8357     const QChar *c = uc_begin;
8358     while (c != uc_end) {
8359         while (c != uc_end && c->unicode() != '%')
8360             ++c;
8361 
8362         if (c == uc_end)
8363             break;
8364         const QChar *escape_start = c;
8365         if (++c == uc_end)
8366             break;
8367 
8368         bool locale_arg = false;
8369         if (c->unicode() == 'L') {
8370             locale_arg = true;
8371             if (++c == uc_end)
8372                 break;
8373         }
8374 
8375         int escape = c->digitValue();
8376         if (escape == -1)
8377             continue;
8378 
8379         ++c;
8380 
8381         if (c != uc_end) {
8382             int next_escape = c->digitValue();
8383             if (next_escape != -1) {
8384                 escape = (10 * escape) + next_escape;
8385                 ++c;
8386             }
8387         }
8388 
8389         if (escape > d.min_escape)
8390             continue;
8391 
8392         if (escape < d.min_escape) {
8393             d.min_escape = escape;
8394             d.occurrences = 0;
8395             d.escape_len = 0;
8396             d.locale_occurrences = 0;
8397         }
8398 
8399         ++d.occurrences;
8400         if (locale_arg)
8401             ++d.locale_occurrences;
8402         d.escape_len += c - escape_start;
8403     }
8404     return d;
8405 }
8406 
replaceArgEscapes(QStringView s,const ArgEscapeData & d,int field_width,QStringView arg,QStringView larg,QChar fillChar)8407 static QString replaceArgEscapes(QStringView s, const ArgEscapeData &d, int field_width,
8408                                  QStringView arg, QStringView larg, QChar fillChar)
8409 {
8410     const QChar *uc_begin = s.begin();
8411     const QChar *uc_end = s.end();
8412 
8413     int abs_field_width = qAbs(field_width);
8414     int result_len = s.length()
8415                      - d.escape_len
8416                      + (d.occurrences - d.locale_occurrences)
8417                      *qMax(abs_field_width, arg.length())
8418                      + d.locale_occurrences
8419                      *qMax(abs_field_width, larg.length());
8420 
8421     QString result(result_len, Qt::Uninitialized);
8422     QChar *result_buff = (QChar*) result.unicode();
8423 
8424     QChar *rc = result_buff;
8425     const QChar *c = uc_begin;
8426     int repl_cnt = 0;
8427     while (c != uc_end) {
8428         /* We don't have to check if we run off the end of the string with c,
8429            because as long as d.occurrences > 0 we KNOW there are valid escape
8430            sequences. */
8431 
8432         const QChar *text_start = c;
8433 
8434         while (c->unicode() != '%')
8435             ++c;
8436 
8437         const QChar *escape_start = c++;
8438 
8439         bool locale_arg = false;
8440         if (c->unicode() == 'L') {
8441             locale_arg = true;
8442             ++c;
8443         }
8444 
8445         int escape = c->digitValue();
8446         if (escape != -1) {
8447             if (c + 1 != uc_end && (c + 1)->digitValue() != -1) {
8448                 escape = (10 * escape) + (c + 1)->digitValue();
8449                 ++c;
8450             }
8451         }
8452 
8453         if (escape != d.min_escape) {
8454             memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
8455             rc += c - text_start;
8456         }
8457         else {
8458             ++c;
8459 
8460             memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
8461             rc += escape_start - text_start;
8462 
8463             uint pad_chars;
8464             if (locale_arg)
8465                 pad_chars = qMax(abs_field_width, larg.length()) - larg.length();
8466             else
8467                 pad_chars = qMax(abs_field_width, arg.length()) - arg.length();
8468 
8469             if (field_width > 0) { // left padded
8470                 for (uint i = 0; i < pad_chars; ++i)
8471                     (rc++)->unicode() = fillChar.unicode();
8472             }
8473 
8474             if (locale_arg) {
8475                 memcpy(rc, larg.data(), larg.length()*sizeof(QChar));
8476                 rc += larg.length();
8477             }
8478             else {
8479                 memcpy(rc, arg.data(), arg.length()*sizeof(QChar));
8480                 rc += arg.length();
8481             }
8482 
8483             if (field_width < 0) { // right padded
8484                 for (uint i = 0; i < pad_chars; ++i)
8485                     (rc++)->unicode() = fillChar.unicode();
8486             }
8487 
8488             if (++repl_cnt == d.occurrences) {
8489                 memcpy(rc, c, (uc_end - c)*sizeof(QChar));
8490                 rc += uc_end - c;
8491                 Q_ASSERT(rc - result_buff == result_len);
8492                 c = uc_end;
8493             }
8494         }
8495     }
8496     Q_ASSERT(rc == result_buff + result_len);
8497 
8498     return result;
8499 }
8500 
8501 #if QT_STRINGVIEW_LEVEL < 2
8502 /*!
8503   Returns a copy of this string with the lowest numbered place marker
8504   replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
8505 
8506   \a fieldWidth specifies the minimum amount of space that argument \a
8507   a shall occupy. If \a a requires less space than \a fieldWidth, it
8508   is padded to \a fieldWidth with character \a fillChar.  A positive
8509   \a fieldWidth produces right-aligned text. A negative \a fieldWidth
8510   produces left-aligned text.
8511 
8512   This example shows how we might create a \c status string for
8513   reporting progress while processing a list of files:
8514 
8515   \snippet qstring/main.cpp 11
8516 
8517   First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
8518   %2. Finally, \c arg(fileName) replaces \c %3.
8519 
8520   One advantage of using arg() over asprintf() is that the order of the
8521   numbered place markers can change, if the application's strings are
8522   translated into other languages, but each arg() will still replace
8523   the lowest numbered unreplaced place marker, no matter where it
8524   appears. Also, if place marker \c %i appears more than once in the
8525   string, the arg() replaces all of them.
8526 
8527   If there is no unreplaced place marker remaining, a warning message
8528   is output and the result is undefined. Place marker numbers must be
8529   in the range 1 to 99.
8530 */
arg(const QString & a,int fieldWidth,QChar fillChar) const8531 QString QString::arg(const QString &a, int fieldWidth, QChar fillChar) const
8532 {
8533     return arg(qToStringViewIgnoringNull(a), fieldWidth, fillChar);
8534 }
8535 #endif // QT_STRINGVIEW_LEVEL < 2
8536 
8537 /*!
8538     \overload
8539     \since 5.10
8540 
8541     Returns a copy of this string with the lowest-numbered place-marker
8542     replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
8543 
8544     \a fieldWidth specifies the minimum amount of space that \a a
8545     shall occupy. If \a a requires less space than \a fieldWidth, it
8546     is padded to \a fieldWidth with character \a fillChar.  A positive
8547     \a fieldWidth produces right-aligned text. A negative \a fieldWidth
8548     produces left-aligned text.
8549 
8550     This example shows how we might create a \c status string for
8551     reporting progress while processing a list of files:
8552 
8553     \snippet qstring/main.cpp 11-qstringview
8554 
8555     First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c
8556     %2. Finally, \c arg(fileName) replaces \c %3.
8557 
8558     One advantage of using arg() over asprintf() is that the order of the
8559     numbered place markers can change, if the application's strings are
8560     translated into other languages, but each arg() will still replace
8561     the lowest-numbered unreplaced place-marker, no matter where it
8562     appears. Also, if place-marker \c %i appears more than once in the
8563     string, arg() replaces all of them.
8564 
8565     If there is no unreplaced place-marker remaining, a warning message
8566     is printed and the result is undefined. Place-marker numbers must be
8567     in the range 1 to 99.
8568 */
arg(QStringView a,int fieldWidth,QChar fillChar) const8569 QString QString::arg(QStringView a, int fieldWidth, QChar fillChar) const
8570 {
8571     ArgEscapeData d = findArgEscapes(*this);
8572 
8573     if (Q_UNLIKELY(d.occurrences == 0)) {
8574         qWarning("QString::arg: Argument missing: %ls, %ls", qUtf16Printable(*this),
8575                   qUtf16Printable(a.toString()));
8576         return *this;
8577     }
8578     return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar);
8579 }
8580 
8581 /*!
8582     \overload
8583     \since 5.10
8584 
8585     Returns a copy of this string with the lowest-numbered place-marker
8586     replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99.
8587 
8588     \a fieldWidth specifies the minimum amount of space that \a a
8589     shall occupy. If \a a requires less space than \a fieldWidth, it
8590     is padded to \a fieldWidth with character \a fillChar.  A positive
8591     \a fieldWidth produces right-aligned text. A negative \a fieldWidth
8592     produces left-aligned text.
8593 
8594     One advantage of using arg() over asprintf() is that the order of the
8595     numbered place markers can change, if the application's strings are
8596     translated into other languages, but each arg() will still replace
8597     the lowest-numbered unreplaced place-marker, no matter where it
8598     appears. Also, if place-marker \c %i appears more than once in the
8599     string, arg() replaces all of them.
8600 
8601     If there is no unreplaced place-marker remaining, a warning message
8602     is printed and the result is undefined. Place-marker numbers must be
8603     in the range 1 to 99.
8604 */
arg(QLatin1String a,int fieldWidth,QChar fillChar) const8605 QString QString::arg(QLatin1String a, int fieldWidth, QChar fillChar) const
8606 {
8607     QVarLengthArray<ushort> utf16(a.size());
8608     qt_from_latin1(utf16.data(), a.data(), a.size());
8609     return arg(QStringView(utf16.data(), utf16.size()), fieldWidth, fillChar);
8610 }
8611 
8612 /*!
8613   \fn QString QString::arg(const QString& a1, const QString& a2) const
8614   \overload arg()
8615 
8616   This is the same as \c {str.arg(a1).arg(a2)}, except that the
8617   strings \a a1 and \a a2 are replaced in one pass. This can make a
8618   difference if \a a1 contains e.g. \c{%1}:
8619 
8620   \snippet qstring/main.cpp 13
8621 
8622   A similar problem occurs when the numbered place markers are not
8623   white space separated:
8624 
8625   \snippet qstring/main.cpp 12
8626   \snippet qstring/main.cpp 97
8627 
8628   Let's look at the substitutions:
8629   \list
8630   \li First, \c Hello replaces \c {%1} so the string becomes \c {"Hello%3%2"}.
8631   \li Then, \c 20 replaces \c {%2} so the string becomes \c {"Hello%320"}.
8632   \li Since the maximum numbered place marker value is 99, \c 50 replaces \c {%32}.
8633   \endlist
8634   Thus the string finally becomes \c {"Hello500"}.
8635 
8636   In such cases, the following yields the expected results:
8637 
8638   \snippet qstring/main.cpp 12
8639   \snippet qstring/main.cpp 98
8640 */
8641 
8642 /*!
8643   \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const
8644   \overload arg()
8645 
8646   This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except
8647   that the strings \a a1, \a a2 and \a a3 are replaced in one pass.
8648 */
8649 
8650 /*!
8651   \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const
8652   \overload arg()
8653 
8654   This is the same as calling \c
8655   {str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a
8656   a1, \a a2, \a a3 and \a a4 are replaced in one pass.
8657 */
8658 
8659 /*!
8660   \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const
8661   \overload arg()
8662 
8663   This is the same as calling \c
8664   {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings
8665   \a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass.
8666 */
8667 
8668 /*!
8669   \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const
8670   \overload arg()
8671 
8672   This is the same as calling \c
8673   {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that
8674   the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are
8675   replaced in one pass.
8676 */
8677 
8678 /*!
8679   \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
8680   \overload arg()
8681 
8682   This is the same as calling \c
8683   {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)},
8684   except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6,
8685   and \a a7 are replaced in one pass.
8686 */
8687 
8688 /*!
8689   \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
8690   \overload arg()
8691 
8692   This is the same as calling \c
8693   {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)},
8694   except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
8695   a7, and \a a8 are replaced in one pass.
8696 */
8697 
8698 /*!
8699   \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
8700   \overload arg()
8701 
8702   This is the same as calling \c
8703   {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)},
8704   except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a
8705   a7, \a a8, and \a a9 are replaced in one pass.
8706 */
8707 
8708 /*! \fn QString QString::arg(int a, int fieldWidth, int base, QChar fillChar) const
8709   \overload arg()
8710 
8711   The \a a argument is expressed in base \a base, which is 10 by
8712   default and must be between 2 and 36. For bases other than 10, \a a
8713   is treated as an unsigned integer.
8714 
8715   \a fieldWidth specifies the minimum amount of space that \a a is
8716   padded to and filled with the character \a fillChar. A positive
8717   value produces right-aligned text; a negative value produces
8718   left-aligned text.
8719 
8720   The '%' can be followed by an 'L', in which case the sequence is
8721   replaced with a localized representation of \a a. The conversion
8722   uses the default locale, set by QLocale::setDefault(). If no default
8723   locale was specified, the "C" locale is used. The 'L' flag is
8724   ignored if \a base is not 10.
8725 
8726   \snippet qstring/main.cpp 12
8727   \snippet qstring/main.cpp 14
8728 
8729   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8730   used. For negative numbers, zero padding might appear before the
8731   minus sign.
8732 */
8733 
8734 /*! \fn QString QString::arg(uint a, int fieldWidth, int base, QChar fillChar) const
8735   \overload arg()
8736 
8737   The \a base argument specifies the base to use when converting the
8738   integer \a a into a string. The base must be between 2 and 36.
8739 
8740   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8741   used. For negative numbers, zero padding might appear before the
8742   minus sign.
8743 */
8744 
8745 /*! \fn QString QString::arg(long a, int fieldWidth, int base, QChar fillChar) const
8746   \overload arg()
8747 
8748   \a fieldWidth specifies the minimum amount of space that \a a is
8749   padded to and filled with the character \a fillChar. A positive
8750   value produces right-aligned text; a negative value produces
8751   left-aligned text.
8752 
8753   The \a a argument is expressed in the given \a base, which is 10 by
8754   default and must be between 2 and 36.
8755 
8756   The '%' can be followed by an 'L', in which case the sequence is
8757   replaced with a localized representation of \a a. The conversion
8758   uses the default locale. The default locale is determined from the
8759   system's locale settings at application startup. It can be changed
8760   using QLocale::setDefault(). The 'L' flag is ignored if \a base is
8761   not 10.
8762 
8763   \snippet qstring/main.cpp 12
8764   \snippet qstring/main.cpp 14
8765 
8766   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8767   used. For negative numbers, zero padding might appear before the
8768   minus sign.
8769 */
8770 
8771 /*! \fn QString QString::arg(ulong a, int fieldWidth, int base, QChar fillChar) const
8772   \overload arg()
8773 
8774   \a fieldWidth specifies the minimum amount of space that \a a is
8775   padded to and filled with the character \a fillChar. A positive
8776   value produces right-aligned text; a negative value produces
8777   left-aligned text.
8778 
8779   The \a base argument specifies the base to use when converting the
8780   integer \a a to a string. The base must be between 2 and 36, with 8
8781   giving octal, 10 decimal, and 16 hexadecimal numbers.
8782 
8783   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8784   used. For negative numbers, zero padding might appear before the
8785   minus sign.
8786 */
8787 
8788 /*!
8789   \overload arg()
8790 
8791   \a fieldWidth specifies the minimum amount of space that \a a is
8792   padded to and filled with the character \a fillChar. A positive
8793   value produces right-aligned text; a negative value produces
8794   left-aligned text.
8795 
8796   The \a base argument specifies the base to use when converting the
8797   integer \a a into a string. The base must be between 2 and 36, with
8798   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
8799 
8800   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8801   used. For negative numbers, zero padding might appear before the
8802   minus sign.
8803 */
arg(qlonglong a,int fieldWidth,int base,QChar fillChar) const8804 QString QString::arg(qlonglong a, int fieldWidth, int base, QChar fillChar) const
8805 {
8806     ArgEscapeData d = findArgEscapes(*this);
8807 
8808     if (d.occurrences == 0) {
8809         qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
8810         return *this;
8811     }
8812 
8813     unsigned flags = QLocaleData::NoFlags;
8814     if (fillChar == QLatin1Char('0'))
8815         flags = QLocaleData::ZeroPadded;
8816 
8817     QString arg;
8818     if (d.occurrences > d.locale_occurrences)
8819         arg = QLocaleData::c()->longLongToString(a, -1, base, fieldWidth, flags);
8820 
8821     QString locale_arg;
8822     if (d.locale_occurrences > 0) {
8823         QLocale locale;
8824         if (!(locale.numberOptions() & QLocale::OmitGroupSeparator))
8825             flags |= QLocaleData::ThousandsGroup;
8826         locale_arg = locale.d->m_data->longLongToString(a, -1, base, fieldWidth, flags);
8827     }
8828 
8829     return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
8830 }
8831 
8832 /*!
8833   \overload arg()
8834 
8835   \a fieldWidth specifies the minimum amount of space that \a a is
8836   padded to and filled with the character \a fillChar. A positive
8837   value produces right-aligned text; a negative value produces
8838   left-aligned text.
8839 
8840   The \a base argument specifies the base to use when converting the
8841   integer \a a into a string. \a base must be between 2 and 36, with 8
8842   giving octal, 10 decimal, and 16 hexadecimal numbers.
8843 
8844   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8845   used. For negative numbers, zero padding might appear before the
8846   minus sign.
8847 */
arg(qulonglong a,int fieldWidth,int base,QChar fillChar) const8848 QString QString::arg(qulonglong a, int fieldWidth, int base, QChar fillChar) const
8849 {
8850     ArgEscapeData d = findArgEscapes(*this);
8851 
8852     if (d.occurrences == 0) {
8853         qWarning() << "QString::arg: Argument missing:" << *this << ',' << a;
8854         return *this;
8855     }
8856 
8857     unsigned flags = QLocaleData::NoFlags;
8858     if (fillChar == QLatin1Char('0'))
8859         flags = QLocaleData::ZeroPadded;
8860 
8861     QString arg;
8862     if (d.occurrences > d.locale_occurrences)
8863         arg = QLocaleData::c()->unsLongLongToString(a, -1, base, fieldWidth, flags);
8864 
8865     QString locale_arg;
8866     if (d.locale_occurrences > 0) {
8867         QLocale locale;
8868         if (!(locale.numberOptions() & QLocale::OmitGroupSeparator))
8869             flags |= QLocaleData::ThousandsGroup;
8870         locale_arg = locale.d->m_data->unsLongLongToString(a, -1, base, fieldWidth, flags);
8871     }
8872 
8873     return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
8874 }
8875 
8876 /*!
8877   \overload arg()
8878 
8879   \fn QString QString::arg(short a, int fieldWidth, int base, QChar fillChar) const
8880 
8881   \a fieldWidth specifies the minimum amount of space that \a a is
8882   padded to and filled with the character \a fillChar. A positive
8883   value produces right-aligned text; a negative value produces
8884   left-aligned text.
8885 
8886   The \a base argument specifies the base to use when converting the
8887   integer \a a into a string. The base must be between 2 and 36, with
8888   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
8889 
8890   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8891   used. For negative numbers, zero padding might appear before the
8892   minus sign.
8893 */
8894 
8895 /*!
8896   \fn QString QString::arg(ushort a, int fieldWidth, int base, QChar fillChar) const
8897   \overload arg()
8898 
8899   \a fieldWidth specifies the minimum amount of space that \a a is
8900   padded to and filled with the character \a fillChar. A positive
8901   value produces right-aligned text; a negative value produces
8902   left-aligned text.
8903 
8904   The \a base argument specifies the base to use when converting the
8905   integer \a a into a string. The base must be between 2 and 36, with
8906   8 giving octal, 10 decimal, and 16 hexadecimal numbers.
8907 
8908   If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is
8909   used. For negative numbers, zero padding might appear before the
8910   minus sign.
8911 */
8912 
8913 /*!
8914     \overload arg()
8915 */
arg(QChar a,int fieldWidth,QChar fillChar) const8916 QString QString::arg(QChar a, int fieldWidth, QChar fillChar) const
8917 {
8918     return arg(QStringView{&a, 1}, fieldWidth, fillChar);
8919 }
8920 
8921 /*!
8922   \overload arg()
8923 
8924   The \a a argument is interpreted as a Latin-1 character.
8925 */
arg(char a,int fieldWidth,QChar fillChar) const8926 QString QString::arg(char a, int fieldWidth, QChar fillChar) const
8927 {
8928     return arg(QLatin1Char(a), fieldWidth, fillChar);
8929 }
8930 
8931 /*!
8932   \fn QString QString::arg(double a, int fieldWidth, char format, int precision, QChar fillChar) const
8933   \overload arg()
8934 
8935   Argument \a a is formatted according to the specified \a format and
8936   \a precision. See \l{Argument Formats} for details.
8937 
8938   \a fieldWidth specifies the minimum amount of space that \a a is
8939   padded to and filled with the character \a fillChar.  A positive
8940   value produces right-aligned text; a negative value produces
8941   left-aligned text.
8942 
8943   \snippet code/src_corelib_tools_qstring.cpp 2
8944 
8945   The '%' can be followed by an 'L', in which case the sequence is
8946   replaced with a localized representation of \a a. The conversion
8947   uses the default locale, set by QLocale::setDefault(). If no
8948   default locale was specified, the "C" locale is used.
8949 
8950   If \a fillChar is '0' (the number 0, ASCII 48), this function will
8951   use the locale's zero to pad. For negative numbers, the zero padding
8952   will probably appear before the minus sign.
8953 
8954   \sa QLocale::toString()
8955 */
arg(double a,int fieldWidth,char fmt,int prec,QChar fillChar) const8956 QString QString::arg(double a, int fieldWidth, char fmt, int prec, QChar fillChar) const
8957 {
8958     ArgEscapeData d = findArgEscapes(*this);
8959 
8960     if (d.occurrences == 0) {
8961         qWarning("QString::arg: Argument missing: %s, %g", toLocal8Bit().data(), a);
8962         return *this;
8963     }
8964 
8965     unsigned flags = QLocaleData::NoFlags;
8966     if (fillChar == QLatin1Char('0'))
8967         flags |= QLocaleData::ZeroPadded;
8968 
8969     if (qIsUpper(fmt))
8970         flags |= QLocaleData::CapitalEorX;
8971 
8972     QLocaleData::DoubleForm form = QLocaleData::DFDecimal;
8973     switch (qToLower(fmt)) {
8974     case 'f':
8975         form = QLocaleData::DFDecimal;
8976         break;
8977     case 'e':
8978         form = QLocaleData::DFExponent;
8979         break;
8980     case 'g':
8981         form = QLocaleData::DFSignificantDigits;
8982         break;
8983     default:
8984 #if defined(QT_CHECK_RANGE)
8985         qWarning("QString::arg: Invalid format char '%c'", fmt);
8986 #endif
8987         break;
8988     }
8989 
8990     QString arg;
8991     if (d.occurrences > d.locale_occurrences)
8992         arg = QLocaleData::c()->doubleToString(a, prec, form, fieldWidth, flags | QLocaleData::ZeroPadExponent);
8993 
8994     QString locale_arg;
8995     if (d.locale_occurrences > 0) {
8996         QLocale locale;
8997 
8998         const QLocale::NumberOptions numberOptions = locale.numberOptions();
8999         if (!(numberOptions & QLocale::OmitGroupSeparator))
9000             flags |= QLocaleData::ThousandsGroup;
9001         if (!(numberOptions & QLocale::OmitLeadingZeroInExponent))
9002             flags |= QLocaleData::ZeroPadExponent;
9003         if (numberOptions & QLocale::IncludeTrailingZeroesAfterDot)
9004             flags |= QLocaleData::AddTrailingZeroes;
9005         locale_arg = locale.d->m_data->doubleToString(a, prec, form, fieldWidth, flags);
9006     }
9007 
9008     return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar);
9009 }
9010 
to_unicode(const QChar c)9011 static inline ushort to_unicode(const QChar c) { return c.unicode(); }
to_unicode(const char c)9012 static inline ushort to_unicode(const char c) { return QLatin1Char{c}.unicode(); }
9013 
9014 template <typename Char>
getEscape(const Char * uc,qsizetype * pos,qsizetype len,int maxNumber=999)9015 static int getEscape(const Char *uc, qsizetype *pos, qsizetype len, int maxNumber = 999)
9016 {
9017     int i = *pos;
9018     ++i;
9019     if (i < len && uc[i] == QLatin1Char('L'))
9020         ++i;
9021     if (i < len) {
9022         int escape = to_unicode(uc[i]) - '0';
9023         if (uint(escape) >= 10U)
9024             return -1;
9025         ++i;
9026         while (i < len) {
9027             int digit = to_unicode(uc[i]) - '0';
9028             if (uint(digit) >= 10U)
9029                 break;
9030             escape = (escape * 10) + digit;
9031             ++i;
9032         }
9033         if (escape <= maxNumber) {
9034             *pos = i;
9035             return escape;
9036         }
9037     }
9038     return -1;
9039 }
9040 
9041 /*
9042     Algorithm for multiArg:
9043 
9044     1. Parse the string as a sequence of verbatim text and placeholders (%L?\d{,3}).
9045        The L is parsed and accepted for compatibility with non-multi-arg, but since
9046        multiArg only accepts strings as replacements, the localization request can
9047        be safely ignored.
9048     2. The result of step (1) is a list of (string-ref,int)-tuples. The string-ref
9049        either points at text to be copied verbatim (in which case the int is -1),
9050        or, initially, at the textual representation of the placeholder. In that case,
9051        the int contains the numerical number as parsed from the placeholder.
9052     3. Next, collect all the non-negative ints found, sort them in ascending order and
9053        remove duplicates.
9054        3a. If the result has more entires than multiArg() was given replacement strings,
9055            we have found placeholders we can't satisfy with replacement strings. That is
9056            fine (there could be another .arg() call coming after this one), so just
9057            truncate the result to the number of actual multiArg() replacement strings.
9058        3b. If the result has less entries than multiArg() was given replacement strings,
9059            the string is missing placeholders. This is an error that the user should be
9060            warned about.
9061     4. The result of step (3) is a mapping from the index of any replacement string to
9062        placeholder number. This is the wrong way around, but since placeholder
9063        numbers could get as large as 999, while we typically don't have more than 9
9064        replacement strings, we trade 4K of sparsely-used memory for doing a reverse lookup
9065        each time we need to map a placeholder number to a replacement string index
9066        (that's a linear search; but still *much* faster than using an associative container).
9067     5. Next, for each of the tuples found in step (1), do the following:
9068        5a. If the int is negative, do nothing.
9069        5b. Otherwise, if the int is found in the result of step (3) at index I, replace
9070            the string-ref with a string-ref for the (complete) I'th replacement string.
9071        5c. Otherwise, do nothing.
9072     6. Concatenate all string refs into a single result string.
9073 */
9074 
9075 namespace {
9076 struct Part
9077 {
9078     Part() = default; // for QVarLengthArray; do not use
Part__anon21da74bc1611::Part9079     Q_DECL_CONSTEXPR Part(QStringView s, int num = -1)
9080         : tag{QtPrivate::ArgBase::U16}, number{num}, data{s.utf16()}, size{s.size()} {}
Part__anon21da74bc1611::Part9081     Q_DECL_CONSTEXPR Part(QLatin1String s, int num = -1)
9082         : tag{QtPrivate::ArgBase::L1}, number{num}, data{s.data()}, size{s.size()} {}
9083 
reset__anon21da74bc1611::Part9084     void reset(QStringView s) noexcept { *this = {s, number}; }
reset__anon21da74bc1611::Part9085     void reset(QLatin1String s) noexcept { *this = {s, number}; }
9086 
9087     QtPrivate::ArgBase::Tag tag;
9088     int number;
9089     const void *data;
9090     qsizetype size;
9091 };
9092 } // unnamed namespace
9093 
9094 Q_DECLARE_TYPEINFO(Part, Q_PRIMITIVE_TYPE);
9095 
9096 namespace {
9097 
9098 enum { ExpectedParts = 32 };
9099 
9100 typedef QVarLengthArray<Part, ExpectedParts> ParseResult;
9101 typedef QVarLengthArray<int, ExpectedParts/2> ArgIndexToPlaceholderMap;
9102 
9103 template <typename StringView>
parseMultiArgFormatString(StringView s)9104 static ParseResult parseMultiArgFormatString(StringView s)
9105 {
9106     ParseResult result;
9107 
9108     const auto uc = s.data();
9109     const auto len = s.size();
9110     const auto end = len - 1;
9111     qsizetype i = 0;
9112     qsizetype last = 0;
9113 
9114     while (i < end) {
9115         if (uc[i] == QLatin1Char('%')) {
9116             qsizetype percent = i;
9117             int number = getEscape(uc, &i, len);
9118             if (number != -1) {
9119                 if (last != percent)
9120                     result.push_back(Part{s.mid(last, percent - last)}); // literal text (incl. failed placeholders)
9121                 result.push_back(Part{s.mid(percent, i - percent), number});  // parsed placeholder
9122                 last = i;
9123                 continue;
9124             }
9125         }
9126         ++i;
9127     }
9128 
9129     if (last < len)
9130         result.push_back(Part{s.mid(last, len - last)}); // trailing literal text
9131 
9132     return result;
9133 }
9134 
makeArgIndexToPlaceholderMap(const ParseResult & parts)9135 static ArgIndexToPlaceholderMap makeArgIndexToPlaceholderMap(const ParseResult &parts)
9136 {
9137     ArgIndexToPlaceholderMap result;
9138 
9139     for (Part part : parts) {
9140         if (part.number >= 0)
9141             result.push_back(part.number);
9142     }
9143 
9144     std::sort(result.begin(), result.end());
9145     result.erase(std::unique(result.begin(), result.end()),
9146                  result.end());
9147 
9148     return result;
9149 }
9150 
resolveStringRefsAndReturnTotalSize(ParseResult & parts,const ArgIndexToPlaceholderMap & argIndexToPlaceholderMap,const QtPrivate::ArgBase * args[])9151 static qsizetype resolveStringRefsAndReturnTotalSize(ParseResult &parts, const ArgIndexToPlaceholderMap &argIndexToPlaceholderMap, const QtPrivate::ArgBase *args[])
9152 {
9153     using namespace QtPrivate;
9154     qsizetype totalSize = 0;
9155     for (Part &part : parts) {
9156         if (part.number != -1) {
9157             const auto it = std::find(argIndexToPlaceholderMap.begin(), argIndexToPlaceholderMap.end(), part.number);
9158             if (it != argIndexToPlaceholderMap.end()) {
9159                 const auto &arg = *args[it - argIndexToPlaceholderMap.begin()];
9160                 switch (arg.tag) {
9161                 case ArgBase::L1:
9162                     part.reset(static_cast<const QLatin1StringArg&>(arg).string);
9163                     break;
9164                 case ArgBase::U8:
9165                     Q_UNREACHABLE(); // waiting for QUtf8String...
9166                     break;
9167                 case ArgBase::U16:
9168                     part.reset(static_cast<const QStringViewArg&>(arg).string);
9169                     break;
9170                 }
9171             }
9172         }
9173         totalSize += part.size;
9174     }
9175     return totalSize;
9176 }
9177 
9178 } // unnamed namespace
9179 
9180 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
multiArg(int numArgs,const QString ** args) const9181 QString QString::multiArg(int numArgs, const QString **args) const
9182 {
9183     QVarLengthArray<QtPrivate::QStringViewArg, 9> sva;
9184     sva.reserve(numArgs);
9185     QVarLengthArray<const QtPrivate::ArgBase *, 9> pointers;
9186     pointers.reserve(numArgs);
9187     for (int i = 0; i < numArgs; ++i) {
9188         sva.push_back(QtPrivate::qStringLikeToArg(*args[i]));
9189         pointers.push_back(&sva.back());
9190     }
9191     return QtPrivate::argToQString(qToStringViewIgnoringNull(*this), static_cast<size_t>(numArgs), pointers.data());
9192 }
9193 #endif
9194 
to_string(QLatin1String s)9195 Q_ALWAYS_INLINE QString to_string(QLatin1String s) noexcept { return s; }
to_string(QStringView s)9196 Q_ALWAYS_INLINE QString to_string(QStringView s) noexcept { return s.toString(); }
9197 
9198 template <typename StringView>
argToQStringImpl(StringView pattern,size_t numArgs,const QtPrivate::ArgBase ** args)9199 static QString argToQStringImpl(StringView pattern, size_t numArgs, const QtPrivate::ArgBase **args)
9200 {
9201     // Step 1-2 above
9202     ParseResult parts = parseMultiArgFormatString(pattern);
9203 
9204     // 3-4
9205     ArgIndexToPlaceholderMap argIndexToPlaceholderMap = makeArgIndexToPlaceholderMap(parts);
9206 
9207     if (static_cast<size_t>(argIndexToPlaceholderMap.size()) > numArgs) // 3a
9208         argIndexToPlaceholderMap.resize(int(numArgs));
9209     else if (Q_UNLIKELY(static_cast<size_t>(argIndexToPlaceholderMap.size()) < numArgs)) // 3b
9210         qWarning("QString::arg: %d argument(s) missing in %ls",
9211                  int(numArgs - argIndexToPlaceholderMap.size()), qUtf16Printable(to_string(pattern)));
9212 
9213     // 5
9214     const qsizetype totalSize = resolveStringRefsAndReturnTotalSize(parts, argIndexToPlaceholderMap, args);
9215 
9216     // 6:
9217     QString result(totalSize, Qt::Uninitialized);
9218     auto out = const_cast<QChar*>(result.constData());
9219 
9220     for (Part part : parts) {
9221         switch (part.tag) {
9222         case QtPrivate::ArgBase::L1:
9223             if (part.size) {
9224                 qt_from_latin1(reinterpret_cast<ushort*>(out),
9225                                reinterpret_cast<const char*>(part.data), part.size);
9226             }
9227             break;
9228         case QtPrivate::ArgBase::U8:
9229             Q_UNREACHABLE(); // waiting for QUtf8String
9230             break;
9231         case QtPrivate::ArgBase::U16:
9232             if (part.size)
9233                 memcpy(out, part.data, part.size * sizeof(QChar));
9234             break;
9235         }
9236         out += part.size;
9237     }
9238 
9239     return result;
9240 }
9241 
argToQString(QStringView pattern,size_t n,const ArgBase ** args)9242 QString QtPrivate::argToQString(QStringView pattern, size_t n, const ArgBase **args)
9243 {
9244     return argToQStringImpl(pattern, n, args);
9245 }
9246 
argToQString(QLatin1String pattern,size_t n,const ArgBase ** args)9247 QString QtPrivate::argToQString(QLatin1String pattern, size_t n, const ArgBase **args)
9248 {
9249     return argToQStringImpl(pattern, n, args);
9250 }
9251 
9252 /*! \fn bool QString::isSimpleText() const
9253 
9254     \internal
9255 */
isSimpleText() const9256 bool QString::isSimpleText() const
9257 {
9258     const ushort *p = d->data();
9259     const ushort * const end = p + d->size;
9260     while (p < end) {
9261         ushort uc = *p;
9262         // sort out regions of complex text formatting
9263         if (uc > 0x058f && (uc < 0x1100 || uc > 0xfb0f)) {
9264             return false;
9265         }
9266         p++;
9267     }
9268 
9269     return true;
9270 }
9271 
9272 /*! \fn bool QString::isRightToLeft() const
9273 
9274     Returns \c true if the string is read right to left.
9275 
9276     \sa QStringRef::isRightToLeft()
9277 */
isRightToLeft() const9278 bool QString::isRightToLeft() const
9279 {
9280     return QtPrivate::isRightToLeft(QStringView(*this));
9281 }
9282 
9283 /*!
9284     \fn bool QString::isValidUtf16() const noexcept
9285     \since 5.15
9286 
9287     Returns \c true if the string contains valid UTF-16 encoded data,
9288     or \c false otherwise.
9289 
9290     Note that this function does not perform any special validation of the
9291     data; it merely checks if it can be successfully decoded from UTF-16.
9292     The data is assumed to be in host byte order; the presence of a BOM
9293     is meaningless.
9294 
9295     \sa QStringView::isValidUtf16()
9296 */
9297 
9298 /*! \fn QChar *QString::data()
9299 
9300     Returns a pointer to the data stored in the QString. The pointer
9301     can be used to access and modify the characters that compose the
9302     string.
9303 
9304     Unlike constData() and unicode(), the returned data is always
9305     '\\0'-terminated.
9306 
9307     Example:
9308 
9309     \snippet qstring/main.cpp 19
9310 
9311     Note that the pointer remains valid only as long as the string is
9312     not modified by other means. For read-only access, constData() is
9313     faster because it never causes a \l{deep copy} to occur.
9314 
9315     \sa constData(), operator[]()
9316 */
9317 
9318 /*! \fn const QChar *QString::data() const
9319 
9320     \overload
9321 
9322     \note The returned string may not be '\\0'-terminated.
9323     Use size() to determine the length of the array.
9324 
9325     \sa fromRawData()
9326 */
9327 
9328 /*! \fn const QChar *QString::constData() const
9329 
9330     Returns a pointer to the data stored in the QString. The pointer
9331     can be used to access the characters that compose the string.
9332 
9333     Note that the pointer remains valid only as long as the string is
9334     not modified.
9335 
9336     \note The returned string may not be '\\0'-terminated.
9337     Use size() to determine the length of the array.
9338 
9339     \sa data(), operator[](), fromRawData()
9340 */
9341 
9342 /*! \fn void QString::push_front(const QString &other)
9343 
9344     This function is provided for STL compatibility, prepending the
9345     given \a other string to the beginning of this string. It is
9346     equivalent to \c prepend(other).
9347 
9348     \sa prepend()
9349 */
9350 
9351 /*! \fn void QString::push_front(QChar ch)
9352 
9353     \overload
9354 
9355     Prepends the given \a ch character to the beginning of this string.
9356 */
9357 
9358 /*! \fn void QString::push_back(const QString &other)
9359 
9360     This function is provided for STL compatibility, appending the
9361     given \a other string onto the end of this string. It is
9362     equivalent to \c append(other).
9363 
9364     \sa append()
9365 */
9366 
9367 /*! \fn void QString::push_back(QChar ch)
9368 
9369     \overload
9370 
9371     Appends the given \a ch character onto the end of this string.
9372 */
9373 
9374 /*! \fn void QString::shrink_to_fit()
9375     \since 5.10
9376 
9377     This function is provided for STL compatibility. It is
9378     equivalent to squeeze().
9379 
9380     \sa squeeze()
9381 */
9382 
9383 /*!
9384     \fn std::string QString::toStdString() const
9385 
9386     Returns a std::string object with the data contained in this
9387     QString. The Unicode data is converted into 8-bit characters using
9388     the toUtf8() function.
9389 
9390     This method is mostly useful to pass a QString to a function
9391     that accepts a std::string object.
9392 
9393     \sa toLatin1(), toUtf8(), toLocal8Bit(), QByteArray::toStdString()
9394 */
9395 
9396 /*!
9397     Constructs a QString that uses the first \a size Unicode characters
9398     in the array \a unicode. The data in \a unicode is \e not
9399     copied. The caller must be able to guarantee that \a unicode will
9400     not be deleted or modified as long as the QString (or an
9401     unmodified copy of it) exists.
9402 
9403     Any attempts to modify the QString or copies of it will cause it
9404     to create a deep copy of the data, ensuring that the raw data
9405     isn't modified.
9406 
9407     Here is an example of how we can use a QRegularExpression on raw data in
9408     memory without requiring to copy the data into a QString:
9409 
9410     \snippet qstring/main.cpp 22
9411     \snippet qstring/main.cpp 23
9412 
9413     \warning A string created with fromRawData() is \e not
9414     '\\0'-terminated, unless the raw data contains a '\\0' character
9415     at position \a size. This means unicode() will \e not return a
9416     '\\0'-terminated string (although utf16() does, at the cost of
9417     copying the raw data).
9418 
9419     \sa fromUtf16(), setRawData()
9420 */
fromRawData(const QChar * unicode,int size)9421 QString QString::fromRawData(const QChar *unicode, int size)
9422 {
9423     Data *x;
9424     if (!unicode) {
9425         x = Data::sharedNull();
9426     } else if (!size) {
9427         x = Data::allocate(0);
9428     } else {
9429         x = Data::fromRawData(reinterpret_cast<const ushort *>(unicode), size);
9430         Q_CHECK_PTR(x);
9431     }
9432     QStringDataPtr dataPtr = { x };
9433     return QString(dataPtr);
9434 }
9435 
9436 /*!
9437     \since 4.7
9438 
9439     Resets the QString to use the first \a size Unicode characters
9440     in the array \a unicode. The data in \a unicode is \e not
9441     copied. The caller must be able to guarantee that \a unicode will
9442     not be deleted or modified as long as the QString (or an
9443     unmodified copy of it) exists.
9444 
9445     This function can be used instead of fromRawData() to re-use
9446     existings QString objects to save memory re-allocations.
9447 
9448     \sa fromRawData()
9449 */
setRawData(const QChar * unicode,int size)9450 QString &QString::setRawData(const QChar *unicode, int size)
9451 {
9452     if (d->ref.isShared() || d->alloc) {
9453         *this = fromRawData(unicode, size);
9454     } else {
9455         if (unicode) {
9456             d->size = size;
9457             d->offset = reinterpret_cast<const char *>(unicode) - reinterpret_cast<char *>(d);
9458         } else {
9459             d->offset = sizeof(QStringData);
9460             d->size = 0;
9461         }
9462     }
9463     return *this;
9464 }
9465 
9466 /*! \fn QString QString::fromStdU16String(const std::u16string &str)
9467     \since 5.5
9468 
9469     Returns a copy of the \a str string. The given string is assumed
9470     to be encoded in UTF-16.
9471 
9472     \sa fromUtf16(), fromStdWString(), fromStdU32String()
9473 */
9474 
9475 /*!
9476     \fn std::u16string QString::toStdU16String() const
9477     \since 5.5
9478 
9479     Returns a std::u16string object with the data contained in this
9480     QString. The Unicode data is the same as returned by the utf16()
9481     method.
9482 
9483     \sa utf16(), toStdWString(), toStdU32String()
9484 */
9485 
9486 /*! \fn QString QString::fromStdU32String(const std::u32string &str)
9487     \since 5.5
9488 
9489     Returns a copy of the \a str string. The given string is assumed
9490     to be encoded in UCS-4.
9491 
9492     \sa fromUcs4(), fromStdWString(), fromStdU16String()
9493 */
9494 
9495 /*!
9496     \fn std::u32string QString::toStdU32String() const
9497     \since 5.5
9498 
9499     Returns a std::u32string object with the data contained in this
9500     QString. The Unicode data is the same as returned by the toUcs4()
9501     method.
9502 
9503     \sa toUcs4(), toStdWString(), toStdU16String()
9504 */
9505 
9506 /*! \class QLatin1String
9507     \inmodule QtCore
9508     \brief The QLatin1String class provides a thin wrapper around an US-ASCII/Latin-1 encoded string literal.
9509 
9510     \ingroup string-processing
9511     \reentrant
9512 
9513     Many of QString's member functions are overloaded to accept
9514     \c{const char *} instead of QString. This includes the copy
9515     constructor, the assignment operator, the comparison operators,
9516     and various other functions such as \l{QString::insert()}{insert()}, \l{QString::replace()}{replace()},
9517     and \l{QString::indexOf()}{indexOf()}. These functions
9518     are usually optimized to avoid constructing a QString object for
9519     the \c{const char *} data. For example, assuming \c str is a
9520     QString,
9521 
9522     \snippet code/src_corelib_tools_qstring.cpp 3
9523 
9524     is much faster than
9525 
9526     \snippet code/src_corelib_tools_qstring.cpp 4
9527 
9528     because it doesn't construct four temporary QString objects and
9529     make a deep copy of the character data.
9530 
9531     Applications that define \c QT_NO_CAST_FROM_ASCII (as explained
9532     in the QString documentation) don't have access to QString's
9533     \c{const char *} API. To provide an efficient way of specifying
9534     constant Latin-1 strings, Qt provides the QLatin1String, which is
9535     just a very thin wrapper around a \c{const char *}. Using
9536     QLatin1String, the example code above becomes
9537 
9538     \snippet code/src_corelib_tools_qstring.cpp 5
9539 
9540     This is a bit longer to type, but it provides exactly the same
9541     benefits as the first version of the code, and is faster than
9542     converting the Latin-1 strings using QString::fromLatin1().
9543 
9544     Thanks to the QString(QLatin1String) constructor,
9545     QLatin1String can be used everywhere a QString is expected. For
9546     example:
9547 
9548     \snippet code/src_corelib_tools_qstring.cpp 6
9549 
9550     \note If the function you're calling with a QLatin1String
9551     argument isn't actually overloaded to take QLatin1String, the
9552     implicit conversion to QString will trigger a memory allocation,
9553     which is usually what you want to avoid by using QLatin1String
9554     in the first place. In those cases, using QStringLiteral may be
9555     the better option.
9556 
9557     \sa QString, QLatin1Char, {QStringLiteral()}{QStringLiteral}, QT_NO_CAST_FROM_ASCII
9558 */
9559 
9560 /*!
9561     \typedef QLatin1String::value_type
9562     \since 5.10
9563 
9564     Alias for \c{const char}. Provided for compatibility with the STL.
9565 */
9566 
9567 /*!
9568     \typedef QLatin1String::difference_type
9569     \since 5.10
9570 
9571     Alias for \c{int}. Provided for compatibility with the STL.
9572 */
9573 
9574 /*!
9575     \typedef QLatin1String::size_type
9576     \since 5.10
9577 
9578     Alias for \c{int}. Provided for compatibility with the STL.
9579 */
9580 
9581 /*!
9582     \typedef QLatin1String::reference
9583     \since 5.10
9584 
9585     Alias for \c{value_type &}. Provided for compatibility with the STL.
9586 */
9587 
9588 /*!
9589     \typedef QLatin1String::const_reference
9590     \since 5.11
9591 
9592     Alias for \c{reference}. Provided for compatibility with the STL.
9593 */
9594 
9595 /*!
9596     \typedef QLatin1String::iterator
9597     \since 5.10
9598 
9599     QLatin1String does not support mutable iterators, so this is the same
9600     as const_iterator.
9601 
9602     \sa const_iterator, reverse_iterator
9603 */
9604 
9605 /*!
9606     \typedef QLatin1String::const_iterator
9607     \since 5.10
9608 
9609     \sa iterator, const_reverse_iterator
9610 */
9611 
9612 /*!
9613     \typedef QLatin1String::reverse_iterator
9614     \since 5.10
9615 
9616     QLatin1String does not support mutable reverse iterators, so this is the
9617     same as const_reverse_iterator.
9618 
9619     \sa const_reverse_iterator, iterator
9620 */
9621 
9622 /*!
9623     \typedef QLatin1String::const_reverse_iterator
9624     \since 5.10
9625 
9626     \sa reverse_iterator, const_iterator
9627 */
9628 
9629 /*! \fn QLatin1String::QLatin1String()
9630     \since 5.6
9631 
9632     Constructs a QLatin1String object that stores a nullptr.
9633 */
9634 
9635 /*! \fn QLatin1String::QLatin1String(const char *str)
9636 
9637     Constructs a QLatin1String object that stores \a str.
9638 
9639     The string data is \e not copied. The caller must be able to
9640     guarantee that \a str will not be deleted or modified as long as
9641     the QLatin1String object exists.
9642 
9643     \sa latin1()
9644 */
9645 
9646 /*! \fn QLatin1String::QLatin1String(const char *str, int size)
9647 
9648     Constructs a QLatin1String object that stores \a str with \a size.
9649 
9650     The string data is \e not copied. The caller must be able to
9651     guarantee that \a str will not be deleted or modified as long as
9652     the QLatin1String object exists.
9653 
9654     \sa latin1()
9655 */
9656 
9657 /*!
9658     \fn QLatin1String::QLatin1String(const char *first, const char *last)
9659     \since 5.10
9660 
9661     Constructs a QLatin1String object that stores \a first with length
9662     (\a last - \a first).
9663 
9664     The range \c{[first,last)} must remain valid for the lifetime of
9665     this Latin-1 string object.
9666 
9667     Passing \nullptr as \a first is safe if \a last is \nullptr,
9668     too, and results in a null Latin-1 string.
9669 
9670     The behavior is undefined if \a last precedes \a first, \a first
9671     is \nullptr and \a last is not, or if \c{last - first >
9672     INT_MAX}.
9673 */
9674 
9675 /*! \fn QLatin1String::QLatin1String(const QByteArray &str)
9676 
9677     Constructs a QLatin1String object that stores \a str.
9678 
9679     The string data is \e not copied. The caller must be able to
9680     guarantee that \a str will not be deleted or modified as long as
9681     the QLatin1String object exists.
9682 
9683     \sa latin1()
9684 */
9685 
9686 /*! \fn const char *QLatin1String::latin1() const
9687 
9688     Returns the Latin-1 string stored in this object.
9689 */
9690 
9691 /*! \fn const char *QLatin1String::data() const
9692 
9693     Returns the Latin-1 string stored in this object.
9694 */
9695 
9696 /*! \fn int QLatin1String::size() const
9697 
9698     Returns the size of the Latin-1 string stored in this object.
9699 */
9700 
9701 /*! \fn bool QLatin1String::isNull() const
9702     \since 5.10
9703 
9704     Returns whether the Latin-1 string stored in this object is null
9705     (\c{data() == nullptr}) or not.
9706 
9707     \sa isEmpty(), data()
9708 */
9709 
9710 /*! \fn bool QLatin1String::isEmpty() const
9711     \since 5.10
9712 
9713     Returns whether the Latin-1 string stored in this object is empty
9714     (\c{size() == 0}) or not.
9715 
9716     \sa isNull(), size()
9717 */
9718 
9719 /*! \fn QLatin1Char QLatin1String::at(int pos) const
9720     \since 5.8
9721 
9722     Returns the character at position \a pos in this object.
9723 
9724     \note This function performs no error checking.
9725     The behavior is undefined when \a pos < 0 or \a pos >= size().
9726 
9727     \sa operator[]()
9728 */
9729 
9730 /*! \fn QLatin1Char QLatin1String::operator[](int pos) const
9731     \since 5.8
9732 
9733     Returns the character at position \a pos in this object.
9734 
9735     \note This function performs no error checking.
9736     The behavior is undefined when \a pos < 0 or \a pos >= size().
9737 
9738     \sa at()
9739 */
9740 
9741 /*!
9742     \fn QLatin1Char QLatin1String::front() const
9743     \since 5.10
9744 
9745     Returns the first character in the string.
9746     Same as \c{at(0)}.
9747 
9748     This function is provided for STL compatibility.
9749 
9750     \warning Calling this function on an empty string constitutes
9751     undefined behavior.
9752 
9753     \sa back(), at(), operator[]()
9754 */
9755 
9756 /*!
9757     \fn QLatin1Char QLatin1String::back() const
9758     \since 5.10
9759 
9760     Returns the last character in the string.
9761     Same as \c{at(size() - 1)}.
9762 
9763     This function is provided for STL compatibility.
9764 
9765     \warning Calling this function on an empty string constitutes
9766     undefined behavior.
9767 
9768     \sa front(), at(), operator[]()
9769 */
9770 
9771 /*!
9772     \fn int QLatin1String::compare(QStringView str, Qt::CaseSensitivity cs) const
9773     \fn int QLatin1String::compare(QLatin1String l1, Qt::CaseSensitivity cs) const
9774     \fn int QLatin1String::compare(QChar ch) const
9775     \fn int QLatin1String::compare(QChar ch, Qt::CaseSensitivity cs) const
9776     \since 5.14
9777 
9778     Returns an integer that compares to zero as this Latin-1 string compares to the
9779     string-view \a str, Latin-1 string \a l1, or character \a ch, respectively.
9780 
9781     If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive;
9782     otherwise the comparison is case-insensitive.
9783 
9784     \sa operator==(), operator<(), operator>()
9785 */
9786 
9787 
9788 /*!
9789     \fn bool QLatin1String::startsWith(QStringView str, Qt::CaseSensitivity cs) const
9790     \since 5.10
9791     \fn bool QLatin1String::startsWith(QLatin1String l1, Qt::CaseSensitivity cs) const
9792     \since 5.10
9793     \fn bool QLatin1String::startsWith(QChar ch) const
9794     \since 5.10
9795     \fn bool QLatin1String::startsWith(QChar ch, Qt::CaseSensitivity cs) const
9796     \since 5.10
9797 
9798     Returns \c true if this Latin-1 string starts with string-view \a str,
9799     Latin-1 string \a l1, or character \a ch, respectively;
9800     otherwise returns \c false.
9801 
9802     If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive;
9803     otherwise the search is case-insensitive.
9804 
9805     \sa endsWith()
9806 */
9807 
9808 /*!
9809     \fn bool QLatin1String::endsWith(QStringView str, Qt::CaseSensitivity cs) const
9810     \since 5.10
9811     \fn bool QLatin1String::endsWith(QLatin1String l1, Qt::CaseSensitivity cs) const
9812     \since 5.10
9813     \fn bool QLatin1String::endsWith(QChar ch) const
9814     \since 5.10
9815     \fn bool QLatin1String::endsWith(QChar ch, Qt::CaseSensitivity cs) const
9816     \since 5.10
9817 
9818     Returns \c true if this Latin-1 string ends with string-view \a str,
9819     Latin-1 string \a l1, or character \a ch, respectively;
9820     otherwise returns \c false.
9821 
9822     If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive;
9823     otherwise the search is case-insensitive.
9824 
9825     \sa startsWith()
9826 */
9827 
9828 /*!
9829     \fn int QLatin1String::indexOf(QStringView str, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
9830     \fn int QLatin1String::indexOf(QLatin1String l1, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
9831     \fn int QLatin1String::indexOf(QChar c, int from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
9832     \since 5.14
9833 
9834     Returns the index position of the first occurrence of the string-view \a str,
9835     Latin-1 string \a l1, or character \a ch, respectively, in this Latin-1 string,
9836     searching forward from index position \a from. Returns -1 if \a str is not found.
9837 
9838     If \a cs is Qt::CaseSensitive (default), the search is case
9839     sensitive; otherwise the search is case insensitive.
9840 
9841     If \a from is -1, the search starts at the last character; if it is
9842     -2, at the next to last character and so on.
9843 
9844     \sa QString::indexOf()
9845 */
9846 
9847 /*!
9848     \fn bool QLatin1String::contains(QStringView str, Qt::CaseSensitivity cs) const
9849     \fn bool QLatin1String::contains(QLatin1String l1, Qt::CaseSensitivity cs) const
9850     \fn bool QLatin1String::contains(QChar c, Qt::CaseSensitivity cs) const
9851     \since 5.14
9852 
9853     Returns \c true if this Latin-1 string contains an occurrence of the string-view
9854     \a str, Latin-1 string \a l1, or character \a ch; otherwise returns \c false.
9855 
9856     If \a cs is Qt::CaseSensitive (the default), the search is
9857     case-sensitive; otherwise the search is case-insensitive.
9858 
9859     \sa indexOf(), QStringView::contains(), QStringView::indexOf(), QString::indexOf()
9860 */
9861 
9862 /*!
9863     \fn int QLatin1String::lastIndexOf(QStringView str, int from, Qt::CaseSensitivity cs) const
9864     \fn int QLatin1String::lastIndexOf(QLatin1String l1, int from, Qt::CaseSensitivity cs) const
9865     \fn int QLatin1String::lastIndexOf(QChar c, int from, Qt::CaseSensitivity cs) const
9866     \since 5.14
9867 
9868     Returns the index position of the last occurrence of the string-view \a str,
9869     Latin-1 string \a l1, or character \a ch, respectively, in this Latin-1 string,
9870     searching backward from index position \a from. If \a from is -1 (default),
9871     the search starts at the last character; if \a from is -2, at the next to last
9872     character and so on. Returns -1 if \a str is not found.
9873 
9874     If \a cs is Qt::CaseSensitive (default), the search is case
9875     sensitive; otherwise the search is case insensitive.
9876 
9877     \sa indexOf(), QStringView::lastIndexOf(), QStringView::indexOf(), QString::indexOf()
9878 */
9879 
9880 /*!
9881     \fn QLatin1String::const_iterator QLatin1String::begin() const
9882     \since 5.10
9883 
9884     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character in
9885     the string.
9886 
9887     This function is provided for STL compatibility.
9888 
9889     \sa end(), cbegin(), rbegin(), data()
9890 */
9891 
9892 /*!
9893     \fn QLatin1String::const_iterator QLatin1String::cbegin() const
9894     \since 5.10
9895 
9896     Same as begin().
9897 
9898     This function is provided for STL compatibility.
9899 
9900     \sa cend(), begin(), crbegin(), data()
9901 */
9902 
9903 /*!
9904     \fn QLatin1String::const_iterator QLatin1String::end() const
9905     \since 5.10
9906 
9907     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
9908     character after the last character in the list.
9909 
9910     This function is provided for STL compatibility.
9911 
9912     \sa begin(), cend(), rend()
9913 */
9914 
9915 /*! \fn QLatin1String::const_iterator QLatin1String::cend() const
9916     \since 5.10
9917 
9918     Same as end().
9919 
9920     This function is provided for STL compatibility.
9921 
9922     \sa cbegin(), end(), crend()
9923 */
9924 
9925 /*!
9926     \fn QLatin1String::const_reverse_iterator QLatin1String::rbegin() const
9927     \since 5.10
9928 
9929     Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
9930     character in the string, in reverse order.
9931 
9932     This function is provided for STL compatibility.
9933 
9934     \sa rend(), crbegin(), begin()
9935 */
9936 
9937 /*!
9938     \fn QLatin1String::const_reverse_iterator QLatin1String::crbegin() const
9939     \since 5.10
9940 
9941     Same as rbegin().
9942 
9943     This function is provided for STL compatibility.
9944 
9945     \sa crend(), rbegin(), cbegin()
9946 */
9947 
9948 /*!
9949     \fn QLatin1String::const_reverse_iterator QLatin1String::rend() const
9950     \since 5.10
9951 
9952     Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
9953     the last character in the string, in reverse order.
9954 
9955     This function is provided for STL compatibility.
9956 
9957     \sa rbegin(), crend(), end()
9958 */
9959 
9960 /*!
9961     \fn QLatin1String::const_reverse_iterator QLatin1String::crend() const
9962     \since 5.10
9963 
9964     Same as rend().
9965 
9966     This function is provided for STL compatibility.
9967 
9968     \sa crbegin(), rend(), cend()
9969 */
9970 
9971 /*! \fn QLatin1String QLatin1String::mid(int start) const
9972     \since 5.8
9973 
9974     Returns the substring starting at position \a start in this object,
9975     and extending to the end of the string.
9976 
9977     \note This function performs no error checking.
9978     The behavior is undefined when \a start < 0 or \a start > size().
9979 
9980     \sa left(), right(), chopped(), chop(), truncate()
9981 */
9982 
9983 /*! \fn QLatin1String QLatin1String::mid(int start, int length) const
9984     \since 5.8
9985     \overload
9986 
9987     Returns the substring of length \a length starting at position
9988     \a start in this object.
9989 
9990     \note This function performs no error checking.
9991     The behavior is undefined when \a start < 0, \a length < 0,
9992     or \a start + \a length > size().
9993 
9994     \sa left(), right(), chopped(), chop(), truncate()
9995 */
9996 
9997 /*! \fn QLatin1String QLatin1String::left(int length) const
9998     \since 5.8
9999 
10000     Returns the substring of length \a length starting at position
10001     0 in this object.
10002 
10003     \note This function performs no error checking.
10004     The behavior is undefined when \a length < 0 or \a length > size().
10005 
10006     \sa mid(), right(), chopped(), chop(), truncate()
10007 */
10008 
10009 /*! \fn QLatin1String QLatin1String::right(int length) const
10010     \since 5.8
10011 
10012     Returns the substring of length \a length starting at position
10013     size() - \a length in this object.
10014 
10015     \note This function performs no error checking.
10016     The behavior is undefined when \a length < 0 or \a length > size().
10017 
10018     \sa mid(), left(), chopped(), chop(), truncate()
10019 */
10020 
10021 /*!
10022     \fn QLatin1String QLatin1String::chopped(int length) const
10023     \since 5.10
10024 
10025     Returns the substring of length size() - \a length starting at the
10026     beginning of this object.
10027 
10028     Same as \c{left(size() - length)}.
10029 
10030     \note The behavior is undefined when \a length < 0 or \a length > size().
10031 
10032     \sa mid(), left(), right(), chop(), truncate()
10033 */
10034 
10035 /*!
10036     \fn void QLatin1String::truncate(int length)
10037     \since 5.10
10038 
10039     Truncates this string to length \a length.
10040 
10041     Same as \c{*this = left(length)}.
10042 
10043     \note The behavior is undefined when \a length < 0 or \a length > size().
10044 
10045     \sa mid(), left(), right(), chopped(), chop()
10046 */
10047 
10048 /*!
10049     \fn void QLatin1String::chop(int length)
10050     \since 5.10
10051 
10052     Truncates this string by \a length characters.
10053 
10054     Same as \c{*this = left(size() - length)}.
10055 
10056     \note The behavior is undefined when \a length < 0 or \a length > size().
10057 
10058     \sa mid(), left(), right(), chopped(), truncate()
10059 */
10060 
10061 /*!
10062     \fn QLatin1String QLatin1String::trimmed() const
10063     \since 5.10
10064 
10065     Strips leading and trailing whitespace and returns the result.
10066 
10067     Whitespace means any character for which QChar::isSpace() returns
10068     \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
10069     '\\f', '\\r', and ' '.
10070 */
10071 
10072 /*! \fn bool QLatin1String::operator==(const QString &other) const
10073 
10074     Returns \c true if this string is equal to string \a other;
10075     otherwise returns \c false.
10076 
10077     \sa {Comparing Strings}
10078 */
10079 
10080 /*!
10081     \fn bool QLatin1String::operator==(const char *other) const
10082     \since 4.3
10083     \overload
10084 
10085     The \a other const char pointer is converted to a QString using
10086     the QString::fromUtf8() function.
10087 
10088     You can disable this operator by defining \c
10089     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10090     can be useful if you want to ensure that all user-visible strings
10091     go through QObject::tr(), for example.
10092 
10093     \sa QT_NO_CAST_FROM_ASCII
10094 */
10095 
10096 /*!
10097     \fn bool QLatin1String::operator==(const QByteArray &other) const
10098     \since 5.0
10099     \overload
10100 
10101     The \a other byte array is converted to a QString using
10102     the QString::fromUtf8() function.
10103 
10104     You can disable this operator by defining \c
10105     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10106     can be useful if you want to ensure that all user-visible strings
10107     go through QObject::tr(), for example.
10108 
10109     \sa QT_NO_CAST_FROM_ASCII
10110 */
10111 
10112 /*! \fn bool QLatin1String::operator!=(const QString &other) const
10113 
10114     Returns \c true if this string is not equal to string \a other;
10115     otherwise returns \c false.
10116 
10117     \sa {Comparing Strings}
10118 */
10119 
10120 /*!
10121     \fn bool QLatin1String::operator!=(const char *other) const
10122     \since 4.3
10123     \overload operator!=()
10124 
10125     The \a other const char pointer is converted to a QString using
10126     the QString::fromUtf8() function.
10127 
10128     You can disable this operator by defining \c
10129     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10130     can be useful if you want to ensure that all user-visible strings
10131     go through QObject::tr(), for example.
10132 
10133     \sa QT_NO_CAST_FROM_ASCII
10134 */
10135 
10136 /*!
10137     \fn bool QLatin1String::operator!=(const QByteArray &other) const
10138     \since 5.0
10139     \overload operator!=()
10140 
10141     The \a other byte array is converted to a QString using
10142     the QString::fromUtf8() function.
10143 
10144     You can disable this operator by defining \c
10145     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10146     can be useful if you want to ensure that all user-visible strings
10147     go through QObject::tr(), for example.
10148 
10149     \sa QT_NO_CAST_FROM_ASCII
10150 */
10151 
10152 /*!
10153     \fn bool QLatin1String::operator>(const QString &other) const
10154 
10155     Returns \c true if this string is lexically greater than string \a
10156     other; otherwise returns \c false.
10157 
10158     \sa {Comparing Strings}
10159 */
10160 
10161 /*!
10162     \fn bool QLatin1String::operator>(const char *other) const
10163     \since 4.3
10164     \overload
10165 
10166     The \a other const char pointer is converted to a QString using
10167     the QString::fromUtf8() function.
10168 
10169     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
10170     when you compile your applications. This can be useful if you want
10171     to ensure that all user-visible strings go through QObject::tr(),
10172     for example.
10173 
10174     \sa QT_NO_CAST_FROM_ASCII
10175 */
10176 
10177 /*!
10178     \fn bool QLatin1String::operator>(const QByteArray &other) const
10179     \since 5.0
10180     \overload
10181 
10182     The \a other const char pointer is converted to a QString using
10183     the QString::fromUtf8() function.
10184 
10185     You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII
10186     when you compile your applications. This can be useful if you want
10187     to ensure that all user-visible strings go through QObject::tr(),
10188     for example.
10189 
10190     \sa QT_NO_CAST_FROM_ASCII
10191 */
10192 
10193 /*!
10194     \fn bool QLatin1String::operator<(const QString &other) const
10195 
10196     Returns \c true if this string is lexically less than the \a other
10197     string; otherwise returns \c false.
10198 
10199     \sa {Comparing Strings}
10200 */
10201 
10202 /*!
10203     \fn bool QLatin1String::operator<(const char *other) const
10204     \since 4.3
10205     \overload
10206 
10207     The \a other const char pointer is converted to a QString using
10208     the QString::fromUtf8() function.
10209 
10210     You can disable this operator by defining \c
10211     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10212     can be useful if you want to ensure that all user-visible strings
10213     go through QObject::tr(), for example.
10214 
10215     \sa QT_NO_CAST_FROM_ASCII
10216 */
10217 
10218 /*!
10219     \fn bool QLatin1String::operator<(const QByteArray &other) const
10220     \since 5.0
10221     \overload
10222 
10223     The \a other const char pointer is converted to a QString using
10224     the QString::fromUtf8() function.
10225 
10226     You can disable this operator by defining \c
10227     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10228     can be useful if you want to ensure that all user-visible strings
10229     go through QObject::tr(), for example.
10230 
10231     \sa QT_NO_CAST_FROM_ASCII
10232 */
10233 
10234 /*!
10235     \fn bool QLatin1String::operator>=(const QString &other) const
10236 
10237     Returns \c true if this string is lexically greater than or equal
10238     to string \a other; otherwise returns \c false.
10239 
10240     \sa {Comparing Strings}
10241 */
10242 
10243 /*!
10244     \fn bool QLatin1String::operator>=(const char *other) const
10245     \since 4.3
10246     \overload
10247 
10248     The \a other const char pointer is converted to a QString using
10249     the QString::fromUtf8() function.
10250 
10251     You can disable this operator by defining \c
10252     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10253     can be useful if you want to ensure that all user-visible strings
10254     go through QObject::tr(), for example.
10255 
10256     \sa QT_NO_CAST_FROM_ASCII
10257 */
10258 
10259 /*!
10260     \fn bool QLatin1String::operator>=(const QByteArray &other) const
10261     \since 5.0
10262     \overload
10263 
10264     The \a other array is converted to a QString using
10265     the QString::fromUtf8() function.
10266 
10267     You can disable this operator by defining \c
10268     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10269     can be useful if you want to ensure that all user-visible strings
10270     go through QObject::tr(), for example.
10271 
10272     \sa QT_NO_CAST_FROM_ASCII
10273 */
10274 
10275 /*! \fn bool QLatin1String::operator<=(const QString &other) const
10276 
10277     Returns \c true if this string is lexically less than or equal
10278     to string \a other; otherwise returns \c false.
10279 
10280     \sa {Comparing Strings}
10281 */
10282 
10283 /*!
10284     \fn bool QLatin1String::operator<=(const char *other) const
10285     \since 4.3
10286     \overload
10287 
10288     The \a other const char pointer is converted to a QString using
10289     the QString::fromUtf8() function.
10290 
10291     You can disable this operator by defining \c
10292     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10293     can be useful if you want to ensure that all user-visible strings
10294     go through QObject::tr(), for example.
10295 
10296     \sa QT_NO_CAST_FROM_ASCII
10297 */
10298 
10299 /*!
10300     \fn bool QLatin1String::operator<=(const QByteArray &other) const
10301     \since 5.0
10302     \overload
10303 
10304     The \a other array is converted to a QString using
10305     the QString::fromUtf8() function.
10306 
10307     You can disable this operator by defining \c
10308     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10309     can be useful if you want to ensure that all user-visible strings
10310     go through QObject::tr(), for example.
10311 
10312     \sa QT_NO_CAST_FROM_ASCII
10313 */
10314 
10315 
10316 /*! \fn bool operator==(QLatin1String s1, QLatin1String s2)
10317    \relates QLatin1String
10318 
10319    Returns \c true if string \a s1 is lexically equal to string \a s2; otherwise
10320    returns \c false.
10321 */
10322 /*! \fn bool operator!=(QLatin1String s1, QLatin1String s2)
10323    \relates QLatin1String
10324 
10325    Returns \c true if string \a s1 is lexically unequal to string \a s2; otherwise
10326    returns \c false.
10327 */
10328 /*! \fn bool operator<(QLatin1String s1, QLatin1String s2)
10329    \relates QLatin1String
10330 
10331    Returns \c true if string \a s1 is lexically smaller than string \a s2; otherwise
10332    returns \c false.
10333 */
10334 /*! \fn bool operator<=(QLatin1String s1, QLatin1String s2)
10335    \relates QLatin1String
10336 
10337    Returns \c true if string \a s1 is lexically smaller than or equal to string \a s2; otherwise
10338    returns \c false.
10339 */
10340 /*! \fn bool operator>(QLatin1String s1, QLatin1String s2)
10341    \relates QLatin1String
10342 
10343    Returns \c true if string \a s1 is lexically greater than string \a s2; otherwise
10344    returns \c false.
10345 */
10346 /*! \fn bool operator>=(QLatin1String s1, QLatin1String s2)
10347    \relates QLatin1String
10348 
10349    Returns \c true if string \a s1 is lexically greater than or equal to
10350    string \a s2; otherwise returns \c false.
10351 */
10352 
10353 
10354 #if !defined(QT_NO_DATASTREAM) || (defined(QT_BOOTSTRAPPED) && !defined(QT_BUILD_QMAKE))
10355 /*!
10356     \fn QDataStream &operator<<(QDataStream &stream, const QString &string)
10357     \relates QString
10358 
10359     Writes the given \a string to the specified \a stream.
10360 
10361     \sa {Serializing Qt Data Types}
10362 */
10363 
operator <<(QDataStream & out,const QString & str)10364 QDataStream &operator<<(QDataStream &out, const QString &str)
10365 {
10366     if (out.version() == 1) {
10367         out << str.toLatin1();
10368     } else {
10369         if (!str.isNull() || out.version() < 3) {
10370             if ((out.byteOrder() == QDataStream::BigEndian) == (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
10371                 out.writeBytes(reinterpret_cast<const char *>(str.unicode()), sizeof(QChar) * str.length());
10372             } else {
10373                 QVarLengthArray<ushort> buffer(str.length());
10374                 qbswap<sizeof(ushort)>(str.constData(), str.length(), buffer.data());
10375                 out.writeBytes(reinterpret_cast<const char *>(buffer.data()), sizeof(ushort) * buffer.size());
10376             }
10377         } else {
10378             // write null marker
10379             out << (quint32)0xffffffff;
10380         }
10381     }
10382     return out;
10383 }
10384 
10385 /*!
10386     \fn QDataStream &operator>>(QDataStream &stream, QString &string)
10387     \relates QString
10388 
10389     Reads a string from the specified \a stream into the given \a string.
10390 
10391     \sa {Serializing Qt Data Types}
10392 */
10393 
operator >>(QDataStream & in,QString & str)10394 QDataStream &operator>>(QDataStream &in, QString &str)
10395 {
10396     if (in.version() == 1) {
10397         QByteArray l;
10398         in >> l;
10399         str = QString::fromLatin1(l);
10400     } else {
10401         quint32 bytes = 0;
10402         in >> bytes;                                  // read size of string
10403         if (bytes == 0xffffffff) {                    // null string
10404             str.clear();
10405         } else if (bytes > 0) {                       // not empty
10406             if (bytes & 0x1) {
10407                 str.clear();
10408                 in.setStatus(QDataStream::ReadCorruptData);
10409                 return in;
10410             }
10411 
10412             const quint32 Step = 1024 * 1024;
10413             quint32 len = bytes / 2;
10414             quint32 allocated = 0;
10415 
10416             while (allocated < len) {
10417                 int blockSize = qMin(Step, len - allocated);
10418                 str.resize(allocated + blockSize);
10419                 if (in.readRawData(reinterpret_cast<char *>(str.data()) + allocated * 2,
10420                                    blockSize * 2) != blockSize * 2) {
10421                     str.clear();
10422                     in.setStatus(QDataStream::ReadPastEnd);
10423                     return in;
10424                 }
10425                 allocated += blockSize;
10426             }
10427 
10428             if ((in.byteOrder() == QDataStream::BigEndian)
10429                     != (QSysInfo::ByteOrder == QSysInfo::BigEndian)) {
10430                 ushort *data = reinterpret_cast<ushort *>(str.data());
10431                 qbswap<sizeof(*data)>(data, len, data);
10432             }
10433         } else {
10434             str = QString(QLatin1String(""));
10435         }
10436     }
10437     return in;
10438 }
10439 #endif // QT_NO_DATASTREAM
10440 
10441 
10442 
10443 
10444 /*!
10445     \class QStringRef
10446     \inmodule QtCore
10447     \since 4.3
10448     \brief The QStringRef class provides a thin wrapper around QString substrings.
10449     \reentrant
10450     \ingroup tools
10451     \ingroup string-processing
10452 
10453     QStringRef provides a read-only subset of the QString API.
10454 
10455     A string reference explicitly references a portion of a string()
10456     with a given size(), starting at a specific position(). Calling
10457     toString() returns a copy of the data as a real QString instance.
10458 
10459     This class is designed to improve the performance of substring
10460     handling when manipulating substrings obtained from existing QString
10461     instances. QStringRef avoids the memory allocation and reference
10462     counting overhead of a standard QString by simply referencing a
10463     part of the original string. This can prove to be advantageous in
10464     low level code, such as that used in a parser, at the expense of
10465     potentially more complex code.
10466 
10467     For most users, there are no semantic benefits to using QStringRef
10468     instead of QString since QStringRef requires attention to be paid
10469     to memory management issues, potentially making code more complex
10470     to write and maintain.
10471 
10472     \warning A QStringRef is only valid as long as the referenced
10473     string exists. If the original string is deleted, the string
10474     reference points to an invalid memory location.
10475 
10476     We suggest that you only use this class in stable code where profiling
10477     has clearly identified that performance improvements can be made by
10478     replacing standard string operations with the optimized substring
10479     handling provided by this class.
10480 
10481     \sa {Implicitly Shared Classes}
10482 */
10483 
10484 /*!
10485     \typedef QStringRef::size_type
10486     \internal
10487 */
10488 
10489 /*!
10490     \typedef QStringRef::value_type
10491     \internal
10492 */
10493 
10494 /*!
10495     \typedef QStringRef::const_pointer
10496     \internal
10497 */
10498 
10499 /*!
10500     \typedef QStringRef::const_reference
10501     \internal
10502 */
10503 
10504 /*!
10505     \typedef QStringRef::const_iterator
10506     \since 5.4
10507 
10508     \sa QStringRef::const_reverse_iterator
10509 */
10510 
10511 /*!
10512     \typedef QStringRef::const_reverse_iterator
10513     \since 5.7
10514 
10515     \sa QStringRef::const_iterator
10516 */
10517 
10518 /*!
10519  \fn QStringRef::QStringRef()
10520 
10521  Constructs an empty string reference.
10522 */
10523 
10524 /*! \fn QStringRef::QStringRef(const QString *string, int position, int length)
10525 
10526 Constructs a string reference to the range of characters in the given
10527 \a string specified by the starting \a position and \a length in characters.
10528 
10529 \warning This function exists to improve performance as much as possible,
10530 and performs no bounds checking. For program correctness, \a position and
10531 \a length must describe a valid substring of \a string.
10532 
10533 This means that the starting \a position must be positive or 0 and smaller
10534 than \a string's length, and \a length must be positive or 0 but smaller than
10535 the string's length minus the starting \a position;
10536 i.e, 0 <= position < string->length() and
10537 0 <= length <= string->length() - position must both be satisfied.
10538 */
10539 
10540 /*! \fn QStringRef::QStringRef(const QString *string)
10541 
10542 Constructs a string reference to the given \a string.
10543 */
10544 
10545 /*! \fn QStringRef::QStringRef(const QStringRef &other)
10546 
10547 Constructs a copy of the \a other string reference.
10548  */
10549 /*!
10550 \fn QStringRef::~QStringRef()
10551 
10552 Destroys the string reference.
10553 
10554 Since this class is only used to refer to string data, and does not take
10555 ownership of it, no memory is freed when instances are destroyed.
10556 */
10557 
10558 /*!
10559     \fn int QStringRef::position() const
10560 
10561     Returns the starting position in the referenced string that is referred to
10562     by the string reference.
10563 
10564     \sa size(), string()
10565 */
10566 
10567 /*!
10568     \fn int QStringRef::size() const
10569 
10570     Returns the number of characters referred to by the string reference.
10571     Equivalent to length() and count().
10572 
10573     \sa position(), string()
10574 */
10575 /*!
10576     \fn int QStringRef::count() const
10577     Returns the number of characters referred to by the string reference.
10578     Equivalent to size() and length().
10579 
10580     \sa position(), string()
10581 */
10582 /*!
10583     \fn int QStringRef::length() const
10584     Returns the number of characters referred to by the string reference.
10585     Equivalent to size() and count().
10586 
10587     \sa position(), string()
10588 */
10589 
10590 
10591 /*!
10592     \fn bool QStringRef::isEmpty() const
10593 
10594     Returns \c true if the string reference has no characters; otherwise returns
10595     \c false.
10596 
10597     A string reference is empty if its size is zero.
10598 
10599     \sa size()
10600 */
10601 
10602 /*!
10603     \fn bool QStringRef::isNull() const
10604 
10605     Returns \c true if this string reference does not reference a string or if
10606     the string it references is null (i.e. QString::isNull() is true).
10607 
10608     \sa size()
10609 */
10610 
10611 /*!
10612     \fn const QString *QStringRef::string() const
10613 
10614     Returns a pointer to the string referred to by the string reference, or
10615     0 if it does not reference a string.
10616 
10617     \sa unicode()
10618 */
10619 
10620 
10621 /*!
10622     \fn const QChar *QStringRef::unicode() const
10623 
10624     Returns a Unicode representation of the string reference. Since
10625     the data stems directly from the referenced string, it is not
10626     \\0'-terminated unless the string reference includes the string's
10627     null terminator.
10628 
10629     \sa string()
10630 */
10631 
10632 /*!
10633     \fn const QChar *QStringRef::data() const
10634 
10635     Same as unicode().
10636 */
10637 
10638 /*!
10639     \fn const QChar *QStringRef::constData() const
10640 
10641     Same as unicode().
10642 */
10643 
10644 /*!
10645     \fn QStringRef::const_iterator QStringRef::begin() const
10646     \since 5.4
10647 
10648     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character in
10649     the string.
10650 
10651     \sa cbegin(), constBegin(), end(), constEnd(), rbegin(), rend()
10652 */
10653 
10654 /*!
10655     \fn QStringRef::const_iterator QStringRef::cbegin() const
10656     \since 5.4
10657 
10658     Same as begin().
10659 
10660     \sa begin(), constBegin(), cend(), constEnd(), rbegin(), rend()
10661 */
10662 
10663 /*!
10664     \fn QStringRef::const_iterator QStringRef::constBegin() const
10665     \since 5.9
10666 
10667     Same as begin().
10668 
10669     \sa begin(), cend(), constEnd(), rbegin(), rend()
10670 */
10671 
10672 /*!
10673     \fn QStringRef::const_iterator QStringRef::end() const
10674     \since 5.4
10675 
10676     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
10677     character after the last character in the list.
10678 
10679     \sa cbegin(), constBegin(), end(), constEnd(), rbegin(), rend()
10680 */
10681 
10682 /*! \fn QStringRef::const_iterator QStringRef::cend() const
10683     \since 5.4
10684 
10685     Same as end().
10686 
10687     \sa end(), constEnd(), cbegin(), constBegin(), rbegin(), rend()
10688 */
10689 
10690 /*! \fn QStringRef::const_iterator QStringRef::constEnd() const
10691     \since 5.9
10692 
10693     Same as end().
10694 
10695     \sa end(), cend(), cbegin(), constBegin(), rbegin(), rend()
10696 */
10697 
10698 /*!
10699     \fn QStringRef::const_reverse_iterator QStringRef::rbegin() const
10700     \since 5.7
10701 
10702     Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
10703     character in the string, in reverse order.
10704 
10705     \sa begin(), crbegin(), rend()
10706 */
10707 
10708 /*!
10709     \fn QStringRef::const_reverse_iterator QStringRef::crbegin() const
10710     \since 5.7
10711 
10712     Same as rbegin().
10713 
10714     \sa begin(), rbegin(), rend()
10715 */
10716 
10717 /*!
10718     \fn QStringRef::const_reverse_iterator QStringRef::rend() const
10719     \since 5.7
10720 
10721     Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
10722     the last character in the string, in reverse order.
10723 
10724     \sa end(), crend(), rbegin()
10725 */
10726 
10727 
10728 /*!
10729     \fn QStringRef::const_reverse_iterator QStringRef::crend() const
10730     \since 5.7
10731 
10732     Same as rend().
10733 
10734     \sa end(), rend(), rbegin()
10735 */
10736 
10737 /*!
10738     Returns a copy of the string reference as a QString object.
10739 
10740     If the string reference is not a complete reference of the string
10741     (meaning that position() is 0 and size() equals string()->size()),
10742     this function will allocate a new string to return.
10743 
10744     \sa string()
10745 */
10746 
toString() const10747 QString QStringRef::toString() const {
10748     if (!m_string)
10749         return QString();
10750     if (m_size && m_position == 0 && m_size == m_string->size())
10751         return *m_string;
10752     return QString(m_string->unicode() + m_position, m_size);
10753 }
10754 
10755 
10756 /*! \relates QStringRef
10757 
10758    Returns \c true if string reference \a s1 is lexically equal to string reference \a s2; otherwise
10759    returns \c false.
10760 */
operator ==(const QStringRef & s1,const QStringRef & s2)10761 bool operator==(const QStringRef &s1,const QStringRef &s2) noexcept
10762 {
10763     return s1.size() == s2.size() && qt_compare_strings(s1, s2, Qt::CaseSensitive) == 0;
10764 }
10765 
10766 /*! \relates QStringRef
10767 
10768    Returns \c true if string \a s1 is lexically equal to string reference \a s2; otherwise
10769    returns \c false.
10770 */
operator ==(const QString & s1,const QStringRef & s2)10771 bool operator==(const QString &s1,const QStringRef &s2) noexcept
10772 {
10773     return s1.size() == s2.size() && qt_compare_strings(s1, s2, Qt::CaseSensitive) == 0;
10774 }
10775 
10776 /*! \relates QStringRef
10777 
10778    Returns \c true if string  \a s1 is lexically equal to string reference \a s2; otherwise
10779    returns \c false.
10780 */
operator ==(QLatin1String s1,const QStringRef & s2)10781 bool operator==(QLatin1String s1, const QStringRef &s2) noexcept
10782 {
10783     if (s1.size() != s2.size())
10784         return false;
10785 
10786     return qt_compare_strings(s2, s1, Qt::CaseSensitive) == 0;
10787 }
10788 
10789 /*!
10790    \relates QStringRef
10791 
10792     Returns \c true if string reference \a s1 is lexically less than
10793     string reference \a s2; otherwise returns \c false.
10794 
10795     \sa {Comparing Strings}
10796 */
operator <(const QStringRef & s1,const QStringRef & s2)10797 bool operator<(const QStringRef &s1,const QStringRef &s2) noexcept
10798 {
10799     return qt_compare_strings(s1, s2, Qt::CaseSensitive) < 0;
10800 }
10801 
10802 /*!\fn bool operator<=(const QStringRef &s1,const QStringRef &s2)
10803 
10804    \relates QStringRef
10805 
10806     Returns \c true if string reference \a s1 is lexically less than
10807     or equal to string reference \a s2; otherwise returns \c false.
10808 
10809     \sa {Comparing Strings}
10810 */
10811 
10812 /*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2)
10813 
10814    \relates QStringRef
10815 
10816     Returns \c true if string reference \a s1 is lexically greater than
10817     or equal to string reference \a s2; otherwise returns \c false.
10818 
10819     \sa {Comparing Strings}
10820 */
10821 
10822 /*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2)
10823 
10824    \relates QStringRef
10825 
10826     Returns \c true if string reference \a s1 is lexically greater than
10827     string reference \a s2; otherwise returns \c false.
10828 
10829     \sa {Comparing Strings}
10830 */
10831 
10832 
10833 /*!
10834     \fn const QChar QStringRef::at(int position) const
10835 
10836     Returns the character at the given index \a position in the
10837     string reference.
10838 
10839     The \a position must be a valid index position in the string
10840     (i.e., 0 <= \a position < size()).
10841 */
10842 
10843 /*!
10844     \fn QChar QStringRef::operator[](int position) const
10845     \since 5.7
10846 
10847     Returns the character at the given index \a position in the
10848     string reference.
10849 
10850     The \a position must be a valid index position in the string
10851     reference (i.e., 0 <= \a position < size()).
10852 
10853     \sa at()
10854 */
10855 
10856 /*!
10857     \fn QChar QStringRef::front() const
10858     \since 5.10
10859 
10860     Returns the first character in the string.
10861     Same as \c{at(0)}.
10862 
10863     This function is provided for STL compatibility.
10864 
10865     \warning Calling this function on an empty string constitutes
10866     undefined behavior.
10867 
10868     \sa back(), at(), operator[]()
10869 */
10870 
10871 /*!
10872     \fn QChar QStringRef::back() const
10873     \since 5.10
10874 
10875     Returns the last character in the string.
10876     Same as \c{at(size() - 1)}.
10877 
10878     This function is provided for STL compatibility.
10879 
10880     \warning Calling this function on an empty string constitutes
10881     undefined behavior.
10882 
10883     \sa front(), at(), operator[]()
10884 */
10885 
10886 /*!
10887     \fn void QStringRef::clear()
10888 
10889     Clears the contents of the string reference by making it null and empty.
10890 
10891     \sa isEmpty(), isNull()
10892 */
10893 
10894 /*!
10895     \fn QStringRef &QStringRef::operator=(const QStringRef &other)
10896 
10897     Assigns the \a other string reference to this string reference, and
10898     returns the result.
10899 */
10900 
10901 /*!
10902     \fn QStringRef &QStringRef::operator=(const QString *string)
10903 
10904     Constructs a string reference to the given \a string and assigns it to
10905     this string reference, returning the result.
10906 */
10907 
10908 /*!
10909     \fn bool QStringRef::operator==(const char * s) const
10910 
10911     \overload operator==()
10912 
10913     The \a s byte array is converted to a QStringRef using the
10914     fromUtf8() function. This function stops conversion at the
10915     first NUL character found, or the end of the byte array.
10916 
10917     You can disable this operator by defining \c
10918     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10919     can be useful if you want to ensure that all user-visible strings
10920     go through QObject::tr(), for example.
10921 
10922     Returns \c true if this string is lexically equal to the parameter
10923     string \a s. Otherwise returns \c false.
10924 
10925     \sa QT_NO_CAST_FROM_ASCII
10926 */
10927 
10928 /*!
10929     \fn bool QStringRef::operator!=(const char * s) const
10930 
10931     \overload operator!=()
10932 
10933     The \a s const char pointer is converted to a QStringRef using
10934     the fromUtf8() function.
10935 
10936     You can disable this operator by defining \c
10937     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10938     can be useful if you want to ensure that all user-visible strings
10939     go through QObject::tr(), for example.
10940 
10941     Returns \c true if this string is not lexically equal to the parameter
10942     string \a s. Otherwise returns \c false.
10943 
10944     \sa QT_NO_CAST_FROM_ASCII
10945 */
10946 
10947 /*!
10948     \fn bool QStringRef::operator<(const char * s) const
10949 
10950     \overload operator<()
10951 
10952     The \a s const char pointer is converted to a QStringRef using
10953     the fromUtf8() function.
10954 
10955     You can disable this operator by defining \c
10956     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10957     can be useful if you want to ensure that all user-visible strings
10958     go through QObject::tr(), for example.
10959 
10960     Returns \c true if this string is lexically smaller than the parameter
10961     string \a s. Otherwise returns \c false.
10962 
10963     \sa QT_NO_CAST_FROM_ASCII
10964 */
10965 
10966 /*!
10967     \fn bool QStringRef::operator<=(const char * s) const
10968 
10969     \overload operator<=()
10970 
10971     The \a s const char pointer is converted to a QStringRef using
10972     the fromUtf8() function.
10973 
10974     You can disable this operator by defining \c
10975     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10976     can be useful if you want to ensure that all user-visible strings
10977     go through QObject::tr(), for example.
10978 
10979     Returns \c true if this string is lexically smaller than or equal to the parameter
10980     string \a s. Otherwise returns \c false.
10981 
10982     \sa QT_NO_CAST_FROM_ASCII
10983 */
10984 
10985 /*!
10986     \fn bool QStringRef::operator>(const char * s) const
10987 
10988 
10989     \overload operator>()
10990 
10991     The \a s const char pointer is converted to a QStringRef using
10992     the fromUtf8() function.
10993 
10994     You can disable this operator by defining \c
10995     QT_NO_CAST_FROM_ASCII when you compile your applications. This
10996     can be useful if you want to ensure that all user-visible strings
10997     go through QObject::tr(), for example.
10998 
10999     Returns \c true if this string is lexically greater than the parameter
11000     string \a s. Otherwise returns \c false.
11001 
11002     \sa QT_NO_CAST_FROM_ASCII
11003 */
11004 
11005 /*!
11006     \fn bool QStringRef::operator>= (const char * s) const
11007 
11008     \overload operator>=()
11009 
11010     The \a s const char pointer is converted to a QStringRef using
11011     the fromUtf8() function.
11012 
11013     You can disable this operator by defining \c
11014     QT_NO_CAST_FROM_ASCII when you compile your applications. This
11015     can be useful if you want to ensure that all user-visible strings
11016     go through QObject::tr(), for example.
11017 
11018     Returns \c true if this string is lexically greater than or equal to the
11019     parameter string \a s. Otherwise returns \c false.
11020 
11021     \sa QT_NO_CAST_FROM_ASCII
11022 */
11023 /*!
11024     \typedef QString::Data
11025     \internal
11026 */
11027 
11028 /*!
11029     \typedef QString::DataPtr
11030     \internal
11031 */
11032 
11033 /*!
11034     \fn DataPtr & QString::data_ptr()
11035     \internal
11036 */
11037 
11038 
11039 
11040 /*!  Appends the string reference to \a string, and returns a new
11041 reference to the combined string data.
11042  */
appendTo(QString * string) const11043 QStringRef QStringRef::appendTo(QString *string) const
11044 {
11045     if (!string)
11046         return QStringRef();
11047     int pos = string->size();
11048     string->insert(pos, unicode(), size());
11049     return QStringRef(string, pos, size());
11050 }
11051 
11052 /*!
11053     \fn int QStringRef::compare(const QStringRef &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
11054     \since 4.5
11055 
11056     Compares the string \a s1 with the string \a s2 and returns an
11057     integer less than, equal to, or greater than zero if \a s1
11058     is less than, equal to, or greater than \a s2.
11059 
11060     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11061     otherwise the comparison is case insensitive.
11062 */
11063 
11064 /*!
11065     \fn int QStringRef::compare(const QStringRef &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
11066     \since 4.5
11067     \overload
11068 
11069     Compares the string \a s1 with the string \a s2 and returns an
11070     integer less than, equal to, or greater than zero if \a s1
11071     is less than, equal to, or greater than \a s2.
11072 
11073     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11074     otherwise the comparison is case insensitive.
11075 */
11076 
11077 /*!
11078     \fn int QStringRef::compare(const QStringRef &s1, QLatin1String s2, Qt::CaseSensitivity cs = Qt::CaseSensitive)
11079     \since 4.5
11080     \overload
11081 
11082     Compares the string \a s1 with the string \a s2 and returns an
11083     integer less than, equal to, or greater than zero if \a s1
11084     is less than, equal to, or greater than \a s2.
11085 
11086     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11087     otherwise the comparison is case insensitive.
11088 */
11089 
11090 /*!
11091     \overload
11092     \fn int QStringRef::compare(const QString &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11093     \since 4.5
11094 
11095     Compares this string with the \a other string and returns an
11096     integer less than, equal to, or greater than zero if this string
11097     is less than, equal to, or greater than the \a other string.
11098 
11099     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11100     otherwise the comparison is case insensitive.
11101 
11102     Equivalent to \c {compare(*this, other, cs)}.
11103 */
11104 
11105 /*!
11106     \overload
11107     \fn int QStringRef::compare(const QStringRef &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11108     \since 4.5
11109 
11110     Compares this string with the \a other string and returns an
11111     integer less than, equal to, or greater than zero if this string
11112     is less than, equal to, or greater than the \a other string.
11113 
11114     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11115     otherwise the comparison is case insensitive.
11116 
11117     Equivalent to \c {compare(*this, other, cs)}.
11118 */
11119 
11120 /*!
11121     \overload
11122     \fn int QStringRef::compare(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11123     \since 5.14
11124 
11125     Compares this string with \a ch and returns an
11126     integer less than, equal to, or greater than zero if this string
11127     is less than, equal to, or greater than \a ch, interpreted as a string of length one.
11128 
11129     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11130     otherwise the comparison is case insensitive.
11131 */
11132 
11133 /*!
11134     \overload
11135     \fn int QStringRef::compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11136     \since 4.5
11137 
11138     Compares this string with the \a other string and returns an
11139     integer less than, equal to, or greater than zero if this string
11140     is less than, equal to, or greater than the \a other string.
11141 
11142     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11143     otherwise the comparison is case insensitive.
11144 
11145     Equivalent to \c {compare(*this, other, cs)}.
11146 */
11147 
11148 /*!
11149     \overload
11150     \fn int QStringRef::compare(const QByteArray &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11151     \since 5.8
11152 
11153     Compares this string with \a other and returns an
11154     integer less than, equal to, or greater than zero if this string
11155     is less than, equal to, or greater than the \a other byte array,
11156     interpreted as a UTF-8 sequence.
11157 
11158     If \a cs is Qt::CaseSensitive, the comparison is case sensitive;
11159     otherwise the comparison is case insensitive.
11160 
11161     Equivalent to \c {compare(*this, other, cs)}.
11162 */
11163 
11164 /*!
11165     \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QString & s2)
11166     \since 4.5
11167 
11168     Compares \a s1 with \a s2 and returns an integer less than, equal
11169     to, or greater than zero if \a s1 is less than, equal to, or
11170     greater than \a s2.
11171 
11172     The comparison is performed in a locale- and also
11173     platform-dependent manner. Use this function to present sorted
11174     lists of strings to the user.
11175 
11176     \sa compare(), QLocale, {Comparing Strings}
11177 */
11178 
11179 /*!
11180     \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QStringRef & s2)
11181     \since 4.5
11182     \overload
11183 
11184     Compares \a s1 with \a s2 and returns an integer less than, equal
11185     to, or greater than zero if \a s1 is less than, equal to, or
11186     greater than \a s2.
11187 
11188     The comparison is performed in a locale- and also
11189     platform-dependent manner. Use this function to present sorted
11190     lists of strings to the user.
11191 
11192     \sa {Comparing Strings}
11193 */
11194 
11195 /*!
11196     \fn int QStringRef::localeAwareCompare(const QString &other) const
11197     \since 4.5
11198     \overload
11199 
11200     Compares this string with the \a other string and returns an
11201     integer less than, equal to, or greater than zero if this string
11202     is less than, equal to, or greater than the \a other string.
11203 
11204     The comparison is performed in a locale- and also
11205     platform-dependent manner. Use this function to present sorted
11206     lists of strings to the user.
11207 
11208     \sa {Comparing Strings}
11209 */
11210 
11211 /*!
11212     \fn int QStringRef::localeAwareCompare(const QStringRef &other) const
11213     \since 4.5
11214     \overload
11215 
11216     Compares this string with the \a other string and returns an
11217     integer less than, equal to, or greater than zero if this string
11218     is less than, equal to, or greater than the \a other string.
11219 
11220     The comparison is performed in a locale- and also
11221     platform-dependent manner. Use this function to present sorted
11222     lists of strings to the user.
11223 
11224     \sa {Comparing Strings}
11225 */
11226 
11227 /*!
11228     \fn QString &QString::append(const QStringRef &reference)
11229     \since 4.4
11230 
11231     Appends the given string \a reference to this string and returns the result.
11232  */
append(const QStringRef & str)11233 QString &QString::append(const QStringRef &str)
11234 {
11235     if (str.string() == this) {
11236         str.appendTo(this);
11237     } else if (!str.isNull()) {
11238         int oldSize = size();
11239         resize(oldSize + str.size());
11240         memcpy(data() + oldSize, str.unicode(), str.size() * sizeof(QChar));
11241     }
11242     return *this;
11243 }
11244 
11245 /*!
11246     \fn QString &QString::append(QStringView str)
11247     \since 5.15.2
11248 
11249     Appends the given string \a str to this string and returns the result.
11250 
11251     \note This method has been added in 5.15.2 to simplify writing code that is portable
11252     between Qt 5.15 and Qt 6.
11253 */
11254 
11255 /*!
11256     \fn QStringRef::left(int n) const
11257     \since 5.2
11258 
11259     Returns a substring reference to the \a n leftmost characters
11260     of the string.
11261 
11262     If \a n is greater than or equal to size(), or less than zero,
11263     a reference to the entire string is returned.
11264 
11265     \sa right(), mid(), startsWith(), chopped(), chop(), truncate()
11266 */
left(int n) const11267 QStringRef QStringRef::left(int n) const
11268 {
11269     if (uint(n) >= uint(m_size))
11270         return *this;
11271     return QStringRef(m_string, m_position, n);
11272 }
11273 
11274 /*!
11275     \since 4.4
11276 
11277     Returns a substring reference to the \a n leftmost characters
11278     of the string.
11279 
11280     If \a n is greater than or equal to size(), or less than zero,
11281     a reference to the entire string is returned.
11282 
11283     \snippet qstring/main.cpp leftRef
11284 
11285     \sa left(), rightRef(), midRef(), startsWith()
11286 */
leftRef(int n) const11287 QStringRef QString::leftRef(int n)  const
11288 {
11289     return QStringRef(this).left(n);
11290 }
11291 
11292 /*!
11293     \fn QStringRef::right(int n) const
11294     \since 5.2
11295 
11296     Returns a substring reference to the \a n rightmost characters
11297     of the string.
11298 
11299     If \a n is greater than or equal to size(), or less than zero,
11300     a reference to the entire string is returned.
11301 
11302     \sa left(), mid(), endsWith(), chopped(), chop(), truncate()
11303 */
right(int n) const11304 QStringRef QStringRef::right(int n) const
11305 {
11306     if (uint(n) >= uint(m_size))
11307         return *this;
11308     return QStringRef(m_string, m_size - n + m_position, n);
11309 }
11310 
11311 /*!
11312     \since 4.4
11313 
11314     Returns a substring reference to the \a n rightmost characters
11315     of the string.
11316 
11317     If \a n is greater than or equal to size(), or less than zero,
11318     a reference to the entire string is returned.
11319 
11320     \snippet qstring/main.cpp rightRef
11321 
11322     \sa right(), leftRef(), midRef(), endsWith()
11323 */
rightRef(int n) const11324 QStringRef QString::rightRef(int n) const
11325 {
11326     return QStringRef(this).right(n);
11327 }
11328 
11329 /*!
11330     \fn QStringRef QStringRef::mid(int position, int n = -1) const
11331     \since 5.2
11332 
11333     Returns a substring reference to \a n characters of this string,
11334     starting at the specified \a position.
11335 
11336     If the \a position exceeds the length of the string, a null
11337     reference is returned.
11338 
11339     If there are less than \a n characters available in the string,
11340     starting at the given \a position, or if \a n is -1 (default), the
11341     function returns all characters from the specified \a position
11342     onwards.
11343 
11344     \sa left(), right(), chopped(), chop(), truncate()
11345 */
mid(int pos,int n) const11346 QStringRef QStringRef::mid(int pos, int n) const
11347 {
11348     using namespace QtPrivate;
11349     switch (QContainerImplHelper::mid(m_size, &pos, &n)) {
11350     case QContainerImplHelper::Null:
11351         return QStringRef();
11352     case QContainerImplHelper::Empty:
11353         return QStringRef(m_string, 0, 0);
11354     case QContainerImplHelper::Full:
11355         return *this;
11356     case QContainerImplHelper::Subset:
11357         return QStringRef(m_string, pos + m_position, n);
11358     }
11359     Q_UNREACHABLE();
11360     return QStringRef();
11361 }
11362 
11363 /*!
11364     \fn QStringRef QStringRef::chopped(int len) const
11365     \since 5.10
11366 
11367     Returns a substring reference to the size() - \a len leftmost characters
11368     of this string.
11369 
11370     \note The behavior is undefined if \a len is negative or greater than size().
11371 
11372     \sa endsWith(), left(), right(), mid(), chop(), truncate()
11373 */
11374 
11375 /*!
11376     \since 4.4
11377 
11378     Returns a substring reference to \a n characters of this string,
11379     starting at the specified \a position.
11380 
11381     If the \a position exceeds the length of the string, a null
11382     reference is returned.
11383 
11384     If there are less than \a n characters available in the string,
11385     starting at the given \a position, or if \a n is -1 (default), the
11386     function returns all characters from the specified \a position
11387     onwards.
11388 
11389     Example:
11390 
11391     \snippet qstring/main.cpp midRef
11392 
11393     \sa mid(), leftRef(), rightRef()
11394 */
midRef(int position,int n) const11395 QStringRef QString::midRef(int position, int n) const
11396 {
11397     return QStringRef(this).mid(position, n);
11398 }
11399 
11400 /*!
11401     \fn void QStringRef::truncate(int position)
11402     \since 5.6
11403 
11404     Truncates the string at the given \a position index.
11405 
11406     If the specified \a position index is beyond the end of the
11407     string, nothing happens.
11408 
11409     If \a position is negative, it is equivalent to passing zero.
11410 
11411     \sa QString::truncate()
11412 */
11413 
11414 /*!
11415     \fn void QStringRef::chop(int n)
11416     \since 5.8
11417 
11418     Removes \a n characters from the end of the string.
11419 
11420     If \a n is greater than or equal to size(), the result is an
11421     empty string; if \a n is negative, it is equivalent to passing zero.
11422 
11423     \sa QString::chop(), truncate()
11424 */
11425 
11426 #if QT_STRINGVIEW_LEVEL < 2
11427 /*!
11428   \since 4.8
11429 
11430   Returns the index position of the first occurrence of the string \a
11431   str in this string reference, searching forward from index position
11432   \a from. Returns -1 if \a str is not found.
11433 
11434   If \a cs is Qt::CaseSensitive (default), the search is case
11435   sensitive; otherwise the search is case insensitive.
11436 
11437   If \a from is -1, the search starts at the last character; if it is
11438   -2, at the next to last character and so on.
11439 
11440   \sa QString::indexOf(), lastIndexOf(), contains(), count()
11441 */
indexOf(const QString & str,int from,Qt::CaseSensitivity cs) const11442 int QStringRef::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
11443 {
11444     // ### Qt6: qsizetype
11445     return int(QtPrivate::findString(QStringView(unicode(), length()), from, QStringView(str.unicode(), str.length()), cs));
11446 }
11447 #endif // QT_STRINGVIEW_LEVEL < 2
11448 
11449 /*!
11450     \fn int QStringRef::indexOf(QStringView str, int from, Qt::CaseSensitivity cs) const
11451     \since 5.14
11452     \overload indexOf()
11453 
11454     Returns the index position of the first occurrence of the string view \a str
11455     in this string reference, searching forward from index position \a from.
11456     Returns -1 if \a str is not found.
11457 
11458     If \a cs is Qt::CaseSensitive (default), the search is case
11459     sensitive; otherwise the search is case insensitive.
11460 
11461     If \a from is -1, the search starts at the last character; if it is
11462     -2, at the next to last character and so on.
11463 
11464     \sa QString::indexOf(), QStringView::indexOf(), lastIndexOf(), contains(), count()
11465 */
11466 
11467 /*!
11468     \since 4.8
11469     \overload indexOf()
11470 
11471     Returns the index position of the first occurrence of the
11472     character \a ch in the string reference, searching forward from
11473     index position \a from. Returns -1 if \a ch could not be found.
11474 
11475     \sa QString::indexOf(), lastIndexOf(), contains(), count()
11476 */
indexOf(QChar ch,int from,Qt::CaseSensitivity cs) const11477 int QStringRef::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
11478 {
11479     // ### Qt6: qsizetype
11480     return int(qFindChar(QStringView(unicode(), length()), ch, from, cs));
11481 }
11482 
11483 /*!
11484   \since 4.8
11485 
11486   Returns the index position of the first occurrence of the string \a
11487   str in this string reference, searching forward from index position
11488   \a from. Returns -1 if \a str is not found.
11489 
11490   If \a cs is Qt::CaseSensitive (default), the search is case
11491   sensitive; otherwise the search is case insensitive.
11492 
11493   If \a from is -1, the search starts at the last character; if it is
11494   -2, at the next to last character and so on.
11495 
11496   \sa QString::indexOf(), lastIndexOf(), contains(), count()
11497 */
indexOf(QLatin1String str,int from,Qt::CaseSensitivity cs) const11498 int QStringRef::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
11499 {
11500     // ### Qt6: qsizetype
11501     return int(QtPrivate::findString(QStringView(unicode(), size()), from, str, cs));
11502 }
11503 
11504 #if QT_STRINGVIEW_LEVEL < 2
11505 /*!
11506     \since 4.8
11507 
11508     \overload indexOf()
11509 
11510     Returns the index position of the first occurrence of the string
11511     reference \a str in this string reference, searching forward from
11512     index position \a from. Returns -1 if \a str is not found.
11513 
11514     If \a cs is Qt::CaseSensitive (default), the search is case
11515     sensitive; otherwise the search is case insensitive.
11516 
11517     \sa QString::indexOf(), lastIndexOf(), contains(), count()
11518 */
indexOf(const QStringRef & str,int from,Qt::CaseSensitivity cs) const11519 int QStringRef::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
11520 {
11521     // ### Qt6: qsizetype
11522     return int(QtPrivate::findString(QStringView(unicode(), size()), from, QStringView(str.unicode(), str.size()), cs));
11523 }
11524 #endif // QT_STRINGVIEW_LEVEL < 2
11525 
11526 /*!
11527   \since 4.8
11528 
11529   Returns the index position of the last occurrence of the string \a
11530   str in this string reference, searching backward from index position
11531   \a from. If \a from is -1 (default), the search starts at the last
11532   character; if \a from is -2, at the next to last character and so
11533   on. Returns -1 if \a str is not found.
11534 
11535   If \a cs is Qt::CaseSensitive (default), the search is case
11536   sensitive; otherwise the search is case insensitive.
11537 
11538   \sa QString::lastIndexOf(), indexOf(), contains(), count()
11539 */
lastIndexOf(const QString & str,int from,Qt::CaseSensitivity cs) const11540 int QStringRef::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const
11541 {
11542     // ### Qt6: qsizetype
11543     return int(QtPrivate::lastIndexOf(*this, from, str, cs));
11544 }
11545 
11546 /*!
11547   \since 4.8
11548   \overload lastIndexOf()
11549 
11550   Returns the index position of the last occurrence of the character
11551   \a ch, searching backward from position \a from.
11552 
11553   \sa QString::lastIndexOf(), indexOf(), contains(), count()
11554 */
lastIndexOf(QChar ch,int from,Qt::CaseSensitivity cs) const11555 int QStringRef::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const
11556 {
11557     // ### Qt6: qsizetype
11558     return int(qLastIndexOf(*this, ch, from, cs));
11559 }
11560 
11561 /*!
11562   \since 4.8
11563   \overload lastIndexOf()
11564 
11565   Returns the index position of the last occurrence of the string \a
11566   str in this string reference, searching backward from index position
11567   \a from. If \a from is -1 (default), the search starts at the last
11568   character; if \a from is -2, at the next to last character and so
11569   on. Returns -1 if \a str is not found.
11570 
11571   If \a cs is Qt::CaseSensitive (default), the search is case
11572   sensitive; otherwise the search is case insensitive.
11573 
11574   \sa QString::lastIndexOf(), indexOf(), contains(), count()
11575 */
lastIndexOf(QLatin1String str,int from,Qt::CaseSensitivity cs) const11576 int QStringRef::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const
11577 {
11578     // ### Qt6: qsizetype
11579     return int(QtPrivate::lastIndexOf(*this, from, str, cs));
11580 }
11581 
11582 /*!
11583   \since 4.8
11584   \overload lastIndexOf()
11585 
11586   Returns the index position of the last occurrence of the string
11587   reference \a str in this string reference, searching backward from
11588   index position \a from. If \a from is -1 (default), the search
11589   starts at the last character; if \a from is -2, at the next to last
11590   character and so on. Returns -1 if \a str is not found.
11591 
11592   If \a cs is Qt::CaseSensitive (default), the search is case
11593   sensitive; otherwise the search is case insensitive.
11594 
11595   \sa QString::lastIndexOf(), indexOf(), contains(), count()
11596 */
lastIndexOf(const QStringRef & str,int from,Qt::CaseSensitivity cs) const11597 int QStringRef::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const
11598 {
11599     // ### Qt6: qsizetype
11600     return int(QtPrivate::lastIndexOf(*this, from, str, cs));
11601 }
11602 
11603 /*!
11604   \fn int QStringRef::lastIndexOf(QStringView str, int from, Qt::CaseSensitivity cs) const
11605   \since 5.14
11606   \overload lastIndexOf()
11607 
11608   Returns the index position of the last occurrence of the string view \a
11609   str in this string, searching backward from index position \a
11610   from. If \a from is -1 (default), the search starts at the last
11611   character; if \a from is -2, at the next to last character and so
11612   on. Returns -1 if \a str is not found.
11613 
11614   If \a cs is Qt::CaseSensitive (default), the search is case
11615   sensitive; otherwise the search is case insensitive.
11616 
11617   \sa indexOf(), contains(), count()
11618 */
11619 
11620 /*!
11621     \since 4.8
11622     Returns the number of (potentially overlapping) occurrences of
11623     the string \a str in this string reference.
11624 
11625     If \a cs is Qt::CaseSensitive (default), the search is
11626     case sensitive; otherwise the search is case insensitive.
11627 
11628     \sa QString::count(), contains(), indexOf()
11629 */
count(const QString & str,Qt::CaseSensitivity cs) const11630 int QStringRef::count(const QString &str, Qt::CaseSensitivity cs) const
11631 {
11632     // ### Qt6: qsizetype
11633     return int(qt_string_count(QStringView(unicode(), size()), QStringView(str.unicode(), str.size()), cs));
11634 }
11635 
11636 /*!
11637     \since 4.8
11638     \overload count()
11639 
11640     Returns the number of occurrences of the character \a ch in the
11641     string reference.
11642 
11643     If \a cs is Qt::CaseSensitive (default), the search is
11644     case sensitive; otherwise the search is case insensitive.
11645 
11646     \sa QString::count(), contains(), indexOf()
11647 */
count(QChar ch,Qt::CaseSensitivity cs) const11648 int QStringRef::count(QChar ch, Qt::CaseSensitivity cs) const
11649 {
11650     // ### Qt6: qsizetype
11651     return int(qt_string_count(QStringView(unicode(), size()), ch, cs));
11652 }
11653 
11654 /*!
11655     \since 4.8
11656     \overload count()
11657 
11658     Returns the number of (potentially overlapping) occurrences of the
11659     string reference \a str in this string reference.
11660 
11661     If \a cs is Qt::CaseSensitive (default), the search is
11662     case sensitive; otherwise the search is case insensitive.
11663 
11664     \sa QString::count(), contains(), indexOf()
11665 */
count(const QStringRef & str,Qt::CaseSensitivity cs) const11666 int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs) const
11667 {
11668     // ### Qt6: qsizetype
11669     return int(qt_string_count(QStringView(unicode(), size()), QStringView(str.unicode(), str.size()), cs));
11670 }
11671 
11672 /*!
11673     \since 5.9
11674 
11675     Returns \c true if the string is read right to left.
11676 
11677     \sa QString::isRightToLeft()
11678 */
isRightToLeft() const11679 bool QStringRef::isRightToLeft() const
11680 {
11681     return QtPrivate::isRightToLeft(QStringView(unicode(), size()));
11682 }
11683 
11684 /*!
11685     \since 5.11
11686     \internal
11687     \relates QStringView
11688 
11689     Returns \c true if the string is read right to left.
11690 
11691     \sa QString::isRightToLeft()
11692 */
isRightToLeft(QStringView string)11693 bool QtPrivate::isRightToLeft(QStringView string) noexcept
11694 {
11695     const ushort *p = reinterpret_cast<const ushort*>(string.data());
11696     const ushort * const end = p + string.size();
11697     int isolateLevel = 0;
11698     while (p < end) {
11699         uint ucs4 = *p;
11700         if (QChar::isHighSurrogate(ucs4) && p < end - 1) {
11701             ushort low = p[1];
11702             if (QChar::isLowSurrogate(low)) {
11703                 ucs4 = QChar::surrogateToUcs4(ucs4, low);
11704                 ++p;
11705             }
11706         }
11707         switch (QChar::direction(ucs4))
11708         {
11709         case QChar::DirRLI:
11710         case QChar::DirLRI:
11711         case QChar::DirFSI:
11712             ++isolateLevel;
11713             break;
11714         case QChar::DirPDI:
11715             if (isolateLevel)
11716                 --isolateLevel;
11717             break;
11718         case QChar::DirL:
11719             if (isolateLevel)
11720                 break;
11721             return false;
11722         case QChar::DirR:
11723         case QChar::DirAL:
11724             if (isolateLevel)
11725                 break;
11726             return true;
11727         default:
11728             break;
11729         }
11730         ++p;
11731     }
11732     return false;
11733 }
11734 
11735 /*!
11736     \since 4.8
11737 
11738     Returns \c true if the string reference starts with \a str; otherwise
11739     returns \c false.
11740 
11741     If \a cs is Qt::CaseSensitive (default), the search is
11742     case sensitive; otherwise the search is case insensitive.
11743 
11744     \sa QString::startsWith(), endsWith()
11745 */
startsWith(const QString & str,Qt::CaseSensitivity cs) const11746 bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs) const
11747 {
11748     return qt_starts_with(*this, str, cs);
11749 }
11750 
11751 /*!
11752     \since 4.8
11753     \overload startsWith()
11754     \sa QString::startsWith(), endsWith()
11755 */
startsWith(QLatin1String str,Qt::CaseSensitivity cs) const11756 bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs) const
11757 {
11758     return qt_starts_with(*this, str, cs);
11759 }
11760 
11761 /*!
11762     \fn bool QStringRef::startsWith(QStringView str, Qt::CaseSensitivity cs) const
11763     \since 5.10
11764     \overload startsWith()
11765     \sa QString::startsWith(), endsWith()
11766 */
11767 
11768 /*!
11769     \since 4.8
11770     \overload startsWith()
11771     \sa QString::startsWith(), endsWith()
11772 */
startsWith(const QStringRef & str,Qt::CaseSensitivity cs) const11773 bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
11774 {
11775     return qt_starts_with(*this, str, cs);
11776 }
11777 
11778 /*!
11779     \since 4.8
11780     \overload startsWith()
11781 
11782     Returns \c true if the string reference starts with \a ch; otherwise
11783     returns \c false.
11784 
11785     If \a cs is Qt::CaseSensitive (default), the search is case
11786     sensitive; otherwise the search is case insensitive.
11787 
11788     \sa QString::startsWith(), endsWith()
11789 */
startsWith(QChar ch,Qt::CaseSensitivity cs) const11790 bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs) const
11791 {
11792     return qt_starts_with(*this, ch, cs);
11793 }
11794 
11795 /*!
11796     \since 4.8
11797     Returns \c true if the string reference ends with \a str; otherwise
11798     returns \c false.
11799 
11800     If \a cs is Qt::CaseSensitive (default), the search is case
11801     sensitive; otherwise the search is case insensitive.
11802 
11803     \sa QString::endsWith(), startsWith()
11804 */
endsWith(const QString & str,Qt::CaseSensitivity cs) const11805 bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs) const
11806 {
11807     return qt_ends_with(*this, str, cs);
11808 }
11809 
11810 /*!
11811     \since 4.8
11812     \overload endsWith()
11813 
11814     Returns \c true if the string reference ends with \a ch; otherwise
11815     returns \c false.
11816 
11817     If \a cs is Qt::CaseSensitive (default), the search is case
11818     sensitive; otherwise the search is case insensitive.
11819 
11820     \sa QString::endsWith(), endsWith()
11821 */
endsWith(QChar ch,Qt::CaseSensitivity cs) const11822 bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs) const
11823 {
11824     return qt_ends_with(*this, ch, cs);
11825 }
11826 
11827 /*!
11828     \since 4.8
11829     \overload endsWith()
11830     \sa QString::endsWith(), endsWith()
11831 */
endsWith(QLatin1String str,Qt::CaseSensitivity cs) const11832 bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs) const
11833 {
11834     return qt_ends_with(*this, str, cs);
11835 }
11836 
11837 /*!
11838     \fn bool QStringRef::endsWith(QStringView str, Qt::CaseSensitivity cs) const
11839     \since 5.10
11840     \overload endsWith()
11841     \sa QString::endsWith(), startsWith()
11842 */
11843 
11844 /*!
11845     \since 4.8
11846     \overload endsWith()
11847     \sa QString::endsWith(), endsWith()
11848 */
endsWith(const QStringRef & str,Qt::CaseSensitivity cs) const11849 bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs) const
11850 {
11851     return qt_ends_with(*this, str, cs);
11852 }
11853 
11854 #if QT_STRINGVIEW_LEVEL < 2
11855 /*! \fn bool QStringRef::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11856 
11857     \since 4.8
11858     Returns \c true if this string reference contains an occurrence of
11859     the string \a str; otherwise returns \c false.
11860 
11861     If \a cs is Qt::CaseSensitive (default), the search is
11862     case sensitive; otherwise the search is case insensitive.
11863 
11864     \sa indexOf(), count()
11865 */
11866 #endif // QT_STRINGVIEW_LEVEL < 2
11867 
11868 /*! \fn bool QStringRef::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11869 
11870     \overload contains()
11871     \since 4.8
11872 
11873     Returns \c true if this string contains an occurrence of the
11874     character \a ch; otherwise returns \c false.
11875 
11876     If \a cs is Qt::CaseSensitive (default), the search is
11877     case sensitive; otherwise the search is case insensitive.
11878 
11879 */
11880 
11881 #if QT_STRINGVIEW_LEVEL < 2
11882 /*! \fn bool QStringRef::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11883     \overload contains()
11884     \since 4.8
11885 
11886     Returns \c true if this string reference contains an occurrence of
11887     the string reference \a str; otherwise returns \c false.
11888 
11889     If \a cs is Qt::CaseSensitive (default), the search is
11890     case sensitive; otherwise the search is case insensitive.
11891 
11892     \sa indexOf(), count()
11893 */
11894 #endif // QT_STRINGVIEW_LEVEL < 2
11895 
11896 /*! \fn bool QStringRef::contains(QLatin1String str, Qt::CaseSensitivity cs) const
11897     \since 4.8
11898     \overload contains()
11899 
11900     Returns \c true if this string reference contains an occurrence of
11901     the string \a str; otherwise returns \c false.
11902 
11903     If \a cs is Qt::CaseSensitive (default), the search is
11904     case sensitive; otherwise the search is case insensitive.
11905 
11906     \sa indexOf(), count()
11907 */
11908 
11909 /*! \fn bool QStringRef::contains(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
11910     \since 5.14
11911     \overload contains()
11912 
11913     Returns \c true if this string reference contains an occurrence of
11914     the string view \a str; otherwise returns \c false.
11915 
11916     If \a cs is Qt::CaseSensitive (default), the search is
11917     case sensitive; otherwise the search is case insensitive.
11918 
11919     \sa indexOf(), count()
11920 */
11921 
qt_string_count(QStringView haystack,QStringView needle,Qt::CaseSensitivity cs)11922 static inline qsizetype qt_string_count(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs)
11923 {
11924     qsizetype num = 0;
11925     qsizetype i = -1;
11926     if (haystack.size() > 500 && needle.size() > 5) {
11927         QStringMatcher matcher(needle, cs);
11928         while ((i = matcher.indexIn(haystack, i + 1)) != -1)
11929             ++num;
11930     } else {
11931         while ((i = QtPrivate::findString(haystack, i + 1, needle, cs)) != -1)
11932             ++num;
11933     }
11934     return num;
11935 }
11936 
qt_string_count(QStringView haystack,QChar ch,Qt::CaseSensitivity cs)11937 static inline qsizetype qt_string_count(QStringView haystack, QChar ch,
11938                                   Qt::CaseSensitivity cs)
11939 {
11940     ushort c = ch.unicode();
11941     qsizetype num = 0;
11942     const ushort *b = reinterpret_cast<const ushort*>(haystack.data());
11943     const ushort *i = b + haystack.size();
11944     if (cs == Qt::CaseSensitive) {
11945         while (i != b)
11946             if (*--i == c)
11947                 ++num;
11948     } else {
11949         c = foldCase(c);
11950         while (i != b)
11951             if (foldCase(*(--i)) == c)
11952                 ++num;
11953     }
11954     return num;
11955 }
11956 
11957 template <typename Haystack, typename Needle>
qt_starts_with_impl(Haystack haystack,Needle needle,Qt::CaseSensitivity cs)11958 bool qt_starts_with_impl(Haystack haystack, Needle needle, Qt::CaseSensitivity cs) noexcept
11959 {
11960     if (haystack.isNull())
11961         return needle.isNull(); // historical behavior, consider changing in ### Qt 6.
11962     const auto haystackLen = haystack.size();
11963     const auto needleLen = needle.size();
11964     if (haystackLen == 0)
11965         return needleLen == 0;
11966     if (needleLen > haystackLen)
11967         return false;
11968 
11969     return qt_compare_strings(haystack.left(needleLen), needle, cs) == 0;
11970 }
11971 
qt_starts_with(QStringView haystack,QStringView needle,Qt::CaseSensitivity cs)11972 static inline bool qt_starts_with(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs)
11973 {
11974     return qt_starts_with_impl(haystack, needle, cs);
11975 }
11976 
qt_starts_with(QStringView haystack,QLatin1String needle,Qt::CaseSensitivity cs)11977 static inline bool qt_starts_with(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs)
11978 {
11979     return qt_starts_with_impl(haystack, needle, cs);
11980 }
11981 
qt_starts_with(QStringView haystack,QChar needle,Qt::CaseSensitivity cs)11982 static inline bool qt_starts_with(QStringView haystack, QChar needle, Qt::CaseSensitivity cs)
11983 {
11984     return haystack.size()
11985            && (cs == Qt::CaseSensitive ? haystack.front() == needle
11986                                        : foldCase(haystack.front()) == foldCase(needle));
11987 }
11988 
11989 /*!
11990     \fn bool QtPrivate::startsWith(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs)
11991     \since 5.10
11992     \fn bool QtPrivate::startsWith(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs)
11993     \since 5.10
11994     \fn bool QtPrivate::startsWith(QLatin1String haystack, QStringView needle, Qt::CaseSensitivity cs)
11995     \since 5.10
11996     \fn bool QtPrivate::startsWith(QLatin1String haystack, QLatin1String needle, Qt::CaseSensitivity cs)
11997     \since 5.10
11998     \internal
11999     \relates QStringView
12000 
12001     Returns \c true if \a haystack starts with \a needle,
12002     otherwise returns \c false.
12003 
12004     If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive;
12005     otherwise the search is case-insensitive.
12006 
12007     \sa QtPrivate::endsWith(), QString::endsWith(), QStringView::endsWith(), QLatin1String::endsWith()
12008 */
12009 
startsWith(QStringView haystack,QStringView needle,Qt::CaseSensitivity cs)12010 bool QtPrivate::startsWith(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs) noexcept
12011 {
12012     return qt_starts_with_impl(haystack, needle, cs);
12013 }
12014 
startsWith(QStringView haystack,QLatin1String needle,Qt::CaseSensitivity cs)12015 bool QtPrivate::startsWith(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12016 {
12017     return qt_starts_with_impl(haystack, needle, cs);
12018 }
12019 
startsWith(QLatin1String haystack,QStringView needle,Qt::CaseSensitivity cs)12020 bool QtPrivate::startsWith(QLatin1String haystack, QStringView needle, Qt::CaseSensitivity cs) noexcept
12021 {
12022     return qt_starts_with_impl(haystack, needle, cs);
12023 }
12024 
startsWith(QLatin1String haystack,QLatin1String needle,Qt::CaseSensitivity cs)12025 bool QtPrivate::startsWith(QLatin1String haystack, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12026 {
12027     return qt_starts_with_impl(haystack, needle, cs);
12028 }
12029 
12030 template <typename Haystack, typename Needle>
qt_ends_with_impl(Haystack haystack,Needle needle,Qt::CaseSensitivity cs)12031 bool qt_ends_with_impl(Haystack haystack, Needle needle, Qt::CaseSensitivity cs) noexcept
12032 {
12033     if (haystack.isNull())
12034         return needle.isNull(); // historical behavior, consider changing in ### Qt 6.
12035     const auto haystackLen = haystack.size();
12036     const auto needleLen = needle.size();
12037     if (haystackLen == 0)
12038         return needleLen == 0;
12039     if (haystackLen < needleLen)
12040         return false;
12041 
12042     return qt_compare_strings(haystack.right(needleLen), needle, cs) == 0;
12043 }
12044 
qt_ends_with(QStringView haystack,QStringView needle,Qt::CaseSensitivity cs)12045 static inline bool qt_ends_with(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs)
12046 {
12047     return qt_ends_with_impl(haystack, needle, cs);
12048 }
12049 
qt_ends_with(QStringView haystack,QLatin1String needle,Qt::CaseSensitivity cs)12050 static inline bool qt_ends_with(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs)
12051 {
12052     return qt_ends_with_impl(haystack, needle, cs);
12053 }
12054 
qt_ends_with(QStringView haystack,QChar needle,Qt::CaseSensitivity cs)12055 static inline bool qt_ends_with(QStringView haystack, QChar needle, Qt::CaseSensitivity cs)
12056 {
12057     return haystack.size()
12058            && (cs == Qt::CaseSensitive ? haystack.back() == needle
12059                                        : foldCase(haystack.back()) == foldCase(needle));
12060 }
12061 
12062 /*!
12063     \fn bool QtPrivate::endsWith(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs)
12064     \since 5.10
12065     \fn bool QtPrivate::endsWith(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs)
12066     \since 5.10
12067     \fn bool QtPrivate::endsWith(QLatin1String haystack, QStringView needle, Qt::CaseSensitivity cs)
12068     \since 5.10
12069     \fn bool QtPrivate::endsWith(QLatin1String haystack, QLatin1String needle, Qt::CaseSensitivity cs)
12070     \since 5.10
12071     \internal
12072     \relates QStringView
12073 
12074     Returns \c true if \a haystack ends with \a needle,
12075     otherwise returns \c false.
12076 
12077     If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive;
12078     otherwise the search is case-insensitive.
12079 
12080     \sa QtPrivate::startsWith(), QString::endsWith(), QStringView::endsWith(), QLatin1String::endsWith()
12081 */
12082 
endsWith(QStringView haystack,QStringView needle,Qt::CaseSensitivity cs)12083 bool QtPrivate::endsWith(QStringView haystack, QStringView needle, Qt::CaseSensitivity cs) noexcept
12084 {
12085     return qt_ends_with_impl(haystack, needle, cs);
12086 }
12087 
endsWith(QStringView haystack,QLatin1String needle,Qt::CaseSensitivity cs)12088 bool QtPrivate::endsWith(QStringView haystack, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12089 {
12090     return qt_ends_with_impl(haystack, needle, cs);
12091 }
12092 
endsWith(QLatin1String haystack,QStringView needle,Qt::CaseSensitivity cs)12093 bool QtPrivate::endsWith(QLatin1String haystack, QStringView needle, Qt::CaseSensitivity cs) noexcept
12094 {
12095     return qt_ends_with_impl(haystack, needle, cs);
12096 }
12097 
endsWith(QLatin1String haystack,QLatin1String needle,Qt::CaseSensitivity cs)12098 bool QtPrivate::endsWith(QLatin1String haystack, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12099 {
12100     return qt_ends_with_impl(haystack, needle, cs);
12101 }
12102 
12103 namespace {
12104 template <typename Pointer>
12105 uint foldCaseHelper(Pointer ch, Pointer start) = delete;
12106 
12107 template <>
foldCaseHelper(const QChar * ch,const QChar * start)12108 uint foldCaseHelper<const QChar*>(const QChar* ch, const QChar* start)
12109 {
12110     return foldCase(reinterpret_cast<const ushort*>(ch), reinterpret_cast<const ushort*>(start));
12111 }
12112 
12113 template <>
foldCaseHelper(const char * ch,const char *)12114 uint foldCaseHelper<const char*>(const char* ch, const char*)
12115 {
12116     return foldCase(ushort(uchar(*ch)));
12117 }
12118 
12119 template <typename T>
12120 ushort valueTypeToUtf16(T t) = delete;
12121 
12122 template <>
valueTypeToUtf16(QChar t)12123 ushort valueTypeToUtf16<QChar>(QChar t)
12124 {
12125     return t.unicode();
12126 }
12127 
12128 template <>
valueTypeToUtf16(char t)12129 ushort valueTypeToUtf16<char>(char t)
12130 {
12131     return ushort(uchar(t));
12132 }
12133 }
12134 
12135 /*!
12136     \internal
12137 
12138     Returns the index position of the first occurrence of the
12139     character \a ch in the string given by \a str and \a len,
12140     searching forward from index
12141     position \a from. Returns -1 if \a ch could not be found.
12142 */
12143 
qFindChar(QStringView str,QChar ch,qsizetype from,Qt::CaseSensitivity cs)12144 static inline qsizetype qFindChar(QStringView str, QChar ch, qsizetype from, Qt::CaseSensitivity cs) noexcept
12145 {
12146     if (from < 0)
12147         from = qMax(from + str.size(), qsizetype(0));
12148     if (from < str.size()) {
12149         const ushort *s = (const ushort *)str.data();
12150         ushort c = ch.unicode();
12151         const ushort *n = s + from;
12152         const ushort *e = s + str.size();
12153         if (cs == Qt::CaseSensitive) {
12154             n = QtPrivate::qustrchr(QStringView(n, e), c);
12155             if (n != e)
12156                 return n - s;
12157         } else {
12158             c = foldCase(c);
12159             --n;
12160             while (++n != e)
12161                 if (foldCase(*n) == c)
12162                     return n - s;
12163         }
12164     }
12165     return -1;
12166 }
12167 
findString(QStringView haystack0,qsizetype from,QStringView needle0,Qt::CaseSensitivity cs)12168 qsizetype QtPrivate::findString(QStringView haystack0, qsizetype from, QStringView needle0, Qt::CaseSensitivity cs) noexcept
12169 {
12170     const qsizetype l = haystack0.size();
12171     const qsizetype sl = needle0.size();
12172     if (from < 0)
12173         from += l;
12174     if (std::size_t(sl + from) > std::size_t(l))
12175         return -1;
12176     if (!sl)
12177         return from;
12178     if (!l)
12179         return -1;
12180 
12181     if (sl == 1)
12182         return qFindChar(haystack0, needle0[0], from, cs);
12183 
12184     /*
12185         We use the Boyer-Moore algorithm in cases where the overhead
12186         for the skip table should pay off, otherwise we use a simple
12187         hash function.
12188     */
12189     if (l > 500 && sl > 5)
12190         return qFindStringBoyerMoore(haystack0, from, needle0, cs);
12191 
12192     auto sv = [sl](const ushort *v) { return QStringView(v, sl); };
12193     /*
12194         We use some hashing for efficiency's sake. Instead of
12195         comparing strings, we compare the hash value of str with that
12196         of a part of this QString. Only if that matches, we call
12197         qt_string_compare().
12198     */
12199     const ushort *needle = (const ushort *)needle0.data();
12200     const ushort *haystack = (const ushort *)(haystack0.data()) + from;
12201     const ushort *end = (const ushort *)(haystack0.data()) + (l - sl);
12202     const std::size_t sl_minus_1 = sl - 1;
12203     std::size_t hashNeedle = 0, hashHaystack = 0;
12204     qsizetype idx;
12205 
12206     if (cs == Qt::CaseSensitive) {
12207         for (idx = 0; idx < sl; ++idx) {
12208             hashNeedle = ((hashNeedle<<1) + needle[idx]);
12209             hashHaystack = ((hashHaystack<<1) + haystack[idx]);
12210         }
12211         hashHaystack -= haystack[sl_minus_1];
12212 
12213         while (haystack <= end) {
12214             hashHaystack += haystack[sl_minus_1];
12215             if (hashHaystack == hashNeedle
12216                  && qt_compare_strings(needle0, sv(haystack), Qt::CaseSensitive) == 0)
12217                 return haystack - (const ushort *)haystack0.data();
12218 
12219             REHASH(*haystack);
12220             ++haystack;
12221         }
12222     } else {
12223         const ushort *haystack_start = (const ushort *)haystack0.data();
12224         for (idx = 0; idx < sl; ++idx) {
12225             hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle);
12226             hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start);
12227         }
12228         hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start);
12229 
12230         while (haystack <= end) {
12231             hashHaystack += foldCase(haystack + sl_minus_1, haystack_start);
12232             if (hashHaystack == hashNeedle
12233                  && qt_compare_strings(needle0, sv(haystack), Qt::CaseInsensitive) == 0)
12234                 return haystack - (const ushort *)haystack0.data();
12235 
12236             REHASH(foldCase(haystack, haystack_start));
12237             ++haystack;
12238         }
12239     }
12240     return -1;
12241 }
12242 
12243 template <typename Haystack>
qLastIndexOf(Haystack haystack,QChar needle,qsizetype from,Qt::CaseSensitivity cs)12244 static inline qsizetype qLastIndexOf(Haystack haystack, QChar needle,
12245                                      qsizetype from, Qt::CaseSensitivity cs) noexcept
12246 {
12247     if (from < 0)
12248         from += haystack.size();
12249     if (std::size_t(from) >= std::size_t(haystack.size()))
12250         return -1;
12251     if (from >= 0) {
12252         ushort c = needle.unicode();
12253         const auto b = haystack.data();
12254         auto n = b + from;
12255         if (cs == Qt::CaseSensitive) {
12256             for (; n >= b; --n)
12257                 if (valueTypeToUtf16(*n) == c)
12258                     return n - b;
12259         } else {
12260             c = foldCase(c);
12261             for (; n >= b; --n)
12262                 if (foldCase(valueTypeToUtf16(*n)) == c)
12263                     return n - b;
12264         }
12265     }
12266     return -1;
12267 }
12268 
12269 template<typename Haystack, typename Needle>
qLastIndexOf(Haystack haystack0,qsizetype from,Needle needle0,Qt::CaseSensitivity cs)12270 static qsizetype qLastIndexOf(Haystack haystack0, qsizetype from,
12271                               Needle needle0, Qt::CaseSensitivity cs) noexcept
12272 {
12273     const qsizetype sl = needle0.size();
12274     if (sl == 1)
12275         return qLastIndexOf(haystack0, needle0.front(), from, cs);
12276 
12277     const qsizetype l = haystack0.size();
12278     if (from < 0)
12279         from += l;
12280     if (from == l && sl == 0)
12281         return from;
12282     const qsizetype delta = l - sl;
12283     if (std::size_t(from) >= std::size_t(l) || delta < 0)
12284         return -1;
12285     if (from > delta)
12286         from = delta;
12287 
12288     auto sv = [sl](const typename Haystack::value_type *v) { return Haystack(v, sl); };
12289 
12290     auto haystack = haystack0.data();
12291     const auto needle = needle0.data();
12292     const auto *end = haystack;
12293     haystack += from;
12294     const std::size_t sl_minus_1 = sl - 1;
12295     const auto *n = needle + sl_minus_1;
12296     const auto *h = haystack + sl_minus_1;
12297     std::size_t hashNeedle = 0, hashHaystack = 0;
12298     qsizetype idx;
12299 
12300     if (cs == Qt::CaseSensitive) {
12301         for (idx = 0; idx < sl; ++idx) {
12302             hashNeedle = (hashNeedle << 1) + valueTypeToUtf16(*(n - idx));
12303             hashHaystack = (hashHaystack << 1) + valueTypeToUtf16(*(h - idx));
12304         }
12305         hashHaystack -= valueTypeToUtf16(*haystack);
12306 
12307         while (haystack >= end) {
12308             hashHaystack += valueTypeToUtf16(*haystack);
12309             if (hashHaystack == hashNeedle
12310                  && qt_compare_strings(needle0, sv(haystack), Qt::CaseSensitive) == 0)
12311                 return haystack - end;
12312             --haystack;
12313             REHASH(valueTypeToUtf16(haystack[sl]));
12314         }
12315     } else {
12316         for (idx = 0; idx < sl; ++idx) {
12317             hashNeedle = (hashNeedle << 1) + foldCaseHelper(n - idx, needle);
12318             hashHaystack = (hashHaystack << 1) + foldCaseHelper(h - idx, end);
12319         }
12320         hashHaystack -= foldCaseHelper(haystack, end);
12321 
12322         while (haystack >= end) {
12323             hashHaystack += foldCaseHelper(haystack, end);
12324             if (hashHaystack == hashNeedle
12325                  && qt_compare_strings(sv(haystack), needle0, Qt::CaseInsensitive) == 0)
12326                 return haystack - end;
12327             --haystack;
12328             REHASH(foldCaseHelper(haystack + sl, end));
12329         }
12330     }
12331     return -1;
12332 }
12333 
findString(QStringView haystack,qsizetype from,QLatin1String needle,Qt::CaseSensitivity cs)12334 qsizetype QtPrivate::findString(QStringView haystack, qsizetype from, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12335 {
12336     if (haystack.size() < needle.size())
12337         return -1;
12338 
12339     QVarLengthArray<ushort> s(needle.size());
12340     qt_from_latin1(s.data(), needle.latin1(), needle.size());
12341     return QtPrivate::findString(haystack, from, QStringView(reinterpret_cast<const QChar*>(s.constData()), s.size()), cs);
12342 }
12343 
findString(QLatin1String haystack,qsizetype from,QStringView needle,Qt::CaseSensitivity cs)12344 qsizetype QtPrivate::findString(QLatin1String haystack, qsizetype from, QStringView needle, Qt::CaseSensitivity cs) noexcept
12345 {
12346     if (haystack.size() < needle.size())
12347         return -1;
12348 
12349     QVarLengthArray<ushort> s(haystack.size());
12350     qt_from_latin1(s.data(), haystack.latin1(), haystack.size());
12351     return QtPrivate::findString(QStringView(reinterpret_cast<const QChar*>(s.constData()), s.size()), from, needle, cs);
12352 }
12353 
findString(QLatin1String haystack,qsizetype from,QLatin1String needle,Qt::CaseSensitivity cs)12354 qsizetype QtPrivate::findString(QLatin1String haystack, qsizetype from, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12355 {
12356     if (haystack.size() < needle.size())
12357         return -1;
12358 
12359     QVarLengthArray<ushort> h(haystack.size());
12360     qt_from_latin1(h.data(), haystack.latin1(), haystack.size());
12361     QVarLengthArray<ushort> n(needle.size());
12362     qt_from_latin1(n.data(), needle.latin1(), needle.size());
12363     return QtPrivate::findString(QStringView(reinterpret_cast<const QChar*>(h.constData()), h.size()), from,
12364                                  QStringView(reinterpret_cast<const QChar*>(n.constData()), n.size()), cs);
12365 }
12366 
lastIndexOf(QStringView haystack,qsizetype from,QStringView needle,Qt::CaseSensitivity cs)12367 qsizetype QtPrivate::lastIndexOf(QStringView haystack, qsizetype from, QStringView needle, Qt::CaseSensitivity cs) noexcept
12368 {
12369     return qLastIndexOf(haystack, from, needle, cs);
12370 }
12371 
lastIndexOf(QStringView haystack,qsizetype from,QLatin1String needle,Qt::CaseSensitivity cs)12372 qsizetype QtPrivate::lastIndexOf(QStringView haystack, qsizetype from, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12373 {
12374     return qLastIndexOf(haystack, from, needle, cs);
12375 }
12376 
lastIndexOf(QLatin1String haystack,qsizetype from,QStringView needle,Qt::CaseSensitivity cs)12377 qsizetype QtPrivate::lastIndexOf(QLatin1String haystack, qsizetype from, QStringView needle, Qt::CaseSensitivity cs) noexcept
12378 {
12379     return qLastIndexOf(haystack, from, needle, cs);
12380 }
12381 
lastIndexOf(QLatin1String haystack,qsizetype from,QLatin1String needle,Qt::CaseSensitivity cs)12382 qsizetype QtPrivate::lastIndexOf(QLatin1String haystack, qsizetype from, QLatin1String needle, Qt::CaseSensitivity cs) noexcept
12383 {
12384     return qLastIndexOf(haystack, from, needle, cs);
12385 }
12386 
12387 /*!
12388     \since 4.8
12389 
12390     Returns a Latin-1 representation of the string as a QByteArray.
12391 
12392     The returned byte array is undefined if the string contains non-Latin1
12393     characters. Those characters may be suppressed or replaced with a
12394     question mark.
12395 
12396     \sa toUtf8(), toLocal8Bit(), QTextCodec
12397 */
toLatin1() const12398 QByteArray QStringRef::toLatin1() const
12399 {
12400     return qt_convert_to_latin1(*this);
12401 }
12402 
12403 /*!
12404     \fn QByteArray QStringRef::toAscii() const
12405     \since 4.8
12406     \deprecated
12407 
12408     Returns an 8-bit representation of the string as a QByteArray.
12409 
12410     This function does the same as toLatin1().
12411 
12412     Note that, despite the name, this function does not necessarily return an US-ASCII
12413     (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.
12414 
12415     \sa toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec
12416 */
12417 
12418 /*!
12419     \since 4.8
12420 
12421     Returns the local 8-bit representation of the string as a
12422     QByteArray. The returned byte array is undefined if the string
12423     contains characters not supported by the local 8-bit encoding.
12424 
12425     QTextCodec::codecForLocale() is used to perform the conversion from
12426     Unicode. If the locale encoding could not be determined, this function
12427     does the same as toLatin1().
12428 
12429     If this string contains any characters that cannot be encoded in the
12430     locale, the returned byte array is undefined. Those characters may be
12431     suppressed or replaced by another.
12432 
12433     \sa toLatin1(), toUtf8(), QTextCodec
12434 */
toLocal8Bit() const12435 QByteArray QStringRef::toLocal8Bit() const
12436 {
12437     return qt_convert_to_local_8bit(*this);
12438 }
12439 
12440 /*!
12441     \since 4.8
12442 
12443     Returns a UTF-8 representation of the string as a QByteArray.
12444 
12445     UTF-8 is a Unicode codec and can represent all characters in a Unicode
12446     string like QString.
12447 
12448     \sa toLatin1(), toLocal8Bit(), QTextCodec
12449 */
toUtf8() const12450 QByteArray QStringRef::toUtf8() const
12451 {
12452     return qt_convert_to_utf8(*this);
12453 }
12454 
12455 /*!
12456     \since 4.8
12457 
12458     Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>.
12459 
12460     UCS-4 is a Unicode codec and therefore it is lossless. All characters from
12461     this string will be encoded in UCS-4. Any invalid sequence of code units in
12462     this string is replaced by the Unicode's replacement character
12463     (QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}).
12464 
12465     The returned vector is not \\0'-terminated.
12466 
12467     \sa toUtf8(), toLatin1(), toLocal8Bit(), QTextCodec
12468 */
toUcs4() const12469 QVector<uint> QStringRef::toUcs4() const
12470 {
12471     return qt_convert_to_ucs4(*this);
12472 }
12473 
12474 /*!
12475     Returns a string that has whitespace removed from the start and
12476     the end.
12477 
12478     Whitespace means any character for which QChar::isSpace() returns
12479     \c true. This includes the ASCII characters '\\t', '\\n', '\\v',
12480     '\\f', '\\r', and ' '.
12481 
12482     Unlike QString::simplified(), trimmed() leaves internal whitespace alone.
12483 
12484     \since 5.1
12485 
12486     \sa QString::trimmed()
12487 */
trimmed() const12488 QStringRef QStringRef::trimmed() const
12489 {
12490     const QChar *begin = cbegin();
12491     const QChar *end = cend();
12492     QStringAlgorithms<const QStringRef>::trimmed_helper_positions(begin, end);
12493     if (begin == cbegin() && end == cend())
12494         return *this;
12495     int position = m_position + (begin - cbegin());
12496     return QStringRef(m_string, position, end - begin);
12497 }
12498 
12499 /*!
12500     Returns the string converted to a \c{long long} using base \a
12501     base, which is 10 by default and must be between 2 and 36, or 0.
12502     Returns 0 if the conversion fails.
12503 
12504     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12505     to \c false, and success by setting *\a{ok} to \c true.
12506 
12507     If \a base is 0, the C language convention is used: If the string
12508     begins with "0x", base 16 is used; if the string begins with "0",
12509     base 8 is used; otherwise, base 10 is used.
12510 
12511     The string conversion will always happen in the 'C' locale. For locale
12512     dependent conversion use QLocale::toLongLong()
12513 
12514     \sa QString::toLongLong()
12515 
12516     \since 5.1
12517 */
12518 
toLongLong(bool * ok,int base) const12519 qint64 QStringRef::toLongLong(bool *ok, int base) const
12520 {
12521     return QString::toIntegral_helper<qint64>(constData(), size(), ok, base);
12522 }
12523 
12524 /*!
12525     Returns the string converted to an \c{unsigned long long} using base \a
12526     base, which is 10 by default and must be between 2 and 36, or 0.
12527     Returns 0 if the conversion fails.
12528 
12529     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12530     to \c false, and success by setting *\a{ok} to \c true.
12531 
12532     If \a base is 0, the C language convention is used: If the string
12533     begins with "0x", base 16 is used; if the string begins with "0",
12534     base 8 is used; otherwise, base 10 is used.
12535 
12536     The string conversion will always happen in the 'C' locale. For locale
12537     dependent conversion use QLocale::toULongLong()
12538 
12539     \sa QString::toULongLong()
12540 
12541     \since 5.1
12542 */
12543 
toULongLong(bool * ok,int base) const12544 quint64 QStringRef::toULongLong(bool *ok, int base) const
12545 {
12546     return QString::toIntegral_helper<quint64>(constData(), size(), ok, base);
12547 }
12548 
12549 /*!
12550     \fn long QStringRef::toLong(bool *ok, int base) const
12551 
12552     Returns the string converted to a \c long using base \a
12553     base, which is 10 by default and must be between 2 and 36, or 0.
12554     Returns 0 if the conversion fails.
12555 
12556     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12557     to \c false, and success by setting *\a{ok} to \c true.
12558 
12559     If \a base is 0, the C language convention is used: If the string
12560     begins with "0x", base 16 is used; if the string begins with "0",
12561     base 8 is used; otherwise, base 10 is used.
12562 
12563     The string conversion will always happen in the 'C' locale. For locale
12564     dependent conversion use QLocale::toLong()
12565 
12566     \sa QString::toLong()
12567 
12568     \since 5.1
12569 */
12570 
toLong(bool * ok,int base) const12571 long QStringRef::toLong(bool *ok, int base) const
12572 {
12573     return QString::toIntegral_helper<long>(constData(), size(), ok, base);
12574 }
12575 
12576 /*!
12577     \fn ulong QStringRef::toULong(bool *ok, int base) const
12578 
12579     Returns the string converted to an \c{unsigned long} using base \a
12580     base, which is 10 by default and must be between 2 and 36, or 0.
12581     Returns 0 if the conversion fails.
12582 
12583     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12584     to \c false, and success by setting *\a{ok} to \c true.
12585 
12586     If \a base is 0, the C language convention is used: If the string
12587     begins with "0x", base 16 is used; if the string begins with "0",
12588     base 8 is used; otherwise, base 10 is used.
12589 
12590     The string conversion will always happen in the 'C' locale. For locale
12591     dependent conversion use QLocale::toULongLong()
12592 
12593     \sa QString::toULong()
12594 
12595     \since 5.1
12596 */
12597 
toULong(bool * ok,int base) const12598 ulong QStringRef::toULong(bool *ok, int base) const
12599 {
12600     return QString::toIntegral_helper<ulong>(constData(), size(), ok, base);
12601 }
12602 
12603 
12604 /*!
12605     Returns the string converted to an \c int using base \a
12606     base, which is 10 by default and must be between 2 and 36, or 0.
12607     Returns 0 if the conversion fails.
12608 
12609     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12610     to \c false, and success by setting *\a{ok} to \c true.
12611 
12612     If \a base is 0, the C language convention is used: If the string
12613     begins with "0x", base 16 is used; if the string begins with "0",
12614     base 8 is used; otherwise, base 10 is used.
12615 
12616     The string conversion will always happen in the 'C' locale. For locale
12617     dependent conversion use QLocale::toInt()
12618 
12619     \sa QString::toInt()
12620 
12621     \since 5.1
12622 */
12623 
toInt(bool * ok,int base) const12624 int QStringRef::toInt(bool *ok, int base) const
12625 {
12626     return QString::toIntegral_helper<int>(constData(), size(), ok, base);
12627 }
12628 
12629 /*!
12630     Returns the string converted to an \c{unsigned int} using base \a
12631     base, which is 10 by default and must be between 2 and 36, or 0.
12632     Returns 0 if the conversion fails.
12633 
12634     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12635     to \c false, and success by setting *\a{ok} to \c true.
12636 
12637     If \a base is 0, the C language convention is used: If the string
12638     begins with "0x", base 16 is used; if the string begins with "0",
12639     base 8 is used; otherwise, base 10 is used.
12640 
12641     The string conversion will always happen in the 'C' locale. For locale
12642     dependent conversion use QLocale::toUInt()
12643 
12644     \sa QString::toUInt()
12645 
12646     \since 5.1
12647 */
12648 
toUInt(bool * ok,int base) const12649 uint QStringRef::toUInt(bool *ok, int base) const
12650 {
12651     return QString::toIntegral_helper<uint>(constData(), size(), ok, base);
12652 }
12653 
12654 /*!
12655     Returns the string converted to a \c short using base \a
12656     base, which is 10 by default and must be between 2 and 36, or 0.
12657     Returns 0 if the conversion fails.
12658 
12659     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12660     to \c false, and success by setting *\a{ok} to \c true.
12661 
12662     If \a base is 0, the C language convention is used: If the string
12663     begins with "0x", base 16 is used; if the string begins with "0",
12664     base 8 is used; otherwise, base 10 is used.
12665 
12666     The string conversion will always happen in the 'C' locale. For locale
12667     dependent conversion use QLocale::toShort()
12668 
12669     \sa QString::toShort()
12670 
12671     \since 5.1
12672 */
12673 
toShort(bool * ok,int base) const12674 short QStringRef::toShort(bool *ok, int base) const
12675 {
12676     return QString::toIntegral_helper<short>(constData(), size(), ok, base);
12677 }
12678 
12679 /*!
12680     Returns the string converted to an \c{unsigned short} using base \a
12681     base, which is 10 by default and must be between 2 and 36, or 0.
12682     Returns 0 if the conversion fails.
12683 
12684     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12685     to \c false, and success by setting *\a{ok} to \c true.
12686 
12687     If \a base is 0, the C language convention is used: If the string
12688     begins with "0x", base 16 is used; if the string begins with "0",
12689     base 8 is used; otherwise, base 10 is used.
12690 
12691     The string conversion will always happen in the 'C' locale. For locale
12692     dependent conversion use QLocale::toUShort()
12693 
12694     \sa QString::toUShort()
12695 
12696     \since 5.1
12697 */
12698 
toUShort(bool * ok,int base) const12699 ushort QStringRef::toUShort(bool *ok, int base) const
12700 {
12701     return QString::toIntegral_helper<ushort>(constData(), size(), ok, base);
12702 }
12703 
12704 
12705 /*!
12706     Returns the string converted to a \c double value.
12707 
12708     Returns an infinity if the conversion overflows or 0.0 if the
12709     conversion fails for other reasons (e.g. underflow).
12710 
12711     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12712     to \c false, and success by setting *\a{ok} to \c true.
12713 
12714     The string conversion will always happen in the 'C' locale. For locale
12715     dependent conversion use QLocale::toDouble()
12716 
12717     For historic reasons, this function does not handle
12718     thousands group separators. If you need to convert such numbers,
12719     use QLocale::toDouble().
12720 
12721     \sa QString::toDouble()
12722 
12723     \since 5.1
12724 */
12725 
toDouble(bool * ok) const12726 double QStringRef::toDouble(bool *ok) const
12727 {
12728     return QLocaleData::c()->stringToDouble(*this, ok, QLocale::RejectGroupSeparator);
12729 }
12730 
12731 /*!
12732     Returns the string converted to a \c float value.
12733 
12734     Returns an infinity if the conversion overflows or 0.0 if the
12735     conversion fails for other reasons (e.g. underflow).
12736 
12737     If \a ok is not \nullptr, failure is reported by setting *\a{ok}
12738     to \c false, and success by setting *\a{ok} to \c true.
12739 
12740     The string conversion will always happen in the 'C' locale. For locale
12741     dependent conversion use QLocale::toFloat()
12742 
12743     \sa QString::toFloat()
12744 
12745     \since 5.1
12746 */
12747 
toFloat(bool * ok) const12748 float QStringRef::toFloat(bool *ok) const
12749 {
12750     return QLocaleData::convertDoubleToFloat(toDouble(ok), ok);
12751 }
12752 
12753 /*!
12754     \obsolete
12755     \fn QString Qt::escape(const QString &plain)
12756 
12757     Use QString::toHtmlEscaped() instead.
12758 */
12759 
12760 /*!
12761     \since 5.0
12762 
12763     Converts a plain text string to an HTML string with
12764     HTML metacharacters \c{<}, \c{>}, \c{&}, and \c{"} replaced by HTML
12765     entities.
12766 
12767     Example:
12768 
12769     \snippet code/src_corelib_tools_qstring.cpp 7
12770 */
toHtmlEscaped() const12771 QString QString::toHtmlEscaped() const
12772 {
12773     QString rich;
12774     const int len = length();
12775     rich.reserve(int(len * 1.1));
12776     for (int i = 0; i < len; ++i) {
12777         if (at(i) == QLatin1Char('<'))
12778             rich += QLatin1String("&lt;");
12779         else if (at(i) == QLatin1Char('>'))
12780             rich += QLatin1String("&gt;");
12781         else if (at(i) == QLatin1Char('&'))
12782             rich += QLatin1String("&amp;");
12783         else if (at(i) == QLatin1Char('"'))
12784             rich += QLatin1String("&quot;");
12785         else
12786             rich += at(i);
12787     }
12788     rich.squeeze();
12789     return rich;
12790 }
12791 
12792 /*!
12793   \macro QStringLiteral(str)
12794   \relates QString
12795 
12796   The macro generates the data for a QString out of the string literal \a str
12797   at compile time. Creating a QString from it is free in this case, and the
12798   generated string data is stored in the read-only segment of the compiled
12799   object file.
12800 
12801   If you have code that looks like this:
12802 
12803   \snippet code/src_corelib_tools_qstring.cpp 9
12804 
12805   then a temporary QString will be created to be passed as the \c{hasAttribute}
12806   function parameter. This can be quite expensive, as it involves a memory
12807   allocation and the copy/conversion of the data into QString's internal
12808   encoding.
12809 
12810   This cost can be avoided by using QStringLiteral instead:
12811 
12812   \snippet code/src_corelib_tools_qstring.cpp 10
12813 
12814   In this case, QString's internal data will be generated at compile time; no
12815   conversion or allocation will occur at runtime.
12816 
12817   Using QStringLiteral instead of a double quoted plain C++ string literal can
12818   significantly speed up creation of QString instances from data known at
12819   compile time.
12820 
12821   \note QLatin1String can still be more efficient than QStringLiteral
12822   when the string is passed to a function that has an overload taking
12823   QLatin1String and this overload avoids conversion to QString.  For
12824   instance, QString::operator==() can compare to a QLatin1String
12825   directly:
12826 
12827   \snippet code/src_corelib_tools_qstring.cpp 11
12828 
12829   \note Some compilers have bugs encoding strings containing characters outside
12830   the US-ASCII character set. Make sure you prefix your string with \c{u} in
12831   those cases. It is optional otherwise.
12832 
12833   \sa QByteArrayLiteral
12834 */
12835 
12836 /*!
12837     \internal
12838  */
appendLatin1To(const char * a,int len,QChar * out)12839 void QAbstractConcatenable::appendLatin1To(const char *a, int len, QChar *out) noexcept
12840 {
12841     qt_from_latin1(reinterpret_cast<ushort *>(out), a, uint(len));
12842 }
12843 
12844 QT_END_NAMESPACE
12845