1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). |
4 | ** Contact: http://www.qt-project.org/legal |
5 | ** |
6 | ** This file is part of the QtCore module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL$ |
9 | ** Commercial License Usage |
10 | ** Licensees holding valid commercial Qt licenses may use this file in |
11 | ** accordance with the commercial license agreement provided with the |
12 | ** Software or, alternatively, in accordance with the terms contained in |
13 | ** a written agreement between you and Digia. For licensing terms and |
14 | ** conditions see http://qt.digia.com/licensing. For further information |
15 | ** use the contact form at http://qt.digia.com/contact-us. |
16 | ** |
17 | ** GNU Lesser General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU Lesser |
19 | ** General Public License version 2.1 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 2.1 requirements |
23 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
24 | ** |
25 | ** In addition, as a special exception, Digia gives you certain additional |
26 | ** rights. These rights are described in the Digia Qt LGPL Exception |
27 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
28 | ** |
29 | ** GNU General Public License Usage |
30 | ** Alternatively, this file may be used under the terms of the GNU |
31 | ** General Public License version 3.0 as published by the Free Software |
32 | ** Foundation and appearing in the file LICENSE.GPL included in the |
33 | ** packaging of this file. Please review the following information to |
34 | ** ensure the GNU General Public License version 3.0 requirements will be |
35 | ** met: http://www.gnu.org/copyleft/gpl.html. |
36 | ** |
37 | ** |
38 | ** $QT_END_LICENSE$ |
39 | ** |
40 | ****************************************************************************/ |
41 | |
42 | #include "qstringlist.h" |
43 | #include "qregexp.h" |
44 | #include "qunicodetables_p.h" |
45 | #ifndef QT_NO_TEXTCODEC |
46 | #include <qtextcodec.h> |
47 | #endif |
48 | #include <private/qutfcodec_p.h> |
49 | #include "qsimd_p.h" |
50 | #include <qdatastream.h> |
51 | #include <qlist.h> |
52 | #include "qlocale.h" |
53 | #include "qlocale_p.h" |
54 | #include "qstringmatcher.h" |
55 | #include "qvarlengtharray.h" |
56 | #include "qtools_p.h" |
57 | #include "qhash.h" |
58 | #include "qdebug.h" |
59 | #include "qendian.h" |
60 | #include "qmutex.h" |
61 | |
62 | #ifdef Q_OS_MAC |
63 | #include <private/qcore_mac_p.h> |
64 | #endif |
65 | |
66 | #include <private/qfunctions_p.h> |
67 | |
68 | #if defined(Q_OS_WINCE) |
69 | #include <windows.h> |
70 | #include <winnls.h> |
71 | #endif |
72 | |
73 | #ifdef Q_OS_SYMBIAN |
74 | #include <e32cmn.h> |
75 | #endif |
76 | |
77 | #include <limits.h> |
78 | #include <string.h> |
79 | #include <stdlib.h> |
80 | #include <stdio.h> |
81 | #include <stdarg.h> |
82 | |
83 | #ifdef truncate |
84 | #undef truncate |
85 | #endif |
86 | |
87 | #include "qchar.cpp" |
88 | #include "qstringmatcher.cpp" |
89 | |
90 | #ifndef LLONG_MAX |
91 | #define LLONG_MAX qint64_C(9223372036854775807) |
92 | #endif |
93 | #ifndef LLONG_MIN |
94 | #define LLONG_MIN (-LLONG_MAX - qint64_C(1)) |
95 | #endif |
96 | #ifndef ULLONG_MAX |
97 | #define ULLONG_MAX quint64_C(18446744073709551615) |
98 | #endif |
99 | |
100 | QT_BEGIN_NAMESPACE |
101 | |
102 | #ifndef QT_NO_TEXTCODEC |
103 | QTextCodec *QString::codecForCStrings; |
104 | #endif |
105 | |
106 | #ifdef QT3_SUPPORT |
107 | static QHash<void *, QByteArray> *asciiCache = 0; |
108 | Q_GLOBAL_STATIC(QMutex, asciiCacheMutex) |
109 | |
110 | #endif |
111 | |
112 | #ifdef QT_USE_ICU |
113 | // qlocale_icu.cpp |
114 | extern bool qt_ucol_strcoll(const QChar *source, int sourceLength, const QChar *target, int targetLength, int *result); |
115 | #endif |
116 | |
117 | // internal |
118 | int qFindString(const QChar *haystack, int haystackLen, int from, |
119 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs); |
120 | int qFindStringBoyerMoore(const QChar *haystack, int haystackLen, int from, |
121 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs); |
122 | static inline int qt_last_index_of(const QChar *haystack, int haystackLen, const QChar &needle, |
123 | int from, Qt::CaseSensitivity cs); |
124 | static inline int qt_string_count(const QChar *haystack, int haystackLen, |
125 | const QChar *needle, int needleLen, |
126 | Qt::CaseSensitivity cs); |
127 | static inline int qt_string_count(const QChar *haystack, int haystackLen, |
128 | const QChar &needle, Qt::CaseSensitivity cs); |
129 | static inline int qt_find_latin1_string(const QChar *hay, int size, const QLatin1String &needle, |
130 | int from, Qt::CaseSensitivity cs); |
131 | static inline bool qt_starts_with(const QChar *haystack, int haystackLen, |
132 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs); |
133 | static inline bool qt_starts_with(const QChar *haystack, int haystackLen, |
134 | const QLatin1String &needle, Qt::CaseSensitivity cs); |
135 | static inline bool qt_ends_with(const QChar *haystack, int haystackLen, |
136 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs); |
137 | static inline bool qt_ends_with(const QChar *haystack, int haystackLen, |
138 | const QLatin1String &needle, Qt::CaseSensitivity cs); |
139 | |
140 | // Unicode case-insensitive comparison |
141 | static int ucstricmp(const ushort *a, const ushort *ae, const ushort *b, const ushort *be) |
142 | { |
143 | if (a == b) |
144 | return (ae - be); |
145 | if (a == 0) |
146 | return 1; |
147 | if (b == 0) |
148 | return -1; |
149 | |
150 | const ushort *e = ae; |
151 | if (be - b < ae - a) |
152 | e = a + (be - b); |
153 | |
154 | uint alast = 0; |
155 | uint blast = 0; |
156 | while (a < e) { |
157 | // qDebug() << hex << alast << blast; |
158 | // qDebug() << hex << "*a=" << *a << "alast=" << alast << "folded=" << foldCase (*a, alast); |
159 | // qDebug() << hex << "*b=" << *b << "blast=" << blast << "folded=" << foldCase (*b, blast); |
160 | int diff = foldCase(*a, alast) - foldCase(*b, blast); |
161 | if ((diff)) |
162 | return diff; |
163 | ++a; |
164 | ++b; |
165 | } |
166 | if (a == ae) { |
167 | if (b == be) |
168 | return 0; |
169 | return -1; |
170 | } |
171 | return 1; |
172 | } |
173 | |
174 | // Case-insensitive comparison between a Unicode string and a QLatin1String |
175 | static int ucstricmp(const ushort *a, const ushort *ae, const uchar *b) |
176 | { |
177 | if (a == 0) { |
178 | if (b == 0) |
179 | return 0; |
180 | return 1; |
181 | } |
182 | if (b == 0) |
183 | return -1; |
184 | |
185 | while (a < ae && *b) { |
186 | int diff = foldCase(*a) - foldCase(*b); |
187 | if ((diff)) |
188 | return diff; |
189 | ++a; |
190 | ++b; |
191 | } |
192 | if (a == ae) { |
193 | if (!*b) |
194 | return 0; |
195 | return -1; |
196 | } |
197 | return 1; |
198 | } |
199 | |
200 | // Unicode case-sensitive compare two same-sized strings |
201 | static int ucstrncmp(const QChar *a, const QChar *b, int l) |
202 | { |
203 | while (l-- && *a == *b) |
204 | a++,b++; |
205 | if (l==-1) |
206 | return 0; |
207 | return a->unicode() - b->unicode(); |
208 | } |
209 | |
210 | // Unicode case-sensitive comparison |
211 | static int ucstrcmp(const QChar *a, int alen, const QChar *b, int blen) |
212 | { |
213 | if (a == b && alen == blen) |
214 | return 0; |
215 | int l = qMin(alen, blen); |
216 | int cmp = ucstrncmp(a, b, l); |
217 | return cmp ? cmp : (alen-blen); |
218 | } |
219 | |
220 | // Unicode case-insensitive compare two same-sized strings |
221 | static int ucstrnicmp(const ushort *a, const ushort *b, int l) |
222 | { |
223 | return ucstricmp(a, a + l, b, b + l); |
224 | } |
225 | |
226 | // Benchmarking indicates that doing memcmp is much slower than |
227 | // executing the comparison ourselves. |
228 | // |
229 | // The profiling was done on a population of calls to qMemEquals, generated |
230 | // during a run of the demo browser. The profile of the data (32-bit x86 |
231 | // Linux) was: |
232 | // |
233 | // total number of comparisons: 21353 |
234 | // longest string compared: 95 |
235 | // average comparison length: 14.8786 |
236 | // cache-line crosses: 5661 (13.3%) |
237 | // alignment histogram: |
238 | // 0xXXX0 = 512 (1.2%) strings, 0 (0.0%) of which same-aligned |
239 | // 0xXXX2 = 15087 (35.3%) strings, 5145 (34.1%) of which same-aligned |
240 | // 0xXXX4 = 525 (1.2%) strings, 0 (0.0%) of which same-aligned |
241 | // 0xXXX6 = 557 (1.3%) strings, 6 (1.1%) of which same-aligned |
242 | // 0xXXX8 = 509 (1.2%) strings, 0 (0.0%) of which same-aligned |
243 | // 0xXXXa = 24358 (57.0%) strings, 9901 (40.6%) of which same-aligned |
244 | // 0xXXXc = 557 (1.3%) strings, 0 (0.0%) of which same-aligned |
245 | // 0xXXXe = 601 (1.4%) strings, 15 (2.5%) of which same-aligned |
246 | // total = 42706 (100%) strings, 15067 (35.3%) of which same-aligned |
247 | // |
248 | // 92% of the strings have alignment of 2 or 10, which is due to malloc on |
249 | // 32-bit Linux returning values aligned to 8 bytes, and offsetof(array, QString::Data) == 18. |
250 | // |
251 | // The profile on 64-bit will be different since offsetof(array, QString::Data) == 26. |
252 | // |
253 | // The benchmark results were, for a Core-i7 @ 2.67 GHz 32-bit, compiled with -O3 -funroll-loops: |
254 | // 16-bit loads only: 872,301 CPU ticks [Qt 4.5 / memcmp] |
255 | // 32- and 16-bit loads: 773,362 CPU ticks [Qt 4.6] |
256 | // SSE2 "movdqu" 128-bit loads: 618,736 CPU ticks |
257 | // SSE3 "lddqu" 128-bit loads: 619,954 CPU ticks |
258 | // SSSE3 "palignr" corrections: 852,147 CPU ticks |
259 | // SSE4.2 "pcmpestrm": 738,702 CPU ticks |
260 | // |
261 | // The same benchmark on an Atom N450 @ 1.66 GHz, is: |
262 | // 16-bit loads only: 2,185,882 CPU ticks |
263 | // 32- and 16-bit loads: 1,805,060 CPU ticks |
264 | // SSE2 "movdqu" 128-bit loads: 2,529,843 CPU ticks |
265 | // SSE3 "lddqu" 128-bit loads: 2,514,858 CPU ticks |
266 | // SSSE3 "palignr" corrections: 2,160,325 CPU ticks |
267 | // SSE4.2 not available |
268 | // |
269 | // The conclusion we reach is that alignment the SSE2 unaligned code can gain |
270 | // 20% improvement in performance in some systems, but suffers a penalty due |
271 | // to the unaligned loads on others. |
272 | |
273 | static bool qMemEquals(const quint16 *a, const quint16 *b, int length) |
274 | { |
275 | if (a == b || !length) |
276 | return true; |
277 | |
278 | register union { |
279 | const quint16 *w; |
280 | const quint32 *d; |
281 | quintptr value; |
282 | } sa, sb; |
283 | sa.w = a; |
284 | sb.w = b; |
285 | |
286 | // check alignment |
287 | if ((sa.value & 2) == (sb.value & 2)) { |
288 | // both addresses have the same alignment |
289 | if (sa.value & 2) { |
290 | // both addresses are not aligned to 4-bytes boundaries |
291 | // compare the first character |
292 | if (*sa.w != *sb.w) |
293 | return false; |
294 | --length; |
295 | ++sa.w; |
296 | ++sb.w; |
297 | |
298 | // now both addresses are 4-bytes aligned |
299 | } |
300 | |
301 | // both addresses are 4-bytes aligned |
302 | // do a fast 32-bit comparison |
303 | register const quint32 *e = sa.d + (length >> 1); |
304 | for ( ; sa.d != e; ++sa.d, ++sb.d) { |
305 | if (*sa.d != *sb.d) |
306 | return false; |
307 | } |
308 | |
309 | // do we have a tail? |
310 | return (length & 1) ? *sa.w == *sb.w : true; |
311 | } else { |
312 | // one of the addresses isn't 4-byte aligned but the other is |
313 | register const quint16 *e = sa.w + length; |
314 | for ( ; sa.w != e; ++sa.w, ++sb.w) { |
315 | if (*sa.w != *sb.w) |
316 | return false; |
317 | } |
318 | } |
319 | return true; |
320 | } |
321 | |
322 | /*! |
323 | \internal |
324 | |
325 | Returns the index position of the first occurrence of the |
326 | character \a ch in the string given by \a str and \a len, |
327 | searching forward from index |
328 | position \a from. Returns -1 if \a ch could not be found. |
329 | */ |
330 | static int findChar(const QChar *str, int len, QChar ch, int from, |
331 | Qt::CaseSensitivity cs) |
332 | { |
333 | const ushort *s = (const ushort *)str; |
334 | ushort c = ch.unicode(); |
335 | if (from < 0) |
336 | from = qMax(from + len, 0); |
337 | if (from < len) { |
338 | const ushort *n = s + from - 1; |
339 | const ushort *e = s + len; |
340 | if (cs == Qt::CaseSensitive) { |
341 | while (++n != e) |
342 | if (*n == c) |
343 | return n - s; |
344 | } else { |
345 | c = foldCase(c); |
346 | while (++n != e) |
347 | if (foldCase(*n) == c) |
348 | return n - s; |
349 | } |
350 | } |
351 | return -1; |
352 | } |
353 | |
354 | #define REHASH(a) \ |
355 | if (sl_minus_1 < (int)sizeof(int) * CHAR_BIT) \ |
356 | hashHaystack -= (a) << sl_minus_1; \ |
357 | hashHaystack <<= 1 |
358 | |
359 | inline bool qIsUpper(char ch) |
360 | { |
361 | return ch >= 'A' && ch <= 'Z'; |
362 | } |
363 | |
364 | inline bool qIsDigit(char ch) |
365 | { |
366 | return ch >= '0' && ch <= '9'; |
367 | } |
368 | |
369 | inline char qToLower(char ch) |
370 | { |
371 | if (ch >= 'A' && ch <= 'Z') |
372 | return ch - 'A' + 'a'; |
373 | else |
374 | return ch; |
375 | } |
376 | |
377 | const QString::Null QString::null = { }; |
378 | |
379 | /*! |
380 | \macro QT_NO_CAST_FROM_ASCII |
381 | \relates QString |
382 | |
383 | Disables automatic conversions from 8-bit strings (char *) to unicode QStrings |
384 | |
385 | \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_BYTEARRAY |
386 | */ |
387 | |
388 | /*! |
389 | \macro QT_NO_CAST_TO_ASCII |
390 | \relates QString |
391 | |
392 | disables automatic conversion from QString to 8-bit strings (char *) |
393 | |
394 | \sa QT_NO_CAST_FROM_ASCII, QT_NO_CAST_FROM_BYTEARRAY |
395 | */ |
396 | |
397 | /*! |
398 | \macro QT_ASCII_CAST_WARNINGS |
399 | \internal |
400 | \relates QString |
401 | |
402 | This macro can be defined to force a warning whenever a function is |
403 | called that automatically converts between unicode and 8-bit encodings. |
404 | |
405 | Note: This only works for compilers that support warnings for |
406 | deprecated API. |
407 | |
408 | \sa QT_NO_CAST_TO_ASCII, QT_NO_CAST_FROM_ASCII |
409 | */ |
410 | |
411 | /*! |
412 | \class QCharRef |
413 | \reentrant |
414 | \brief The QCharRef class is a helper class for QString. |
415 | |
416 | \internal |
417 | |
418 | \ingroup string-processing |
419 | |
420 | When you get an object of type QCharRef, if you can assign to it, |
421 | the assignment will apply to the character in the string from |
422 | which you got the reference. That is its whole purpose in life. |
423 | The QCharRef becomes invalid once modifications are made to the |
424 | string: if you want to keep the character, copy it into a QChar. |
425 | |
426 | Most of the QChar member functions also exist in QCharRef. |
427 | However, they are not explicitly documented here. |
428 | |
429 | \sa QString::operator[]() QString::at() QChar |
430 | */ |
431 | |
432 | /*! |
433 | \class QString |
434 | \reentrant |
435 | |
436 | \brief The QString class provides a Unicode character string. |
437 | |
438 | \ingroup tools |
439 | \ingroup shared |
440 | \ingroup string-processing |
441 | |
442 | QString stores a string of 16-bit \l{QChar}s, where each QChar |
443 | corresponds one Unicode 4.0 character. (Unicode characters |
444 | with code values above 65535 are stored using surrogate pairs, |
445 | i.e., two consecutive \l{QChar}s.) |
446 | |
447 | \l{Unicode} is an international standard that supports most of the |
448 | writing systems in use today. It is a superset of US-ASCII (ANSI |
449 | X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1 |
450 | characters are available at the same code positions. |
451 | |
452 | Behind the scenes, QString uses \l{implicit sharing} |
453 | (copy-on-write) to reduce memory usage and to avoid the needless |
454 | copying of data. This also helps reduce the inherent overhead of |
455 | storing 16-bit characters instead of 8-bit characters. |
456 | |
457 | In addition to QString, Qt also provides the QByteArray class to |
458 | store raw bytes and traditional 8-bit '\\0'-terminated strings. |
459 | For most purposes, QString is the class you want to use. It is |
460 | used throughout the Qt API, and the Unicode support ensures that |
461 | your applications will be easy to translate if you want to expand |
462 | your application's market at some point. The two main cases where |
463 | QByteArray is appropriate are when you need to store raw binary |
464 | data, and when memory conservation is critical (e.g., with |
465 | \l{Qt for Embedded Linux}). |
466 | |
467 | \tableofcontents |
468 | |
469 | \section1 Initializing a String |
470 | |
471 | One way to initialize a QString is simply to pass a \c{const char |
472 | *} to its constructor. For example, the following code creates a |
473 | QString of size 5 containing the data "Hello": |
474 | |
475 | \snippet doc/src/snippets/qstring/main.cpp 0 |
476 | |
477 | QString converts the \c{const char *} data into Unicode using the |
478 | fromAscii() function. By default, fromAscii() treats character |
479 | above 128 as Latin-1 characters, but this can be changed by |
480 | calling QTextCodec::setCodecForCStrings(). |
481 | |
482 | In all of the QString functions that take \c{const char *} |
483 | parameters, the \c{const char *} is interpreted as a classic |
484 | C-style '\\0'-terminated string. It is legal for the \c{const char |
485 | *} parameter to be 0. |
486 | |
487 | You can also provide string data as an array of \l{QChar}s: |
488 | |
489 | \snippet doc/src/snippets/qstring/main.cpp 1 |
490 | |
491 | QString makes a deep copy of the QChar data, so you can modify it |
492 | later without experiencing side effects. (If for performance |
493 | reasons you don't want to take a deep copy of the character data, |
494 | use QString::fromRawData() instead.) |
495 | |
496 | Another approach is to set the size of the string using resize() |
497 | and to initialize the data character per character. QString uses |
498 | 0-based indexes, just like C++ arrays. To access the character at |
499 | a particular index position, you can use \l operator[](). On |
500 | non-const strings, \l operator[]() returns a reference to a |
501 | character that can be used on the left side of an assignment. For |
502 | example: |
503 | |
504 | \snippet doc/src/snippets/qstring/main.cpp 2 |
505 | |
506 | For read-only access, an alternative syntax is to use the at() |
507 | function: |
508 | |
509 | \snippet doc/src/snippets/qstring/main.cpp 3 |
510 | |
511 | The at() function can be faster than \l operator[](), because it |
512 | never causes a \l{deep copy} to occur. Alternatively, use the |
513 | left(), right(), or mid() functions to extract several characters |
514 | at a time. |
515 | |
516 | A QString can embed '\\0' characters (QChar::Null). The size() |
517 | function always returns the size of the whole string, including |
518 | embedded '\\0' characters. |
519 | |
520 | After a call to the resize() function, newly allocated characters |
521 | have undefined values. To set all the characters in the string to |
522 | a particular value, use the fill() function. |
523 | |
524 | QString provides dozens of overloads designed to simplify string |
525 | usage. For example, if you want to compare a QString with a string |
526 | literal, you can write code like this and it will work as expected: |
527 | |
528 | \snippet doc/src/snippets/qstring/main.cpp 4 |
529 | |
530 | You can also pass string literals to functions that take QStrings |
531 | as arguments, invoking the QString(const char *) |
532 | constructor. Similarly, you can pass a QString to a function that |
533 | takes a \c{const char *} argument using the \l qPrintable() macro |
534 | which returns the given QString as a \c{const char *}. This is |
535 | equivalent to calling <QString>.toLocal8Bit().constData(). |
536 | |
537 | \section1 Manipulating String Data |
538 | |
539 | QString provides the following basic functions for modifying the |
540 | character data: append(), prepend(), insert(), replace(), and |
541 | remove(). For example: |
542 | |
543 | \snippet doc/src/snippets/qstring/main.cpp 5 |
544 | |
545 | If you are building a QString gradually and know in advance |
546 | approximately how many characters the QString will contain, you |
547 | can call reserve(), asking QString to preallocate a certain amount |
548 | of memory. You can also call capacity() to find out how much |
549 | memory QString actually allocated. |
550 | |
551 | The replace() and remove() functions' first two arguments are the |
552 | position from which to start erasing and the number of characters |
553 | that should be erased. If you want to replace all occurrences of |
554 | a particular substring with another, use one of the two-parameter |
555 | replace() overloads. |
556 | |
557 | A frequent requirement is to remove whitespace characters from a |
558 | string ('\\n', '\\t', ' ', etc.). If you want to remove whitespace |
559 | from both ends of a QString, use the trimmed() function. If you |
560 | want to remove whitespace from both ends and replace multiple |
561 | consecutive whitespaces with a single space character within the |
562 | string, use simplified(). |
563 | |
564 | If you want to find all occurrences of a particular character or |
565 | substring in a QString, use the indexOf() or lastIndexOf() |
566 | functions. The former searches forward starting from a given index |
567 | position, the latter searches backward. Both return the index |
568 | position of the character or substring if they find it; otherwise, |
569 | they return -1. For example, here's a typical loop that finds all |
570 | occurrences of a particular substring: |
571 | |
572 | \snippet doc/src/snippets/qstring/main.cpp 6 |
573 | |
574 | QString provides many functions for converting numbers into |
575 | strings and strings into numbers. See the arg() functions, the |
576 | setNum() functions, the number() static functions, and the |
577 | toInt(), toDouble(), and similar functions. |
578 | |
579 | To get an upper- or lowercase version of a string use toUpper() or |
580 | toLower(). |
581 | |
582 | Lists of strings are handled by the QStringList class. You can |
583 | split a string into a list of strings using the split() function, |
584 | and join a list of strings into a single string with an optional |
585 | separator using QStringList::join(). You can obtain a list of |
586 | strings from a string list that contain a particular substring or |
587 | that match a particular QRegExp using the QStringList::filter() |
588 | function. |
589 | |
590 | \section1 Querying String Data |
591 | |
592 | If you want to see if a QString starts or ends with a particular |
593 | substring use startsWith() or endsWith(). If you simply want to |
594 | check whether a QString contains a particular character or |
595 | substring, use the contains() function. If you want to find out |
596 | how many times a particular character or substring occurs in the |
597 | string, use count(). |
598 | |
599 | QStrings can be compared using overloaded operators such as \l |
600 | operator<(), \l operator<=(), \l operator==(), \l operator>=(), |
601 | and so on. Note that the comparison is based exclusively on the |
602 | numeric Unicode values of the characters. It is very fast, but is |
603 | not what a human would expect; the QString::localeAwareCompare() |
604 | function is a better choice for sorting user-interface strings. |
605 | |
606 | To obtain a pointer to the actual character data, call data() or |
607 | constData(). These functions return a pointer to the beginning of |
608 | the QChar data. The pointer is guaranteed to remain valid until a |
609 | non-const function is called on the QString. |
610 | |
611 | \section1 Converting Between 8-Bit Strings and Unicode Strings |
612 | |
613 | QString provides the following four functions that return a |
614 | \c{const char *} version of the string as QByteArray: toAscii(), |
615 | toLatin1(), toUtf8(), and toLocal8Bit(). |
616 | |
617 | \list |
618 | \o toAscii() returns an 8-bit string encoded using the codec |
619 | specified by QTextCodec::codecForCStrings (by default, that is |
620 | Latin 1). |
621 | \o toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string. |
622 | \o toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a |
623 | superset of US-ASCII (ANSI X3.4-1986) that supports the entire |
624 | Unicode character set through multibyte sequences. |
625 | \o toLocal8Bit() returns an 8-bit string using the system's local |
626 | encoding. |
627 | \endlist |
628 | |
629 | To convert from one of these encodings, QString provides |
630 | fromAscii(), fromLatin1(), fromUtf8(), and fromLocal8Bit(). Other |
631 | encodings are supported through the QTextCodec class. |
632 | |
633 | As mentioned above, QString provides a lot of functions and |
634 | operators that make it easy to interoperate with \c{const char *} |
635 | strings. But this functionality is a double-edged sword: It makes |
636 | QString more convenient to use if all strings are US-ASCII or |
637 | Latin-1, but there is always the risk that an implicit conversion |
638 | from or to \c{const char *} is done using the wrong 8-bit |
639 | encoding. To minimize these risks, you can turn off these implicit |
640 | conversions by defining the following two preprocessor symbols: |
641 | |
642 | \list |
643 | \o \c QT_NO_CAST_FROM_ASCII disables automatic conversions from |
644 | C string literals and pointers to Unicode. |
645 | \o \c QT_NO_CAST_TO_ASCII disables automatic conversion from QString |
646 | to C strings. |
647 | \endlist |
648 | |
649 | One way to define these preprocessor symbols globally for your |
650 | application is to add the following entry to your |
651 | \l{qmake Project Files}{qmake project file}: |
652 | |
653 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 0 |
654 | |
655 | You then need to explicitly call fromAscii(), fromLatin1(), |
656 | fromUtf8(), or fromLocal8Bit() to construct a QString from an |
657 | 8-bit string, or use the lightweight QLatin1String class, for |
658 | example: |
659 | |
660 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 1 |
661 | |
662 | Similarly, you must call toAscii(), toLatin1(), toUtf8(), or |
663 | toLocal8Bit() explicitly to convert the QString to an 8-bit |
664 | string. (Other encodings are supported through the QTextCodec |
665 | class.) |
666 | |
667 | \table 100 % |
668 | \header |
669 | \o Note for C Programmers |
670 | |
671 | \row |
672 | \o |
673 | Due to C++'s type system and the fact that QString is |
674 | \l{implicitly shared}, QStrings may be treated like \c{int}s or |
675 | other basic types. For example: |
676 | |
677 | \snippet doc/src/snippets/qstring/main.cpp 7 |
678 | |
679 | The \c result variable, is a normal variable allocated on the |
680 | stack. When \c return is called, and because we're returning by |
681 | value, the copy constructor is called and a copy of the string is |
682 | returned. No actual copying takes place thanks to the implicit |
683 | sharing. |
684 | |
685 | \endtable |
686 | |
687 | \section1 Distinction Between Null and Empty Strings |
688 | |
689 | For historical reasons, QString distinguishes between a null |
690 | string and an empty string. A \e null string is a string that is |
691 | initialized using QString's default constructor or by passing |
692 | (const char *)0 to the constructor. An \e empty string is any |
693 | string with size 0. A null string is always empty, but an empty |
694 | string isn't necessarily null: |
695 | |
696 | \snippet doc/src/snippets/qstring/main.cpp 8 |
697 | |
698 | All functions except isNull() treat null strings the same as empty |
699 | strings. For example, toAscii().constData() returns a pointer to a |
700 | '\\0' character for a null string (\e not a null pointer), and |
701 | QString() compares equal to QString(""). We recommend that you |
702 | always use the isEmpty() function and avoid isNull(). |
703 | |
704 | \section1 Argument Formats |
705 | |
706 | In member functions where an argument \e format can be specified |
707 | (e.g., arg(), number()), the argument \e format can be one of the |
708 | following: |
709 | |
710 | \table |
711 | \header \o Format \o Meaning |
712 | \row \o \c e \o format as [-]9.9e[+|-]999 |
713 | \row \o \c E \o format as [-]9.9E[+|-]999 |
714 | \row \o \c f \o format as [-]9.9 |
715 | \row \o \c g \o use \c e or \c f format, whichever is the most concise |
716 | \row \o \c G \o use \c E or \c f format, whichever is the most concise |
717 | \endtable |
718 | |
719 | A \e precision is also specified with the argument \e format. For |
720 | the 'e', 'E', and 'f' formats, the \e precision represents the |
721 | number of digits \e after the decimal point. For the 'g' and 'G' |
722 | formats, the \e precision represents the maximum number of |
723 | significant digits (trailing zeroes are omitted). |
724 | |
725 | \section1 More Efficient String Construction |
726 | |
727 | Using the QString \c{'+'} operator, it is easy to construct a |
728 | complex string from multiple substrings. You will often write code |
729 | like this: |
730 | |
731 | \snippet doc/src/snippets/qstring/stringbuilder.cpp 0 |
732 | |
733 | There is nothing wrong with either of these string constructions, |
734 | but there are a few hidden inefficiencies. Beginning with Qt 4.6, |
735 | you can eliminate them. |
736 | |
737 | First, multiple uses of the \c{'+'} operator usually means |
738 | multiple memory allocations. When concatenating \e{n} substrings, |
739 | where \e{n > 2}, there can be as many as \e{n - 1} calls to the |
740 | memory allocator. |
741 | |
742 | Second, QLatin1String does not store its length internally but |
743 | calls qstrlen() when it needs to know its length. |
744 | |
745 | In 4.6, an internal template class \c{QStringBuilder} has been |
746 | added along with a few helper functions. This class is marked |
747 | internal and does not appear in the documentation, because you |
748 | aren't meant to instantiate it in your code. Its use will be |
749 | automatic, as described below. The class is found in |
750 | \c {src/corelib/tools/qstringbuilder.cpp} if you want to have a |
751 | look at it. |
752 | |
753 | \c{QStringBuilder} uses expression templates and reimplements the |
754 | \c{'%'} operator so that when you use \c{'%'} for string |
755 | concatenation instead of \c{'+'}, multiple substring |
756 | concatenations will be postponed until the final result is about |
757 | to be assigned to a QString. At this point, the amount of memory |
758 | required for the final result is known. The memory allocator is |
759 | then called \e{once} to get the required space, and the substrings |
760 | are copied into it one by one. |
761 | |
762 | \c{QLatin1Literal} is a second internal class that can replace |
763 | QLatin1String, which can't be changed for compatibility reasons. |
764 | \c{QLatin1Literal} stores its length, thereby saving time when |
765 | \c{QStringBuilder} computes the amount of memory required for the |
766 | final string. |
767 | |
768 | Additional efficiency is gained by inlining and reduced reference |
769 | counting (the QString created from a \c{QStringBuilder} typically |
770 | has a ref count of 1, whereas QString::append() needs an extra |
771 | test). |
772 | |
773 | There are three ways you can access this improved method of string |
774 | construction. The straightforward way is to include |
775 | \c{QStringBuilder} wherever you want to use it, and use the |
776 | \c{'%'} operator instead of \c{'+'} when concatenating strings: |
777 | |
778 | \snippet doc/src/snippets/qstring/stringbuilder.cpp 5 |
779 | |
780 | A more global approach which is the most convenient but |
781 | not entirely source compatible, is to this define in your |
782 | .pro file: |
783 | |
784 | \snippet doc/src/snippets/qstring/stringbuilder.cpp 3 |
785 | |
786 | and the \c{'+'} will automatically be performed as the |
787 | \c{QStringBuilder} \c{'%'} everywhere. |
788 | |
789 | \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef |
790 | */ |
791 | |
792 | /*! |
793 | \enum QString::SplitBehavior |
794 | |
795 | This enum specifies how the split() function should behave with |
796 | respect to empty strings. |
797 | |
798 | \value KeepEmptyParts If a field is empty, keep it in the result. |
799 | \value SkipEmptyParts If a field is empty, don't include it in the result. |
800 | |
801 | \sa split() |
802 | */ |
803 | |
804 | QString::Data QString::shared_null = { Q_BASIC_ATOMIC_INITIALIZER(1), |
805 | 0, 0, shared_null.array, 0, 0, 0, 0, 0, 0, {0} }; |
806 | QString::Data QString::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1), |
807 | 0, 0, shared_empty.array, 0, 0, 0, 0, 0, 0, {0} }; |
808 | |
809 | int QString::grow(int size) |
810 | { |
811 | return qAllocMore(size * sizeof(QChar), sizeof(Data)) / sizeof(QChar); |
812 | } |
813 | |
814 | /*! \typedef QString::ConstIterator |
815 | |
816 | Qt-style synonym for QString::const_iterator. |
817 | */ |
818 | |
819 | /*! \typedef QString::Iterator |
820 | |
821 | Qt-style synonym for QString::iterator. |
822 | */ |
823 | |
824 | /*! \typedef QString::const_iterator |
825 | |
826 | The QString::const_iterator typedef provides an STL-style const |
827 | iterator for QString. |
828 | |
829 | \sa QString::iterator |
830 | */ |
831 | |
832 | /*! \typedef QString::iterator |
833 | |
834 | The QString::iterator typedef provides an STL-style non-const |
835 | iterator for QString. |
836 | |
837 | \sa QString::const_iterator |
838 | */ |
839 | |
840 | /*! |
841 | \typedef QString::const_reference |
842 | \since 4.8 |
843 | |
844 | The QString::const_reference typedef provides an STL-style |
845 | const reference for QString. |
846 | */ |
847 | /*! |
848 | \typedef QString::reference |
849 | \since 4.8 |
850 | |
851 | The QString::const_reference typedef provides an STL-style |
852 | reference for QString. |
853 | */ |
854 | /*! |
855 | \typedef QString::value_type |
856 | \since 4.8 |
857 | |
858 | The QString::const_reference typedef provides an STL-style |
859 | value type for QString. |
860 | */ |
861 | |
862 | /*! \fn QString::iterator QString::begin() |
863 | |
864 | Returns an \l{STL-style iterator} pointing to the first character in |
865 | the string. |
866 | |
867 | \sa constBegin(), end() |
868 | */ |
869 | |
870 | /*! \fn QString::const_iterator QString::begin() const |
871 | |
872 | \overload begin() |
873 | */ |
874 | |
875 | /*! \fn QString::const_iterator QString::constBegin() const |
876 | |
877 | Returns a const \l{STL-style iterator} pointing to the first character |
878 | in the string. |
879 | |
880 | \sa begin(), constEnd() |
881 | */ |
882 | |
883 | /*! \fn QString::iterator QString::end() |
884 | |
885 | Returns an \l{STL-style iterator} pointing to the imaginary character |
886 | after the last character in the string. |
887 | |
888 | \sa begin(), constEnd() |
889 | */ |
890 | |
891 | /*! \fn QString::const_iterator QString::end() const |
892 | |
893 | \overload end() |
894 | */ |
895 | |
896 | /*! \fn QString::const_iterator QString::constEnd() const |
897 | |
898 | Returns a const \l{STL-style iterator} pointing to the imaginary |
899 | item after the last item in the list. |
900 | |
901 | \sa constBegin(), end() |
902 | */ |
903 | |
904 | /*! |
905 | \fn QString::QString() |
906 | |
907 | Constructs a null string. Null strings are also empty. |
908 | |
909 | \sa isEmpty() |
910 | */ |
911 | |
912 | /*! \fn QString::QString(const char *str) |
913 | |
914 | Constructs a string initialized with the 8-bit string \a str. The |
915 | given const char pointer is converted to Unicode using the |
916 | fromAscii() function. |
917 | |
918 | You can disable this constructor by defining \c |
919 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
920 | can be useful if you want to ensure that all user-visible strings |
921 | go through QObject::tr(), for example. |
922 | |
923 | \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8() |
924 | */ |
925 | |
926 | /*! \fn QString QString::fromStdString(const std::string &str) |
927 | |
928 | Returns a copy of the \a str string. The given string is converted |
929 | to Unicode using the fromAscii() function. |
930 | |
931 | This constructor is only available if Qt is configured with STL |
932 | compatibility enabled. |
933 | |
934 | \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8() |
935 | */ |
936 | |
937 | /*! \fn QString QString::fromStdWString(const std::wstring &str) |
938 | |
939 | Returns a copy of the \a str string. The given string is assumed |
940 | to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on |
941 | windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix |
942 | systems). |
943 | |
944 | This method is only available if Qt is configured with STL |
945 | compatibility enabled. |
946 | |
947 | \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4() |
948 | */ |
949 | |
950 | /*! |
951 | \since 4.2 |
952 | |
953 | Returns a copy of the \a string, where the encoding of \a string depends on |
954 | the size of wchar. If wchar is 4 bytes, the \a string is interpreted as ucs-4, |
955 | if wchar is 2 bytes it is interpreted as ucs-2. |
956 | |
957 | If \a size is -1 (default), the \a string has to be 0 terminated. |
958 | |
959 | \sa fromUtf16(), fromLatin1(), fromLocal8Bit(), fromUtf8(), fromUcs4(), fromStdWString() |
960 | */ |
961 | QString QString::fromWCharArray(const wchar_t *string, int size) |
962 | { |
963 | if (sizeof(wchar_t) == sizeof(QChar)) { |
964 | return fromUtf16((const ushort *)string, size); |
965 | } else { |
966 | return fromUcs4((uint *)string, size); |
967 | } |
968 | } |
969 | |
970 | /*! \fn std::wstring QString::toStdWString() const |
971 | |
972 | Returns a std::wstring object with the data contained in this |
973 | QString. The std::wstring is encoded in utf16 on platforms where |
974 | wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms |
975 | where wchar_t is 4 bytes wide (most Unix systems). |
976 | |
977 | This operator is mostly useful to pass a QString to a function |
978 | that accepts a std::wstring object. |
979 | |
980 | This operator is only available if Qt is configured with STL |
981 | compatibility enabled. |
982 | |
983 | \sa utf16(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit() |
984 | */ |
985 | |
986 | template<typename T> int toUcs4_helper(const unsigned short *uc, int length, T *out) |
987 | { |
988 | int i = 0; |
989 | for (; i < length; ++i) { |
990 | uint u = uc[i]; |
991 | if (QChar::isHighSurrogate(u) && i < length-1) { |
992 | ushort low = uc[i+1]; |
993 | if (QChar::isLowSurrogate(low)) { |
994 | ++i; |
995 | u = QChar::surrogateToUcs4(u, low); |
996 | } |
997 | } |
998 | *out = T(u); |
999 | ++out; |
1000 | } |
1001 | return i; |
1002 | } |
1003 | |
1004 | /*! |
1005 | \since 4.2 |
1006 | |
1007 | Fills the \a array with the data contained in this QString object. |
1008 | The array is encoded in utf16 on platforms where |
1009 | wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms |
1010 | where wchar_t is 4 bytes wide (most Unix systems). |
1011 | |
1012 | \a array has to be allocated by the caller and contain enough space to |
1013 | hold the complete string (allocating the array with the same length as the |
1014 | string is always sufficient). |
1015 | |
1016 | returns the actual length of the string in \a array. |
1017 | |
1018 | \note This function does not append a null character to the array. |
1019 | |
1020 | \sa utf16(), toUcs4(), toAscii(), toLatin1(), toUtf8(), toLocal8Bit(), toStdWString() |
1021 | */ |
1022 | int QString::toWCharArray(wchar_t *array) const |
1023 | { |
1024 | if (sizeof(wchar_t) == sizeof(QChar)) { |
1025 | memcpy(array, utf16(), sizeof(wchar_t)*length()); |
1026 | return length(); |
1027 | } else { |
1028 | return toUcs4_helper<wchar_t>(utf16(), length(), array); |
1029 | } |
1030 | } |
1031 | |
1032 | /*! \fn QString::QString(const QString &other) |
1033 | |
1034 | Constructs a copy of \a other. |
1035 | |
1036 | This operation takes \l{constant time}, because QString is |
1037 | \l{implicitly shared}. This makes returning a QString from a |
1038 | function very fast. If a shared instance is modified, it will be |
1039 | copied (copy-on-write), and that takes \l{linear time}. |
1040 | |
1041 | \sa operator=() |
1042 | */ |
1043 | |
1044 | /*! |
1045 | Constructs a string initialized with the first \a size characters |
1046 | of the QChar array \a unicode. |
1047 | |
1048 | QString makes a deep copy of the string data. The unicode data is copied as |
1049 | is and the Byte Order Mark is preserved if present. |
1050 | */ |
1051 | QString::QString(const QChar *unicode, int size) |
1052 | { |
1053 | if (!unicode) { |
1054 | d = &shared_null; |
1055 | d->ref.ref(); |
1056 | } else if (size <= 0) { |
1057 | d = &shared_empty; |
1058 | d->ref.ref(); |
1059 | } else { |
1060 | d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar)); |
1061 | Q_CHECK_PTR(d); |
1062 | d->ref = 1; |
1063 | d->alloc = d->size = size; |
1064 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
1065 | d->data = d->array; |
1066 | memcpy(d->array, unicode, size * sizeof(QChar)); |
1067 | d->array[size] = '\0'; |
1068 | } |
1069 | } |
1070 | |
1071 | /*! |
1072 | \since 4.7 |
1073 | |
1074 | Constructs a string initialized with the characters of the QChar array |
1075 | \a unicode, which must be terminated with a 0. |
1076 | |
1077 | QString makes a deep copy of the string data. The unicode data is copied as |
1078 | is and the Byte Order Mark is preserved if present. |
1079 | */ |
1080 | QString::QString(const QChar *unicode) |
1081 | { |
1082 | if (!unicode) { |
1083 | d = &shared_null; |
1084 | d->ref.ref(); |
1085 | } else { |
1086 | int size = 0; |
1087 | while (unicode[size] != 0) |
1088 | ++size; |
1089 | if (!size) { |
1090 | d = &shared_empty; |
1091 | d->ref.ref(); |
1092 | } else { |
1093 | d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar)); |
1094 | Q_CHECK_PTR(d); |
1095 | d->ref = 1; |
1096 | d->alloc = d->size = size; |
1097 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
1098 | d->data = d->array; |
1099 | memcpy(d->array, unicode, size * sizeof(QChar)); |
1100 | d->array[size] = '\0'; |
1101 | } |
1102 | } |
1103 | } |
1104 | |
1105 | |
1106 | /*! |
1107 | Constructs a string of the given \a size with every character set |
1108 | to \a ch. |
1109 | |
1110 | \sa fill() |
1111 | */ |
1112 | QString::QString(int size, QChar ch) |
1113 | { |
1114 | if (size <= 0) { |
1115 | d = &shared_empty; |
1116 | d->ref.ref(); |
1117 | } else { |
1118 | d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar)); |
1119 | Q_CHECK_PTR(d); |
1120 | d->ref = 1; |
1121 | d->alloc = d->size = size; |
1122 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
1123 | d->data = d->array; |
1124 | d->array[size] = '\0'; |
1125 | ushort *i = d->array + size; |
1126 | ushort *b = d->array; |
1127 | const ushort value = ch.unicode(); |
1128 | while (i != b) |
1129 | *--i = value; |
1130 | } |
1131 | } |
1132 | |
1133 | /*! \fn QString::QString(int size, Qt::Initialization) |
1134 | \internal |
1135 | |
1136 | Constructs a string of the given \a size without initializing the |
1137 | characters. This is only used in \c QStringBuilder::toString(). |
1138 | */ |
1139 | QString::QString(int size, Qt::Initialization) |
1140 | { |
1141 | d = (Data*) qMalloc(sizeof(Data)+size*sizeof(QChar)); |
1142 | Q_CHECK_PTR(d); |
1143 | d->ref = 1; |
1144 | d->alloc = d->size = size; |
1145 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
1146 | d->data = d->array; |
1147 | d->array[size] = '\0'; |
1148 | } |
1149 | |
1150 | /*! \fn QString::QString(const QLatin1String &str) |
1151 | |
1152 | Constructs a copy of the Latin-1 string \a str. |
1153 | |
1154 | \sa fromLatin1() |
1155 | */ |
1156 | |
1157 | /*! |
1158 | Constructs a string of size 1 containing the character \a ch. |
1159 | */ |
1160 | QString::QString(QChar ch) |
1161 | { |
1162 | void *buf = qMalloc(sizeof(Data) + sizeof(QChar)); |
1163 | Q_CHECK_PTR(buf); |
1164 | d = reinterpret_cast<Data *>(buf); |
1165 | d->ref = 1; |
1166 | d->alloc = d->size = 1; |
1167 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
1168 | d->data = d->array; |
1169 | d->array[0] = ch.unicode(); |
1170 | d->array[1] = '\0'; |
1171 | } |
1172 | |
1173 | /*! \fn QString::QString(const QByteArray &ba) |
1174 | |
1175 | Constructs a string initialized with the byte array \a ba. The |
1176 | given byte array is converted to Unicode using fromAscii(). Stops |
1177 | copying at the first 0 character, otherwise copies the entire byte |
1178 | array. |
1179 | |
1180 | You can disable this constructor by defining \c |
1181 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1182 | can be useful if you want to ensure that all user-visible strings |
1183 | go through QObject::tr(), for example. |
1184 | |
1185 | \sa fromAscii(), fromLatin1(), fromLocal8Bit(), fromUtf8() |
1186 | */ |
1187 | |
1188 | /*! \fn QString::QString(const Null &) |
1189 | \internal |
1190 | */ |
1191 | |
1192 | /*! \fn QString &QString::operator=(const Null &) |
1193 | \internal |
1194 | */ |
1195 | |
1196 | /*! |
1197 | \fn QString::~QString() |
1198 | |
1199 | Destroys the string. |
1200 | */ |
1201 | |
1202 | |
1203 | /*! \fn void QString::swap(QString &other) |
1204 | \since 4.8 |
1205 | |
1206 | Swaps string \a other with this string. This operation is very fast and |
1207 | never fails. |
1208 | */ |
1209 | |
1210 | /*! \fn void QString::detach() |
1211 | |
1212 | \internal |
1213 | */ |
1214 | |
1215 | /*! \fn bool QString::isDetached() const |
1216 | |
1217 | \internal |
1218 | */ |
1219 | |
1220 | /*! \fn bool QString::isSharedWith(const QString &other) const |
1221 | |
1222 | \internal |
1223 | */ |
1224 | |
1225 | // ### Qt 5: rename freeData() to avoid confusion. See task 197625. |
1226 | void QString::free(Data *d) |
1227 | { |
1228 | #ifdef QT3_SUPPORT |
1229 | if (d->asciiCache) { |
1230 | QMutexLocker locker(asciiCacheMutex()); |
1231 | Q_ASSERT(asciiCache); |
1232 | asciiCache->remove(d); |
1233 | } |
1234 | #endif |
1235 | qFree(d); |
1236 | } |
1237 | |
1238 | /*! |
1239 | Sets the size of the string to \a size characters. |
1240 | |
1241 | If \a size is greater than the current size, the string is |
1242 | extended to make it \a size characters long with the extra |
1243 | characters added to the end. The new characters are uninitialized. |
1244 | |
1245 | If \a size is less than the current size, characters are removed |
1246 | from the end. |
1247 | |
1248 | Example: |
1249 | |
1250 | \snippet doc/src/snippets/qstring/main.cpp 45 |
1251 | |
1252 | If you want to append a certain number of identical characters to |
1253 | the string, use \l operator+=() as follows rather than resize(): |
1254 | |
1255 | \snippet doc/src/snippets/qstring/main.cpp 46 |
1256 | |
1257 | If you want to expand the string so that it reaches a certain |
1258 | width and fill the new positions with a particular character, use |
1259 | the leftJustified() function: |
1260 | |
1261 | If \a size is negative, it is equivalent to passing zero. |
1262 | |
1263 | \snippet doc/src/snippets/qstring/main.cpp 47 |
1264 | |
1265 | \sa truncate(), reserve() |
1266 | */ |
1267 | |
1268 | void QString::resize(int size) |
1269 | { |
1270 | if (size < 0) |
1271 | size = 0; |
1272 | |
1273 | if (size == 0 && !d->capacity) { |
1274 | Data *x = &shared_empty; |
1275 | x->ref.ref(); |
1276 | if (!d->ref.deref()) |
1277 | QString::free(d); |
1278 | d = x; |
1279 | } else { |
1280 | if (d->ref != 1 || size > d->alloc || |
1281 | (!d->capacity && size < d->size && size < d->alloc >> 1)) |
1282 | realloc(grow(size)); |
1283 | if (d->alloc >= size) { |
1284 | d->size = size; |
1285 | if (d->data == d->array) { |
1286 | d->array[size] = '\0'; |
1287 | } |
1288 | } |
1289 | } |
1290 | } |
1291 | |
1292 | /*! \fn int QString::capacity() const |
1293 | |
1294 | Returns the maximum number of characters that can be stored in |
1295 | the string without forcing a reallocation. |
1296 | |
1297 | The sole purpose of this function is to provide a means of fine |
1298 | tuning QString's memory usage. In general, you will rarely ever |
1299 | need to call this function. If you want to know how many |
1300 | characters are in the string, call size(). |
1301 | |
1302 | \sa reserve(), squeeze() |
1303 | */ |
1304 | |
1305 | /*! |
1306 | \fn void QString::reserve(int size) |
1307 | |
1308 | Attempts to allocate memory for at least \a size characters. If |
1309 | you know in advance how large the string will be, you can call |
1310 | this function, and if you resize the string often you are likely |
1311 | to get better performance. If \a size is an underestimate, the |
1312 | worst that will happen is that the QString will be a bit slower. |
1313 | |
1314 | The sole purpose of this function is to provide a means of fine |
1315 | tuning QString's memory usage. In general, you will rarely ever |
1316 | need to call this function. If you want to change the size of the |
1317 | string, call resize(). |
1318 | |
1319 | This function is useful for code that needs to build up a long |
1320 | string and wants to avoid repeated reallocation. In this example, |
1321 | we want to add to the string until some condition is true, and |
1322 | we're fairly sure that size is large enough to make a call to |
1323 | reserve() worthwhile: |
1324 | |
1325 | \snippet doc/src/snippets/qstring/main.cpp 44 |
1326 | |
1327 | \sa squeeze(), capacity() |
1328 | */ |
1329 | |
1330 | /*! |
1331 | \fn void QString::squeeze() |
1332 | |
1333 | Releases any memory not required to store the character data. |
1334 | |
1335 | The sole purpose of this function is to provide a means of fine |
1336 | tuning QString's memory usage. In general, you will rarely ever |
1337 | need to call this function. |
1338 | |
1339 | \sa reserve(), capacity() |
1340 | */ |
1341 | |
1342 | // ### Qt 5: rename reallocData() to avoid confusion. 197625 |
1343 | void QString::realloc(int alloc) |
1344 | { |
1345 | if (d->ref != 1 || d->data != d->array) { |
1346 | Data *x = static_cast<Data *>(qMalloc(sizeof(Data) + alloc * sizeof(QChar))); |
1347 | Q_CHECK_PTR(x); |
1348 | x->size = qMin(alloc, d->size); |
1349 | ::memcpy(x->array, d->data, x->size * sizeof(QChar)); |
1350 | x->array[x->size] = 0; |
1351 | x->asciiCache = 0; |
1352 | x->ref = 1; |
1353 | x->alloc = alloc; |
1354 | x->clean = d->clean; |
1355 | x->simpletext = d->simpletext; |
1356 | x->righttoleft = d->righttoleft; |
1357 | x->capacity = d->capacity; |
1358 | x->data = x->array; |
1359 | if (!d->ref.deref()) |
1360 | QString::free(d); |
1361 | d = x; |
1362 | } else { |
1363 | #ifdef QT3_SUPPORT |
1364 | if (d->asciiCache) { |
1365 | QMutexLocker locker(asciiCacheMutex()); |
1366 | Q_ASSERT(asciiCache); |
1367 | asciiCache->remove(d); |
1368 | } |
1369 | #endif |
1370 | Data *p = static_cast<Data *>(qRealloc(d, sizeof(Data) + alloc * sizeof(QChar))); |
1371 | Q_CHECK_PTR(p); |
1372 | d = p; |
1373 | d->alloc = alloc; |
1374 | d->data = d->array; |
1375 | } |
1376 | } |
1377 | |
1378 | void QString::realloc() |
1379 | { |
1380 | realloc(d->size); |
1381 | } |
1382 | |
1383 | void QString::expand(int i) |
1384 | { |
1385 | int sz = d->size; |
1386 | resize(qMax(i + 1, sz)); |
1387 | if (d->size - 1 > sz) { |
1388 | ushort *n = d->data + d->size - 1; |
1389 | ushort *e = d->data + sz; |
1390 | while (n != e) |
1391 | * --n = ' '; |
1392 | } |
1393 | } |
1394 | |
1395 | /*! \fn void QString::clear() |
1396 | |
1397 | Clears the contents of the string and makes it empty. |
1398 | |
1399 | \sa resize(), isEmpty() |
1400 | */ |
1401 | |
1402 | /*! \fn QString &QString::operator=(const QString &other) |
1403 | |
1404 | Assigns \a other to this string and returns a reference to this |
1405 | string. |
1406 | */ |
1407 | |
1408 | QString &QString::operator=(const QString &other) |
1409 | { |
1410 | other.d->ref.ref(); |
1411 | if (!d->ref.deref()) |
1412 | QString::free(d); |
1413 | d = other.d; |
1414 | return *this; |
1415 | } |
1416 | |
1417 | |
1418 | /*! \fn QString &QString::operator=(const QLatin1String &str) |
1419 | |
1420 | \overload operator=() |
1421 | |
1422 | Assigns the Latin-1 string \a str to this string. |
1423 | */ |
1424 | |
1425 | /*! \fn QString &QString::operator=(const QByteArray &ba) |
1426 | |
1427 | \overload operator=() |
1428 | |
1429 | Assigns \a ba to this string. The byte array is converted to Unicode |
1430 | using the fromAscii() function. This function stops conversion at the |
1431 | first NUL character found, or the end of the \a ba byte array. |
1432 | |
1433 | You can disable this operator by defining \c |
1434 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1435 | can be useful if you want to ensure that all user-visible strings |
1436 | go through QObject::tr(), for example. |
1437 | */ |
1438 | |
1439 | /*! \fn QString &QString::operator=(const char *str) |
1440 | |
1441 | \overload operator=() |
1442 | |
1443 | Assigns \a str to this string. The const char pointer is converted |
1444 | to Unicode using the fromAscii() function. |
1445 | |
1446 | You can disable this operator by defining \c |
1447 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1448 | can be useful if you want to ensure that all user-visible strings |
1449 | go through QObject::tr(), for example. |
1450 | */ |
1451 | |
1452 | /*! \fn QString &QString::operator=(char ch) |
1453 | |
1454 | \overload operator=() |
1455 | |
1456 | Assigns character \a ch to this string. The character is converted |
1457 | to Unicode using the fromAscii() function. |
1458 | |
1459 | You can disable this operator by defining \c |
1460 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1461 | can be useful if you want to ensure that all user-visible strings |
1462 | go through QObject::tr(), for example. |
1463 | */ |
1464 | |
1465 | /*! |
1466 | \overload operator=() |
1467 | |
1468 | Sets the string to contain the single character \a ch. |
1469 | */ |
1470 | QString &QString::operator=(QChar ch) |
1471 | { |
1472 | return operator=(QString(ch)); |
1473 | } |
1474 | |
1475 | /*! |
1476 | \fn QString& QString::insert(int position, const QString &str) |
1477 | |
1478 | Inserts the string \a str at the given index \a position and |
1479 | returns a reference to this string. |
1480 | |
1481 | Example: |
1482 | |
1483 | \snippet doc/src/snippets/qstring/main.cpp 26 |
1484 | |
1485 | If the given \a position is greater than size(), the array is |
1486 | first extended using resize(). |
1487 | |
1488 | \sa append(), prepend(), replace(), remove() |
1489 | */ |
1490 | |
1491 | |
1492 | /*! |
1493 | \fn QString &QString::insert(int position, const QLatin1String &str) |
1494 | \overload insert() |
1495 | |
1496 | Inserts the Latin-1 string \a str at the given index \a position. |
1497 | */ |
1498 | QString &QString::insert(int i, const QLatin1String &str) |
1499 | { |
1500 | const uchar *s = (const uchar *)str.latin1(); |
1501 | if (i < 0 || !s || !(*s)) |
1502 | return *this; |
1503 | |
1504 | int len = qstrlen(str.latin1()); |
1505 | expand(qMax(d->size, i) + len - 1); |
1506 | |
1507 | ::memmove(d->data + i + len, d->data + i, (d->size - i - len) * sizeof(QChar)); |
1508 | for (int j = 0; j < len; ++j) |
1509 | d->data[i + j] = s[j]; |
1510 | return *this; |
1511 | } |
1512 | |
1513 | /*! |
1514 | \fn QString& QString::insert(int position, const QChar *unicode, int size) |
1515 | \overload insert() |
1516 | |
1517 | Inserts the first \a size characters of the QChar array \a unicode |
1518 | at the given index \a position in the string. |
1519 | */ |
1520 | QString& QString::insert(int i, const QChar *unicode, int size) |
1521 | { |
1522 | if (i < 0 || size <= 0) |
1523 | return *this; |
1524 | |
1525 | const ushort *s = (const ushort *)unicode; |
1526 | if (s >= d->data && s < d->data + d->alloc) { |
1527 | // Part of me - take a copy |
1528 | ushort *tmp = static_cast<ushort *>(qMalloc(size * sizeof(QChar))); |
1529 | Q_CHECK_PTR(tmp); |
1530 | memcpy(tmp, s, size * sizeof(QChar)); |
1531 | insert(i, reinterpret_cast<const QChar *>(tmp), size); |
1532 | qFree(tmp); |
1533 | return *this; |
1534 | } |
1535 | |
1536 | expand(qMax(d->size, i) + size - 1); |
1537 | |
1538 | ::memmove(d->data + i + size, d->data + i, (d->size - i - size) * sizeof(QChar)); |
1539 | memcpy(d->data + i, s, size * sizeof(QChar)); |
1540 | return *this; |
1541 | } |
1542 | |
1543 | /*! |
1544 | \fn QString& QString::insert(int position, QChar ch) |
1545 | \overload insert() |
1546 | |
1547 | Inserts \a ch at the given index \a position in the string. |
1548 | */ |
1549 | |
1550 | QString& QString::insert(int i, QChar ch) |
1551 | { |
1552 | if (i < 0) |
1553 | i += d->size; |
1554 | if (i < 0) |
1555 | return *this; |
1556 | expand(qMax(i, d->size)); |
1557 | ::memmove(d->data + i + 1, d->data + i, (d->size - i) * sizeof(QChar)); |
1558 | d->data[i] = ch.unicode(); |
1559 | return *this; |
1560 | } |
1561 | |
1562 | /*! |
1563 | Appends the string \a str onto the end of this string. |
1564 | |
1565 | Example: |
1566 | |
1567 | \snippet doc/src/snippets/qstring/main.cpp 9 |
1568 | |
1569 | This is the same as using the insert() function: |
1570 | |
1571 | \snippet doc/src/snippets/qstring/main.cpp 10 |
1572 | |
1573 | The append() function is typically very fast (\l{constant time}), |
1574 | because QString preallocates extra space at the end of the string |
1575 | data so it can grow without reallocating the entire string each |
1576 | time. |
1577 | |
1578 | \sa operator+=(), prepend(), insert() |
1579 | */ |
1580 | QString &QString::append(const QString &str) |
1581 | { |
1582 | if (str.d != &shared_null) { |
1583 | if (d == &shared_null) { |
1584 | operator=(str); |
1585 | } else { |
1586 | if (d->ref != 1 || d->size + str.d->size > d->alloc) |
1587 | realloc(grow(d->size + str.d->size)); |
1588 | memcpy(d->data + d->size, str.d->data, str.d->size * sizeof(QChar)); |
1589 | d->size += str.d->size; |
1590 | d->data[d->size] = '\0'; |
1591 | } |
1592 | } |
1593 | return *this; |
1594 | } |
1595 | |
1596 | /*! |
1597 | \overload append() |
1598 | |
1599 | Appends the Latin-1 string \a str to this string. |
1600 | */ |
1601 | QString &QString::append(const QLatin1String &str) |
1602 | { |
1603 | const uchar *s = (const uchar *)str.latin1(); |
1604 | if (s) { |
1605 | int len = qstrlen((char *)s); |
1606 | if (d->ref != 1 || d->size + len > d->alloc) |
1607 | realloc(grow(d->size + len)); |
1608 | ushort *i = d->data + d->size; |
1609 | while ((*i++ = *s++)) |
1610 | ; |
1611 | d->size += len; |
1612 | } |
1613 | return *this; |
1614 | } |
1615 | |
1616 | /*! \fn QString &QString::append(const QByteArray &ba) |
1617 | |
1618 | \overload append() |
1619 | |
1620 | Appends the byte array \a ba to this string. The given byte array |
1621 | is converted to Unicode using the fromAscii() function. |
1622 | |
1623 | You can disable this function by defining \c QT_NO_CAST_FROM_ASCII |
1624 | when you compile your applications. This can be useful if you want |
1625 | to ensure that all user-visible strings go through QObject::tr(), |
1626 | for example. |
1627 | */ |
1628 | |
1629 | /*! \fn QString &QString::append(const char *str) |
1630 | |
1631 | \overload append() |
1632 | |
1633 | Appends the string \a str to this string. The given const char |
1634 | pointer is converted to Unicode using the fromAscii() function. |
1635 | |
1636 | You can disable this function by defining \c QT_NO_CAST_FROM_ASCII |
1637 | when you compile your applications. This can be useful if you want |
1638 | to ensure that all user-visible strings go through QObject::tr(), |
1639 | for example. |
1640 | */ |
1641 | |
1642 | /*! |
1643 | \overload append() |
1644 | |
1645 | Appends the character \a ch to this string. |
1646 | */ |
1647 | QString &QString::append(QChar ch) |
1648 | { |
1649 | if (d->ref != 1 || d->size + 1 > d->alloc) |
1650 | realloc(grow(d->size + 1)); |
1651 | d->data[d->size++] = ch.unicode(); |
1652 | d->data[d->size] = '\0'; |
1653 | return *this; |
1654 | } |
1655 | |
1656 | /*! \fn QString &QString::prepend(const QString &str) |
1657 | |
1658 | Prepends the string \a str to the beginning of this string and |
1659 | returns a reference to this string. |
1660 | |
1661 | Example: |
1662 | |
1663 | \snippet doc/src/snippets/qstring/main.cpp 36 |
1664 | |
1665 | \sa append(), insert() |
1666 | */ |
1667 | |
1668 | /*! \fn QString &QString::prepend(const QLatin1String &str) |
1669 | |
1670 | \overload prepend() |
1671 | |
1672 | Prepends the Latin-1 string \a str to this string. |
1673 | */ |
1674 | |
1675 | /*! \fn QString &QString::prepend(const QByteArray &ba) |
1676 | |
1677 | \overload prepend() |
1678 | |
1679 | Prepends the byte array \a ba to this string. The byte array is |
1680 | converted to Unicode using the fromAscii() function. |
1681 | |
1682 | You can disable this function by defining \c |
1683 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1684 | can be useful if you want to ensure that all user-visible strings |
1685 | go through QObject::tr(), for example. |
1686 | */ |
1687 | |
1688 | /*! \fn QString &QString::prepend(const char *str) |
1689 | |
1690 | \overload prepend() |
1691 | |
1692 | Prepends the string \a str to this string. The const char pointer |
1693 | is converted to Unicode using the fromAscii() function. |
1694 | |
1695 | You can disable this function by defining \c |
1696 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
1697 | can be useful if you want to ensure that all user-visible strings |
1698 | go through QObject::tr(), for example. |
1699 | */ |
1700 | |
1701 | /*! \fn QString &QString::prepend(QChar ch) |
1702 | |
1703 | \overload prepend() |
1704 | |
1705 | Prepends the character \a ch to this string. |
1706 | */ |
1707 | |
1708 | /*! |
1709 | \fn QString &QString::remove(int position, int n) |
1710 | |
1711 | Removes \a n characters from the string, starting at the given \a |
1712 | position index, and returns a reference to the string. |
1713 | |
1714 | If the specified \a position index is within the string, but \a |
1715 | position + \a n is beyond the end of the string, the string is |
1716 | truncated at the specified \a position. |
1717 | |
1718 | \snippet doc/src/snippets/qstring/main.cpp 37 |
1719 | |
1720 | \sa insert(), replace() |
1721 | */ |
1722 | QString &QString::remove(int pos, int len) |
1723 | { |
1724 | if (pos < 0) // count from end of string |
1725 | pos += d->size; |
1726 | if (pos < 0 || pos >= d->size) { |
1727 | // range problems |
1728 | } else if (len >= d->size - pos) { |
1729 | resize(pos); // truncate |
1730 | } else if (len > 0) { |
1731 | detach(); |
1732 | memmove(d->data + pos, d->data + pos + len, |
1733 | (d->size - pos - len + 1) * sizeof(ushort)); |
1734 | d->size -= len; |
1735 | } |
1736 | return *this; |
1737 | } |
1738 | |
1739 | /*! |
1740 | Removes every occurrence of the given \a str string in this |
1741 | string, and returns a reference to this string. |
1742 | |
1743 | If \a cs is Qt::CaseSensitive (default), the search is |
1744 | case sensitive; otherwise the search is case insensitive. |
1745 | |
1746 | This is the same as \c replace(str, "", cs). |
1747 | |
1748 | \sa replace() |
1749 | */ |
1750 | QString &QString::remove(const QString &str, Qt::CaseSensitivity cs) |
1751 | { |
1752 | if (str.d->size) { |
1753 | int i = 0; |
1754 | while ((i = indexOf(str, i, cs)) != -1) |
1755 | remove(i, str.d->size); |
1756 | } |
1757 | return *this; |
1758 | } |
1759 | |
1760 | /*! |
1761 | Removes every occurrence of the character \a ch in this string, and |
1762 | returns a reference to this string. |
1763 | |
1764 | If \a cs is Qt::CaseSensitive (default), the search is case |
1765 | sensitive; otherwise the search is case insensitive. |
1766 | |
1767 | Example: |
1768 | |
1769 | \snippet doc/src/snippets/qstring/main.cpp 38 |
1770 | |
1771 | This is the same as \c replace(ch, "", cs). |
1772 | |
1773 | \sa replace() |
1774 | */ |
1775 | QString &QString::remove(QChar ch, Qt::CaseSensitivity cs) |
1776 | { |
1777 | int i = 0; |
1778 | ushort c = ch.unicode(); |
1779 | if (cs == Qt::CaseSensitive) { |
1780 | while (i < d->size) |
1781 | if (d->data[i] == ch) |
1782 | remove(i, 1); |
1783 | else |
1784 | i++; |
1785 | } else { |
1786 | c = foldCase(c); |
1787 | while (i < d->size) |
1788 | if (foldCase(d->data[i]) == c) |
1789 | remove(i, 1); |
1790 | else |
1791 | i++; |
1792 | } |
1793 | return *this; |
1794 | } |
1795 | |
1796 | /*! |
1797 | \fn QString &QString::remove(const QRegExp &rx) |
1798 | |
1799 | Removes every occurrence of the regular expression \a rx in the |
1800 | string, and returns a reference to the string. For example: |
1801 | |
1802 | \snippet doc/src/snippets/qstring/main.cpp 39 |
1803 | |
1804 | \sa indexOf(), lastIndexOf(), replace() |
1805 | */ |
1806 | |
1807 | /*! |
1808 | \fn QString &QString::replace(int position, int n, const QString &after) |
1809 | |
1810 | Replaces \a n characters beginning at index \a position with |
1811 | the string \a after and returns a reference to this string. |
1812 | |
1813 | Example: |
1814 | |
1815 | \snippet doc/src/snippets/qstring/main.cpp 40 |
1816 | |
1817 | \sa insert(), remove() |
1818 | */ |
1819 | QString &QString::replace(int pos, int len, const QString &after) |
1820 | { |
1821 | QString copy = after; |
1822 | return replace(pos, len, copy.constData(), copy.length()); |
1823 | } |
1824 | |
1825 | /*! |
1826 | \fn QString &QString::replace(int position, int n, const QChar *unicode, int size) |
1827 | \overload replace() |
1828 | Replaces \a n characters beginning at index \a position with the |
1829 | first \a size characters of the QChar array \a unicode and returns a |
1830 | reference to this string. |
1831 | */ |
1832 | QString &QString::replace(int pos, int len, const QChar *unicode, int size) |
1833 | { |
1834 | if (pos < 0 || pos > d->size) |
1835 | return *this; |
1836 | if (pos + len > d->size) |
1837 | len = d->size - pos; |
1838 | |
1839 | uint index = pos; |
1840 | replace_helper(&index, 1, len, unicode, size); |
1841 | return *this; |
1842 | } |
1843 | |
1844 | /*! |
1845 | \fn QString &QString::replace(int position, int n, QChar after) |
1846 | \overload replace() |
1847 | |
1848 | Replaces \a n characters beginning at index \a position with the |
1849 | character \a after and returns a reference to this string. |
1850 | */ |
1851 | QString &QString::replace(int pos, int len, QChar after) |
1852 | { |
1853 | return replace(pos, len, &after, 1); |
1854 | } |
1855 | |
1856 | /*! |
1857 | \overload replace() |
1858 | Replaces every occurrence of the string \a before with the string \a |
1859 | after and returns a reference to this string. |
1860 | |
1861 | If \a cs is Qt::CaseSensitive (default), the search is case |
1862 | sensitive; otherwise the search is case insensitive. |
1863 | |
1864 | Example: |
1865 | |
1866 | \snippet doc/src/snippets/qstring/main.cpp 41 |
1867 | |
1868 | \note The replacement text is not rescanned after it is inserted. |
1869 | |
1870 | Example: |
1871 | |
1872 | \snippet doc/src/snippets/qstring/main.cpp 86 |
1873 | */ |
1874 | QString &QString::replace(const QString &before, const QString &after, Qt::CaseSensitivity cs) |
1875 | { |
1876 | return replace(before.constData(), before.size(), after.constData(), after.size(), cs); |
1877 | } |
1878 | |
1879 | /*! |
1880 | \internal |
1881 | */ |
1882 | void QString::replace_helper(uint *indices, int nIndices, int blen, const QChar *after, int alen) |
1883 | { |
1884 | // copy *after in case it lies inside our own d->data area |
1885 | // (which we could possibly invalidate via a realloc or corrupt via memcpy operations.) |
1886 | QChar *afterBuffer = const_cast<QChar *>(after); |
1887 | if (after >= reinterpret_cast<QChar *>(d->data) && after < reinterpret_cast<QChar *>(d->data) + d->size) { |
1888 | afterBuffer = static_cast<QChar *>(qMalloc(alen*sizeof(QChar))); |
1889 | Q_CHECK_PTR(afterBuffer); |
1890 | ::memcpy(afterBuffer, after, alen*sizeof(QChar)); |
1891 | } |
1892 | |
1893 | QT_TRY { |
1894 | if (blen == alen) { |
1895 | // replace in place |
1896 | detach(); |
1897 | for (int i = 0; i < nIndices; ++i) |
1898 | memcpy(d->data + indices[i], afterBuffer, alen * sizeof(QChar)); |
1899 | } else if (alen < blen) { |
1900 | // replace from front |
1901 | detach(); |
1902 | uint to = indices[0]; |
1903 | if (alen) |
1904 | memcpy(d->data+to, after, alen*sizeof(QChar)); |
1905 | to += alen; |
1906 | uint movestart = indices[0] + blen; |
1907 | for (int i = 1; i < nIndices; ++i) { |
1908 | int msize = indices[i] - movestart; |
1909 | if (msize > 0) { |
1910 | memmove(d->data + to, d->data + movestart, msize * sizeof(QChar)); |
1911 | to += msize; |
1912 | } |
1913 | if (alen) { |
1914 | memcpy(d->data + to, afterBuffer, alen*sizeof(QChar)); |
1915 | to += alen; |
1916 | } |
1917 | movestart = indices[i] + blen; |
1918 | } |
1919 | int msize = d->size - movestart; |
1920 | if (msize > 0) |
1921 | memmove(d->data + to, d->data + movestart, msize * sizeof(QChar)); |
1922 | resize(d->size - nIndices*(blen-alen)); |
1923 | } else { |
1924 | // replace from back |
1925 | int adjust = nIndices*(alen-blen); |
1926 | int newLen = d->size + adjust; |
1927 | int moveend = d->size; |
1928 | resize(newLen); |
1929 | |
1930 | while (nIndices) { |
1931 | --nIndices; |
1932 | int movestart = indices[nIndices] + blen; |
1933 | int insertstart = indices[nIndices] + nIndices*(alen-blen); |
1934 | int moveto = insertstart + alen; |
1935 | memmove(d->data + moveto, d->data + movestart, |
1936 | (moveend - movestart)*sizeof(QChar)); |
1937 | memcpy(d->data + insertstart, afterBuffer, alen*sizeof(QChar)); |
1938 | moveend = movestart-blen; |
1939 | } |
1940 | } |
1941 | } QT_CATCH(const std::bad_alloc &) { |
1942 | if (afterBuffer != after) |
1943 | qFree(afterBuffer); |
1944 | QT_RETHROW; |
1945 | } |
1946 | if (afterBuffer != after) |
1947 | qFree(afterBuffer); |
1948 | } |
1949 | |
1950 | /*! |
1951 | \since 4.5 |
1952 | \overload replace() |
1953 | |
1954 | Replaces each occurrence in this string of the first \a blen |
1955 | characters of \a before with the first \a alen characters of \a |
1956 | after and returns a reference to this string. |
1957 | |
1958 | If \a cs is Qt::CaseSensitive (default), the search is case |
1959 | sensitive; otherwise the search is case insensitive. |
1960 | */ |
1961 | QString &QString::replace(const QChar *before, int blen, |
1962 | const QChar *after, int alen, |
1963 | Qt::CaseSensitivity cs) |
1964 | { |
1965 | if (d->size == 0) { |
1966 | if (blen) |
1967 | return *this; |
1968 | } else { |
1969 | if (cs == Qt::CaseSensitive && before == after && blen == alen) |
1970 | return *this; |
1971 | } |
1972 | if (alen == 0 && blen == 0) |
1973 | return *this; |
1974 | |
1975 | QStringMatcher matcher(before, blen, cs); |
1976 | |
1977 | int index = 0; |
1978 | while (1) { |
1979 | uint indices[1024]; |
1980 | uint pos = 0; |
1981 | while (pos < 1023) { |
1982 | index = matcher.indexIn(*this, index); |
1983 | if (index == -1) |
1984 | break; |
1985 | indices[pos++] = index; |
1986 | index += blen; |
1987 | // avoid infinite loop |
1988 | if (!blen) |
1989 | index++; |
1990 | } |
1991 | if (!pos) |
1992 | break; |
1993 | |
1994 | replace_helper(indices, pos, blen, after, alen); |
1995 | |
1996 | if (index == -1) |
1997 | break; |
1998 | // index has to be adjusted in case we get back into the loop above. |
1999 | index += pos*(alen-blen); |
2000 | } |
2001 | |
2002 | return *this; |
2003 | } |
2004 | |
2005 | /*! |
2006 | \overload replace() |
2007 | Replaces every occurrence of the character \a ch in the string with |
2008 | \a after and returns a reference to this string. |
2009 | |
2010 | If \a cs is Qt::CaseSensitive (default), the search is case |
2011 | sensitive; otherwise the search is case insensitive. |
2012 | */ |
2013 | QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs) |
2014 | { |
2015 | if (after.d->size == 0) |
2016 | return remove(ch, cs); |
2017 | |
2018 | if (after.d->size == 1) |
2019 | return replace(ch, after.d->data[0], cs); |
2020 | |
2021 | if (d->size == 0) |
2022 | return *this; |
2023 | |
2024 | ushort cc = (cs == Qt::CaseSensitive ? ch.unicode() : ch.toCaseFolded().unicode()); |
2025 | |
2026 | int index = 0; |
2027 | while (1) { |
2028 | uint indices[1024]; |
2029 | uint pos = 0; |
2030 | if (cs == Qt::CaseSensitive) { |
2031 | while (pos < 1023 && index < d->size) { |
2032 | if (d->data[index] == cc) |
2033 | indices[pos++] = index; |
2034 | index++; |
2035 | } |
2036 | } else { |
2037 | while (pos < 1023 && index < d->size) { |
2038 | if (QChar::toCaseFolded(d->data[index]) == cc) |
2039 | indices[pos++] = index; |
2040 | index++; |
2041 | } |
2042 | } |
2043 | if (!pos) |
2044 | break; |
2045 | |
2046 | replace_helper(indices, pos, 1, after.constData(), after.d->size); |
2047 | |
2048 | if (index == -1) |
2049 | break; |
2050 | // index has to be adjusted in case we get back into the loop above. |
2051 | index += pos*(after.d->size - 1); |
2052 | } |
2053 | return *this; |
2054 | } |
2055 | |
2056 | /*! |
2057 | \overload replace() |
2058 | Replaces every occurrence of the character \a before with the |
2059 | character \a after and returns a reference to this string. |
2060 | |
2061 | If \a cs is Qt::CaseSensitive (default), the search is case |
2062 | sensitive; otherwise the search is case insensitive. |
2063 | */ |
2064 | QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs) |
2065 | { |
2066 | ushort a = after.unicode(); |
2067 | ushort b = before.unicode(); |
2068 | if (d->size) { |
2069 | detach(); |
2070 | ushort *i = d->data; |
2071 | const ushort *e = i + d->size; |
2072 | if (cs == Qt::CaseSensitive) { |
2073 | for (; i != e; ++i) |
2074 | if (*i == b) |
2075 | *i = a; |
2076 | } else { |
2077 | b = foldCase(b); |
2078 | for (; i != e; ++i) |
2079 | if (foldCase(*i) == b) |
2080 | *i = a; |
2081 | } |
2082 | } |
2083 | return *this; |
2084 | } |
2085 | |
2086 | /*! |
2087 | \since 4.5 |
2088 | \overload replace() |
2089 | |
2090 | Replaces every occurrence of the string \a before with the string \a |
2091 | after and returns a reference to this string. |
2092 | |
2093 | If \a cs is Qt::CaseSensitive (default), the search is case |
2094 | sensitive; otherwise the search is case insensitive. |
2095 | |
2096 | \note The text is not rescanned after a replacement. |
2097 | */ |
2098 | QString &QString::replace(const QLatin1String &before, |
2099 | const QLatin1String &after, |
2100 | Qt::CaseSensitivity cs) |
2101 | { |
2102 | int alen = qstrlen(after.latin1()); |
2103 | QVarLengthArray<ushort> a(alen); |
2104 | for (int i = 0; i < alen; ++i) |
2105 | a[i] = (uchar)after.latin1()[i]; |
2106 | int blen = qstrlen(before.latin1()); |
2107 | QVarLengthArray<ushort> b(blen); |
2108 | for (int i = 0; i < blen; ++i) |
2109 | b[i] = (uchar)before.latin1()[i]; |
2110 | return replace((const QChar *)b.data(), blen, (const QChar *)a.data(), alen, cs); |
2111 | } |
2112 | |
2113 | /*! |
2114 | \since 4.5 |
2115 | \overload replace() |
2116 | |
2117 | Replaces every occurrence of the string \a before with the string \a |
2118 | after and returns a reference to this string. |
2119 | |
2120 | If \a cs is Qt::CaseSensitive (default), the search is case |
2121 | sensitive; otherwise the search is case insensitive. |
2122 | |
2123 | \note The text is not rescanned after a replacement. |
2124 | */ |
2125 | QString &QString::replace(const QLatin1String &before, |
2126 | const QString &after, |
2127 | Qt::CaseSensitivity cs) |
2128 | { |
2129 | int blen = qstrlen(before.latin1()); |
2130 | QVarLengthArray<ushort> b(blen); |
2131 | for (int i = 0; i < blen; ++i) |
2132 | b[i] = (uchar)before.latin1()[i]; |
2133 | return replace((const QChar *)b.data(), blen, after.constData(), after.d->size, cs); |
2134 | } |
2135 | |
2136 | /*! |
2137 | \since 4.5 |
2138 | \overload replace() |
2139 | |
2140 | Replaces every occurrence of the string \a before with the string \a |
2141 | after and returns a reference to this string. |
2142 | |
2143 | If \a cs is Qt::CaseSensitive (default), the search is case |
2144 | sensitive; otherwise the search is case insensitive. |
2145 | |
2146 | \note The text is not rescanned after a replacement. |
2147 | */ |
2148 | QString &QString::replace(const QString &before, |
2149 | const QLatin1String &after, |
2150 | Qt::CaseSensitivity cs) |
2151 | { |
2152 | int alen = qstrlen(after.latin1()); |
2153 | QVarLengthArray<ushort> a(alen); |
2154 | for (int i = 0; i < alen; ++i) |
2155 | a[i] = (uchar)after.latin1()[i]; |
2156 | return replace(before.constData(), before.d->size, (const QChar *)a.data(), alen, cs); |
2157 | } |
2158 | |
2159 | /*! |
2160 | \since 4.5 |
2161 | \overload replace() |
2162 | |
2163 | Replaces every occurrence of the character \a c with the string \a |
2164 | after and returns a reference to this string. |
2165 | |
2166 | If \a cs is Qt::CaseSensitive (default), the search is case |
2167 | sensitive; otherwise the search is case insensitive. |
2168 | |
2169 | \note The text is not rescanned after a replacement. |
2170 | */ |
2171 | QString &QString::replace(QChar c, const QLatin1String &after, Qt::CaseSensitivity cs) |
2172 | { |
2173 | int alen = qstrlen(after.latin1()); |
2174 | QVarLengthArray<ushort> a(alen); |
2175 | for (int i = 0; i < alen; ++i) |
2176 | a[i] = (uchar)after.latin1()[i]; |
2177 | return replace(&c, 1, (const QChar *)a.data(), alen, cs); |
2178 | } |
2179 | |
2180 | |
2181 | /*! |
2182 | Returns true if string \a other is equal to this string; otherwise |
2183 | returns false. |
2184 | |
2185 | The comparison is based exclusively on the numeric Unicode values of |
2186 | the characters and is very fast, but is not what a human would |
2187 | expect. Consider sorting user-interface strings with |
2188 | localeAwareCompare(). |
2189 | */ |
2190 | bool QString::operator==(const QString &other) const |
2191 | { |
2192 | if (d->size != other.d->size) |
2193 | return false; |
2194 | |
2195 | return qMemEquals(d->data, other.d->data, d->size); |
2196 | } |
2197 | |
2198 | /*! |
2199 | \overload operator==() |
2200 | */ |
2201 | bool QString::operator==(const QLatin1String &other) const |
2202 | { |
2203 | const ushort *uc = d->data; |
2204 | const ushort *e = uc + d->size; |
2205 | const uchar *c = (uchar *)other.latin1(); |
2206 | |
2207 | if (!c) |
2208 | return isEmpty(); |
2209 | |
2210 | while (*c) { |
2211 | if (uc == e || *uc != *c) |
2212 | return false; |
2213 | ++uc; |
2214 | ++c; |
2215 | } |
2216 | return (uc == e); |
2217 | } |
2218 | |
2219 | /*! \fn bool QString::operator==(const QByteArray &other) const |
2220 | |
2221 | \overload operator==() |
2222 | |
2223 | The \a other byte array is converted to a QString using the |
2224 | fromAscii() function. This function stops conversion at the |
2225 | first NUL character found, or the end of the byte array. |
2226 | |
2227 | You can disable this operator by defining \c |
2228 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2229 | can be useful if you want to ensure that all user-visible strings |
2230 | go through QObject::tr(), for example. |
2231 | */ |
2232 | |
2233 | /*! \fn bool QString::operator==(const char *other) const |
2234 | |
2235 | \overload operator==() |
2236 | |
2237 | The \a other const char pointer is converted to a QString using |
2238 | the fromAscii() function. |
2239 | |
2240 | You can disable this operator by defining \c |
2241 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2242 | can be useful if you want to ensure that all user-visible strings |
2243 | go through QObject::tr(), for example. |
2244 | */ |
2245 | |
2246 | /*! |
2247 | Returns true if this string is lexically less than string \a |
2248 | other; otherwise returns false. |
2249 | |
2250 | The comparison is based exclusively on the numeric Unicode values |
2251 | of the characters and is very fast, but is not what a human would |
2252 | expect. Consider sorting user-interface strings using the |
2253 | QString::localeAwareCompare() function. |
2254 | */ |
2255 | bool QString::operator<(const QString &other) const |
2256 | { |
2257 | return ucstrcmp(constData(), length(), other.constData(), other.length()) < 0; |
2258 | } |
2259 | |
2260 | /*! |
2261 | \overload operator<() |
2262 | */ |
2263 | bool QString::operator<(const QLatin1String &other) const |
2264 | { |
2265 | const ushort *uc = d->data; |
2266 | const ushort *e = uc + d->size; |
2267 | const uchar *c = (uchar *) other.latin1(); |
2268 | |
2269 | if (!c || *c == 0) |
2270 | return false; |
2271 | |
2272 | while (*c) { |
2273 | if (uc == e || *uc != *c) |
2274 | break; |
2275 | ++uc; |
2276 | ++c; |
2277 | } |
2278 | return (uc == e ? *c : *uc < *c); |
2279 | } |
2280 | |
2281 | /*! \fn bool QString::operator<(const QByteArray &other) const |
2282 | |
2283 | \overload operator<() |
2284 | |
2285 | The \a other byte array is converted to a QString using the |
2286 | fromAscii() function. If any NUL characters ('\0') are embedded |
2287 | in the byte array, they will be included in the transformation. |
2288 | |
2289 | You can disable this operator by defining \c |
2290 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2291 | can be useful if you want to ensure that all user-visible strings |
2292 | go through QObject::tr(), for example. |
2293 | */ |
2294 | |
2295 | /*! \fn bool QString::operator<(const char *other) const |
2296 | |
2297 | \overload operator<() |
2298 | |
2299 | The \a other const char pointer is converted to a QString using |
2300 | the fromAscii() function. |
2301 | |
2302 | You can disable this operator by defining \c |
2303 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2304 | can be useful if you want to ensure that all user-visible strings |
2305 | go through QObject::tr(), for example. |
2306 | */ |
2307 | |
2308 | /*! \fn bool QString::operator<=(const QString &other) const |
2309 | |
2310 | Returns true if this string is lexically less than or equal to |
2311 | string \a other; otherwise returns false. |
2312 | |
2313 | The comparison is based exclusively on the numeric Unicode values |
2314 | of the characters and is very fast, but is not what a human would |
2315 | expect. Consider sorting user-interface strings with |
2316 | localeAwareCompare(). |
2317 | */ |
2318 | |
2319 | /*! \fn bool QString::operator<=(const QLatin1String &other) const |
2320 | |
2321 | \overload operator<=() |
2322 | */ |
2323 | |
2324 | /*! \fn bool QString::operator<=(const QByteArray &other) const |
2325 | |
2326 | \overload operator<=() |
2327 | |
2328 | The \a other byte array is converted to a QString using the |
2329 | fromAscii() function. If any NUL characters ('\0') are embedded |
2330 | in the byte array, they will be included in the transformation. |
2331 | |
2332 | You can disable this operator by defining \c |
2333 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2334 | can be useful if you want to ensure that all user-visible strings |
2335 | go through QObject::tr(), for example. |
2336 | */ |
2337 | |
2338 | /*! \fn bool QString::operator<=(const char *other) const |
2339 | |
2340 | \overload operator<=() |
2341 | |
2342 | The \a other const char pointer is converted to a QString using |
2343 | the fromAscii() function. |
2344 | |
2345 | You can disable this operator by defining \c |
2346 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2347 | can be useful if you want to ensure that all user-visible strings |
2348 | go through QObject::tr(), for example. |
2349 | */ |
2350 | |
2351 | /*! \fn bool QString::operator>(const QString &other) const |
2352 | |
2353 | Returns true if this string is lexically greater than string \a |
2354 | other; otherwise returns false. |
2355 | |
2356 | The comparison is based exclusively on the numeric Unicode values |
2357 | of the characters and is very fast, but is not what a human would |
2358 | expect. Consider sorting user-interface strings with |
2359 | localeAwareCompare(). |
2360 | */ |
2361 | |
2362 | /*! |
2363 | \overload operator>() |
2364 | */ |
2365 | bool QString::operator>(const QLatin1String &other) const |
2366 | { |
2367 | const ushort *uc = d->data;; |
2368 | const ushort *e = uc + d->size; |
2369 | const uchar *c = (uchar *) other.latin1(); |
2370 | |
2371 | if (!c || *c == '\0') |
2372 | return !isEmpty(); |
2373 | |
2374 | while (*c) { |
2375 | if (uc == e || *uc != *c) |
2376 | break; |
2377 | ++uc; |
2378 | ++c; |
2379 | } |
2380 | return (uc == e ? false : *uc > *c); |
2381 | } |
2382 | |
2383 | /*! \fn bool QString::operator>(const QByteArray &other) const |
2384 | |
2385 | \overload operator>() |
2386 | |
2387 | The \a other byte array is converted to a QString using the |
2388 | fromAscii() function. If any NUL characters ('\0') are embedded |
2389 | in the byte array, they will be included in the transformation. |
2390 | |
2391 | You can disable this operator by defining \c |
2392 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2393 | can be useful if you want to ensure that all user-visible strings |
2394 | go through QObject::tr(), for example. |
2395 | */ |
2396 | |
2397 | /*! \fn bool QString::operator>(const char *other) const |
2398 | |
2399 | \overload operator>() |
2400 | |
2401 | The \a other const char pointer is converted to a QString using |
2402 | the fromAscii() function. |
2403 | |
2404 | You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII |
2405 | when you compile your applications. This can be useful if you want |
2406 | to ensure that all user-visible strings go through QObject::tr(), |
2407 | for example. |
2408 | */ |
2409 | |
2410 | /*! \fn bool QString::operator>=(const QString &other) const |
2411 | |
2412 | Returns true if this string is lexically greater than or equal to |
2413 | string \a other; otherwise returns false. |
2414 | |
2415 | The comparison is based exclusively on the numeric Unicode values |
2416 | of the characters and is very fast, but is not what a human would |
2417 | expect. Consider sorting user-interface strings with |
2418 | localeAwareCompare(). |
2419 | */ |
2420 | |
2421 | /*! \fn bool QString::operator>=(const QLatin1String &other) const |
2422 | |
2423 | \overload operator>=() |
2424 | */ |
2425 | |
2426 | /*! \fn bool QString::operator>=(const QByteArray &other) const |
2427 | |
2428 | \overload operator>=() |
2429 | |
2430 | The \a other byte array is converted to a QString using the |
2431 | fromAscii() function. If any NUL characters ('\0') are embedded in |
2432 | the byte array, they will be included in the transformation. |
2433 | |
2434 | You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII |
2435 | when you compile your applications. This can be useful if you want |
2436 | to ensure that all user-visible strings go through QObject::tr(), |
2437 | for example. |
2438 | */ |
2439 | |
2440 | /*! \fn bool QString::operator>=(const char *other) const |
2441 | |
2442 | \overload operator>=() |
2443 | |
2444 | The \a other const char pointer is converted to a QString using |
2445 | the fromAscii() function. |
2446 | |
2447 | You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII |
2448 | when you compile your applications. This can be useful if you want |
2449 | to ensure that all user-visible strings go through QObject::tr(), |
2450 | for example. |
2451 | */ |
2452 | |
2453 | /*! \fn bool QString::operator!=(const QString &other) const |
2454 | |
2455 | Returns true if this string is not equal to string \a other; |
2456 | otherwise returns false. |
2457 | |
2458 | The comparison is based exclusively on the numeric Unicode values |
2459 | of the characters and is very fast, but is not what a human would |
2460 | expect. Consider sorting user-interface strings with |
2461 | localeAwareCompare(). |
2462 | */ |
2463 | |
2464 | /*! \fn bool QString::operator!=(const QLatin1String &other) const |
2465 | |
2466 | \overload operator!=() |
2467 | */ |
2468 | |
2469 | /*! \fn bool QString::operator!=(const QByteArray &other) const |
2470 | |
2471 | \overload operator!=() |
2472 | |
2473 | The \a other byte array is converted to a QString using the |
2474 | fromAscii() function. If any NUL characters ('\0') are embedded |
2475 | in the byte array, they will be included in the transformation. |
2476 | |
2477 | You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII |
2478 | when you compile your applications. This can be useful if you want |
2479 | to ensure that all user-visible strings go through QObject::tr(), |
2480 | for example. |
2481 | */ |
2482 | |
2483 | /*! \fn bool QString::operator!=(const char *other) const |
2484 | |
2485 | \overload operator!=() |
2486 | |
2487 | The \a other const char pointer is converted to a QString using |
2488 | the fromAscii() function. |
2489 | |
2490 | You can disable this operator by defining \c |
2491 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
2492 | can be useful if you want to ensure that all user-visible strings |
2493 | go through QObject::tr(), for example. |
2494 | */ |
2495 | |
2496 | /*! |
2497 | Returns the index position of the first occurrence of the string \a |
2498 | str in this string, searching forward from index position \a |
2499 | from. Returns -1 if \a str is not found. |
2500 | |
2501 | If \a cs is Qt::CaseSensitive (default), the search is case |
2502 | sensitive; otherwise the search is case insensitive. |
2503 | |
2504 | Example: |
2505 | |
2506 | \snippet doc/src/snippets/qstring/main.cpp 24 |
2507 | |
2508 | If \a from is -1, the search starts at the last character; if it is |
2509 | -2, at the next to last character and so on. |
2510 | |
2511 | \sa lastIndexOf(), contains(), count() |
2512 | */ |
2513 | int QString::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const |
2514 | { |
2515 | return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs); |
2516 | } |
2517 | |
2518 | /*! |
2519 | \since 4.5 |
2520 | Returns the index position of the first occurrence of the string \a |
2521 | str in this string, searching forward from index position \a |
2522 | from. Returns -1 if \a str is not found. |
2523 | |
2524 | If \a cs is Qt::CaseSensitive (default), the search is case |
2525 | sensitive; otherwise the search is case insensitive. |
2526 | |
2527 | Example: |
2528 | |
2529 | \snippet doc/src/snippets/qstring/main.cpp 24 |
2530 | |
2531 | If \a from is -1, the search starts at the last character; if it is |
2532 | -2, at the next to last character and so on. |
2533 | |
2534 | \sa lastIndexOf(), contains(), count() |
2535 | */ |
2536 | |
2537 | int QString::indexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const |
2538 | { |
2539 | return qt_find_latin1_string(unicode(), size(), str, from, cs); |
2540 | } |
2541 | |
2542 | int qFindString( |
2543 | const QChar *haystack0, int haystackLen, int from, |
2544 | const QChar *needle0, int needleLen, Qt::CaseSensitivity cs) |
2545 | { |
2546 | const int l = haystackLen; |
2547 | const int sl = needleLen; |
2548 | if (from < 0) |
2549 | from += l; |
2550 | if (uint(sl + from) > (uint)l) |
2551 | return -1; |
2552 | if (!sl) |
2553 | return from; |
2554 | if (!l) |
2555 | return -1; |
2556 | |
2557 | if (sl == 1) |
2558 | return findChar(haystack0, haystackLen, needle0[0], from, cs); |
2559 | |
2560 | /* |
2561 | We use the Boyer-Moore algorithm in cases where the overhead |
2562 | for the skip table should pay off, otherwise we use a simple |
2563 | hash function. |
2564 | */ |
2565 | if (l > 500 && sl > 5) |
2566 | return qFindStringBoyerMoore(haystack0, haystackLen, from, |
2567 | needle0, needleLen, cs); |
2568 | |
2569 | /* |
2570 | We use some hashing for efficiency's sake. Instead of |
2571 | comparing strings, we compare the hash value of str with that |
2572 | of a part of this QString. Only if that matches, we call |
2573 | ucstrncmp() or ucstrnicmp(). |
2574 | */ |
2575 | const ushort *needle = (const ushort *)needle0; |
2576 | const ushort *haystack = (const ushort *)haystack0 + from; |
2577 | const ushort *end = (const ushort *)haystack0 + (l-sl); |
2578 | const int sl_minus_1 = sl-1; |
2579 | int hashNeedle = 0, hashHaystack = 0, idx; |
2580 | |
2581 | if (cs == Qt::CaseSensitive) { |
2582 | for (idx = 0; idx < sl; ++idx) { |
2583 | hashNeedle = ((hashNeedle<<1) + needle[idx]); |
2584 | hashHaystack = ((hashHaystack<<1) + haystack[idx]); |
2585 | } |
2586 | hashHaystack -= haystack[sl_minus_1]; |
2587 | |
2588 | while (haystack <= end) { |
2589 | hashHaystack += haystack[sl_minus_1]; |
2590 | if (hashHaystack == hashNeedle |
2591 | && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0) |
2592 | return haystack - (const ushort *)haystack0; |
2593 | |
2594 | REHASH(*haystack); |
2595 | ++haystack; |
2596 | } |
2597 | } else { |
2598 | const ushort *haystack_start = (const ushort *)haystack0; |
2599 | for (idx = 0; idx < sl; ++idx) { |
2600 | hashNeedle = (hashNeedle<<1) + foldCase(needle + idx, needle); |
2601 | hashHaystack = (hashHaystack<<1) + foldCase(haystack + idx, haystack_start); |
2602 | } |
2603 | hashHaystack -= foldCase(haystack + sl_minus_1, haystack_start); |
2604 | |
2605 | while (haystack <= end) { |
2606 | hashHaystack += foldCase(haystack + sl_minus_1, haystack_start); |
2607 | if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0) |
2608 | return haystack - (const ushort *)haystack0; |
2609 | |
2610 | REHASH(foldCase(haystack, haystack_start)); |
2611 | ++haystack; |
2612 | } |
2613 | } |
2614 | return -1; |
2615 | } |
2616 | |
2617 | /*! |
2618 | \overload indexOf() |
2619 | |
2620 | Returns the index position of the first occurrence of the |
2621 | character \a ch in the string, searching forward from index |
2622 | position \a from. Returns -1 if \a ch could not be found. |
2623 | */ |
2624 | int QString::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const |
2625 | { |
2626 | return findChar(unicode(), length(), ch, from, cs); |
2627 | } |
2628 | |
2629 | /*! |
2630 | \since 4.8 |
2631 | |
2632 | \overload indexOf() |
2633 | |
2634 | Returns the index position of the first occurrence of the string |
2635 | reference \a str in this string, searching forward from index |
2636 | position \a from. Returns -1 if \a str is not found. |
2637 | |
2638 | If \a cs is Qt::CaseSensitive (default), the search is case |
2639 | sensitive; otherwise the search is case insensitive. |
2640 | */ |
2641 | int QString::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const |
2642 | { |
2643 | return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs); |
2644 | } |
2645 | |
2646 | static int lastIndexOfHelper(const ushort *haystack, int from, const ushort *needle, int sl, Qt::CaseSensitivity cs) |
2647 | { |
2648 | /* |
2649 | See indexOf() for explanations. |
2650 | */ |
2651 | |
2652 | const ushort *end = haystack; |
2653 | haystack += from; |
2654 | const int sl_minus_1 = sl-1; |
2655 | const ushort *n = needle+sl_minus_1; |
2656 | const ushort *h = haystack+sl_minus_1; |
2657 | int hashNeedle = 0, hashHaystack = 0, idx; |
2658 | |
2659 | if (cs == Qt::CaseSensitive) { |
2660 | for (idx = 0; idx < sl; ++idx) { |
2661 | hashNeedle = ((hashNeedle<<1) + *(n-idx)); |
2662 | hashHaystack = ((hashHaystack<<1) + *(h-idx)); |
2663 | } |
2664 | hashHaystack -= *haystack; |
2665 | |
2666 | while (haystack >= end) { |
2667 | hashHaystack += *haystack; |
2668 | if (hashHaystack == hashNeedle |
2669 | && ucstrncmp((const QChar *)needle, (const QChar *)haystack, sl) == 0) |
2670 | return haystack - end; |
2671 | --haystack; |
2672 | REHASH(haystack[sl]); |
2673 | } |
2674 | } else { |
2675 | for (idx = 0; idx < sl; ++idx) { |
2676 | hashNeedle = ((hashNeedle<<1) + foldCase(n-idx, needle)); |
2677 | hashHaystack = ((hashHaystack<<1) + foldCase(h-idx, end)); |
2678 | } |
2679 | hashHaystack -= foldCase(haystack, end); |
2680 | |
2681 | while (haystack >= end) { |
2682 | hashHaystack += foldCase(haystack, end); |
2683 | if (hashHaystack == hashNeedle && ucstrnicmp(needle, haystack, sl) == 0) |
2684 | return haystack - end; |
2685 | --haystack; |
2686 | REHASH(foldCase(haystack + sl, end)); |
2687 | } |
2688 | } |
2689 | return -1; |
2690 | } |
2691 | |
2692 | /*! |
2693 | Returns the index position of the last occurrence of the string \a |
2694 | str in this string, searching backward from index position \a |
2695 | from. If \a from is -1 (default), the search starts at the last |
2696 | character; if \a from is -2, at the next to last character and so |
2697 | on. Returns -1 if \a str is not found. |
2698 | |
2699 | If \a cs is Qt::CaseSensitive (default), the search is case |
2700 | sensitive; otherwise the search is case insensitive. |
2701 | |
2702 | Example: |
2703 | |
2704 | \snippet doc/src/snippets/qstring/main.cpp 29 |
2705 | |
2706 | \sa indexOf(), contains(), count() |
2707 | */ |
2708 | int QString::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const |
2709 | { |
2710 | const int sl = str.d->size; |
2711 | if (sl == 1) |
2712 | return lastIndexOf(QChar(str.d->data[0]), from, cs); |
2713 | |
2714 | const int l = d->size; |
2715 | if (from < 0) |
2716 | from += l; |
2717 | int delta = l-sl; |
2718 | if (from == l && sl == 0) |
2719 | return from; |
2720 | if (from < 0 || from >= l || delta < 0) |
2721 | return -1; |
2722 | if (from > delta) |
2723 | from = delta; |
2724 | |
2725 | return lastIndexOfHelper(d->data, from, str.d->data, str.d->size, cs); |
2726 | } |
2727 | |
2728 | /*! |
2729 | \since 4.5 |
2730 | \overload lastIndexOf() |
2731 | |
2732 | Returns the index position of the last occurrence of the string \a |
2733 | str in this string, searching backward from index position \a |
2734 | from. If \a from is -1 (default), the search starts at the last |
2735 | character; if \a from is -2, at the next to last character and so |
2736 | on. Returns -1 if \a str is not found. |
2737 | |
2738 | If \a cs is Qt::CaseSensitive (default), the search is case |
2739 | sensitive; otherwise the search is case insensitive. |
2740 | |
2741 | Example: |
2742 | |
2743 | \snippet doc/src/snippets/qstring/main.cpp 29 |
2744 | |
2745 | \sa indexOf(), contains(), count() |
2746 | */ |
2747 | int QString::lastIndexOf(const QLatin1String &str, int from, Qt::CaseSensitivity cs) const |
2748 | { |
2749 | const int sl = qstrlen(str.latin1()); |
2750 | if (sl == 1) |
2751 | return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs); |
2752 | |
2753 | const int l = d->size; |
2754 | if (from < 0) |
2755 | from += l; |
2756 | int delta = l-sl; |
2757 | if (from == l && sl == 0) |
2758 | return from; |
2759 | if (from < 0 || from >= l || delta < 0) |
2760 | return -1; |
2761 | if (from > delta) |
2762 | from = delta; |
2763 | |
2764 | QVarLengthArray<ushort> s(sl); |
2765 | for (int i = 0; i < sl; ++i) |
2766 | s[i] = str.latin1()[i]; |
2767 | |
2768 | return lastIndexOfHelper(d->data, from, s.data(), sl, cs); |
2769 | } |
2770 | |
2771 | /*! |
2772 | \overload lastIndexOf() |
2773 | |
2774 | Returns the index position of the last occurrence of the character |
2775 | \a ch, searching backward from position \a from. |
2776 | */ |
2777 | int QString::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const |
2778 | { |
2779 | return qt_last_index_of(unicode(), size(), ch, from, cs); |
2780 | } |
2781 | |
2782 | /*! |
2783 | \since 4.8 |
2784 | \overload lastIndexOf() |
2785 | |
2786 | Returns the index position of the last occurrence of the string |
2787 | reference \a str in this string, searching backward from index |
2788 | position \a from. If \a from is -1 (default), the search starts at |
2789 | the last character; if \a from is -2, at the next to last character |
2790 | and so on. Returns -1 if \a str is not found. |
2791 | |
2792 | If \a cs is Qt::CaseSensitive (default), the search is case |
2793 | sensitive; otherwise the search is case insensitive. |
2794 | |
2795 | \sa indexOf(), contains(), count() |
2796 | */ |
2797 | int QString::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const |
2798 | { |
2799 | const int sl = str.size(); |
2800 | if (sl == 1) |
2801 | return lastIndexOf(str.at(0), from, cs); |
2802 | |
2803 | const int l = d->size; |
2804 | if (from < 0) |
2805 | from += l; |
2806 | int delta = l - sl; |
2807 | if (from == l && sl == 0) |
2808 | return from; |
2809 | if (from < 0 || from >= l || delta < 0) |
2810 | return -1; |
2811 | if (from > delta) |
2812 | from = delta; |
2813 | |
2814 | return lastIndexOfHelper(d->data, from, reinterpret_cast<const ushort*>(str.unicode()), |
2815 | str.size(), cs); |
2816 | } |
2817 | |
2818 | #ifndef QT_NO_REGEXP |
2819 | struct QStringCapture |
2820 | { |
2821 | int pos; |
2822 | int len; |
2823 | int no; |
2824 | }; |
2825 | |
2826 | /*! |
2827 | \overload replace() |
2828 | |
2829 | Replaces every occurrence of the regular expression \a rx in the |
2830 | string with \a after. Returns a reference to the string. For |
2831 | example: |
2832 | |
2833 | \snippet doc/src/snippets/qstring/main.cpp 42 |
2834 | |
2835 | For regular expressions containing \l{capturing parentheses}, |
2836 | occurrences of \bold{\\1}, \bold{\\2}, ..., in \a after are replaced |
2837 | with \a{rx}.cap(1), cap(2), ... |
2838 | |
2839 | \snippet doc/src/snippets/qstring/main.cpp 43 |
2840 | |
2841 | \sa indexOf(), lastIndexOf(), remove(), QRegExp::cap() |
2842 | */ |
2843 | QString& QString::replace(const QRegExp &rx, const QString &after) |
2844 | { |
2845 | QRegExp rx2(rx); |
2846 | |
2847 | if (isEmpty() && rx2.indexIn(*this) == -1) |
2848 | return *this; |
2849 | |
2850 | realloc(); |
2851 | |
2852 | int index = 0; |
2853 | int numCaptures = rx2.captureCount(); |
2854 | int al = after.length(); |
2855 | QRegExp::CaretMode caretMode = QRegExp::CaretAtZero; |
2856 | |
2857 | if (numCaptures > 0) { |
2858 | const QChar *uc = after.unicode(); |
2859 | int numBackRefs = 0; |
2860 | |
2861 | for (int i = 0; i < al - 1; i++) { |
2862 | if (uc[i] == QLatin1Char('\\')) { |
2863 | int no = uc[i + 1].digitValue(); |
2864 | if (no > 0 && no <= numCaptures) |
2865 | numBackRefs++; |
2866 | } |
2867 | } |
2868 | |
2869 | /* |
2870 | This is the harder case where we have back-references. |
2871 | */ |
2872 | if (numBackRefs > 0) { |
2873 | QVarLengthArray<QStringCapture, 16> captures(numBackRefs); |
2874 | int j = 0; |
2875 | |
2876 | for (int i = 0; i < al - 1; i++) { |
2877 | if (uc[i] == QLatin1Char('\\')) { |
2878 | int no = uc[i + 1].digitValue(); |
2879 | if (no > 0 && no <= numCaptures) { |
2880 | QStringCapture capture; |
2881 | capture.pos = i; |
2882 | capture.len = 2; |
2883 | |
2884 | if (i < al - 2) { |
2885 | int secondDigit = uc[i + 2].digitValue(); |
2886 | if (secondDigit != -1 && ((no * 10) + secondDigit) <= numCaptures) { |
2887 | no = (no * 10) + secondDigit; |
2888 | ++capture.len; |
2889 | } |
2890 | } |
2891 | |
2892 | capture.no = no; |
2893 | captures[j++] = capture; |
2894 | } |
2895 | } |
2896 | } |
2897 | |
2898 | while (index <= length()) { |
2899 | index = rx2.indexIn(*this, index, caretMode); |
2900 | if (index == -1) |
2901 | break; |
2902 | |
2903 | QString after2(after); |
2904 | for (j = numBackRefs - 1; j >= 0; j--) { |
2905 | const QStringCapture &capture = captures[j]; |
2906 | after2.replace(capture.pos, capture.len, rx2.cap(capture.no)); |
2907 | } |
2908 | |
2909 | replace(index, rx2.matchedLength(), after2); |
2910 | index += after2.length(); |
2911 | |
2912 | // avoid infinite loop on 0-length matches (e.g., QRegExp("[a-z]*")) |
2913 | if (rx2.matchedLength() == 0) |
2914 | ++index; |
2915 | |
2916 | caretMode = QRegExp::CaretWontMatch; |
2917 | } |
2918 | return *this; |
2919 | } |
2920 | } |
2921 | |
2922 | /* |
2923 | This is the simple and optimized case where we don't have |
2924 | back-references. |
2925 | */ |
2926 | while (index != -1) { |
2927 | struct { |
2928 | int pos; |
2929 | int length; |
2930 | } replacements[2048]; |
2931 | |
2932 | int pos = 0; |
2933 | int adjust = 0; |
2934 | while (pos < 2047) { |
2935 | index = rx2.indexIn(*this, index, caretMode); |
2936 | if (index == -1) |
2937 | break; |
2938 | int ml = rx2.matchedLength(); |
2939 | replacements[pos].pos = index; |
2940 | replacements[pos++].length = ml; |
2941 | index += ml; |
2942 | adjust += al - ml; |
2943 | // avoid infinite loop |
2944 | if (!ml) |
2945 | index++; |
2946 | } |
2947 | if (!pos) |
2948 | break; |
2949 | replacements[pos].pos = d->size; |
2950 | int newlen = d->size + adjust; |
2951 | |
2952 | // to continue searching at the right position after we did |
2953 | // the first round of replacements |
2954 | if (index != -1) |
2955 | index += adjust; |
2956 | QString newstring; |
2957 | newstring.reserve(newlen + 1); |
2958 | QChar *newuc = newstring.data(); |
2959 | QChar *uc = newuc; |
2960 | int copystart = 0; |
2961 | int i = 0; |
2962 | while (i < pos) { |
2963 | int copyend = replacements[i].pos; |
2964 | int size = copyend - copystart; |
2965 | memcpy(uc, d->data + copystart, size * sizeof(QChar)); |
2966 | uc += size; |
2967 | memcpy(uc, after.d->data, al * sizeof(QChar)); |
2968 | uc += al; |
2969 | copystart = copyend + replacements[i].length; |
2970 | i++; |
2971 | } |
2972 | memcpy(uc, d->data + copystart, (d->size - copystart) * sizeof(QChar)); |
2973 | newstring.resize(newlen); |
2974 | *this = newstring; |
2975 | caretMode = QRegExp::CaretWontMatch; |
2976 | } |
2977 | return *this; |
2978 | } |
2979 | #endif |
2980 | |
2981 | /*! |
2982 | Returns the number of (potentially overlapping) occurrences of |
2983 | the string \a str in this string. |
2984 | |
2985 | If \a cs is Qt::CaseSensitive (default), the search is |
2986 | case sensitive; otherwise the search is case insensitive. |
2987 | |
2988 | \sa contains(), indexOf() |
2989 | */ |
2990 | |
2991 | int QString::count(const QString &str, Qt::CaseSensitivity cs) const |
2992 | { |
2993 | return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs); |
2994 | } |
2995 | |
2996 | /*! |
2997 | \overload count() |
2998 | |
2999 | Returns the number of occurrences of character \a ch in the string. |
3000 | */ |
3001 | |
3002 | int QString::count(QChar ch, Qt::CaseSensitivity cs) const |
3003 | { |
3004 | return qt_string_count(unicode(), size(), ch, cs); |
3005 | } |
3006 | |
3007 | /*! |
3008 | \since 4.8 |
3009 | \overload count() |
3010 | Returns the number of (potentially overlapping) occurrences of the |
3011 | string reference \a str in this string. |
3012 | |
3013 | If \a cs is Qt::CaseSensitive (default), the search is |
3014 | case sensitive; otherwise the search is case insensitive. |
3015 | |
3016 | \sa contains(), indexOf() |
3017 | */ |
3018 | int QString::count(const QStringRef &str, Qt::CaseSensitivity cs) const |
3019 | { |
3020 | return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs); |
3021 | } |
3022 | |
3023 | |
3024 | /*! \fn bool QString::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
3025 | |
3026 | Returns true if this string contains an occurrence of the string |
3027 | \a str; otherwise returns false. |
3028 | |
3029 | If \a cs is Qt::CaseSensitive (default), the search is |
3030 | case sensitive; otherwise the search is case insensitive. |
3031 | |
3032 | Example: |
3033 | \snippet doc/src/snippets/qstring/main.cpp 17 |
3034 | |
3035 | \sa indexOf(), count() |
3036 | */ |
3037 | |
3038 | /*! \fn bool QString::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
3039 | |
3040 | \overload contains() |
3041 | |
3042 | Returns true if this string contains an occurrence of the |
3043 | character \a ch; otherwise returns false. |
3044 | */ |
3045 | |
3046 | /*! \fn bool QString::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
3047 | \since 4.8 |
3048 | |
3049 | Returns true if this string contains an occurrence of the string |
3050 | reference \a str; otherwise returns false. |
3051 | |
3052 | If \a cs is Qt::CaseSensitive (default), the search is |
3053 | case sensitive; otherwise the search is case insensitive. |
3054 | |
3055 | \sa indexOf(), count() |
3056 | */ |
3057 | |
3058 | /*! \fn bool QString::contains(const QRegExp &rx) const |
3059 | |
3060 | \overload contains() |
3061 | |
3062 | Returns true if the regular expression \a rx matches somewhere in |
3063 | this string; otherwise returns false. |
3064 | */ |
3065 | |
3066 | /*! \fn bool QString::contains(QRegExp &rx) const |
3067 | \overload contains() |
3068 | \since 4.5 |
3069 | |
3070 | Returns true if the regular expression \a rx matches somewhere in |
3071 | this string; otherwise returns false. |
3072 | |
3073 | If there is a match, the \a rx regular expression will contain the |
3074 | matched captures (see QRegExp::matchedLength, QRegExp::cap). |
3075 | */ |
3076 | |
3077 | #ifndef QT_NO_REGEXP |
3078 | /*! |
3079 | \overload indexOf() |
3080 | |
3081 | Returns the index position of the first match of the regular |
3082 | expression \a rx in the string, searching forward from index |
3083 | position \a from. Returns -1 if \a rx didn't match anywhere. |
3084 | |
3085 | Example: |
3086 | |
3087 | \snippet doc/src/snippets/qstring/main.cpp 25 |
3088 | */ |
3089 | int QString::indexOf(const QRegExp& rx, int from) const |
3090 | { |
3091 | QRegExp rx2(rx); |
3092 | return rx2.indexIn(*this, from); |
3093 | } |
3094 | |
3095 | /*! |
3096 | \overload indexOf() |
3097 | \since 4.5 |
3098 | |
3099 | Returns the index position of the first match of the regular |
3100 | expression \a rx in the string, searching forward from index |
3101 | position \a from. Returns -1 if \a rx didn't match anywhere. |
3102 | |
3103 | If there is a match, the \a rx regular expression will contain the |
3104 | matched captures (see QRegExp::matchedLength, QRegExp::cap). |
3105 | |
3106 | Example: |
3107 | |
3108 | \snippet doc/src/snippets/qstring/main.cpp 25 |
3109 | */ |
3110 | int QString::indexOf(QRegExp& rx, int from) const |
3111 | { |
3112 | return rx.indexIn(*this, from); |
3113 | } |
3114 | |
3115 | /*! |
3116 | \overload lastIndexOf() |
3117 | |
3118 | Returns the index position of the last match of the regular |
3119 | expression \a rx in the string, searching backward from index |
3120 | position \a from. Returns -1 if \a rx didn't match anywhere. |
3121 | |
3122 | Example: |
3123 | |
3124 | \snippet doc/src/snippets/qstring/main.cpp 30 |
3125 | */ |
3126 | int QString::lastIndexOf(const QRegExp& rx, int from) const |
3127 | { |
3128 | QRegExp rx2(rx); |
3129 | return rx2.lastIndexIn(*this, from); |
3130 | } |
3131 | |
3132 | /*! |
3133 | \overload lastIndexOf() |
3134 | \since 4.5 |
3135 | |
3136 | Returns the index position of the last match of the regular |
3137 | expression \a rx in the string, searching backward from index |
3138 | position \a from. Returns -1 if \a rx didn't match anywhere. |
3139 | |
3140 | If there is a match, the \a rx regular expression will contain the |
3141 | matched captures (see QRegExp::matchedLength, QRegExp::cap). |
3142 | |
3143 | Example: |
3144 | |
3145 | \snippet doc/src/snippets/qstring/main.cpp 30 |
3146 | */ |
3147 | int QString::lastIndexOf(QRegExp& rx, int from) const |
3148 | { |
3149 | return rx.lastIndexIn(*this, from); |
3150 | } |
3151 | |
3152 | /*! |
3153 | \overload count() |
3154 | |
3155 | Returns the number of times the regular expression \a rx matches |
3156 | in the string. |
3157 | |
3158 | This function counts overlapping matches, so in the example |
3159 | below, there are four instances of "ana" or "ama": |
3160 | |
3161 | \snippet doc/src/snippets/qstring/main.cpp 18 |
3162 | |
3163 | */ |
3164 | int QString::count(const QRegExp& rx) const |
3165 | { |
3166 | QRegExp rx2(rx); |
3167 | int count = 0; |
3168 | int index = -1; |
3169 | int len = length(); |
3170 | while (index < len - 1) { // count overlapping matches |
3171 | index = rx2.indexIn(*this, index + 1); |
3172 | if (index == -1) |
3173 | break; |
3174 | count++; |
3175 | } |
3176 | return count; |
3177 | } |
3178 | #endif // QT_NO_REGEXP |
3179 | |
3180 | /*! \fn int QString::count() const |
3181 | |
3182 | \overload count() |
3183 | |
3184 | Same as size(). |
3185 | */ |
3186 | |
3187 | |
3188 | /*! |
3189 | \enum QString::SectionFlag |
3190 | |
3191 | This enum specifies flags that can be used to affect various |
3192 | aspects of the section() function's behavior with respect to |
3193 | separators and empty fields. |
3194 | |
3195 | \value SectionDefault Empty fields are counted, leading and |
3196 | trailing separators are not included, and the separator is |
3197 | compared case sensitively. |
3198 | |
3199 | \value SectionSkipEmpty Treat empty fields as if they don't exist, |
3200 | i.e. they are not considered as far as \e start and \e end are |
3201 | concerned. |
3202 | |
3203 | \value SectionIncludeLeadingSep Include the leading separator (if |
3204 | any) in the result string. |
3205 | |
3206 | \value SectionIncludeTrailingSep Include the trailing separator |
3207 | (if any) in the result string. |
3208 | |
3209 | \value SectionCaseInsensitiveSeps Compare the separator |
3210 | case-insensitively. |
3211 | |
3212 | \sa section() |
3213 | */ |
3214 | |
3215 | /*! |
3216 | \fn QString QString::section(QChar sep, int start, int end = -1, SectionFlags flags) const |
3217 | |
3218 | This function returns a section of the string. |
3219 | |
3220 | This string is treated as a sequence of fields separated by the |
3221 | character, \a sep. The returned string consists of the fields from |
3222 | position \a start to position \a end inclusive. If \a end is not |
3223 | specified, all fields from position \a start to the end of the |
3224 | string are included. Fields are numbered 0, 1, 2, etc., counting |
3225 | from the left, and -1, -2, etc., counting from right to left. |
3226 | |
3227 | The \a flags argument can be used to affect some aspects of the |
3228 | function's behavior, e.g. whether to be case sensitive, whether |
3229 | to skip empty fields and how to deal with leading and trailing |
3230 | separators; see \l{SectionFlags}. |
3231 | |
3232 | \snippet doc/src/snippets/qstring/main.cpp 52 |
3233 | |
3234 | If \a start or \a end is negative, we count fields from the right |
3235 | of the string, the right-most field being -1, the one from |
3236 | right-most field being -2, and so on. |
3237 | |
3238 | \snippet doc/src/snippets/qstring/main.cpp 53 |
3239 | |
3240 | \sa split() |
3241 | */ |
3242 | |
3243 | /*! |
3244 | \overload section() |
3245 | |
3246 | \snippet doc/src/snippets/qstring/main.cpp 51 |
3247 | \snippet doc/src/snippets/qstring/main.cpp 54 |
3248 | |
3249 | \sa split() |
3250 | */ |
3251 | |
3252 | QString QString::section(const QString &sep, int start, int end, SectionFlags flags) const |
3253 | { |
3254 | QStringList sections = split(sep, KeepEmptyParts, |
3255 | (flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive : Qt::CaseSensitive); |
3256 | if (sections.isEmpty()) |
3257 | return QString(); |
3258 | if (!(flags & SectionSkipEmpty)) { |
3259 | if (start < 0) |
3260 | start += sections.count(); |
3261 | if (end < 0) |
3262 | end += sections.count(); |
3263 | } else { |
3264 | int skip = 0; |
3265 | for (int k=0; k<sections.size(); ++k) { |
3266 | if (sections.at(k).isEmpty()) |
3267 | skip++; |
3268 | } |
3269 | if (start < 0) |
3270 | start += sections.count() - skip; |
3271 | if (end < 0) |
3272 | end += sections.count() - skip; |
3273 | } |
3274 | int x = 0; |
3275 | QString ret; |
3276 | int first_i = start, last_i = end; |
3277 | for (int i = 0; x <= end && i < sections.size(); ++i) { |
3278 | QString section = sections.at(i); |
3279 | const bool empty = section.isEmpty(); |
3280 | if (x >= start) { |
3281 | if(x == start) |
3282 | first_i = i; |
3283 | if(x == end) |
3284 | last_i = i; |
3285 | if(x > start) |
3286 | ret += sep; |
3287 | ret += section; |
3288 | } |
3289 | if (!empty || !(flags & SectionSkipEmpty)) |
3290 | x++; |
3291 | } |
3292 | if((flags & SectionIncludeLeadingSep) && first_i) |
3293 | ret.prepend(sep); |
3294 | if((flags & SectionIncludeTrailingSep) && last_i < sections.size()-1) |
3295 | ret += sep; |
3296 | return ret; |
3297 | } |
3298 | |
3299 | #ifndef QT_NO_REGEXP |
3300 | class qt_section_chunk { |
3301 | public: |
3302 | qt_section_chunk(int l, QString s) { length = l; string = s; } |
3303 | int length; |
3304 | QString string; |
3305 | }; |
3306 | |
3307 | /*! |
3308 | \overload section() |
3309 | |
3310 | This string is treated as a sequence of fields separated by the |
3311 | regular expression, \a reg. |
3312 | |
3313 | \snippet doc/src/snippets/qstring/main.cpp 55 |
3314 | |
3315 | \warning Using this QRegExp version is much more expensive than |
3316 | the overloaded string and character versions. |
3317 | |
3318 | \sa split() simplified() |
3319 | */ |
3320 | QString QString::section(const QRegExp ®, int start, int end, SectionFlags flags) const |
3321 | { |
3322 | const QChar *uc = unicode(); |
3323 | if(!uc) |
3324 | return QString(); |
3325 | |
3326 | QRegExp sep(reg); |
3327 | sep.setCaseSensitivity((flags & SectionCaseInsensitiveSeps) ? Qt::CaseInsensitive |
3328 | : Qt::CaseSensitive); |
3329 | |
3330 | QList<qt_section_chunk> sections; |
3331 | int n = length(), m = 0, last_m = 0, last_len = 0; |
3332 | while ((m = sep.indexIn(*this, m)) != -1) { |
3333 | sections.append(qt_section_chunk(last_len, QString(uc + last_m, m - last_m))); |
3334 | last_m = m; |
3335 | last_len = sep.matchedLength(); |
3336 | m += qMax(sep.matchedLength(), 1); |
3337 | } |
3338 | sections.append(qt_section_chunk(last_len, QString(uc + last_m, n - last_m))); |
3339 | |
3340 | if(start < 0) |
3341 | start += sections.count(); |
3342 | if(end < 0) |
3343 | end += sections.count(); |
3344 | |
3345 | QString ret; |
3346 | int x = 0; |
3347 | int first_i = start, last_i = end; |
3348 | for (int i = 0; x <= end && i < sections.size(); ++i) { |
3349 | const qt_section_chunk §ion = sections.at(i); |
3350 | const bool empty = (section.length == section.string.length()); |
3351 | if (x >= start) { |
3352 | if(x == start) |
3353 | first_i = i; |
3354 | if(x == end) |
3355 | last_i = i; |
3356 | if(x != start) |
3357 | ret += section.string; |
3358 | else |
3359 | ret += section.string.mid(section.length); |
3360 | } |
3361 | if (!empty || !(flags & SectionSkipEmpty)) |
3362 | x++; |
3363 | } |
3364 | if((flags & SectionIncludeLeadingSep) && first_i < sections.size()) { |
3365 | const qt_section_chunk §ion = sections.at(first_i); |
3366 | ret.prepend(section.string.left(section.length)); |
3367 | } |
3368 | if((flags & SectionIncludeTrailingSep) && last_i+1 <= sections.size()-1) { |
3369 | const qt_section_chunk §ion = sections.at(last_i+1); |
3370 | ret += section.string.left(section.length); |
3371 | } |
3372 | return ret; |
3373 | } |
3374 | #endif |
3375 | |
3376 | /*! |
3377 | Returns a substring that contains the \a n leftmost characters |
3378 | of the string. |
3379 | |
3380 | The entire string is returned if \a n is greater than size() or |
3381 | less than zero. |
3382 | |
3383 | \snippet doc/src/snippets/qstring/main.cpp 31 |
3384 | |
3385 | \sa right(), mid(), startsWith() |
3386 | */ |
3387 | QString QString::left(int n) const |
3388 | { |
3389 | if (n >= d->size || n < 0) |
3390 | return *this; |
3391 | return QString((const QChar*) d->data, n); |
3392 | } |
3393 | |
3394 | /*! |
3395 | Returns a substring that contains the \a n rightmost characters |
3396 | of the string. |
3397 | |
3398 | The entire string is returned if \a n is greater than size() or |
3399 | less than zero. |
3400 | |
3401 | \snippet doc/src/snippets/qstring/main.cpp 48 |
3402 | |
3403 | \sa left(), mid(), endsWith() |
3404 | */ |
3405 | QString QString::right(int n) const |
3406 | { |
3407 | if (n >= d->size || n < 0) |
3408 | return *this; |
3409 | return QString((const QChar*) d->data + d->size - n, n); |
3410 | } |
3411 | |
3412 | /*! |
3413 | Returns a string that contains \a n characters of this string, |
3414 | starting at the specified \a position index. |
3415 | |
3416 | Returns a null string if the \a position index exceeds the |
3417 | length of the string. If there are less than \a n characters |
3418 | available in the string starting at the given \a position, or if |
3419 | \a n is -1 (default), the function returns all characters that |
3420 | are available from the specified \a position. |
3421 | |
3422 | Example: |
3423 | |
3424 | \snippet doc/src/snippets/qstring/main.cpp 34 |
3425 | |
3426 | \sa left(), right() |
3427 | */ |
3428 | |
3429 | QString QString::mid(int position, int n) const |
3430 | { |
3431 | if (d == &shared_null || position >= d->size) |
3432 | return QString(); |
3433 | if (n < 0) |
3434 | n = d->size - position; |
3435 | if (position < 0) { |
3436 | n += position; |
3437 | position = 0; |
3438 | } |
3439 | if (n + position > d->size) |
3440 | n = d->size - position; |
3441 | if (position == 0 && n == d->size) |
3442 | return *this; |
3443 | return QString((const QChar*) d->data + position, n); |
3444 | } |
3445 | |
3446 | /*! |
3447 | Returns true if the string starts with \a s; otherwise returns |
3448 | false. |
3449 | |
3450 | If \a cs is Qt::CaseSensitive (default), the search is |
3451 | case sensitive; otherwise the search is case insensitive. |
3452 | |
3453 | \snippet doc/src/snippets/qstring/main.cpp 65 |
3454 | |
3455 | \sa endsWith() |
3456 | */ |
3457 | bool QString::startsWith(const QString& s, Qt::CaseSensitivity cs) const |
3458 | { |
3459 | return qt_starts_with(isNull() ? 0 : unicode(), size(), |
3460 | s.isNull() ? 0 : s.unicode(), s.size(), cs); |
3461 | } |
3462 | |
3463 | /*! |
3464 | \overload startsWith() |
3465 | */ |
3466 | bool QString::startsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const |
3467 | { |
3468 | return qt_starts_with(isNull() ? 0 : unicode(), size(), s, cs); |
3469 | } |
3470 | |
3471 | /*! |
3472 | \overload startsWith() |
3473 | |
3474 | Returns true if the string starts with \a c; otherwise returns |
3475 | false. |
3476 | */ |
3477 | bool QString::startsWith(const QChar &c, Qt::CaseSensitivity cs) const |
3478 | { |
3479 | return d->size |
3480 | && (cs == Qt::CaseSensitive |
3481 | ? d->data[0] == c |
3482 | : foldCase(d->data[0]) == foldCase(c.unicode())); |
3483 | } |
3484 | |
3485 | /*! |
3486 | \since 4.8 |
3487 | \overload |
3488 | Returns true if the string starts with the string reference \a s; |
3489 | otherwise returns false. |
3490 | |
3491 | If \a cs is Qt::CaseSensitive (default), the search is case |
3492 | sensitive; otherwise the search is case insensitive. |
3493 | |
3494 | \sa endsWith() |
3495 | */ |
3496 | bool QString::startsWith(const QStringRef &s, Qt::CaseSensitivity cs) const |
3497 | { |
3498 | return qt_starts_with(isNull() ? 0 : unicode(), size(), |
3499 | s.isNull() ? 0 : s.unicode(), s.size(), cs); |
3500 | } |
3501 | |
3502 | /*! |
3503 | Returns true if the string ends with \a s; otherwise returns |
3504 | false. |
3505 | |
3506 | If \a cs is Qt::CaseSensitive (default), the search is case |
3507 | sensitive; otherwise the search is case insensitive. |
3508 | |
3509 | \snippet doc/src/snippets/qstring/main.cpp 20 |
3510 | |
3511 | \sa startsWith() |
3512 | */ |
3513 | bool QString::endsWith(const QString& s, Qt::CaseSensitivity cs) const |
3514 | { |
3515 | return qt_ends_with(isNull() ? 0 : unicode(), size(), |
3516 | s.isNull() ? 0 : s.unicode(), s.size(), cs); |
3517 | } |
3518 | |
3519 | /*! |
3520 | \since 4.8 |
3521 | \overload endsWith() |
3522 | Returns true if the string ends with the string reference \a s; |
3523 | otherwise returns false. |
3524 | |
3525 | If \a cs is Qt::CaseSensitive (default), the search is case |
3526 | sensitive; otherwise the search is case insensitive. |
3527 | |
3528 | \sa startsWith() |
3529 | */ |
3530 | bool QString::endsWith(const QStringRef &s, Qt::CaseSensitivity cs) const |
3531 | { |
3532 | return qt_ends_with(isNull() ? 0 : unicode(), size(), |
3533 | s.isNull() ? 0 : s.unicode(), s.size(), cs); |
3534 | } |
3535 | |
3536 | |
3537 | /*! |
3538 | \overload endsWith() |
3539 | */ |
3540 | bool QString::endsWith(const QLatin1String& s, Qt::CaseSensitivity cs) const |
3541 | { |
3542 | return qt_ends_with(isNull() ? 0 : unicode(), size(), s, cs); |
3543 | } |
3544 | |
3545 | /*! |
3546 | Returns true if the string ends with \a c; otherwise returns |
3547 | false. |
3548 | |
3549 | \overload endsWith() |
3550 | */ |
3551 | bool QString::endsWith(const QChar &c, Qt::CaseSensitivity cs) const |
3552 | { |
3553 | return d->size |
3554 | && (cs == Qt::CaseSensitive |
3555 | ? d->data[d->size - 1] == c |
3556 | : foldCase(d->data[d->size - 1]) == foldCase(c.unicode())); |
3557 | } |
3558 | |
3559 | /*! \fn const char *QString::ascii() const |
3560 | \nonreentrant |
3561 | |
3562 | Use toAscii() instead. |
3563 | */ |
3564 | |
3565 | /*! \fn const char *QString::latin1() const |
3566 | \nonreentrant |
3567 | |
3568 | Use toLatin1() instead. |
3569 | */ |
3570 | |
3571 | /*! \fn const char *QString::utf8() const |
3572 | \nonreentrant |
3573 | |
3574 | Use toUtf8() instead. |
3575 | */ |
3576 | |
3577 | /*! \fn const char *QString::local8Bit() const |
3578 | \nonreentrant |
3579 | |
3580 | Use toLocal8Bit() instead. |
3581 | */ |
3582 | |
3583 | #if defined(QT_ALWAYS_HAVE_SSE2) |
3584 | static inline __m128i mergeQuestionMarks(__m128i chunk) |
3585 | { |
3586 | const __m128i questionMark = _mm_set1_epi16('?'); |
3587 | |
3588 | # ifdef __SSE4_2__ |
3589 | // compare the unsigned shorts for the range 0x0100-0xFFFF |
3590 | // note on the use of _mm_cmpestrm: |
3591 | // The MSDN documentation online (http://technet.microsoft.com/en-us/library/bb514080.aspx) |
3592 | // says for range search the following: |
3593 | // For each character c in a, determine whether b0 <= c <= b1 or b2 <= c <= b3 |
3594 | // |
3595 | // However, all examples on the Internet, including from Intel |
3596 | // (see http://software.intel.com/en-us/articles/xml-parsing-accelerator-with-intel-streaming-simd-extensions-4-intel-sse4/) |
3597 | // put the range to be searched first |
3598 | // |
3599 | // Disassembly and instruction-level debugging with GCC and ICC show |
3600 | // that they are doing the right thing. Inverting the arguments in the |
3601 | // instruction does cause a bunch of test failures. |
3602 | |
3603 | const int mode = _SIDD_UWORD_OPS | _SIDD_CMP_RANGES | _SIDD_UNIT_MASK; |
3604 | const __m128i rangeMatch = _mm_cvtsi32_si128(0xffff0100); |
3605 | const __m128i offLimitMask = _mm_cmpestrm(rangeMatch, 2, chunk, 8, mode); |
3606 | |
3607 | // replace the non-Latin 1 characters in the chunk with question marks |
3608 | chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask); |
3609 | # else |
3610 | // SSE has no compare instruction for unsigned comparison. |
3611 | // The variables must be shiffted + 0x8000 to be compared |
3612 | const __m128i signedBitOffset = _mm_set1_epi16(0x8000); |
3613 | const __m128i thresholdMask = _mm_set1_epi16(0xff + 0x8000); |
3614 | |
3615 | const __m128i signedChunk = _mm_add_epi16(chunk, signedBitOffset); |
3616 | const __m128i offLimitMask = _mm_cmpgt_epi16(signedChunk, thresholdMask); |
3617 | |
3618 | # ifdef __SSE4_1__ |
3619 | // replace the non-Latin 1 characters in the chunk with question marks |
3620 | chunk = _mm_blendv_epi8(chunk, questionMark, offLimitMask); |
3621 | # else |
3622 | // offLimitQuestionMark contains '?' for each 16 bits that was off-limit |
3623 | // the 16 bits that were correct contains zeros |
3624 | const __m128i offLimitQuestionMark = _mm_and_si128(offLimitMask, questionMark); |
3625 | |
3626 | // correctBytes contains the bytes that were in limit |
3627 | // the 16 bits that were off limits contains zeros |
3628 | const __m128i correctBytes = _mm_andnot_si128(offLimitMask, chunk); |
3629 | |
3630 | // merge offLimitQuestionMark and correctBytes to have the result |
3631 | chunk = _mm_or_si128(correctBytes, offLimitQuestionMark); |
3632 | # endif |
3633 | # endif |
3634 | return chunk; |
3635 | } |
3636 | #endif |
3637 | |
3638 | static QByteArray toLatin1_helper(const QChar *data, int length) |
3639 | { |
3640 | QByteArray ba; |
3641 | if (length) { |
3642 | ba.resize(length); |
3643 | const ushort *src = reinterpret_cast<const ushort *>(data); |
3644 | uchar *dst = (uchar*) ba.data(); |
3645 | #if defined(QT_ALWAYS_HAVE_SSE2) |
3646 | if (length >= 16) { |
3647 | const int chunkCount = length >> 4; // divided by 16 |
3648 | |
3649 | for (int i = 0; i < chunkCount; ++i) { |
3650 | __m128i chunk1 = _mm_loadu_si128((__m128i*)src); // load |
3651 | chunk1 = mergeQuestionMarks(chunk1); |
3652 | src += 8; |
3653 | |
3654 | __m128i chunk2 = _mm_loadu_si128((__m128i*)src); // load |
3655 | chunk2 = mergeQuestionMarks(chunk2); |
3656 | src += 8; |
3657 | |
3658 | // pack the two vector to 16 x 8bits elements |
3659 | const __m128i result = _mm_packus_epi16(chunk1, chunk2); |
3660 | |
3661 | _mm_storeu_si128((__m128i*)dst, result); // store |
3662 | dst += 16; |
3663 | } |
3664 | length = length % 16; |
3665 | } |
3666 | #elif defined(QT_ALWAYS_HAVE_NEON) |
3667 | // Refer to the documentation of the SSE2 implementation |
3668 | // this use eactly the same method as for SSE except: |
3669 | // 1) neon has unsigned comparison |
3670 | // 2) packing is done to 64 bits (8 x 8bits component). |
3671 | if (length >= 16) { |
3672 | const int chunkCount = length >> 3; // divided by 8 |
3673 | const uint16x8_t questionMark = vdupq_n_u16('?'); // set |
3674 | const uint16x8_t thresholdMask = vdupq_n_u16(0xff); // set |
3675 | for (int i = 0; i < chunkCount; ++i) { |
3676 | uint16x8_t chunk = vld1q_u16((uint16_t *)src); // load |
3677 | src += 8; |
3678 | |
3679 | const uint16x8_t offLimitMask = vcgtq_u16(chunk, thresholdMask); // chunk > thresholdMask |
3680 | const uint16x8_t offLimitQuestionMark = vandq_u16(offLimitMask, questionMark); // offLimitMask & questionMark |
3681 | const uint16x8_t correctBytes = vbicq_u16(chunk, offLimitMask); // !offLimitMask & chunk |
3682 | chunk = vorrq_u16(correctBytes, offLimitQuestionMark); // correctBytes | offLimitQuestionMark |
3683 | const uint8x8_t result = vmovn_u16(chunk); // narrowing move->packing |
3684 | vst1_u8(dst, result); // store |
3685 | dst += 8; |
3686 | } |
3687 | length = length % 8; |
3688 | } |
3689 | #endif |
3690 | while (length--) { |
3691 | *dst++ = (*src>0xff) ? '?' : (uchar) *src; |
3692 | ++src; |
3693 | } |
3694 | } |
3695 | return ba; |
3696 | } |
3697 | |
3698 | /*! |
3699 | Returns a Latin-1 representation of the string as a QByteArray. |
3700 | |
3701 | The returned byte array is undefined if the string contains non-Latin1 |
3702 | characters. Those characters may be suppressed or replaced with a |
3703 | question mark. |
3704 | |
3705 | \sa fromLatin1(), toAscii(), toUtf8(), toLocal8Bit(), QTextCodec |
3706 | */ |
3707 | QByteArray QString::toLatin1() const |
3708 | { |
3709 | return toLatin1_helper(unicode(), length()); |
3710 | } |
3711 | |
3712 | // ### Qt 5: Change the return type of at least toAscii(), |
3713 | // toLatin1() and unicode() such that the use of Q_COMPILER_MANGLES_RETURN_TYPE |
3714 | // isn't necessary in the header. See task 177402. |
3715 | |
3716 | /*! |
3717 | Returns an 8-bit representation of the string as a QByteArray. |
3718 | |
3719 | If a codec has been set using QTextCodec::setCodecForCStrings(), |
3720 | it is used to convert Unicode to 8-bit char; otherwise this |
3721 | function does the same as toLatin1(). |
3722 | |
3723 | Note that, despite the name, this function does not necessarily return an US-ASCII |
3724 | (ANSI X3.4-1986) string and its result may not be US-ASCII compatible. |
3725 | |
3726 | \sa fromAscii(), toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec |
3727 | */ |
3728 | QByteArray QString::toAscii() const |
3729 | { |
3730 | #ifndef QT_NO_TEXTCODEC |
3731 | if (codecForCStrings) |
3732 | return codecForCStrings->fromUnicode(*this); |
3733 | #endif // QT_NO_TEXTCODEC |
3734 | return toLatin1(); |
3735 | } |
3736 | |
3737 | #if !defined(Q_WS_MAC) && defined(Q_OS_UNIX) |
3738 | static QByteArray toLocal8Bit_helper(const QChar *data, int length) |
3739 | { |
3740 | #ifndef QT_NO_TEXTCODEC |
3741 | if (QTextCodec::codecForLocale()) |
3742 | return QTextCodec::codecForLocale()->fromUnicode(data, length); |
3743 | #endif // QT_NO_TEXTCODEC |
3744 | return toLatin1_helper(data, length); |
3745 | } |
3746 | #endif |
3747 | |
3748 | /*! |
3749 | Returns the local 8-bit representation of the string as a |
3750 | QByteArray. The returned byte array is undefined if the string |
3751 | contains characters not supported by the local 8-bit encoding. |
3752 | |
3753 | QTextCodec::codecForLocale() is used to perform the conversion from |
3754 | Unicode. If the locale encoding could not be determined, this function |
3755 | does the same as toLatin1(). |
3756 | |
3757 | If this string contains any characters that cannot be encoded in the |
3758 | locale, the returned byte array is undefined. Those characters may be |
3759 | suppressed or replaced by another. |
3760 | |
3761 | \sa fromLocal8Bit(), toAscii(), toLatin1(), toUtf8(), QTextCodec |
3762 | */ |
3763 | QByteArray QString::toLocal8Bit() const |
3764 | { |
3765 | #ifndef QT_NO_TEXTCODEC |
3766 | if (QTextCodec::codecForLocale()) |
3767 | return QTextCodec::codecForLocale()->fromUnicode(*this); |
3768 | #endif // QT_NO_TEXTCODEC |
3769 | return toLatin1(); |
3770 | } |
3771 | |
3772 | /*! |
3773 | Returns a UTF-8 representation of the string as a QByteArray. |
3774 | |
3775 | UTF-8 is a Unicode codec and can represent all characters in a Unicode |
3776 | string like QString. |
3777 | |
3778 | However, in the Unicode range, there are certain codepoints that are not |
3779 | considered characters. The Unicode standard reserves the last two |
3780 | codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, |
3781 | U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF, |
3782 | inclusive, as non-characters. If any of those appear in the string, they |
3783 | may be discarded and will not appear in the UTF-8 representation, or they |
3784 | may be replaced by one or more replacement characters. |
3785 | |
3786 | \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec |
3787 | */ |
3788 | QByteArray QString::toUtf8() const |
3789 | { |
3790 | if (isNull()) |
3791 | return QByteArray(); |
3792 | |
3793 | return QUtf8::convertFromUnicode(constData(), length(), 0); |
3794 | } |
3795 | |
3796 | /*! |
3797 | \since 4.2 |
3798 | |
3799 | Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>. |
3800 | |
3801 | UCS-4 is a Unicode codec and is lossless. All characters from this string |
3802 | can be encoded in UCS-4. The vector is not null terminated. |
3803 | |
3804 | \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray() |
3805 | */ |
3806 | QVector<uint> QString::toUcs4() const |
3807 | { |
3808 | QVector<uint> v(length()); |
3809 | uint *a = v.data(); |
3810 | int len = toUcs4_helper<uint>(utf16(), length(), a); |
3811 | v.resize(len); |
3812 | return v; |
3813 | } |
3814 | |
3815 | QString::Data *QString::fromLatin1_helper(const char *str, int size) |
3816 | { |
3817 | Data *d; |
3818 | if (!str) { |
3819 | d = &shared_null; |
3820 | d->ref.ref(); |
3821 | } else if (size == 0 || (!*str && size < 0)) { |
3822 | d = &shared_empty; |
3823 | d->ref.ref(); |
3824 | } else { |
3825 | if (size < 0) |
3826 | size = qstrlen(str); |
3827 | d = static_cast<Data *>(qMalloc(sizeof(Data) + size * sizeof(QChar))); |
3828 | Q_CHECK_PTR(d); |
3829 | d->ref = 1; |
3830 | d->alloc = d->size = size; |
3831 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
3832 | d->data = d->array; |
3833 | d->array[size] = '\0'; |
3834 | ushort *dst = d->data; |
3835 | /* SIMD: |
3836 | * Unpacking with SSE has been shown to improve performance on recent CPUs |
3837 | * The same method gives no improvement with NEON. |
3838 | */ |
3839 | #if defined(QT_ALWAYS_HAVE_SSE2) |
3840 | if (size >= 16) { |
3841 | int chunkCount = size >> 4; // divided by 16 |
3842 | const __m128i nullMask = _mm_set1_epi32(0); |
3843 | for (int i = 0; i < chunkCount; ++i) { |
3844 | const __m128i chunk = _mm_loadu_si128((__m128i*)str); // load |
3845 | str += 16; |
3846 | |
3847 | // unpack the first 8 bytes, padding with zeros |
3848 | const __m128i firstHalf = _mm_unpacklo_epi8(chunk, nullMask); |
3849 | _mm_storeu_si128((__m128i*)dst, firstHalf); // store |
3850 | dst += 8; |
3851 | |
3852 | // unpack the last 8 bytes, padding with zeros |
3853 | const __m128i secondHalf = _mm_unpackhi_epi8 (chunk, nullMask); |
3854 | _mm_storeu_si128((__m128i*)dst, secondHalf); // store |
3855 | dst += 8; |
3856 | } |
3857 | size = size % 16; |
3858 | } |
3859 | #endif |
3860 | while (size--) |
3861 | *dst++ = (uchar)*str++; |
3862 | } |
3863 | return d; |
3864 | } |
3865 | |
3866 | QString::Data *QString::fromAscii_helper(const char *str, int size) |
3867 | { |
3868 | #ifndef QT_NO_TEXTCODEC |
3869 | if (codecForCStrings) { |
3870 | Data *d; |
3871 | if (!str) { |
3872 | d = &shared_null; |
3873 | d->ref.ref(); |
3874 | } else if (size == 0 || (!*str && size < 0)) { |
3875 | d = &shared_empty; |
3876 | d->ref.ref(); |
3877 | } else { |
3878 | if (size < 0) |
3879 | size = qstrlen(str); |
3880 | QString s = codecForCStrings->toUnicode(str, size); |
3881 | d = s.d; |
3882 | d->ref.ref(); |
3883 | } |
3884 | return d; |
3885 | } |
3886 | #endif |
3887 | return fromLatin1_helper(str, size); |
3888 | } |
3889 | |
3890 | /*! |
3891 | Returns a QString initialized with the first \a size characters |
3892 | of the Latin-1 string \a str. |
3893 | |
3894 | If \a size is -1 (default), it is taken to be qstrlen(\a |
3895 | str). |
3896 | |
3897 | \sa toLatin1(), fromAscii(), fromUtf8(), fromLocal8Bit() |
3898 | */ |
3899 | QString QString::fromLatin1(const char *str, int size) |
3900 | { |
3901 | return QString(fromLatin1_helper(str, size), 0); |
3902 | } |
3903 | |
3904 | |
3905 | #ifdef QT3_SUPPORT |
3906 | |
3907 | /*! |
3908 | \internal |
3909 | */ |
3910 | const char *QString::ascii_helper() const |
3911 | { |
3912 | QMutexLocker locker(asciiCacheMutex()); |
3913 | if (!asciiCache) |
3914 | asciiCache = new QHash<void *, QByteArray>(); |
3915 | |
3916 | d->asciiCache = true; |
3917 | QByteArray ascii = toAscii(); |
3918 | QByteArray old = asciiCache->value(d); |
3919 | if (old == ascii) |
3920 | return old.constData(); |
3921 | asciiCache->insert(d, ascii); |
3922 | return ascii.constData(); |
3923 | } |
3924 | |
3925 | /*! |
3926 | \internal |
3927 | */ |
3928 | const char *QString::latin1_helper() const |
3929 | { |
3930 | QMutexLocker locker(asciiCacheMutex()); |
3931 | if (!asciiCache) |
3932 | asciiCache = new QHash<void *, QByteArray>(); |
3933 | |
3934 | d->asciiCache = true; |
3935 | QByteArray ascii = toLatin1(); |
3936 | QByteArray old = asciiCache->value(d); |
3937 | if (old == ascii) |
3938 | return old.constData(); |
3939 | asciiCache->insert(d, ascii); |
3940 | return ascii.constData(); |
3941 | } |
3942 | |
3943 | #endif |
3944 | |
3945 | /*! |
3946 | Returns a QString initialized with the first \a size characters |
3947 | of the 8-bit string \a str. |
3948 | |
3949 | If \a size is -1 (default), it is taken to be qstrlen(\a |
3950 | str). |
3951 | |
3952 | QTextCodec::codecForLocale() is used to perform the conversion. |
3953 | |
3954 | \sa toLocal8Bit(), fromAscii(), fromLatin1(), fromUtf8() |
3955 | */ |
3956 | QString QString::fromLocal8Bit(const char *str, int size) |
3957 | { |
3958 | if (!str) |
3959 | return QString(); |
3960 | if (size == 0 || (!*str && size < 0)) |
3961 | return QLatin1String("" ); |
3962 | #if !defined(QT_NO_TEXTCODEC) |
3963 | if (size < 0) |
3964 | size = qstrlen(str); |
3965 | QTextCodec *codec = QTextCodec::codecForLocale(); |
3966 | if (codec) |
3967 | return codec->toUnicode(str, size); |
3968 | #endif // !QT_NO_TEXTCODEC |
3969 | return fromLatin1(str, size); |
3970 | } |
3971 | |
3972 | /*! |
3973 | Returns a QString initialized with the first \a size characters |
3974 | from the string \a str. |
3975 | |
3976 | If \a size is -1 (default), it is taken to be qstrlen(\a |
3977 | str). |
3978 | |
3979 | Note that, despite the name, this function actually uses the codec |
3980 | defined by QTextCodec::setCodecForCStrings() to convert \a str to |
3981 | Unicode. Depending on the codec, it may not accept valid US-ASCII (ANSI |
3982 | X3.4-1986) input. If no codec has been set, this function does the same |
3983 | as fromLatin1(). |
3984 | |
3985 | \sa toAscii(), fromLatin1(), fromUtf8(), fromLocal8Bit() |
3986 | */ |
3987 | QString QString::fromAscii(const char *str, int size) |
3988 | { |
3989 | return QString(fromAscii_helper(str, size), 0); |
3990 | } |
3991 | |
3992 | /*! |
3993 | Returns a QString initialized with the first \a size bytes |
3994 | of the UTF-8 string \a str. |
3995 | |
3996 | If \a size is -1 (default), it is taken to be qstrlen(\a |
3997 | str). |
3998 | |
3999 | UTF-8 is a Unicode codec and can represent all characters in a Unicode |
4000 | string like QString. However, invalid sequences are possible with UTF-8 |
4001 | and, if any such are found, they will be replaced with one or more |
4002 | "replacement characters", or suppressed. These include non-Unicode |
4003 | sequences, non-characters, overlong sequences or surrogate codepoints |
4004 | encoded into UTF-8. |
4005 | |
4006 | Non-characters are codepoints that the Unicode standard reserves and must |
4007 | not be used in text interchange. They are the last two codepoints in each |
4008 | Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well |
4009 | as 16 codepoints in the range U+FDD0..U+FDDF, inclusive. |
4010 | |
4011 | \sa toUtf8(), fromAscii(), fromLatin1(), fromLocal8Bit() |
4012 | */ |
4013 | QString QString::fromUtf8(const char *str, int size) |
4014 | { |
4015 | if (!str) |
4016 | return QString(); |
4017 | if (size < 0) |
4018 | size = qstrlen(str); |
4019 | |
4020 | return QUtf8::convertToUnicode(str, size, 0); |
4021 | } |
4022 | |
4023 | /*! |
4024 | Returns a QString initialized with the first \a size characters |
4025 | of the Unicode string \a unicode (ISO-10646-UTF-16 encoded). |
4026 | |
4027 | If \a size is -1 (default), \a unicode must be terminated |
4028 | with a 0. |
4029 | |
4030 | This function checks for a Byte Order Mark (BOM). If it is missing, |
4031 | host byte order is assumed. |
4032 | |
4033 | This function is slow compared to the other Unicode conversions. |
4034 | Use QString(const QChar *, int) or QString(const QChar *) if possible. |
4035 | |
4036 | QString makes a deep copy of the Unicode data. |
4037 | |
4038 | \sa utf16(), setUtf16() |
4039 | */ |
4040 | QString QString::fromUtf16(const ushort *unicode, int size) |
4041 | { |
4042 | if (!unicode) |
4043 | return QString(); |
4044 | if (size < 0) { |
4045 | size = 0; |
4046 | while (unicode[size] != 0) |
4047 | ++size; |
4048 | } |
4049 | return QUtf16::convertToUnicode((const char *)unicode, size*2, 0); |
4050 | } |
4051 | |
4052 | |
4053 | /*! |
4054 | \since 4.2 |
4055 | |
4056 | Returns a QString initialized with the first \a size characters |
4057 | of the Unicode string \a unicode (ISO-10646-UCS-4 encoded). |
4058 | |
4059 | If \a size is -1 (default), \a unicode must be terminated |
4060 | with a 0. |
4061 | |
4062 | \sa toUcs4(), fromUtf16(), utf16(), setUtf16(), fromWCharArray() |
4063 | */ |
4064 | QString QString::fromUcs4(const uint *unicode, int size) |
4065 | { |
4066 | if (!unicode) |
4067 | return QString(); |
4068 | if (size < 0) { |
4069 | size = 0; |
4070 | while (unicode[size] != 0) |
4071 | ++size; |
4072 | } |
4073 | return QUtf32::convertToUnicode((const char *)unicode, size*4, 0); |
4074 | } |
4075 | |
4076 | /*! |
4077 | Resizes the string to \a size characters and copies \a unicode |
4078 | into the string. |
4079 | |
4080 | If \a unicode is 0, nothing is copied, but the string is still |
4081 | resized to \a size. |
4082 | |
4083 | \sa unicode(), setUtf16() |
4084 | */ |
4085 | QString& QString::setUnicode(const QChar *unicode, int size) |
4086 | { |
4087 | resize(size); |
4088 | if (unicode && size) |
4089 | memcpy(d->data, unicode, size * sizeof(QChar)); |
4090 | return *this; |
4091 | } |
4092 | |
4093 | /*! |
4094 | \fn QString &QString::setUtf16(const ushort *unicode, int size) |
4095 | |
4096 | Resizes the string to \a size characters and copies \a unicode |
4097 | into the string. |
4098 | |
4099 | If \a unicode is 0, nothing is copied, but the string is still |
4100 | resized to \a size. |
4101 | |
4102 | Note that unlike fromUtf16(), this function does not consider BOMs and |
4103 | possibly differing byte ordering. |
4104 | |
4105 | \sa utf16(), setUnicode() |
4106 | */ |
4107 | |
4108 | /*! |
4109 | Returns a string that has whitespace removed from the start |
4110 | and the end, and that has each sequence of internal whitespace |
4111 | replaced with a single space. |
4112 | |
4113 | Whitespace means any character for which QChar::isSpace() returns |
4114 | true. This includes the ASCII characters '\\t', '\\n', '\\v', |
4115 | '\\f', '\\r', and ' '. |
4116 | |
4117 | Example: |
4118 | |
4119 | \snippet doc/src/snippets/qstring/main.cpp 57 |
4120 | |
4121 | \sa trimmed() |
4122 | */ |
4123 | QString QString::simplified() const |
4124 | { |
4125 | if (d->size == 0) |
4126 | return *this; |
4127 | |
4128 | const QChar * const start = reinterpret_cast<QChar *>(d->data); |
4129 | const QChar *from = start; |
4130 | const QChar *fromEnd = start + d->size; |
4131 | forever { |
4132 | QChar ch = *from; |
4133 | if (!ch.isSpace()) |
4134 | break; |
4135 | if (++from == fromEnd) { |
4136 | // All-whitespace string |
4137 | shared_empty.ref.ref(); |
4138 | return QString(&shared_empty, 0); |
4139 | } |
4140 | } |
4141 | // This loop needs no underflow check, as we already determined that |
4142 | // the string contains non-whitespace. If the string has exactly one |
4143 | // non-whitespace, it will be checked twice - we can live with that. |
4144 | while (fromEnd[-1].isSpace()) |
4145 | fromEnd--; |
4146 | // The rest of the function depends on the fact that we already know |
4147 | // that the last character in the source is no whitespace. |
4148 | const QChar *copyFrom = from; |
4149 | int copyCount; |
4150 | forever { |
4151 | if (++from == fromEnd) { |
4152 | // Only leading and/or trailing whitespace, if any at all |
4153 | return mid(copyFrom - start, from - copyFrom); |
4154 | } |
4155 | QChar ch = *from; |
4156 | if (!ch.isSpace()) |
4157 | continue; |
4158 | if (ch != QLatin1Char(' ')) { |
4159 | copyCount = from - copyFrom; |
4160 | break; |
4161 | } |
4162 | ch = *++from; |
4163 | if (ch.isSpace()) { |
4164 | copyCount = from - copyFrom - 1; |
4165 | break; |
4166 | } |
4167 | } |
4168 | // 'from' now points at the non-trailing whitespace which made the |
4169 | // string not simplified in the first place. 'copyCount' is the number |
4170 | // of already simplified characters - at least one, obviously - |
4171 | // without a trailing space. |
4172 | QString result((fromEnd - from) + copyCount, Qt::Uninitialized); |
4173 | QChar *to = reinterpret_cast<QChar *>(result.d->data); |
4174 | ::memcpy(to, copyFrom, copyCount * 2); |
4175 | to += copyCount; |
4176 | fromEnd--; |
4177 | QChar ch; |
4178 | forever { |
4179 | *to++ = QLatin1Char(' '); |
4180 | do { |
4181 | ch = *++from; |
4182 | } while (ch.isSpace()); |
4183 | if (from == fromEnd) |
4184 | break; |
4185 | do { |
4186 | *to++ = ch; |
4187 | ch = *++from; |
4188 | if (from == fromEnd) |
4189 | goto done; |
4190 | } while (!ch.isSpace()); |
4191 | } |
4192 | done: |
4193 | *to++ = ch; |
4194 | result.truncate(to - reinterpret_cast<QChar *>(result.d->data)); |
4195 | return result; |
4196 | } |
4197 | |
4198 | /*! |
4199 | Returns a string that has whitespace removed from the start and |
4200 | the end. |
4201 | |
4202 | Whitespace means any character for which QChar::isSpace() returns |
4203 | true. This includes the ASCII characters '\\t', '\\n', '\\v', |
4204 | '\\f', '\\r', and ' '. |
4205 | |
4206 | Example: |
4207 | |
4208 | \snippet doc/src/snippets/qstring/main.cpp 82 |
4209 | |
4210 | Unlike simplified(), trimmed() leaves internal whitespace alone. |
4211 | |
4212 | \sa simplified() |
4213 | */ |
4214 | QString QString::trimmed() const |
4215 | { |
4216 | if (d->size == 0) |
4217 | return *this; |
4218 | const QChar *s = (const QChar*)d->data; |
4219 | if (!s->isSpace() && !s[d->size-1].isSpace()) |
4220 | return *this; |
4221 | int start = 0; |
4222 | int end = d->size - 1; |
4223 | while (start<=end && s[start].isSpace()) // skip white space from start |
4224 | start++; |
4225 | if (start <= end) { // only white space |
4226 | while (end && s[end].isSpace()) // skip white space from end |
4227 | end--; |
4228 | } |
4229 | int l = end - start + 1; |
4230 | if (l <= 0) { |
4231 | shared_empty.ref.ref(); |
4232 | return QString(&shared_empty, 0); |
4233 | } |
4234 | return QString(s + start, l); |
4235 | } |
4236 | |
4237 | /*! \fn const QChar QString::at(int position) const |
4238 | |
4239 | Returns the character at the given index \a position in the |
4240 | string. |
4241 | |
4242 | The \a position must be a valid index position in the string |
4243 | (i.e., 0 <= \a position < size()). |
4244 | |
4245 | \sa operator[]() |
4246 | */ |
4247 | |
4248 | /*! |
4249 | \fn QCharRef QString::operator[](int position) |
4250 | |
4251 | Returns the character at the specified \a position in the string as a |
4252 | modifiable reference. |
4253 | |
4254 | Example: |
4255 | |
4256 | \snippet doc/src/snippets/qstring/main.cpp 85 |
4257 | |
4258 | The return value is of type QCharRef, a helper class for QString. |
4259 | When you get an object of type QCharRef, you can use it as if it |
4260 | were a QChar &. If you assign to it, the assignment will apply to |
4261 | the character in the QString from which you got the reference. |
4262 | |
4263 | \sa at() |
4264 | */ |
4265 | |
4266 | /*! |
4267 | \fn const QChar QString::operator[](int position) const |
4268 | |
4269 | \overload operator[]() |
4270 | */ |
4271 | |
4272 | /*! \fn QCharRef QString::operator[](uint position) |
4273 | |
4274 | \overload operator[]() |
4275 | |
4276 | Returns the character at the specified \a position in the string as a |
4277 | modifiable reference. Equivalent to \c at(position). |
4278 | */ |
4279 | |
4280 | /*! \fn const QChar QString::operator[](uint position) const |
4281 | |
4282 | \overload operator[]() |
4283 | */ |
4284 | |
4285 | /*! |
4286 | \fn void QString::truncate(int position) |
4287 | |
4288 | Truncates the string at the given \a position index. |
4289 | |
4290 | If the specified \a position index is beyond the end of the |
4291 | string, nothing happens. |
4292 | |
4293 | Example: |
4294 | |
4295 | \snippet doc/src/snippets/qstring/main.cpp 83 |
4296 | |
4297 | If \a position is negative, it is equivalent to passing zero. |
4298 | |
4299 | \sa chop(), resize(), left() |
4300 | */ |
4301 | |
4302 | void QString::truncate(int pos) |
4303 | { |
4304 | if (pos < d->size) |
4305 | resize(pos); |
4306 | } |
4307 | |
4308 | |
4309 | /*! |
4310 | Removes \a n characters from the end of the string. |
4311 | |
4312 | If \a n is greater than size(), the result is an empty string. |
4313 | |
4314 | Example: |
4315 | \snippet doc/src/snippets/qstring/main.cpp 15 |
4316 | |
4317 | If you want to remove characters from the \e beginning of the |
4318 | string, use remove() instead. |
4319 | |
4320 | \sa truncate(), resize(), remove() |
4321 | */ |
4322 | void QString::chop(int n) |
4323 | { |
4324 | if (n > 0) |
4325 | resize(d->size - n); |
4326 | } |
4327 | |
4328 | /*! |
4329 | Sets every character in the string to character \a ch. If \a size |
4330 | is different from -1 (default), the string is resized to \a |
4331 | size beforehand. |
4332 | |
4333 | Example: |
4334 | |
4335 | \snippet doc/src/snippets/qstring/main.cpp 21 |
4336 | |
4337 | \sa resize() |
4338 | */ |
4339 | |
4340 | QString& QString::fill(QChar ch, int size) |
4341 | { |
4342 | resize(size < 0 ? d->size : size); |
4343 | if (d->size) { |
4344 | QChar *i = (QChar*)d->data + d->size; |
4345 | QChar *b = (QChar*)d->data; |
4346 | while (i != b) |
4347 | *--i = ch; |
4348 | } |
4349 | return *this; |
4350 | } |
4351 | |
4352 | /*! |
4353 | \fn int QString::length() const |
4354 | |
4355 | Returns the number of characters in this string. Equivalent to |
4356 | size(). |
4357 | |
4358 | \sa resize() |
4359 | */ |
4360 | |
4361 | /*! |
4362 | \fn int QString::size() const |
4363 | |
4364 | Returns the number of characters in this string. |
4365 | |
4366 | The last character in the string is at position size() - 1. In |
4367 | addition, QString ensures that the character at position size() |
4368 | is always '\\0', so that you can use the return value of data() |
4369 | and constData() as arguments to functions that expect |
4370 | '\\0'-terminated strings. |
4371 | |
4372 | Example: |
4373 | |
4374 | \snippet doc/src/snippets/qstring/main.cpp 58 |
4375 | |
4376 | \sa isEmpty(), resize() |
4377 | */ |
4378 | |
4379 | /*! \fn bool QString::isNull() const |
4380 | |
4381 | Returns true if this string is null; otherwise returns false. |
4382 | |
4383 | Example: |
4384 | |
4385 | \snippet doc/src/snippets/qstring/main.cpp 28 |
4386 | |
4387 | Qt makes a distinction between null strings and empty strings for |
4388 | historical reasons. For most applications, what matters is |
4389 | whether or not a string contains any data, and this can be |
4390 | determined using the isEmpty() function. |
4391 | |
4392 | \sa isEmpty() |
4393 | */ |
4394 | |
4395 | /*! \fn bool QString::isEmpty() const |
4396 | |
4397 | Returns true if the string has no characters; otherwise returns |
4398 | false. |
4399 | |
4400 | Example: |
4401 | |
4402 | \snippet doc/src/snippets/qstring/main.cpp 27 |
4403 | |
4404 | \sa size() |
4405 | */ |
4406 | |
4407 | /*! \fn QString &QString::operator+=(const QString &other) |
4408 | |
4409 | Appends the string \a other onto the end of this string and |
4410 | returns a reference to this string. |
4411 | |
4412 | Example: |
4413 | |
4414 | \snippet doc/src/snippets/qstring/main.cpp 84 |
4415 | |
4416 | This operation is typically very fast (\l{constant time}), |
4417 | because QString preallocates extra space at the end of the string |
4418 | data so it can grow without reallocating the entire string each |
4419 | time. |
4420 | |
4421 | \sa append(), prepend() |
4422 | */ |
4423 | |
4424 | /*! \fn QString &QString::operator+=(const QLatin1String &str) |
4425 | |
4426 | \overload operator+=() |
4427 | |
4428 | Appends the Latin-1 string \a str to this string. |
4429 | */ |
4430 | |
4431 | /*! \fn QString &QString::operator+=(const QByteArray &ba) |
4432 | |
4433 | \overload operator+=() |
4434 | |
4435 | Appends the byte array \a ba to this string. The byte array is converted |
4436 | to Unicode using the fromAscii() function. If any NUL characters ('\0') |
4437 | are embedded in the \a ba byte array, they will be included in the |
4438 | transformation. |
4439 | |
4440 | You can disable this function by defining \c |
4441 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
4442 | can be useful if you want to ensure that all user-visible strings |
4443 | go through QObject::tr(), for example. |
4444 | */ |
4445 | |
4446 | /*! \fn QString &QString::operator+=(const char *str) |
4447 | |
4448 | \overload operator+=() |
4449 | |
4450 | Appends the string \a str to this string. The const char pointer |
4451 | is converted to Unicode using the fromAscii() function. |
4452 | |
4453 | You can disable this function by defining \c QT_NO_CAST_FROM_ASCII |
4454 | when you compile your applications. This can be useful if you want |
4455 | to ensure that all user-visible strings go through QObject::tr(), |
4456 | for example. |
4457 | */ |
4458 | |
4459 | /*! \fn QString &QString::operator+=(const QStringRef &str) |
4460 | |
4461 | \overload operator+=() |
4462 | |
4463 | Appends the string section referenced by \a str to this string. |
4464 | */ |
4465 | |
4466 | /*! \fn QString &QString::operator+=(char ch) |
4467 | |
4468 | \overload operator+=() |
4469 | |
4470 | Appends the character \a ch to this string. The character is |
4471 | converted to Unicode using the fromAscii() function. |
4472 | |
4473 | You can disable this function by defining \c QT_NO_CAST_FROM_ASCII |
4474 | when you compile your applications. This can be useful if you want |
4475 | to ensure that all user-visible strings go through QObject::tr(), |
4476 | for example. |
4477 | */ |
4478 | |
4479 | /*! \fn QString &QString::operator+=(QChar ch) |
4480 | |
4481 | \overload operator+=() |
4482 | |
4483 | Appends the character \a ch to the string. |
4484 | */ |
4485 | |
4486 | /*! \fn QString &QString::operator+=(QChar::SpecialCharacter c) |
4487 | |
4488 | \overload operator+=() |
4489 | |
4490 | \internal |
4491 | */ |
4492 | |
4493 | /*! |
4494 | \fn bool operator==(const char *s1, const QString &s2) |
4495 | |
4496 | \overload operator==() |
4497 | \relates QString |
4498 | |
4499 | Returns true if \a s1 is equal to \a s2; otherwise returns false. |
4500 | Note that no string is equal to \a s1 being 0. |
4501 | |
4502 | Equivalent to \c {s1 != 0 && compare(s1, s2) == 0}. |
4503 | |
4504 | \sa QString::compare() |
4505 | */ |
4506 | |
4507 | /*! |
4508 | \fn bool operator!=(const char *s1, const QString &s2) |
4509 | \relates QString |
4510 | |
4511 | Returns true if \a s1 is not equal to \a s2; otherwise returns |
4512 | false. |
4513 | |
4514 | For \a s1 != 0, this is equivalent to \c {compare(} \a s1, \a s2 |
4515 | \c {) != 0}. Note that no string is equal to \a s1 being 0. |
4516 | |
4517 | \sa QString::compare() |
4518 | */ |
4519 | |
4520 | /*! |
4521 | \fn bool operator<(const char *s1, const QString &s2) |
4522 | \relates QString |
4523 | |
4524 | Returns true if \a s1 is lexically less than \a s2; otherwise |
4525 | returns false. For \a s1 != 0, this is equivalent to \c |
4526 | {compare(s1, s2) < 0}. |
4527 | |
4528 | The comparison is based exclusively on the numeric Unicode values |
4529 | of the characters and is very fast, but is not what a human would |
4530 | expect. Consider sorting user-interface strings using the |
4531 | QString::localeAwareCompare() function. |
4532 | |
4533 | \sa QString::compare() |
4534 | */ |
4535 | |
4536 | /*! |
4537 | \fn bool operator<=(const char *s1, const QString &s2) |
4538 | \relates QString |
4539 | |
4540 | Returns true if \a s1 is lexically less than or equal to \a s2; |
4541 | otherwise returns false. For \a s1 != 0, this is equivalent to \c |
4542 | {compare(s1, s2) <= 0}. |
4543 | |
4544 | The comparison is based exclusively on the numeric Unicode values |
4545 | of the characters and is very fast, but is not what a human would |
4546 | expect. Consider sorting user-interface strings with |
4547 | QString::localeAwareCompare(). |
4548 | |
4549 | \sa QString::compare() |
4550 | */ |
4551 | |
4552 | /*! |
4553 | \fn bool operator>(const char *s1, const QString &s2) |
4554 | \relates QString |
4555 | |
4556 | Returns true if \a s1 is lexically greater than \a s2; otherwise |
4557 | returns false. Equivalent to \c {compare(s1, s2) > 0}. |
4558 | |
4559 | The comparison is based exclusively on the numeric Unicode values |
4560 | of the characters and is very fast, but is not what a human would |
4561 | expect. Consider sorting user-interface strings using the |
4562 | QString::localeAwareCompare() function. |
4563 | |
4564 | \sa QString::compare() |
4565 | */ |
4566 | |
4567 | /*! |
4568 | \fn bool operator>=(const char *s1, const QString &s2) |
4569 | \relates QString |
4570 | |
4571 | Returns true if \a s1 is lexically greater than or equal to \a s2; |
4572 | otherwise returns false. For \a s1 != 0, this is equivalent to \c |
4573 | {compare(s1, s2) >= 0}. |
4574 | |
4575 | The comparison is based exclusively on the numeric Unicode values |
4576 | of the characters and is very fast, but is not what a human would |
4577 | expect. Consider sorting user-interface strings using the |
4578 | QString::localeAwareCompare() function. |
4579 | */ |
4580 | |
4581 | /*! |
4582 | \fn const QString operator+(const QString &s1, const QString &s2) |
4583 | \relates QString |
4584 | |
4585 | Returns a string which is the result of concatenating \a s1 and \a |
4586 | s2. |
4587 | */ |
4588 | |
4589 | /*! |
4590 | \fn const QString operator+(const QString &s1, const char *s2) |
4591 | \relates QString |
4592 | |
4593 | Returns a string which is the result of concatenating \a s1 and \a |
4594 | s2 (\a s2 is converted to Unicode using the QString::fromAscii() |
4595 | function). |
4596 | |
4597 | \sa QString::fromAscii() |
4598 | */ |
4599 | |
4600 | /*! |
4601 | \fn const QString operator+(const char *s1, const QString &s2) |
4602 | \relates QString |
4603 | |
4604 | Returns a string which is the result of concatenating \a s1 and \a |
4605 | s2 (\a s1 is converted to Unicode using the QString::fromAscii() |
4606 | function). |
4607 | |
4608 | \sa QString::fromAscii() |
4609 | */ |
4610 | |
4611 | /*! |
4612 | \fn const QString operator+(const QString &s, char ch) |
4613 | \relates QString |
4614 | |
4615 | Returns a string which is the result of concatenating the string |
4616 | \a s and the character \a ch. |
4617 | */ |
4618 | |
4619 | /*! |
4620 | \fn const QString operator+(char ch, const QString &s) |
4621 | \relates QString |
4622 | |
4623 | Returns a string which is the result of concatenating the |
4624 | character \a ch and the string \a s. |
4625 | */ |
4626 | |
4627 | /*! |
4628 | \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs) |
4629 | \since 4.2 |
4630 | |
4631 | Compares \a s1 with \a s2 and returns an integer less than, equal |
4632 | to, or greater than zero if \a s1 is less than, equal to, or |
4633 | greater than \a s2. |
4634 | |
4635 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
4636 | otherwise the comparison is case insensitive. |
4637 | |
4638 | Case sensitive comparison is based exclusively on the numeric |
4639 | Unicode values of the characters and is very fast, but is not what |
4640 | a human would expect. Consider sorting user-visible strings with |
4641 | localeAwareCompare(). |
4642 | |
4643 | \snippet doc/src/snippets/qstring/main.cpp 16 |
4644 | |
4645 | \sa operator==(), operator<(), operator>() |
4646 | */ |
4647 | |
4648 | /*! |
4649 | \fn int QString::compare(const QString & s1, const QString & s2) |
4650 | |
4651 | \overload compare() |
4652 | |
4653 | Performs a case sensitive compare of \a s1 and \a s2. |
4654 | */ |
4655 | |
4656 | /*! |
4657 | \fn int QString::compare(const QString &s1, const QLatin1String &s2, Qt::CaseSensitivity cs) |
4658 | \since 4.2 |
4659 | \overload compare() |
4660 | |
4661 | Performs a comparison of \a s1 and \a s2, using the case |
4662 | sensitivity setting \a cs. |
4663 | */ |
4664 | |
4665 | /*! |
4666 | \fn int QString::compare(const QLatin1String &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
4667 | |
4668 | \since 4.2 |
4669 | \overload compare() |
4670 | |
4671 | Performs a comparison of \a s1 and \a s2, using the case |
4672 | sensitivity setting \a cs. |
4673 | */ |
4674 | |
4675 | /*! |
4676 | \overload compare() |
4677 | |
4678 | Lexically compares this string with the \a other string and |
4679 | returns an integer less than, equal to, or greater than zero if |
4680 | this string is less than, equal to, or greater than the other |
4681 | string. |
4682 | |
4683 | Equivalent to \c {compare(*this, other)}. |
4684 | */ |
4685 | int QString::compare(const QString &other) const |
4686 | { |
4687 | return ucstrcmp(constData(), length(), other.constData(), other.length()); |
4688 | } |
4689 | |
4690 | /*! |
4691 | \overload compare() |
4692 | \since 4.2 |
4693 | |
4694 | Same as compare(*this, \a other, \a cs). |
4695 | */ |
4696 | int QString::compare(const QString &other, Qt::CaseSensitivity cs) const |
4697 | { |
4698 | if (cs == Qt::CaseSensitive) |
4699 | return ucstrcmp(constData(), length(), other.constData(), other.length()); |
4700 | return ucstricmp(d->data, d->data + d->size, other.d->data, other.d->data + other.d->size); |
4701 | } |
4702 | |
4703 | /*! |
4704 | \internal |
4705 | \since 4.5 |
4706 | */ |
4707 | int QString::compare_helper(const QChar *data1, int length1, const QChar *data2, int length2, |
4708 | Qt::CaseSensitivity cs) |
4709 | { |
4710 | if (cs == Qt::CaseSensitive) |
4711 | return ucstrcmp(data1, length1, data2, length2); |
4712 | register const ushort *s1 = reinterpret_cast<const ushort *>(data1); |
4713 | register const ushort *s2 = reinterpret_cast<const ushort *>(data2); |
4714 | return ucstricmp(s1, s1 + length1, s2, s2 + length2); |
4715 | } |
4716 | |
4717 | /*! |
4718 | \overload compare() |
4719 | \since 4.2 |
4720 | |
4721 | Same as compare(*this, \a other, \a cs). |
4722 | */ |
4723 | int QString::compare(const QLatin1String &other, Qt::CaseSensitivity cs) const |
4724 | { |
4725 | return compare_helper(unicode(), length(), other, cs); |
4726 | } |
4727 | |
4728 | /*! |
4729 | \fn int QString::compare(const QStringRef &ref, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
4730 | \overload compare() |
4731 | |
4732 | Compares the string reference, \a ref, with the string and returns |
4733 | an integer less than, equal to, or greater than zero if the string |
4734 | is less than, equal to, or greater than \a ref. |
4735 | */ |
4736 | |
4737 | /*! |
4738 | \fn int QString::compare(const QString &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
4739 | \overload compare() |
4740 | */ |
4741 | |
4742 | /*! |
4743 | \internal |
4744 | \since 4.5 |
4745 | */ |
4746 | int QString::compare_helper(const QChar *data1, int length1, QLatin1String s2, |
4747 | Qt::CaseSensitivity cs) |
4748 | { |
4749 | const ushort *uc = reinterpret_cast<const ushort *>(data1); |
4750 | const ushort *e = uc + length1; |
4751 | const uchar *c = (uchar *)s2.latin1(); |
4752 | |
4753 | if (!c) |
4754 | return length1; |
4755 | |
4756 | if (cs == Qt::CaseSensitive) { |
4757 | while (uc < e && *c && *uc == *c) |
4758 | uc++, c++; |
4759 | |
4760 | if (uc == e) |
4761 | return -*c; |
4762 | |
4763 | return *uc - *c; |
4764 | } else { |
4765 | return ucstricmp(uc, e, c); |
4766 | } |
4767 | } |
4768 | |
4769 | /*! |
4770 | \fn int QString::localeAwareCompare(const QString & s1, const QString & s2) |
4771 | |
4772 | Compares \a s1 with \a s2 and returns an integer less than, equal |
4773 | to, or greater than zero if \a s1 is less than, equal to, or |
4774 | greater than \a s2. |
4775 | |
4776 | The comparison is performed in a locale- and also |
4777 | platform-dependent manner. Use this function to present sorted |
4778 | lists of strings to the user. |
4779 | |
4780 | On Mac OS X since Qt 4.3, this function compares according the |
4781 | "Order for sorted lists" setting in the International prefereces panel. |
4782 | |
4783 | \sa compare(), QTextCodec::locale() |
4784 | */ |
4785 | |
4786 | /*! |
4787 | \fn int QString::localeAwareCompare(const QStringRef &other) const |
4788 | \since 4.5 |
4789 | \overload localeAwareCompare() |
4790 | |
4791 | Compares this string with the \a other string and returns an |
4792 | integer less than, equal to, or greater than zero if this string |
4793 | is less than, equal to, or greater than the \a other string. |
4794 | |
4795 | The comparison is performed in a locale- and also |
4796 | platform-dependent manner. Use this function to present sorted |
4797 | lists of strings to the user. |
4798 | |
4799 | Same as \c {localeAwareCompare(*this, other)}. |
4800 | */ |
4801 | |
4802 | /*! |
4803 | \fn int QString::localeAwareCompare(const QString &s1, const QStringRef &s2) |
4804 | \since 4.5 |
4805 | \overload localeAwareCompare() |
4806 | |
4807 | Compares \a s1 with \a s2 and returns an integer less than, equal |
4808 | to, or greater than zero if \a s1 is less than, equal to, or |
4809 | greater than \a s2. |
4810 | |
4811 | The comparison is performed in a locale- and also |
4812 | platform-dependent manner. Use this function to present sorted |
4813 | lists of strings to the user. |
4814 | */ |
4815 | |
4816 | |
4817 | #if !defined(CSTR_LESS_THAN) |
4818 | #define CSTR_LESS_THAN 1 |
4819 | #define CSTR_EQUAL 2 |
4820 | #define CSTR_GREATER_THAN 3 |
4821 | #endif |
4822 | |
4823 | /*! |
4824 | \overload localeAwareCompare() |
4825 | |
4826 | Compares this string with the \a other string and returns an |
4827 | integer less than, equal to, or greater than zero if this string |
4828 | is less than, equal to, or greater than the \a other string. |
4829 | |
4830 | The comparison is performed in a locale- and also |
4831 | platform-dependent manner. Use this function to present sorted |
4832 | lists of strings to the user. |
4833 | |
4834 | Same as \c {localeAwareCompare(*this, other)}. |
4835 | */ |
4836 | int QString::localeAwareCompare(const QString &other) const |
4837 | { |
4838 | return localeAwareCompare_helper(constData(), length(), other.constData(), other.length()); |
4839 | } |
4840 | |
4841 | #if defined(Q_OS_WIN32) || defined(Q_OS_WINCE) |
4842 | QT_END_NAMESPACE |
4843 | #include "qt_windows.h" |
4844 | QT_BEGIN_NAMESPACE |
4845 | #endif |
4846 | |
4847 | /*! |
4848 | \internal |
4849 | \since 4.5 |
4850 | */ |
4851 | int QString::localeAwareCompare_helper(const QChar *data1, int length1, |
4852 | const QChar *data2, int length2) |
4853 | { |
4854 | // do the right thing for null and empty |
4855 | if (length1 == 0 || length2 == 0) |
4856 | return ucstrcmp(data1, length1, data2, length2); |
4857 | |
4858 | #if defined(Q_OS_WIN32) || defined(Q_OS_WINCE) |
4859 | int res = CompareString(GetUserDefaultLCID(), 0, (wchar_t*)data1, length1, (wchar_t*)data2, length2); |
4860 | |
4861 | switch (res) { |
4862 | case CSTR_LESS_THAN: |
4863 | return -1; |
4864 | case CSTR_GREATER_THAN: |
4865 | return 1; |
4866 | default: |
4867 | return 0; |
4868 | } |
4869 | #elif defined (Q_OS_MAC) |
4870 | // Use CFStringCompare for comparing strings on Mac. This makes Qt order |
4871 | // strings the same way as native applications do, and also respects |
4872 | // the "Order for sorted lists" setting in the International preferences |
4873 | // panel. |
4874 | const CFStringRef thisString = |
4875 | CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault, |
4876 | reinterpret_cast<const UniChar *>(data1), length1, kCFAllocatorNull); |
4877 | const CFStringRef otherString = |
4878 | CFStringCreateWithCharactersNoCopy(kCFAllocatorDefault, |
4879 | reinterpret_cast<const UniChar *>(data2), length2, kCFAllocatorNull); |
4880 | |
4881 | const int result = CFStringCompare(thisString, otherString, kCFCompareLocalized); |
4882 | CFRelease(thisString); |
4883 | CFRelease(otherString); |
4884 | return result; |
4885 | #elif defined(Q_OS_SYMBIAN) |
4886 | TPtrC p1 = TPtrC16(reinterpret_cast<const TUint16 *>(data1), length1); |
4887 | TPtrC p2 = TPtrC16(reinterpret_cast<const TUint16 *>(data2), length2); |
4888 | return p1.CompareC(p2); |
4889 | #elif defined(Q_OS_UNIX) |
4890 | # if defined(QT_USE_ICU) |
4891 | int res; |
4892 | if (qt_ucol_strcoll(data1, length1, data2, length2, &res)) { |
4893 | if (res == 0) |
4894 | res = ucstrcmp(data1, length1, data2, length2); |
4895 | return res; |
4896 | } // else fall through |
4897 | # endif |
4898 | // declared in <string.h> |
4899 | int delta = strcoll(toLocal8Bit_helper(data1, length1), toLocal8Bit_helper(data2, length2)); |
4900 | if (delta == 0) |
4901 | delta = ucstrcmp(data1, length1, data2, length2); |
4902 | return delta; |
4903 | #else |
4904 | return ucstrcmp(data1, length1, data2, length2); |
4905 | #endif |
4906 | } |
4907 | |
4908 | |
4909 | /*! |
4910 | \fn const QChar *QString::unicode() const |
4911 | |
4912 | Returns a '\\0'-terminated Unicode representation of the string. |
4913 | The result remains valid until the string is modified. |
4914 | |
4915 | \sa utf16() |
4916 | */ |
4917 | |
4918 | /*! |
4919 | \fn const ushort *QString::utf16() const |
4920 | |
4921 | Returns the QString as a '\\0\'-terminated array of unsigned |
4922 | shorts. The result remains valid until the string is modified. |
4923 | |
4924 | The returned string is in host byte order. |
4925 | |
4926 | \sa unicode() |
4927 | */ |
4928 | |
4929 | const ushort *QString::utf16() const |
4930 | { |
4931 | if (d->data != d->array) { |
4932 | QString *that = const_cast<QString*>(this); |
4933 | that->realloc(); // ensure '\\0'-termination for ::fromRawData strings |
4934 | return that->d->data; |
4935 | } |
4936 | return d->array; |
4937 | } |
4938 | |
4939 | /*! |
4940 | Returns a string of size \a width that contains this string |
4941 | padded by the \a fill character. |
4942 | |
4943 | If \a truncate is false and the size() of the string is more than |
4944 | \a width, then the returned string is a copy of the string. |
4945 | |
4946 | \snippet doc/src/snippets/qstring/main.cpp 32 |
4947 | |
4948 | If \a truncate is true and the size() of the string is more than |
4949 | \a width, then any characters in a copy of the string after |
4950 | position \a width are removed, and the copy is returned. |
4951 | |
4952 | \snippet doc/src/snippets/qstring/main.cpp 33 |
4953 | |
4954 | \sa rightJustified() |
4955 | */ |
4956 | |
4957 | QString QString::leftJustified(int width, QChar fill, bool truncate) const |
4958 | { |
4959 | QString result; |
4960 | int len = length(); |
4961 | int padlen = width - len; |
4962 | if (padlen > 0) { |
4963 | result.resize(len+padlen); |
4964 | if (len) |
4965 | memcpy(result.d->data, d->data, sizeof(QChar)*len); |
4966 | QChar *uc = (QChar*)result.d->data + len; |
4967 | while (padlen--) |
4968 | * uc++ = fill; |
4969 | } else { |
4970 | if (truncate) |
4971 | result = left(width); |
4972 | else |
4973 | result = *this; |
4974 | } |
4975 | return result; |
4976 | } |
4977 | |
4978 | /*! |
4979 | Returns a string of size() \a width that contains the \a fill |
4980 | character followed by the string. For example: |
4981 | |
4982 | \snippet doc/src/snippets/qstring/main.cpp 49 |
4983 | |
4984 | If \a truncate is false and the size() of the string is more than |
4985 | \a width, then the returned string is a copy of the string. |
4986 | |
4987 | If \a truncate is true and the size() of the string is more than |
4988 | \a width, then the resulting string is truncated at position \a |
4989 | width. |
4990 | |
4991 | \snippet doc/src/snippets/qstring/main.cpp 50 |
4992 | |
4993 | \sa leftJustified() |
4994 | */ |
4995 | |
4996 | QString QString::rightJustified(int width, QChar fill, bool truncate) const |
4997 | { |
4998 | QString result; |
4999 | int len = length(); |
5000 | int padlen = width - len; |
5001 | if (padlen > 0) { |
5002 | result.resize(len+padlen); |
5003 | QChar *uc = (QChar*)result.d->data; |
5004 | while (padlen--) |
5005 | * uc++ = fill; |
5006 | if (len) |
5007 | memcpy(uc, d->data, sizeof(QChar)*len); |
5008 | } else { |
5009 | if (truncate) |
5010 | result = left(width); |
5011 | else |
5012 | result = *this; |
5013 | } |
5014 | return result; |
5015 | } |
5016 | |
5017 | /*! |
5018 | Returns a lowercase copy of the string. |
5019 | |
5020 | \snippet doc/src/snippets/qstring/main.cpp 75 |
5021 | |
5022 | The case conversion will always happen in the 'C' locale. For locale dependent |
5023 | case folding use QLocale::toLower() |
5024 | |
5025 | \sa toUpper(), QLocale::toLower() |
5026 | */ |
5027 | |
5028 | QString QString::toLower() const |
5029 | { |
5030 | const ushort *p = d->data; |
5031 | if (!p) |
5032 | return *this; |
5033 | if (!d->size) |
5034 | return *this; |
5035 | |
5036 | const ushort *e = d->data + d->size; |
5037 | |
5038 | // this avoids one out of bounds check in the loop |
5039 | if (QChar(*p).isLowSurrogate()) |
5040 | ++p; |
5041 | |
5042 | while (p != e) { |
5043 | uint c = *p; |
5044 | if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate()) |
5045 | c = QChar::surrogateToUcs4(*(p - 1), c); |
5046 | const QUnicodeTables::Properties *prop = qGetProp(c); |
5047 | if (prop->lowerCaseDiff || prop->lowerCaseSpecial) { |
5048 | QString s(d->size, Qt::Uninitialized); |
5049 | memcpy(s.d->data, d->data, (p - d->data)*sizeof(ushort)); |
5050 | ushort *pp = s.d->data + (p - d->data); |
5051 | while (p < e) { |
5052 | uint c = *p; |
5053 | if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate()) |
5054 | c = QChar::surrogateToUcs4(*(p - 1), c); |
5055 | prop = qGetProp(c); |
5056 | if (prop->lowerCaseSpecial) { |
5057 | int pos = pp - s.d->data; |
5058 | s.resize(s.d->size + SPECIAL_CASE_MAX_LEN); |
5059 | pp = s.d->data + pos; |
5060 | const ushort *specialCase = specialCaseMap + prop->lowerCaseDiff; |
5061 | while (*specialCase) |
5062 | *pp++ = *specialCase++; |
5063 | } else { |
5064 | *pp++ = *p + prop->lowerCaseDiff; |
5065 | } |
5066 | ++p; |
5067 | } |
5068 | s.truncate(pp - s.d->data); |
5069 | return s; |
5070 | } |
5071 | ++p; |
5072 | } |
5073 | return *this; |
5074 | } |
5075 | |
5076 | /*! |
5077 | Returns the case folded equivalent of the string. For most Unicode |
5078 | characters this is the same as toLower(). |
5079 | */ |
5080 | QString QString::toCaseFolded() const |
5081 | { |
5082 | if (!d->size) |
5083 | return *this; |
5084 | |
5085 | const ushort *p = d->data; |
5086 | if (!p) |
5087 | return *this; |
5088 | |
5089 | const ushort *e = d->data + d->size; |
5090 | |
5091 | uint last = 0; |
5092 | while (p < e) { |
5093 | ushort folded = foldCase(*p, last); |
5094 | if (folded != *p) { |
5095 | QString s(*this); |
5096 | s.detach(); |
5097 | ushort *pp = s.d->data + (p - d->data); |
5098 | const ushort *ppe = s.d->data + s.d->size; |
5099 | last = pp > s.d->data ? *(pp - 1) : 0; |
5100 | while (pp < ppe) { |
5101 | *pp = foldCase(*pp, last); |
5102 | ++pp; |
5103 | } |
5104 | return s; |
5105 | } |
5106 | p++; |
5107 | } |
5108 | return *this; |
5109 | } |
5110 | |
5111 | /*! |
5112 | Returns an uppercase copy of the string. |
5113 | |
5114 | \snippet doc/src/snippets/qstring/main.cpp 81 |
5115 | |
5116 | The case conversion will always happen in the 'C' locale. For locale dependent |
5117 | case folding use QLocale::toUpper() |
5118 | |
5119 | \sa toLower(), QLocale::toLower() |
5120 | */ |
5121 | |
5122 | QString QString::toUpper() const |
5123 | { |
5124 | const ushort *p = d->data; |
5125 | if (!p) |
5126 | return *this; |
5127 | if (!d->size) |
5128 | return *this; |
5129 | |
5130 | const ushort *e = d->data + d->size; |
5131 | |
5132 | // this avoids one out of bounds check in the loop |
5133 | if (QChar(*p).isLowSurrogate()) |
5134 | ++p; |
5135 | |
5136 | while (p != e) { |
5137 | uint c = *p; |
5138 | if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate()) |
5139 | c = QChar::surrogateToUcs4(*(p - 1), c); |
5140 | const QUnicodeTables::Properties *prop = qGetProp(c); |
5141 | if (prop->upperCaseDiff || prop->upperCaseSpecial) { |
5142 | QString s(d->size, Qt::Uninitialized); |
5143 | memcpy(s.d->data, d->data, (p - d->data)*sizeof(ushort)); |
5144 | ushort *pp = s.d->data + (p - d->data); |
5145 | while (p < e) { |
5146 | uint c = *p; |
5147 | if (QChar(c).isLowSurrogate() && QChar(*(p - 1)).isHighSurrogate()) |
5148 | c = QChar::surrogateToUcs4(*(p - 1), c); |
5149 | prop = qGetProp(c); |
5150 | if (prop->upperCaseSpecial) { |
5151 | int pos = pp - s.d->data; |
5152 | s.resize(s.d->size + SPECIAL_CASE_MAX_LEN); |
5153 | pp = s.d->data + pos; |
5154 | const ushort *specialCase = specialCaseMap + prop->upperCaseDiff; |
5155 | while (*specialCase) |
5156 | *pp++ = *specialCase++; |
5157 | } else { |
5158 | *pp++ = *p + prop->upperCaseDiff; |
5159 | } |
5160 | ++p; |
5161 | } |
5162 | s.truncate(pp - s.d->data); |
5163 | return s; |
5164 | } |
5165 | ++p; |
5166 | } |
5167 | return *this; |
5168 | } |
5169 | |
5170 | // ### Qt 5: Consider whether this function shouldn't be removed See task 202871. |
5171 | /*! |
5172 | Safely builds a formatted string from the format string \a cformat |
5173 | and an arbitrary list of arguments. |
5174 | |
5175 | The %lc escape sequence expects a unicode character of type ushort |
5176 | (as returned by QChar::unicode()). The %ls escape sequence expects |
5177 | a pointer to a zero-terminated array of unicode characters of type |
5178 | ushort (as returned by QString::utf16()). |
5179 | |
5180 | \note This function expects a UTF-8 string for %s and Latin-1 for |
5181 | the format string. |
5182 | |
5183 | The format string supports most of the conversion specifiers |
5184 | provided by printf() in the standard C++ library. It doesn't |
5185 | honor the length modifiers (e.g. \c h for \c short, \c ll for |
5186 | \c{long long}). If you need those, use the standard snprintf() |
5187 | function instead: |
5188 | |
5189 | \snippet doc/src/snippets/qstring/main.cpp 63 |
5190 | |
5191 | \warning We do not recommend using QString::sprintf() in new Qt |
5192 | code. Instead, consider using QTextStream or arg(), both of |
5193 | which support Unicode strings seamlessly and are type-safe. |
5194 | Here's an example that uses QTextStream: |
5195 | |
5196 | \snippet doc/src/snippets/qstring/main.cpp 64 |
5197 | |
5198 | For \l {QObject::tr()}{translations}, especially if the strings |
5199 | contains more than one escape sequence, you should consider using |
5200 | the arg() function instead. This allows the order of the |
5201 | replacements to be controlled by the translator. |
5202 | |
5203 | \sa arg() |
5204 | */ |
5205 | |
5206 | QString &QString::sprintf(const char *cformat, ...) |
5207 | { |
5208 | va_list ap; |
5209 | va_start(ap, cformat); |
5210 | QString &s = vsprintf(cformat, ap); |
5211 | va_end(ap); |
5212 | return s; |
5213 | } |
5214 | |
5215 | /*! |
5216 | Equivalent method to sprintf(), but takes a va_list \a ap |
5217 | instead a list of variable arguments. See the sprintf() |
5218 | documentation for an explanation of \a cformat. |
5219 | |
5220 | This method does not call the va_end macro, the caller |
5221 | is responsible to call va_end on \a ap. |
5222 | |
5223 | \sa sprintf() |
5224 | */ |
5225 | |
5226 | QString &QString::vsprintf(const char* cformat, va_list ap) |
5227 | { |
5228 | QLocale locale(QLocale::C); |
5229 | |
5230 | if (!cformat || !*cformat) { |
5231 | // Qt 1.x compat |
5232 | *this = fromLatin1("" ); |
5233 | return *this; |
5234 | } |
5235 | |
5236 | // Parse cformat |
5237 | |
5238 | QString result; |
5239 | const char *c = cformat; |
5240 | for (;;) { |
5241 | // Copy non-escape chars to result |
5242 | #ifndef QT_NO_TEXTCODEC |
5243 | int i = 0; |
5244 | while (*(c + i) != '\0' && *(c + i) != '%') |
5245 | ++i; |
5246 | if (codecForCStrings) |
5247 | result.append(codecForCStrings->toUnicode(c, i)); |
5248 | else |
5249 | result.append(fromLatin1(c, i)); |
5250 | c += i; |
5251 | #else |
5252 | while (*c != '\0' && *c != '%') |
5253 | result.append(QLatin1Char(*c++)); |
5254 | #endif |
5255 | |
5256 | if (*c == '\0') |
5257 | break; |
5258 | |
5259 | // Found '%' |
5260 | const char *escape_start = c; |
5261 | ++c; |
5262 | |
5263 | if (*c == '\0') { |
5264 | result.append(QLatin1Char('%')); // a % at the end of the string - treat as non-escape text |
5265 | break; |
5266 | } |
5267 | if (*c == '%') { |
5268 | result.append(QLatin1Char('%')); // %% |
5269 | ++c; |
5270 | continue; |
5271 | } |
5272 | |
5273 | // Parse flag characters |
5274 | uint flags = 0; |
5275 | bool no_more_flags = false; |
5276 | do { |
5277 | switch (*c) { |
5278 | case '#': flags |= QLocalePrivate::Alternate; break; |
5279 | case '0': flags |= QLocalePrivate::ZeroPadded; break; |
5280 | case '-': flags |= QLocalePrivate::LeftAdjusted; break; |
5281 | case ' ': flags |= QLocalePrivate::BlankBeforePositive; break; |
5282 | case '+': flags |= QLocalePrivate::AlwaysShowSign; break; |
5283 | case '\'': flags |= QLocalePrivate::ThousandsGroup; break; |
5284 | default: no_more_flags = true; break; |
5285 | } |
5286 | |
5287 | if (!no_more_flags) |
5288 | ++c; |
5289 | } while (!no_more_flags); |
5290 | |
5291 | if (*c == '\0') { |
5292 | result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text |
5293 | break; |
5294 | } |
5295 | |
5296 | // Parse field width |
5297 | int width = -1; // -1 means unspecified |
5298 | if (qIsDigit(*c)) { |
5299 | QString width_str; |
5300 | while (*c != '\0' && qIsDigit(*c)) |
5301 | width_str.append(QLatin1Char(*c++)); |
5302 | |
5303 | // can't be negative - started with a digit |
5304 | // contains at least one digit |
5305 | width = width_str.toInt(); |
5306 | } |
5307 | else if (*c == '*') { |
5308 | width = va_arg(ap, int); |
5309 | if (width < 0) |
5310 | width = -1; // treat all negative numbers as unspecified |
5311 | ++c; |
5312 | } |
5313 | |
5314 | if (*c == '\0') { |
5315 | result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text |
5316 | break; |
5317 | } |
5318 | |
5319 | // Parse precision |
5320 | int precision = -1; // -1 means unspecified |
5321 | if (*c == '.') { |
5322 | ++c; |
5323 | if (qIsDigit(*c)) { |
5324 | QString precision_str; |
5325 | while (*c != '\0' && qIsDigit(*c)) |
5326 | precision_str.append(QLatin1Char(*c++)); |
5327 | |
5328 | // can't be negative - started with a digit |
5329 | // contains at least one digit |
5330 | precision = precision_str.toInt(); |
5331 | } |
5332 | else if (*c == '*') { |
5333 | precision = va_arg(ap, int); |
5334 | if (precision < 0) |
5335 | precision = -1; // treat all negative numbers as unspecified |
5336 | ++c; |
5337 | } |
5338 | } |
5339 | |
5340 | if (*c == '\0') { |
5341 | result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text |
5342 | break; |
5343 | } |
5344 | |
5345 | // Parse the length modifier |
5346 | enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t }; |
5347 | LengthMod length_mod = lm_none; |
5348 | switch (*c) { |
5349 | case 'h': |
5350 | ++c; |
5351 | if (*c == 'h') { |
5352 | length_mod = lm_hh; |
5353 | ++c; |
5354 | } |
5355 | else |
5356 | length_mod = lm_h; |
5357 | break; |
5358 | |
5359 | case 'l': |
5360 | ++c; |
5361 | if (*c == 'l') { |
5362 | length_mod = lm_ll; |
5363 | ++c; |
5364 | } |
5365 | else |
5366 | length_mod = lm_l; |
5367 | break; |
5368 | |
5369 | case 'L': |
5370 | ++c; |
5371 | length_mod = lm_L; |
5372 | break; |
5373 | |
5374 | case 'j': |
5375 | ++c; |
5376 | length_mod = lm_j; |
5377 | break; |
5378 | |
5379 | case 'z': |
5380 | case 'Z': |
5381 | ++c; |
5382 | length_mod = lm_z; |
5383 | break; |
5384 | |
5385 | case 't': |
5386 | ++c; |
5387 | length_mod = lm_t; |
5388 | break; |
5389 | |
5390 | default: break; |
5391 | } |
5392 | |
5393 | if (*c == '\0') { |
5394 | result.append(QLatin1String(escape_start)); // incomplete escape, treat as non-escape text |
5395 | break; |
5396 | } |
5397 | |
5398 | // Parse the conversion specifier and do the conversion |
5399 | QString subst; |
5400 | switch (*c) { |
5401 | case 'd': |
5402 | case 'i': { |
5403 | qint64 i; |
5404 | switch (length_mod) { |
5405 | case lm_none: i = va_arg(ap, int); break; |
5406 | case lm_hh: i = va_arg(ap, int); break; |
5407 | case lm_h: i = va_arg(ap, int); break; |
5408 | case lm_l: i = va_arg(ap, long int); break; |
5409 | case lm_ll: i = va_arg(ap, qint64); break; |
5410 | case lm_j: i = va_arg(ap, long int); break; |
5411 | case lm_z: i = va_arg(ap, size_t); break; |
5412 | case lm_t: i = va_arg(ap, int); break; |
5413 | default: i = 0; break; |
5414 | } |
5415 | subst = locale.d()->longLongToString(i, precision, 10, width, flags); |
5416 | ++c; |
5417 | break; |
5418 | } |
5419 | case 'o': |
5420 | case 'u': |
5421 | case 'x': |
5422 | case 'X': { |
5423 | quint64 u; |
5424 | switch (length_mod) { |
5425 | case lm_none: u = va_arg(ap, uint); break; |
5426 | case lm_hh: u = va_arg(ap, uint); break; |
5427 | case lm_h: u = va_arg(ap, uint); break; |
5428 | case lm_l: u = va_arg(ap, ulong); break; |
5429 | case lm_ll: u = va_arg(ap, quint64); break; |
5430 | case lm_z: u = va_arg(ap, size_t); break; |
5431 | default: u = 0; break; |
5432 | } |
5433 | |
5434 | if (qIsUpper(*c)) |
5435 | flags |= QLocalePrivate::CapitalEorX; |
5436 | |
5437 | int base = 10; |
5438 | switch (qToLower(*c)) { |
5439 | case 'o': |
5440 | base = 8; break; |
5441 | case 'u': |
5442 | base = 10; break; |
5443 | case 'x': |
5444 | base = 16; break; |
5445 | default: break; |
5446 | } |
5447 | subst = locale.d()->unsLongLongToString(u, precision, base, width, flags); |
5448 | ++c; |
5449 | break; |
5450 | } |
5451 | case 'E': |
5452 | case 'e': |
5453 | case 'F': |
5454 | case 'f': |
5455 | case 'G': |
5456 | case 'g': |
5457 | case 'A': |
5458 | case 'a': { |
5459 | double d; |
5460 | if (length_mod == lm_L) |
5461 | d = va_arg(ap, long double); // not supported - converted to a double |
5462 | else |
5463 | d = va_arg(ap, double); |
5464 | |
5465 | if (qIsUpper(*c)) |
5466 | flags |= QLocalePrivate::CapitalEorX; |
5467 | |
5468 | QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal; |
5469 | switch (qToLower(*c)) { |
5470 | case 'e': form = QLocalePrivate::DFExponent; break; |
5471 | case 'a': // not supported - decimal form used instead |
5472 | case 'f': form = QLocalePrivate::DFDecimal; break; |
5473 | case 'g': form = QLocalePrivate::DFSignificantDigits; break; |
5474 | default: break; |
5475 | } |
5476 | subst = locale.d()->doubleToString(d, precision, form, width, flags); |
5477 | ++c; |
5478 | break; |
5479 | } |
5480 | case 'c': { |
5481 | if (length_mod == lm_l) |
5482 | subst = QChar((ushort) va_arg(ap, int)); |
5483 | else |
5484 | subst = QLatin1Char((uchar) va_arg(ap, int)); |
5485 | ++c; |
5486 | break; |
5487 | } |
5488 | case 's': { |
5489 | if (length_mod == lm_l) { |
5490 | const ushort *buff = va_arg(ap, const ushort*); |
5491 | const ushort *ch = buff; |
5492 | while (*ch != 0) |
5493 | ++ch; |
5494 | subst.setUtf16(buff, ch - buff); |
5495 | } else |
5496 | subst = QString::fromUtf8(va_arg(ap, const char*)); |
5497 | if (precision != -1) |
5498 | subst.truncate(precision); |
5499 | ++c; |
5500 | break; |
5501 | } |
5502 | case 'p': { |
5503 | void *arg = va_arg(ap, void*); |
5504 | #ifdef Q_OS_WIN64 |
5505 | quint64 i = reinterpret_cast<quint64>(arg); |
5506 | #else |
5507 | quint64 i = reinterpret_cast<unsigned long>(arg); |
5508 | #endif |
5509 | flags |= QLocalePrivate::Alternate; |
5510 | subst = locale.d()->unsLongLongToString(i, precision, 16, width, flags); |
5511 | ++c; |
5512 | break; |
5513 | } |
5514 | case 'n': |
5515 | switch (length_mod) { |
5516 | case lm_hh: { |
5517 | signed char *n = va_arg(ap, signed char*); |
5518 | *n = result.length(); |
5519 | break; |
5520 | } |
5521 | case lm_h: { |
5522 | short int *n = va_arg(ap, short int*); |
5523 | *n = result.length(); |
5524 | break; |
5525 | } |
5526 | case lm_l: { |
5527 | long int *n = va_arg(ap, long int*); |
5528 | *n = result.length(); |
5529 | break; |
5530 | } |
5531 | case lm_ll: { |
5532 | qint64 *n = va_arg(ap, qint64*); |
5533 | volatile uint tmp = result.length(); // egcs-2.91.66 gets internal |
5534 | *n = tmp; // compiler error without volatile |
5535 | break; |
5536 | } |
5537 | default: { |
5538 | int *n = va_arg(ap, int*); |
5539 | *n = result.length(); |
5540 | break; |
5541 | } |
5542 | } |
5543 | ++c; |
5544 | break; |
5545 | |
5546 | default: // bad escape, treat as non-escape text |
5547 | for (const char *cc = escape_start; cc != c; ++cc) |
5548 | result.append(QLatin1Char(*cc)); |
5549 | continue; |
5550 | } |
5551 | |
5552 | if (flags & QLocalePrivate::LeftAdjusted) |
5553 | result.append(subst.leftJustified(width)); |
5554 | else |
5555 | result.append(subst.rightJustified(width)); |
5556 | } |
5557 | |
5558 | *this = result; |
5559 | |
5560 | return *this; |
5561 | } |
5562 | |
5563 | /*! |
5564 | Returns the string converted to a \c{long long} using base \a |
5565 | base, which is 10 by default and must be between 2 and 36, or 0. |
5566 | Returns 0 if the conversion fails. |
5567 | |
5568 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5569 | *\a{ok} is set to true. |
5570 | |
5571 | If \a base is 0, the C language convention is used: If the string |
5572 | begins with "0x", base 16 is used; if the string begins with "0", |
5573 | base 8 is used; otherwise, base 10 is used. |
5574 | |
5575 | Example: |
5576 | |
5577 | \snippet doc/src/snippets/qstring/main.cpp 74 |
5578 | |
5579 | \sa number(), toULongLong(), toInt() |
5580 | */ |
5581 | |
5582 | qint64 QString::toLongLong(bool *ok, int base) const |
5583 | { |
5584 | #if defined(QT_CHECK_RANGE) |
5585 | if (base != 0 && (base < 2 || base > 36)) { |
5586 | qWarning("QString::toLongLong: Invalid base (%d)" , base); |
5587 | base = 10; |
5588 | } |
5589 | #endif |
5590 | |
5591 | bool my_ok; |
5592 | QLocale def_locale; |
5593 | qint64 result = def_locale.d()->stringToLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators); |
5594 | if (my_ok) { |
5595 | if (ok != 0) |
5596 | *ok = true; |
5597 | return result; |
5598 | } |
5599 | |
5600 | QLocale c_locale(QLocale::C); |
5601 | return c_locale.d()->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators); |
5602 | } |
5603 | |
5604 | /*! |
5605 | Returns the string converted to an \c{unsigned long long} using base \a |
5606 | base, which is 10 by default and must be between 2 and 36, or 0. |
5607 | Returns 0 if the conversion fails. |
5608 | |
5609 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5610 | *\a{ok} is set to true. |
5611 | |
5612 | If \a base is 0, the C language convention is used: If the string |
5613 | begins with "0x", base 16 is used; if the string begins with "0", |
5614 | base 8 is used; otherwise, base 10 is used. |
5615 | |
5616 | Example: |
5617 | |
5618 | \snippet doc/src/snippets/qstring/main.cpp 79 |
5619 | |
5620 | \sa number(), toLongLong() |
5621 | */ |
5622 | |
5623 | quint64 QString::toULongLong(bool *ok, int base) const |
5624 | { |
5625 | #if defined(QT_CHECK_RANGE) |
5626 | if (base != 0 && (base < 2 || base > 36)) { |
5627 | qWarning("QString::toULongLong: Invalid base (%d)" , base); |
5628 | base = 10; |
5629 | } |
5630 | #endif |
5631 | |
5632 | bool my_ok; |
5633 | QLocale def_locale; |
5634 | quint64 result = def_locale.d()->stringToUnsLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators); |
5635 | if (my_ok) { |
5636 | if (ok != 0) |
5637 | *ok = true; |
5638 | return result; |
5639 | } |
5640 | |
5641 | QLocale c_locale(QLocale::C); |
5642 | return c_locale.d()->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators); |
5643 | } |
5644 | |
5645 | /*! |
5646 | \fn long QString::toLong(bool *ok, int base) const |
5647 | |
5648 | Returns the string converted to a \c long using base \a |
5649 | base, which is 10 by default and must be between 2 and 36, or 0. |
5650 | Returns 0 if the conversion fails. |
5651 | |
5652 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5653 | *\a{ok} is set to true. |
5654 | |
5655 | If \a base is 0, the C language convention is used: If the string |
5656 | begins with "0x", base 16 is used; if the string begins with "0", |
5657 | base 8 is used; otherwise, base 10 is used. |
5658 | |
5659 | Example: |
5660 | |
5661 | \snippet doc/src/snippets/qstring/main.cpp 73 |
5662 | |
5663 | \sa number(), toULong(), toInt() |
5664 | */ |
5665 | |
5666 | long QString::toLong(bool *ok, int base) const |
5667 | { |
5668 | qint64 v = toLongLong(ok, base); |
5669 | if (v < LONG_MIN || v > LONG_MAX) { |
5670 | if (ok) |
5671 | *ok = false; |
5672 | v = 0; |
5673 | } |
5674 | return (long)v; |
5675 | } |
5676 | |
5677 | /*! |
5678 | \fn ulong QString::toULong(bool *ok, int base) const |
5679 | |
5680 | Returns the string converted to an \c{unsigned long} using base \a |
5681 | base, which is 10 by default and must be between 2 and 36, or 0. |
5682 | Returns 0 if the conversion fails. |
5683 | |
5684 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5685 | *\a{ok} is set to true. |
5686 | |
5687 | If \a base is 0, the C language convention is used: If the string |
5688 | begins with "0x", base 16 is used; if the string begins with "0", |
5689 | base 8 is used; otherwise, base 10 is used. |
5690 | |
5691 | Example: |
5692 | |
5693 | \snippet doc/src/snippets/qstring/main.cpp 78 |
5694 | |
5695 | \sa number() |
5696 | */ |
5697 | |
5698 | ulong QString::toULong(bool *ok, int base) const |
5699 | { |
5700 | quint64 v = toULongLong(ok, base); |
5701 | if (v > ULONG_MAX) { |
5702 | if (ok) |
5703 | *ok = false; |
5704 | v = 0; |
5705 | } |
5706 | return (ulong)v; |
5707 | } |
5708 | |
5709 | |
5710 | /*! |
5711 | Returns the string converted to an \c int using base \a |
5712 | base, which is 10 by default and must be between 2 and 36, or 0. |
5713 | Returns 0 if the conversion fails. |
5714 | |
5715 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5716 | *\a{ok} is set to true. |
5717 | |
5718 | If \a base is 0, the C language convention is used: If the string |
5719 | begins with "0x", base 16 is used; if the string begins with "0", |
5720 | base 8 is used; otherwise, base 10 is used. |
5721 | |
5722 | Example: |
5723 | |
5724 | \snippet doc/src/snippets/qstring/main.cpp 72 |
5725 | |
5726 | \sa number(), toUInt(), toDouble() |
5727 | */ |
5728 | |
5729 | int QString::toInt(bool *ok, int base) const |
5730 | { |
5731 | qint64 v = toLongLong(ok, base); |
5732 | if (v < INT_MIN || v > INT_MAX) { |
5733 | if (ok) |
5734 | *ok = false; |
5735 | v = 0; |
5736 | } |
5737 | return v; |
5738 | } |
5739 | |
5740 | /*! |
5741 | Returns the string converted to an \c{unsigned int} using base \a |
5742 | base, which is 10 by default and must be between 2 and 36, or 0. |
5743 | Returns 0 if the conversion fails. |
5744 | |
5745 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5746 | *\a{ok} is set to true. |
5747 | |
5748 | If \a base is 0, the C language convention is used: If the string |
5749 | begins with "0x", base 16 is used; if the string begins with "0", |
5750 | base 8 is used; otherwise, base 10 is used. |
5751 | |
5752 | Example: |
5753 | |
5754 | \snippet doc/src/snippets/qstring/main.cpp 77 |
5755 | |
5756 | \sa number(), toInt() |
5757 | */ |
5758 | |
5759 | uint QString::toUInt(bool *ok, int base) const |
5760 | { |
5761 | quint64 v = toULongLong(ok, base); |
5762 | if (v > UINT_MAX) { |
5763 | if (ok) |
5764 | *ok = false; |
5765 | v = 0; |
5766 | } |
5767 | return (uint)v; |
5768 | } |
5769 | |
5770 | /*! |
5771 | Returns the string converted to a \c short using base \a |
5772 | base, which is 10 by default and must be between 2 and 36, or 0. |
5773 | Returns 0 if the conversion fails. |
5774 | |
5775 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5776 | *\a{ok} is set to true. |
5777 | |
5778 | If \a base is 0, the C language convention is used: If the string |
5779 | begins with "0x", base 16 is used; if the string begins with "0", |
5780 | base 8 is used; otherwise, base 10 is used. |
5781 | |
5782 | Example: |
5783 | |
5784 | \snippet doc/src/snippets/qstring/main.cpp 76 |
5785 | |
5786 | \sa number(), toUShort(), toInt() |
5787 | */ |
5788 | |
5789 | short QString::toShort(bool *ok, int base) const |
5790 | { |
5791 | long v = toLongLong(ok, base); |
5792 | if (v < SHRT_MIN || v > SHRT_MAX) { |
5793 | if (ok) |
5794 | *ok = false; |
5795 | v = 0; |
5796 | } |
5797 | return (short)v; |
5798 | } |
5799 | |
5800 | /*! |
5801 | Returns the string converted to an \c{unsigned short} using base \a |
5802 | base, which is 10 by default and must be between 2 and 36, or 0. |
5803 | Returns 0 if the conversion fails. |
5804 | |
5805 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5806 | *\a{ok} is set to true. |
5807 | |
5808 | If \a base is 0, the C language convention is used: If the string |
5809 | begins with "0x", base 16 is used; if the string begins with "0", |
5810 | base 8 is used; otherwise, base 10 is used. |
5811 | |
5812 | Example: |
5813 | |
5814 | \snippet doc/src/snippets/qstring/main.cpp 80 |
5815 | |
5816 | \sa number(), toShort() |
5817 | */ |
5818 | |
5819 | ushort QString::toUShort(bool *ok, int base) const |
5820 | { |
5821 | ulong v = toULongLong(ok, base); |
5822 | if (v > USHRT_MAX) { |
5823 | if (ok) |
5824 | *ok = false; |
5825 | v = 0; |
5826 | } |
5827 | return (ushort)v; |
5828 | } |
5829 | |
5830 | |
5831 | /*! |
5832 | Returns the string converted to a \c double value. |
5833 | |
5834 | Returns 0.0 if the conversion fails. |
5835 | |
5836 | If a conversion error occurs, \c{*}\a{ok} is set to false; |
5837 | otherwise \c{*}\a{ok} is set to true. |
5838 | |
5839 | \snippet doc/src/snippets/qstring/main.cpp 66 |
5840 | |
5841 | Various string formats for floating point numbers can be converted |
5842 | to double values: |
5843 | |
5844 | \snippet doc/src/snippets/qstring/main.cpp 67 |
5845 | |
5846 | This function tries to interpret the string according to the |
5847 | current locale. The current locale is determined from the |
5848 | system at application startup and can be changed by calling |
5849 | QLocale::setDefault(). If the string cannot be interpreted |
5850 | according to the current locale, this function falls back |
5851 | on the "C" locale. |
5852 | |
5853 | \snippet doc/src/snippets/qstring/main.cpp 69 |
5854 | \snippet doc/src/snippets/qstring/main.cpp 70 |
5855 | |
5856 | Due to the ambiguity between the decimal point and thousands group |
5857 | separator in various locales, this function does not handle |
5858 | thousands group separators. If you need to convert such numbers, |
5859 | see QLocale::toDouble(). |
5860 | |
5861 | \snippet doc/src/snippets/qstring/main.cpp 68 |
5862 | |
5863 | \sa number() QLocale::setDefault() QLocale::toDouble() trimmed() |
5864 | */ |
5865 | |
5866 | double QString::toDouble(bool *ok) const |
5867 | { |
5868 | bool my_ok; |
5869 | QLocale def_locale; |
5870 | double result = def_locale.d()->stringToDouble(*this, &my_ok, QLocalePrivate::FailOnGroupSeparators); |
5871 | if (my_ok) { |
5872 | if (ok != 0) |
5873 | *ok = true; |
5874 | return result; |
5875 | } |
5876 | |
5877 | QLocale c_locale(QLocale::C); |
5878 | return c_locale.d()->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators); |
5879 | } |
5880 | |
5881 | /*! |
5882 | Returns the string converted to a \c float value. |
5883 | |
5884 | If a conversion error occurs, *\a{ok} is set to false; otherwise |
5885 | *\a{ok} is set to true. Returns 0.0 if the conversion fails. |
5886 | |
5887 | Example: |
5888 | |
5889 | \snippet doc/src/snippets/qstring/main.cpp 71 |
5890 | |
5891 | \sa number(), toDouble(), toInt() |
5892 | */ |
5893 | |
5894 | #define QT_MAX_FLOAT 3.4028234663852886e+38 |
5895 | |
5896 | float QString::toFloat(bool *ok) const |
5897 | { |
5898 | bool myOk; |
5899 | double d = toDouble(&myOk); |
5900 | if (!myOk || d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) { |
5901 | if (ok != 0) |
5902 | *ok = false; |
5903 | return 0.0; |
5904 | } |
5905 | if (ok != 0) |
5906 | *ok = true; |
5907 | return (float) d; |
5908 | } |
5909 | |
5910 | /*! \fn QString &QString::setNum(int n, int base) |
5911 | |
5912 | Sets the string to the printed value of \a n in the specified \a |
5913 | base, and returns a reference to the string. |
5914 | |
5915 | The base is 10 by default and must be between 2 and 36. For bases |
5916 | other than 10, \a n is treated as an unsigned integer. |
5917 | |
5918 | \snippet doc/src/snippets/qstring/main.cpp 56 |
5919 | |
5920 | The formatting always uses QLocale::C, i.e., English/UnitedStates. |
5921 | To get a localized string representation of a number, use |
5922 | QLocale::toString() with the appropriate locale. |
5923 | */ |
5924 | |
5925 | /*! \fn QString &QString::setNum(uint n, int base) |
5926 | |
5927 | \overload |
5928 | */ |
5929 | |
5930 | /*! \fn QString &QString::setNum(long n, int base) |
5931 | |
5932 | \overload |
5933 | */ |
5934 | |
5935 | /*! \fn QString &QString::setNum(ulong n, int base) |
5936 | |
5937 | \overload |
5938 | */ |
5939 | |
5940 | /*! |
5941 | \overload |
5942 | */ |
5943 | QString &QString::setNum(qlonglong n, int base) |
5944 | { |
5945 | #if defined(QT_CHECK_RANGE) |
5946 | if (base < 2 || base > 36) { |
5947 | qWarning("QString::setNum: Invalid base (%d)" , base); |
5948 | base = 10; |
5949 | } |
5950 | #endif |
5951 | QLocale locale(QLocale::C); |
5952 | *this = locale.d()->longLongToString(n, -1, base); |
5953 | return *this; |
5954 | } |
5955 | |
5956 | /*! |
5957 | \overload |
5958 | */ |
5959 | QString &QString::setNum(qulonglong n, int base) |
5960 | { |
5961 | #if defined(QT_CHECK_RANGE) |
5962 | if (base < 2 || base > 36) { |
5963 | qWarning("QString::setNum: Invalid base (%d)" , base); |
5964 | base = 10; |
5965 | } |
5966 | #endif |
5967 | QLocale locale(QLocale::C); |
5968 | *this = locale.d()->unsLongLongToString(n, -1, base); |
5969 | return *this; |
5970 | } |
5971 | |
5972 | /*! \fn QString &QString::setNum(short n, int base) |
5973 | |
5974 | \overload |
5975 | */ |
5976 | |
5977 | /*! \fn QString &QString::setNum(ushort n, int base) |
5978 | |
5979 | \overload |
5980 | */ |
5981 | |
5982 | /*! |
5983 | \fn QString &QString::setNum(double n, char format, int precision) |
5984 | \overload |
5985 | |
5986 | Sets the string to the printed value of \a n, formatted according |
5987 | to the given \a format and \a precision, and returns a reference |
5988 | to the string. |
5989 | |
5990 | The \a format can be 'f', 'F', 'e', 'E', 'g' or 'G' (see the |
5991 | arg() function documentation for an explanation of the formats). |
5992 | |
5993 | Unlike QLocale::toString(), this function doesn't honor the |
5994 | user's locale settings. |
5995 | */ |
5996 | |
5997 | QString &QString::setNum(double n, char f, int prec) |
5998 | { |
5999 | QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal; |
6000 | uint flags = 0; |
6001 | |
6002 | if (qIsUpper(f)) |
6003 | flags = QLocalePrivate::CapitalEorX; |
6004 | f = qToLower(f); |
6005 | |
6006 | switch (f) { |
6007 | case 'f': |
6008 | form = QLocalePrivate::DFDecimal; |
6009 | break; |
6010 | case 'e': |
6011 | form = QLocalePrivate::DFExponent; |
6012 | break; |
6013 | case 'g': |
6014 | form = QLocalePrivate::DFSignificantDigits; |
6015 | break; |
6016 | default: |
6017 | #if defined(QT_CHECK_RANGE) |
6018 | qWarning("QString::setNum: Invalid format char '%c'" , f); |
6019 | #endif |
6020 | break; |
6021 | } |
6022 | |
6023 | QLocale locale(QLocale::C); |
6024 | *this = locale.d()->doubleToString(n, prec, form, -1, flags); |
6025 | return *this; |
6026 | } |
6027 | |
6028 | /*! |
6029 | \fn QString &QString::setNum(float n, char format, int precision) |
6030 | \overload |
6031 | |
6032 | Sets the string to the printed value of \a n, formatted according |
6033 | to the given \a format and \a precision, and returns a reference |
6034 | to the string. |
6035 | */ |
6036 | |
6037 | |
6038 | /*! |
6039 | \fn QString QString::number(long n, int base) |
6040 | |
6041 | Returns a string equivalent of the number \a n according to the |
6042 | specified \a base. |
6043 | |
6044 | The base is 10 by default and must be between 2 |
6045 | and 36. For bases other than 10, \a n is treated as an |
6046 | unsigned integer. |
6047 | |
6048 | \snippet doc/src/snippets/qstring/main.cpp 35 |
6049 | |
6050 | \sa setNum() |
6051 | */ |
6052 | |
6053 | QString QString::number(long n, int base) |
6054 | { |
6055 | QString s; |
6056 | s.setNum(n, base); |
6057 | return s; |
6058 | } |
6059 | |
6060 | /*! |
6061 | \fn QString QString::number(ulong n, int base) |
6062 | |
6063 | \overload |
6064 | */ |
6065 | QString QString::number(ulong n, int base) |
6066 | { |
6067 | QString s; |
6068 | s.setNum(n, base); |
6069 | return s; |
6070 | } |
6071 | |
6072 | /*! |
6073 | \overload |
6074 | */ |
6075 | QString QString::number(int n, int base) |
6076 | { |
6077 | QString s; |
6078 | s.setNum(n, base); |
6079 | return s; |
6080 | } |
6081 | |
6082 | /*! |
6083 | \overload |
6084 | */ |
6085 | QString QString::number(uint n, int base) |
6086 | { |
6087 | QString s; |
6088 | s.setNum(n, base); |
6089 | return s; |
6090 | } |
6091 | |
6092 | /*! |
6093 | \overload |
6094 | */ |
6095 | QString QString::number(qlonglong n, int base) |
6096 | { |
6097 | QString s; |
6098 | s.setNum(n, base); |
6099 | return s; |
6100 | } |
6101 | |
6102 | /*! |
6103 | \overload |
6104 | */ |
6105 | QString QString::number(qulonglong n, int base) |
6106 | { |
6107 | QString s; |
6108 | s.setNum(n, base); |
6109 | return s; |
6110 | } |
6111 | |
6112 | |
6113 | /*! |
6114 | \fn QString QString::number(double n, char format, int precision) |
6115 | |
6116 | Returns a string equivalent of the number \a n, formatted |
6117 | according to the specified \a format and \a precision. See |
6118 | \l{Argument Formats} for details. |
6119 | |
6120 | Unlike QLocale::toString(), this function does not honor the |
6121 | user's locale settings. |
6122 | |
6123 | \sa setNum(), QLocale::toString() |
6124 | */ |
6125 | QString QString::number(double n, char f, int prec) |
6126 | { |
6127 | QString s; |
6128 | s.setNum(n, f, prec); |
6129 | return s; |
6130 | } |
6131 | |
6132 | /*! |
6133 | Splits the string into substrings wherever \a sep occurs, and |
6134 | returns the list of those strings. If \a sep does not match |
6135 | anywhere in the string, split() returns a single-element list |
6136 | containing this string. |
6137 | |
6138 | \a cs specifies whether \a sep should be matched case |
6139 | sensitively or case insensitively. |
6140 | |
6141 | If \a behavior is QString::SkipEmptyParts, empty entries don't |
6142 | appear in the result. By default, empty entries are kept. |
6143 | |
6144 | Example: |
6145 | |
6146 | \snippet doc/src/snippets/qstring/main.cpp 62 |
6147 | |
6148 | \sa QStringList::join(), section() |
6149 | */ |
6150 | QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const |
6151 | { |
6152 | QStringList list; |
6153 | int start = 0; |
6154 | int = 0; |
6155 | int end; |
6156 | while ((end = indexOf(sep, start + extra, cs)) != -1) { |
6157 | if (start != end || behavior == KeepEmptyParts) |
6158 | list.append(mid(start, end - start)); |
6159 | start = end + sep.size(); |
6160 | extra = (sep.size() == 0 ? 1 : 0); |
6161 | } |
6162 | if (start != size() || behavior == KeepEmptyParts) |
6163 | list.append(mid(start)); |
6164 | return list; |
6165 | } |
6166 | |
6167 | /*! |
6168 | \overload |
6169 | */ |
6170 | QStringList QString::split(const QChar &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const |
6171 | { |
6172 | QStringList list; |
6173 | int start = 0; |
6174 | int end; |
6175 | while ((end = indexOf(sep, start, cs)) != -1) { |
6176 | if (start != end || behavior == KeepEmptyParts) |
6177 | list.append(mid(start, end - start)); |
6178 | start = end + 1; |
6179 | } |
6180 | if (start != size() || behavior == KeepEmptyParts) |
6181 | list.append(mid(start)); |
6182 | return list; |
6183 | } |
6184 | |
6185 | #ifndef QT_NO_REGEXP |
6186 | /*! |
6187 | \overload |
6188 | |
6189 | Splits the string into substrings wherever the regular expression |
6190 | \a rx matches, and returns the list of those strings. If \a rx |
6191 | does not match anywhere in the string, split() returns a |
6192 | single-element list containing this string. |
6193 | |
6194 | Here's an example where we extract the words in a sentence |
6195 | using one or more whitespace characters as the separator: |
6196 | |
6197 | \snippet doc/src/snippets/qstring/main.cpp 59 |
6198 | |
6199 | Here's a similar example, but this time we use any sequence of |
6200 | non-word characters as the separator: |
6201 | |
6202 | \snippet doc/src/snippets/qstring/main.cpp 60 |
6203 | |
6204 | Here's a third example where we use a zero-length assertion, |
6205 | \bold{\\b} (word boundary), to split the string into an |
6206 | alternating sequence of non-word and word tokens: |
6207 | |
6208 | \snippet doc/src/snippets/qstring/main.cpp 61 |
6209 | |
6210 | \sa QStringList::join(), section() |
6211 | */ |
6212 | QStringList QString::split(const QRegExp &rx, SplitBehavior behavior) const |
6213 | { |
6214 | QRegExp rx2(rx); |
6215 | QStringList list; |
6216 | int start = 0; |
6217 | int = 0; |
6218 | int end; |
6219 | while ((end = rx2.indexIn(*this, start + extra)) != -1) { |
6220 | int matchedLen = rx2.matchedLength(); |
6221 | if (start != end || behavior == KeepEmptyParts) |
6222 | list.append(mid(start, end - start)); |
6223 | start = end + matchedLen; |
6224 | extra = (matchedLen == 0) ? 1 : 0; |
6225 | } |
6226 | if (start != size() || behavior == KeepEmptyParts) |
6227 | list.append(mid(start)); |
6228 | return list; |
6229 | } |
6230 | #endif |
6231 | |
6232 | /*! |
6233 | \enum QString::NormalizationForm |
6234 | |
6235 | This enum describes the various normalized forms of Unicode text. |
6236 | |
6237 | \value NormalizationForm_D Canonical Decomposition |
6238 | \value NormalizationForm_C Canonical Decomposition followed by Canonical Composition |
6239 | \value NormalizationForm_KD Compatibility Decomposition |
6240 | \value NormalizationForm_KC Compatibility Decomposition followed by Canonical Composition |
6241 | |
6242 | \sa normalized(), |
6243 | {http://www.unicode.org/reports/tr15/}{Unicode Standard Annex #15} |
6244 | */ |
6245 | |
6246 | /*! |
6247 | \fn QString QString::normalized(NormalizationForm mode) const |
6248 | Returns the string in the given Unicode normalization \a mode. |
6249 | */ |
6250 | QString QString::normalized(QString::NormalizationForm mode) const |
6251 | { |
6252 | return normalized(mode, UNICODE_DATA_VERSION); |
6253 | } |
6254 | |
6255 | /*! |
6256 | \since 4.5 |
6257 | |
6258 | Returns a copy of this string repeated the specified number of \a times. |
6259 | |
6260 | If \a times is less than 1, an empty string is returned. |
6261 | |
6262 | Example: |
6263 | |
6264 | \code |
6265 | QString str("ab"); |
6266 | str.repeated(4); // returns "abababab" |
6267 | \endcode |
6268 | */ |
6269 | QString QString::repeated(int times) const |
6270 | { |
6271 | if (d->size == 0) |
6272 | return *this; |
6273 | |
6274 | if (times <= 1) { |
6275 | if (times == 1) |
6276 | return *this; |
6277 | return QString(); |
6278 | } |
6279 | |
6280 | const int resultSize = times * d->size; |
6281 | |
6282 | QString result; |
6283 | result.reserve(resultSize); |
6284 | if (result.d->alloc != resultSize) |
6285 | return QString(); // not enough memory |
6286 | |
6287 | memcpy(result.d->data, d->data, d->size * sizeof(ushort)); |
6288 | |
6289 | int sizeSoFar = d->size; |
6290 | ushort *end = result.d->data + sizeSoFar; |
6291 | |
6292 | const int halfResultSize = resultSize >> 1; |
6293 | while (sizeSoFar <= halfResultSize) { |
6294 | memcpy(end, result.d->data, sizeSoFar * sizeof(ushort)); |
6295 | end += sizeSoFar; |
6296 | sizeSoFar <<= 1; |
6297 | } |
6298 | memcpy(end, result.d->data, (resultSize - sizeSoFar) * sizeof(ushort)); |
6299 | result.d->data[resultSize] = '\0'; |
6300 | result.d->size = resultSize; |
6301 | return result; |
6302 | } |
6303 | |
6304 | void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from); |
6305 | /*! |
6306 | \overload |
6307 | \fn QString QString::normalized(NormalizationForm mode, QChar::UnicodeVersion version) const |
6308 | |
6309 | Returns the string in the given Unicode normalization \a mode, |
6310 | according to the given \a version of the Unicode standard. |
6311 | */ |
6312 | QString QString::normalized(QString::NormalizationForm mode, QChar::UnicodeVersion version) const |
6313 | { |
6314 | QString copy = *this; |
6315 | qt_string_normalize(©, mode, version, 0); |
6316 | return copy; |
6317 | } |
6318 | |
6319 | void qt_string_normalize(QString *data, QString::NormalizationForm mode, QChar::UnicodeVersion version, int from) |
6320 | { |
6321 | bool simple = true; |
6322 | const QChar *p = data->constData(); |
6323 | int len = data->length(); |
6324 | for (int i = from; i < len; ++i) { |
6325 | if (p[i].unicode() >= 0x80) { |
6326 | simple = false; |
6327 | break; |
6328 | } |
6329 | } |
6330 | if (simple) |
6331 | return; |
6332 | |
6333 | if (version == QChar::Unicode_Unassigned) { |
6334 | version = UNICODE_DATA_VERSION; |
6335 | } else if (version != UNICODE_DATA_VERSION) { |
6336 | const QString &s = *data; |
6337 | QChar *d = 0; |
6338 | for (int i = 0; i < NumNormalizationCorrections; ++i) { |
6339 | const NormalizationCorrection &n = uc_normalization_corrections[i]; |
6340 | if (n.version > version) { |
6341 | int pos = from; |
6342 | if (QChar::requiresSurrogates(n.ucs4)) { |
6343 | ushort ucs4High = QChar::highSurrogate(n.ucs4); |
6344 | ushort ucs4Low = QChar::lowSurrogate(n.ucs4); |
6345 | ushort oldHigh = QChar::highSurrogate(n.old_mapping); |
6346 | ushort oldLow = QChar::lowSurrogate(n.old_mapping); |
6347 | while (pos < s.length() - 1) { |
6348 | if (s.at(pos).unicode() == ucs4High && s.at(pos + 1).unicode() == ucs4Low) { |
6349 | if (!d) |
6350 | d = data->data(); |
6351 | d[pos] = QChar(oldHigh); |
6352 | d[++pos] = QChar(oldLow); |
6353 | } |
6354 | ++pos; |
6355 | } |
6356 | } else { |
6357 | while (pos < s.length()) { |
6358 | if (s.at(pos).unicode() == n.ucs4) { |
6359 | if (!d) |
6360 | d = data->data(); |
6361 | d[pos] = QChar(n.old_mapping); |
6362 | } |
6363 | ++pos; |
6364 | } |
6365 | } |
6366 | } |
6367 | } |
6368 | } |
6369 | decomposeHelper(data, mode < QString::NormalizationForm_KD, version, from); |
6370 | |
6371 | canonicalOrderHelper(data, version, from); |
6372 | |
6373 | if (mode == QString::NormalizationForm_D || mode == QString::NormalizationForm_KD) |
6374 | return; |
6375 | |
6376 | composeHelper(data, version, from); |
6377 | } |
6378 | |
6379 | |
6380 | struct ArgEscapeData |
6381 | { |
6382 | int min_escape; // lowest escape sequence number |
6383 | int occurrences; // number of occurrences of the lowest escape sequence number |
6384 | int locale_occurrences; // number of occurrences of the lowest escape sequence number that |
6385 | // contain 'L' |
6386 | int escape_len; // total length of escape sequences which will be replaced |
6387 | }; |
6388 | |
6389 | static ArgEscapeData findArgEscapes(const QString &s) |
6390 | { |
6391 | const QChar *uc_begin = s.unicode(); |
6392 | const QChar *uc_end = uc_begin + s.length(); |
6393 | |
6394 | ArgEscapeData d; |
6395 | |
6396 | d.min_escape = INT_MAX; |
6397 | d.occurrences = 0; |
6398 | d.escape_len = 0; |
6399 | d.locale_occurrences = 0; |
6400 | |
6401 | const QChar *c = uc_begin; |
6402 | while (c != uc_end) { |
6403 | while (c != uc_end && c->unicode() != '%') |
6404 | ++c; |
6405 | |
6406 | if (c == uc_end) |
6407 | break; |
6408 | const QChar *escape_start = c; |
6409 | if (++c == uc_end) |
6410 | break; |
6411 | |
6412 | bool locale_arg = false; |
6413 | if (c->unicode() == 'L') { |
6414 | locale_arg = true; |
6415 | if (++c == uc_end) |
6416 | break; |
6417 | } |
6418 | |
6419 | if (c->digitValue() == -1) |
6420 | continue; |
6421 | |
6422 | int escape = c->digitValue(); |
6423 | ++c; |
6424 | |
6425 | if (c != uc_end && c->digitValue() != -1) { |
6426 | escape = (10 * escape) + c->digitValue(); |
6427 | ++c; |
6428 | } |
6429 | |
6430 | if (escape > d.min_escape) |
6431 | continue; |
6432 | |
6433 | if (escape < d.min_escape) { |
6434 | d.min_escape = escape; |
6435 | d.occurrences = 0; |
6436 | d.escape_len = 0; |
6437 | d.locale_occurrences = 0; |
6438 | } |
6439 | |
6440 | ++d.occurrences; |
6441 | if (locale_arg) |
6442 | ++d.locale_occurrences; |
6443 | d.escape_len += c - escape_start; |
6444 | } |
6445 | return d; |
6446 | } |
6447 | |
6448 | static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width, |
6449 | const QString &arg, const QString &larg, const QChar &fillChar = QLatin1Char(' ')) |
6450 | { |
6451 | const QChar *uc_begin = s.unicode(); |
6452 | const QChar *uc_end = uc_begin + s.length(); |
6453 | |
6454 | int abs_field_width = qAbs(field_width); |
6455 | int result_len = s.length() |
6456 | - d.escape_len |
6457 | + (d.occurrences - d.locale_occurrences) |
6458 | *qMax(abs_field_width, arg.length()) |
6459 | + d.locale_occurrences |
6460 | *qMax(abs_field_width, larg.length()); |
6461 | |
6462 | QString result(result_len, Qt::Uninitialized); |
6463 | QChar *result_buff = (QChar*) result.unicode(); |
6464 | |
6465 | QChar *rc = result_buff; |
6466 | const QChar *c = uc_begin; |
6467 | int repl_cnt = 0; |
6468 | while (c != uc_end) { |
6469 | /* We don't have to check if we run off the end of the string with c, |
6470 | because as long as d.occurrences > 0 we KNOW there are valid escape |
6471 | sequences. */ |
6472 | |
6473 | const QChar *text_start = c; |
6474 | |
6475 | while (c->unicode() != '%') |
6476 | ++c; |
6477 | |
6478 | const QChar *escape_start = c++; |
6479 | |
6480 | bool locale_arg = false; |
6481 | if (c->unicode() == 'L') { |
6482 | locale_arg = true; |
6483 | ++c; |
6484 | } |
6485 | |
6486 | int escape = c->digitValue(); |
6487 | if (escape != -1) { |
6488 | if (c + 1 != uc_end && (c + 1)->digitValue() != -1) { |
6489 | escape = (10 * escape) + (c + 1)->digitValue(); |
6490 | ++c; |
6491 | } |
6492 | } |
6493 | |
6494 | if (escape != d.min_escape) { |
6495 | memcpy(rc, text_start, (c - text_start)*sizeof(QChar)); |
6496 | rc += c - text_start; |
6497 | } |
6498 | else { |
6499 | ++c; |
6500 | |
6501 | memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar)); |
6502 | rc += escape_start - text_start; |
6503 | |
6504 | uint pad_chars; |
6505 | if (locale_arg) |
6506 | pad_chars = qMax(abs_field_width, larg.length()) - larg.length(); |
6507 | else |
6508 | pad_chars = qMax(abs_field_width, arg.length()) - arg.length(); |
6509 | |
6510 | if (field_width > 0) { // left padded |
6511 | for (uint i = 0; i < pad_chars; ++i) |
6512 | (rc++)->unicode() = fillChar.unicode(); |
6513 | } |
6514 | |
6515 | if (locale_arg) { |
6516 | memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar)); |
6517 | rc += larg.length(); |
6518 | } |
6519 | else { |
6520 | memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar)); |
6521 | rc += arg.length(); |
6522 | } |
6523 | |
6524 | if (field_width < 0) { // right padded |
6525 | for (uint i = 0; i < pad_chars; ++i) |
6526 | (rc++)->unicode() = fillChar.unicode(); |
6527 | } |
6528 | |
6529 | if (++repl_cnt == d.occurrences) { |
6530 | memcpy(rc, c, (uc_end - c)*sizeof(QChar)); |
6531 | rc += uc_end - c; |
6532 | Q_ASSERT(rc - result_buff == result_len); |
6533 | c = uc_end; |
6534 | } |
6535 | } |
6536 | } |
6537 | Q_ASSERT(rc == result_buff + result_len); |
6538 | |
6539 | return result; |
6540 | } |
6541 | |
6542 | /*! |
6543 | Returns a copy of this string with the lowest numbered place marker |
6544 | replaced by string \a a, i.e., \c %1, \c %2, ..., \c %99. |
6545 | |
6546 | \a fieldWidth specifies the minimum amount of space that argument \a |
6547 | a shall occupy. If \a a requires less space than \a fieldWidth, it |
6548 | is padded to \a fieldWidth with character \a fillChar. A positive |
6549 | \a fieldWidth produces right-aligned text. A negative \a fieldWidth |
6550 | produces left-aligned text. |
6551 | |
6552 | This example shows how we might create a \c status string for |
6553 | reporting progress while processing a list of files: |
6554 | |
6555 | \snippet doc/src/snippets/qstring/main.cpp 11 |
6556 | |
6557 | First, \c arg(i) replaces \c %1. Then \c arg(total) replaces \c |
6558 | %2. Finally, \c arg(fileName) replaces \c %3. |
6559 | |
6560 | One advantage of using arg() over sprintf() is that the order of the |
6561 | numbered place markers can change, if the application's strings are |
6562 | translated into other languages, but each arg() will still replace |
6563 | the lowest numbered unreplaced place marker, no matter where it |
6564 | appears. Also, if place marker \c %i appears more than once in the |
6565 | string, the arg() replaces all of them. |
6566 | |
6567 | If there is no unreplaced place marker remaining, a warning message |
6568 | is output and the result is undefined. Place marker numbers must be |
6569 | in the range 1 to 99. |
6570 | */ |
6571 | QString QString::arg(const QString &a, int fieldWidth, const QChar &fillChar) const |
6572 | { |
6573 | ArgEscapeData d = findArgEscapes(*this); |
6574 | |
6575 | if (d.occurrences == 0) { |
6576 | qWarning("QString::arg: Argument missing: %s, %s" , toLocal8Bit().data(), |
6577 | a.toLocal8Bit().data()); |
6578 | return *this; |
6579 | } |
6580 | return replaceArgEscapes(*this, d, fieldWidth, a, a, fillChar); |
6581 | } |
6582 | |
6583 | /*! |
6584 | \fn QString QString::arg(const QString& a1, const QString& a2) const |
6585 | \overload arg() |
6586 | |
6587 | This is the same as \c {str.arg(a1).arg(a2)}, except that the |
6588 | strings \a a1 and \a a2 are replaced in one pass. This can make a |
6589 | difference if \a a1 contains e.g. \c{%1}: |
6590 | |
6591 | \snippet doc/src/snippets/qstring/main.cpp 13 |
6592 | */ |
6593 | |
6594 | /*! |
6595 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3) const |
6596 | \overload arg() |
6597 | |
6598 | This is the same as calling \c str.arg(a1).arg(a2).arg(a3), except |
6599 | that the strings \a a1, \a a2 and \a a3 are replaced in one pass. |
6600 | */ |
6601 | |
6602 | /*! |
6603 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4) const |
6604 | \overload arg() |
6605 | |
6606 | This is the same as calling \c |
6607 | {str.arg(a1).arg(a2).arg(a3).arg(a4)}, except that the strings \a |
6608 | a1, \a a2, \a a3 and \a a4 are replaced in one pass. |
6609 | */ |
6610 | |
6611 | /*! |
6612 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5) const |
6613 | \overload arg() |
6614 | |
6615 | This is the same as calling \c |
6616 | {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5)}, except that the strings |
6617 | \a a1, \a a2, \a a3, \a a4, and \a a5 are replaced in one pass. |
6618 | */ |
6619 | |
6620 | /*! |
6621 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6) const |
6622 | \overload arg() |
6623 | |
6624 | This is the same as calling \c |
6625 | {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6))}, except that |
6626 | the strings \a a1, \a a2, \a a3, \a a4, \a a5, and \a a6 are |
6627 | replaced in one pass. |
6628 | */ |
6629 | |
6630 | /*! |
6631 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7) const |
6632 | \overload arg() |
6633 | |
6634 | This is the same as calling \c |
6635 | {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7)}, |
6636 | except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, |
6637 | and \a a7 are replaced in one pass. |
6638 | */ |
6639 | |
6640 | /*! |
6641 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8) const |
6642 | \overload arg() |
6643 | |
6644 | This is the same as calling \c |
6645 | {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8)}, |
6646 | except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a |
6647 | a7, and \a a8 are replaced in one pass. |
6648 | */ |
6649 | |
6650 | /*! |
6651 | \fn QString QString::arg(const QString& a1, const QString& a2, const QString& a3, const QString& a4, const QString& a5, const QString& a6, const QString& a7, const QString& a8, const QString& a9) const |
6652 | \overload arg() |
6653 | |
6654 | This is the same as calling \c |
6655 | {str.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9)}, |
6656 | except that the strings \a a1, \a a2, \a a3, \a a4, \a a5, \a a6, \a |
6657 | a7, \a a8, and \a a9 are replaced in one pass. |
6658 | */ |
6659 | |
6660 | /*! \fn QString QString::arg(int a, int fieldWidth, int base, const QChar &fillChar) const |
6661 | \overload arg() |
6662 | |
6663 | The \a a argument is expressed in base \a base, which is 10 by |
6664 | default and must be between 2 and 36. For bases other than 10, \a a |
6665 | is treated as an unsigned integer. |
6666 | |
6667 | \a fieldWidth specifies the minimum amount of space that \a a is |
6668 | padded to and filled with the character \a fillChar. A positive |
6669 | value produces right-aligned text; a negative value produces |
6670 | left-aligned text. |
6671 | |
6672 | The '%' can be followed by an 'L', in which case the sequence is |
6673 | replaced with a localized representation of \a a. The conversion |
6674 | uses the default locale, set by QLocale::setDefault(). If no default |
6675 | locale was specified, the "C" locale is used. The 'L' flag is |
6676 | ignored if \a base is not 10. |
6677 | |
6678 | \snippet doc/src/snippets/qstring/main.cpp 12 |
6679 | \snippet doc/src/snippets/qstring/main.cpp 14 |
6680 | |
6681 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6682 | used. For negative numbers, zero padding might appear before the |
6683 | minus sign. |
6684 | */ |
6685 | |
6686 | /*! \fn QString QString::arg(uint a, int fieldWidth, int base, const QChar &fillChar) const |
6687 | \overload arg() |
6688 | |
6689 | The \a base argument specifies the base to use when converting the |
6690 | integer \a a into a string. The base must be between 2 and 36. |
6691 | |
6692 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6693 | used. For negative numbers, zero padding might appear before the |
6694 | minus sign. |
6695 | */ |
6696 | |
6697 | /*! \fn QString QString::arg(long a, int fieldWidth, int base, const QChar &fillChar) const |
6698 | \overload arg() |
6699 | |
6700 | \a fieldWidth specifies the minimum amount of space that \a a is |
6701 | padded to and filled with the character \a fillChar. A positive |
6702 | value produces right-aligned text; a negative value produces |
6703 | left-aligned text. |
6704 | |
6705 | The \a a argument is expressed in the given \a base, which is 10 by |
6706 | default and must be between 2 and 36. |
6707 | |
6708 | The '%' can be followed by an 'L', in which case the sequence is |
6709 | replaced with a localized representation of \a a. The conversion |
6710 | uses the default locale. The default locale is determined from the |
6711 | system's locale settings at application startup. It can be changed |
6712 | using QLocale::setDefault(). The 'L' flag is ignored if \a base is |
6713 | not 10. |
6714 | |
6715 | \snippet doc/src/snippets/qstring/main.cpp 12 |
6716 | \snippet doc/src/snippets/qstring/main.cpp 14 |
6717 | |
6718 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6719 | used. For negative numbers, zero padding might appear before the |
6720 | minus sign. |
6721 | */ |
6722 | |
6723 | /*! \fn QString QString::arg(ulong a, int fieldWidth, int base, const QChar &fillChar) const |
6724 | \overload arg() |
6725 | |
6726 | \a fieldWidth specifies the minimum amount of space that \a a is |
6727 | padded to and filled with the character \a fillChar. A positive |
6728 | value produces right-aligned text; a negative value produces |
6729 | left-aligned text. |
6730 | |
6731 | The \a base argument specifies the base to use when converting the |
6732 | integer \a a to a string. The base must be between 2 and 36, with 8 |
6733 | giving octal, 10 decimal, and 16 hexadecimal numbers. |
6734 | |
6735 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6736 | used. For negative numbers, zero padding might appear before the |
6737 | minus sign. |
6738 | */ |
6739 | |
6740 | /*! |
6741 | \overload arg() |
6742 | |
6743 | \a fieldWidth specifies the minimum amount of space that \a a is |
6744 | padded to and filled with the character \a fillChar. A positive |
6745 | value produces right-aligned text; a negative value produces |
6746 | left-aligned text. |
6747 | |
6748 | The \a base argument specifies the base to use when converting the |
6749 | integer \a a into a string. The base must be between 2 and 36, with |
6750 | 8 giving octal, 10 decimal, and 16 hexadecimal numbers. |
6751 | |
6752 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6753 | used. For negative numbers, zero padding might appear before the |
6754 | minus sign. |
6755 | */ |
6756 | QString QString::arg(qlonglong a, int fieldWidth, int base, const QChar &fillChar) const |
6757 | { |
6758 | ArgEscapeData d = findArgEscapes(*this); |
6759 | |
6760 | if (d.occurrences == 0) { |
6761 | qWarning() << "QString::arg: Argument missing:" << *this << ',' << a; |
6762 | return *this; |
6763 | } |
6764 | |
6765 | unsigned flags = QLocalePrivate::NoFlags; |
6766 | if (fillChar == QLatin1Char('0')) |
6767 | flags = QLocalePrivate::ZeroPadded; |
6768 | |
6769 | QString arg; |
6770 | if (d.occurrences > d.locale_occurrences) |
6771 | arg = QLocale::c().d()->longLongToString(a, -1, base, fieldWidth, flags); |
6772 | |
6773 | QString locale_arg; |
6774 | if (d.locale_occurrences > 0) { |
6775 | QLocale locale; |
6776 | if (!locale.numberOptions() & QLocale::OmitGroupSeparator) |
6777 | flags |= QLocalePrivate::ThousandsGroup; |
6778 | locale_arg = locale.d()->longLongToString(a, -1, base, fieldWidth, flags); |
6779 | } |
6780 | |
6781 | return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar); |
6782 | } |
6783 | |
6784 | /*! |
6785 | \overload arg() |
6786 | |
6787 | \a fieldWidth specifies the minimum amount of space that \a a is |
6788 | padded to and filled with the character \a fillChar. A positive |
6789 | value produces right-aligned text; a negative value produces |
6790 | left-aligned text. |
6791 | |
6792 | The \a base argument specifies the base to use when converting the |
6793 | integer \a a into a string. \a base must be between 2 and 36, with 8 |
6794 | giving octal, 10 decimal, and 16 hexadecimal numbers. |
6795 | |
6796 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6797 | used. For negative numbers, zero padding might appear before the |
6798 | minus sign. |
6799 | */ |
6800 | QString QString::arg(qulonglong a, int fieldWidth, int base, const QChar &fillChar) const |
6801 | { |
6802 | ArgEscapeData d = findArgEscapes(*this); |
6803 | |
6804 | if (d.occurrences == 0) { |
6805 | qWarning() << "QString::arg: Argument missing:" << *this << ',' << a; |
6806 | return *this; |
6807 | } |
6808 | |
6809 | unsigned flags = QLocalePrivate::NoFlags; |
6810 | if (fillChar == QLatin1Char('0')) |
6811 | flags = QLocalePrivate::ZeroPadded; |
6812 | |
6813 | QString arg; |
6814 | if (d.occurrences > d.locale_occurrences) |
6815 | arg = QLocale::c().d()->unsLongLongToString(a, -1, base, fieldWidth, flags); |
6816 | |
6817 | QString locale_arg; |
6818 | if (d.locale_occurrences > 0) { |
6819 | QLocale locale; |
6820 | if (!locale.numberOptions() & QLocale::OmitGroupSeparator) |
6821 | flags |= QLocalePrivate::ThousandsGroup; |
6822 | locale_arg = locale.d()->unsLongLongToString(a, -1, base, fieldWidth, flags); |
6823 | } |
6824 | |
6825 | return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar); |
6826 | } |
6827 | |
6828 | /*! |
6829 | \overload arg() |
6830 | |
6831 | \fn QString QString::arg(short a, int fieldWidth, int base, const QChar &fillChar) const |
6832 | |
6833 | \a fieldWidth specifies the minimum amount of space that \a a is |
6834 | padded to and filled with the character \a fillChar. A positive |
6835 | value produces right-aligned text; a negative value produces |
6836 | left-aligned text. |
6837 | |
6838 | The \a base argument specifies the base to use when converting the |
6839 | integer \a a into a string. The base must be between 2 and 36, with |
6840 | 8 giving octal, 10 decimal, and 16 hexadecimal numbers. |
6841 | |
6842 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6843 | used. For negative numbers, zero padding might appear before the |
6844 | minus sign. |
6845 | */ |
6846 | |
6847 | /*! |
6848 | \fn QString QString::arg(ushort a, int fieldWidth, int base, const QChar &fillChar) const |
6849 | \overload arg() |
6850 | |
6851 | \a fieldWidth specifies the minimum amount of space that \a a is |
6852 | padded to and filled with the character \a fillChar. A positive |
6853 | value produces right-aligned text; a negative value produces |
6854 | left-aligned text. |
6855 | |
6856 | The \a base argument specifies the base to use when converting the |
6857 | integer \a a into a string. The base must be between 2 and 36, with |
6858 | 8 giving octal, 10 decimal, and 16 hexadecimal numbers. |
6859 | |
6860 | If \a fillChar is '0' (the number 0, ASCII 48), the locale's zero is |
6861 | used. For negative numbers, zero padding might appear before the |
6862 | minus sign. |
6863 | */ |
6864 | |
6865 | /*! |
6866 | \overload arg() |
6867 | */ |
6868 | QString QString::arg(QChar a, int fieldWidth, const QChar &fillChar) const |
6869 | { |
6870 | QString c; |
6871 | c += a; |
6872 | return arg(c, fieldWidth, fillChar); |
6873 | } |
6874 | |
6875 | /*! |
6876 | \overload arg() |
6877 | |
6878 | The \a a argument is interpreted as a Latin-1 character. |
6879 | */ |
6880 | QString QString::arg(char a, int fieldWidth, const QChar &fillChar) const |
6881 | { |
6882 | QString c; |
6883 | c += QLatin1Char(a); |
6884 | return arg(c, fieldWidth, fillChar); |
6885 | } |
6886 | |
6887 | /*! |
6888 | \fn QString QString::arg(double a, int fieldWidth, char format, int precision, const QChar &fillChar) const |
6889 | \overload arg() |
6890 | |
6891 | Argument \a a is formatted according to the specified \a format and |
6892 | \a precision. See \l{Argument Formats} for details. |
6893 | |
6894 | \a fieldWidth specifies the minimum amount of space that \a a is |
6895 | padded to and filled with the character \a fillChar. A positive |
6896 | value produces right-aligned text; a negative value produces |
6897 | left-aligned text. |
6898 | |
6899 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 2 |
6900 | |
6901 | The '%' can be followed by an 'L', in which case the sequence is |
6902 | replaced with a localized representation of \a a. The conversion |
6903 | uses the default locale, set by QLocale::setDefaultLocale(). If no |
6904 | default locale was specified, the "C" locale is used. |
6905 | |
6906 | If \a fillChar is '0' (the number 0, ASCII 48), this function will |
6907 | use the locale's zero to pad. For negative numbers, the zero padding |
6908 | will probably appear before the minus sign. |
6909 | |
6910 | \sa QLocale::toString() |
6911 | */ |
6912 | QString QString::arg(double a, int fieldWidth, char fmt, int prec, const QChar &fillChar) const |
6913 | { |
6914 | ArgEscapeData d = findArgEscapes(*this); |
6915 | |
6916 | if (d.occurrences == 0) { |
6917 | qWarning("QString::arg: Argument missing: %s, %g" , toLocal8Bit().data(), a); |
6918 | return *this; |
6919 | } |
6920 | |
6921 | unsigned flags = QLocalePrivate::NoFlags; |
6922 | if (fillChar == QLatin1Char('0')) |
6923 | flags = QLocalePrivate::ZeroPadded; |
6924 | |
6925 | if (qIsUpper(fmt)) |
6926 | flags |= QLocalePrivate::CapitalEorX; |
6927 | fmt = qToLower(fmt); |
6928 | |
6929 | QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal; |
6930 | switch (fmt) { |
6931 | case 'f': |
6932 | form = QLocalePrivate::DFDecimal; |
6933 | break; |
6934 | case 'e': |
6935 | form = QLocalePrivate::DFExponent; |
6936 | break; |
6937 | case 'g': |
6938 | form = QLocalePrivate::DFSignificantDigits; |
6939 | break; |
6940 | default: |
6941 | #if defined(QT_CHECK_RANGE) |
6942 | qWarning("QString::arg: Invalid format char '%c'" , fmt); |
6943 | #endif |
6944 | break; |
6945 | } |
6946 | |
6947 | QString arg; |
6948 | if (d.occurrences > d.locale_occurrences) |
6949 | arg = QLocale::c().d()->doubleToString(a, prec, form, fieldWidth, flags); |
6950 | |
6951 | QString locale_arg; |
6952 | if (d.locale_occurrences > 0) { |
6953 | QLocale locale; |
6954 | |
6955 | if (!locale.numberOptions() & QLocale::OmitGroupSeparator) |
6956 | flags |= QLocalePrivate::ThousandsGroup; |
6957 | locale_arg = locale.d()->doubleToString(a, prec, form, fieldWidth, flags); |
6958 | } |
6959 | |
6960 | return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg, fillChar); |
6961 | } |
6962 | |
6963 | static int getEscape(const QChar *uc, int *pos, int len, int maxNumber = 999) |
6964 | { |
6965 | int i = *pos; |
6966 | ++i; |
6967 | if (i < len && uc[i] == QLatin1Char('L')) |
6968 | ++i; |
6969 | if (i < len) { |
6970 | int escape = uc[i].unicode() - '0'; |
6971 | if (uint(escape) >= 10U) |
6972 | return -1; |
6973 | ++i; |
6974 | while (i < len) { |
6975 | int digit = uc[i].unicode() - '0'; |
6976 | if (uint(digit) >= 10U) |
6977 | break; |
6978 | escape = (escape * 10) + digit; |
6979 | ++i; |
6980 | } |
6981 | if (escape <= maxNumber) { |
6982 | *pos = i; |
6983 | return escape; |
6984 | } |
6985 | } |
6986 | return -1; |
6987 | } |
6988 | |
6989 | QString QString::multiArg(int numArgs, const QString **args) const |
6990 | { |
6991 | QString result; |
6992 | QMap<int, int> numbersUsed; |
6993 | const QChar *uc = (const QChar *) d->data; |
6994 | const int len = d->size; |
6995 | const int end = len - 1; |
6996 | int lastNumber = -1; |
6997 | int i = 0; |
6998 | |
6999 | // populate the numbersUsed map with the %n's that actually occur in the string |
7000 | while (i < end) { |
7001 | if (uc[i] == QLatin1Char('%')) { |
7002 | int number = getEscape(uc, &i, len); |
7003 | if (number != -1) { |
7004 | numbersUsed.insert(number, -1); |
7005 | continue; |
7006 | } |
7007 | } |
7008 | ++i; |
7009 | } |
7010 | |
7011 | // assign an argument number to each of the %n's |
7012 | QMap<int, int>::iterator j = numbersUsed.begin(); |
7013 | QMap<int, int>::iterator jend = numbersUsed.end(); |
7014 | int arg = 0; |
7015 | while (j != jend && arg < numArgs) { |
7016 | *j = arg++; |
7017 | lastNumber = j.key(); |
7018 | ++j; |
7019 | } |
7020 | |
7021 | // sanity |
7022 | if (numArgs > arg) { |
7023 | qWarning("QString::arg: %d argument(s) missing in %s" , numArgs - arg, toLocal8Bit().data()); |
7024 | numArgs = arg; |
7025 | } |
7026 | |
7027 | i = 0; |
7028 | while (i < len) { |
7029 | if (uc[i] == QLatin1Char('%') && i != end) { |
7030 | int number = getEscape(uc, &i, len, lastNumber); |
7031 | int arg = numbersUsed[number]; |
7032 | if (number != -1 && arg != -1) { |
7033 | result += *args[arg]; |
7034 | continue; |
7035 | } |
7036 | } |
7037 | result += uc[i++]; |
7038 | } |
7039 | return result; |
7040 | } |
7041 | |
7042 | static bool isStringRightToLeft(const ushort *p, const ushort *end) |
7043 | { |
7044 | bool righttoleft = false; |
7045 | while (p < end) { |
7046 | switch(QChar::direction(*p)) |
7047 | { |
7048 | case QChar::DirL: |
7049 | goto end; |
7050 | case QChar::DirR: |
7051 | case QChar::DirAL: |
7052 | righttoleft = true; |
7053 | goto end; |
7054 | default: |
7055 | break; |
7056 | } |
7057 | ++p; |
7058 | } |
7059 | end: |
7060 | return righttoleft; |
7061 | } |
7062 | |
7063 | /*! \internal |
7064 | */ |
7065 | void QString::updateProperties() const |
7066 | { |
7067 | ushort *p = d->data; |
7068 | ushort *end = p + d->size; |
7069 | d->simpletext = true; |
7070 | while (p < end) { |
7071 | ushort uc = *p; |
7072 | // sort out regions of complex text formatting |
7073 | if (uc > 0x058f && (uc < 0x1100 || uc > 0xfb0f)) { |
7074 | d->simpletext = false; |
7075 | } |
7076 | p++; |
7077 | } |
7078 | |
7079 | d->righttoleft = isStringRightToLeft(d->data, d->data + d->size); |
7080 | d->clean = true; |
7081 | } |
7082 | |
7083 | bool QString::isRightToLeft() const |
7084 | { |
7085 | return isStringRightToLeft(d->data, d->data + d->size); |
7086 | } |
7087 | |
7088 | /*! \fn bool QString::isSimpleText() const |
7089 | |
7090 | \internal |
7091 | */ |
7092 | |
7093 | /*! \fn bool QString::isRightToLeft() const |
7094 | |
7095 | Returns true if the string is read right to left. |
7096 | */ |
7097 | |
7098 | |
7099 | /*! \fn QChar *QString::data() |
7100 | |
7101 | Returns a pointer to the data stored in the QString. The pointer |
7102 | can be used to access and modify the characters that compose the |
7103 | string. For convenience, the data is '\\0'-terminated. |
7104 | |
7105 | Example: |
7106 | |
7107 | \snippet doc/src/snippets/qstring/main.cpp 19 |
7108 | |
7109 | Note that the pointer remains valid only as long as the string is |
7110 | not modified by other means. For read-only access, constData() is |
7111 | faster because it never causes a \l{deep copy} to occur. |
7112 | |
7113 | \sa constData(), operator[]() |
7114 | */ |
7115 | |
7116 | /*! \fn const QChar *QString::data() const |
7117 | |
7118 | \overload |
7119 | */ |
7120 | |
7121 | /*! \fn const QChar *QString::constData() const |
7122 | |
7123 | Returns a pointer to the data stored in the QString. The pointer |
7124 | can be used to access the characters that compose the string. For |
7125 | convenience, the data is '\\0'-terminated. |
7126 | |
7127 | Note that the pointer remains valid only as long as the string is |
7128 | not modified. |
7129 | |
7130 | \sa data(), operator[]() |
7131 | */ |
7132 | |
7133 | /*! \fn void QString::push_front(const QString &other) |
7134 | |
7135 | This function is provided for STL compatibility, prepending the |
7136 | given \a other string to the beginning of this string. It is |
7137 | equivalent to \c prepend(other). |
7138 | |
7139 | \sa prepend() |
7140 | */ |
7141 | |
7142 | /*! \fn void QString::push_front(QChar ch) |
7143 | |
7144 | \overload |
7145 | |
7146 | Prepends the given \a ch character to the beginning of this string. |
7147 | */ |
7148 | |
7149 | /*! \fn void QString::push_back(const QString &other) |
7150 | |
7151 | This function is provided for STL compatibility, appending the |
7152 | given \a other string onto the end of this string. It is |
7153 | equivalent to \c append(other). |
7154 | |
7155 | \sa append() |
7156 | */ |
7157 | |
7158 | /*! \fn void QString::push_back(QChar ch) |
7159 | |
7160 | \overload |
7161 | |
7162 | Appends the given \a ch character onto the end of this string. |
7163 | */ |
7164 | |
7165 | /*! |
7166 | \fn std::string QString::toStdString() const |
7167 | |
7168 | Returns a std::string object with the data contained in this |
7169 | QString. The Unicode data is converted into 8-bit characters using |
7170 | the toAscii() function. |
7171 | |
7172 | This operator is mostly useful to pass a QString to a function |
7173 | that accepts a std::string object. |
7174 | |
7175 | If the QString contains Unicode characters that the |
7176 | QTextCodec::codecForCStrings() codec cannot handle, using this operator |
7177 | can lead to loss of information. |
7178 | |
7179 | This operator is only available if Qt is configured with STL |
7180 | compatibility enabled. |
7181 | |
7182 | \sa toAscii(), toLatin1(), toUtf8(), toLocal8Bit() |
7183 | */ |
7184 | |
7185 | /*! |
7186 | Constructs a QString that uses the first \a size Unicode characters |
7187 | in the array \a unicode. The data in \a unicode is \e not |
7188 | copied. The caller must be able to guarantee that \a unicode will |
7189 | not be deleted or modified as long as the QString (or an |
7190 | unmodified copy of it) exists. |
7191 | |
7192 | Any attempts to modify the QString or copies of it will cause it |
7193 | to create a deep copy of the data, ensuring that the raw data |
7194 | isn't modified. |
7195 | |
7196 | Here's an example of how we can use a QRegExp on raw data in |
7197 | memory without requiring to copy the data into a QString: |
7198 | |
7199 | \snippet doc/src/snippets/qstring/main.cpp 22 |
7200 | \snippet doc/src/snippets/qstring/main.cpp 23 |
7201 | |
7202 | \warning A string created with fromRawData() is \e not |
7203 | '\\0'-terminated, unless the raw data contains a '\\0' character |
7204 | at position \a size. This means unicode() will \e not return a |
7205 | '\\0'-terminated string (although utf16() does, at the cost of |
7206 | copying the raw data). |
7207 | |
7208 | \sa fromUtf16(), setRawData() |
7209 | */ |
7210 | QString QString::fromRawData(const QChar *unicode, int size) |
7211 | { |
7212 | Data *x = static_cast<Data *>(qMalloc(sizeof(Data))); |
7213 | Q_CHECK_PTR(x); |
7214 | if (unicode) { |
7215 | x->data = (ushort *)unicode; |
7216 | } else { |
7217 | x->data = x->array; |
7218 | size = 0; |
7219 | } |
7220 | x->ref = 1; |
7221 | x->alloc = x->size = size; |
7222 | *x->array = '\0'; |
7223 | x->clean = x->asciiCache = x->simpletext = x->righttoleft = x->capacity = 0; |
7224 | return QString(x, 0); |
7225 | } |
7226 | |
7227 | /*! |
7228 | \since 4.7 |
7229 | |
7230 | Resets the QString to use the first \a size Unicode characters |
7231 | in the array \a unicode. The data in \a unicode is \e not |
7232 | copied. The caller must be able to guarantee that \a unicode will |
7233 | not be deleted or modified as long as the QString (or an |
7234 | unmodified copy of it) exists. |
7235 | |
7236 | This function can be used instead of fromRawData() to re-use |
7237 | existings QString objects to save memory re-allocations. |
7238 | |
7239 | \sa fromRawData() |
7240 | */ |
7241 | QString &QString::setRawData(const QChar *unicode, int size) |
7242 | { |
7243 | if (d->ref != 1 || (d->data == d->array && d->alloc)) { |
7244 | *this = fromRawData(unicode, size); |
7245 | } else { |
7246 | #ifdef QT3_SUPPORT |
7247 | if (d->asciiCache) { |
7248 | QMutexLocker locker(asciiCacheMutex()); |
7249 | Q_ASSERT(asciiCache); |
7250 | asciiCache->remove(d); |
7251 | } |
7252 | #endif |
7253 | if (unicode) { |
7254 | d->data = (ushort *)unicode; |
7255 | } else { |
7256 | d->data = d->array; |
7257 | size = 0; |
7258 | } |
7259 | d->alloc = d->size = size; |
7260 | *d->array = '\0'; |
7261 | d->clean = d->asciiCache = d->simpletext = d->righttoleft = d->capacity = 0; |
7262 | } |
7263 | return *this; |
7264 | } |
7265 | |
7266 | /*! \class QLatin1String |
7267 | \brief The QLatin1String class provides a thin wrapper around an US-ASCII/Latin-1 encoded string literal. |
7268 | |
7269 | \ingroup string-processing |
7270 | \reentrant |
7271 | |
7272 | Many of QString's member functions are overloaded to accept |
7273 | \c{const char *} instead of QString. This includes the copy |
7274 | constructor, the assignment operator, the comparison operators, |
7275 | and various other functions such as \link QString::insert() |
7276 | insert() \endlink, \link QString::replace() replace()\endlink, |
7277 | and \link QString::indexOf() indexOf()\endlink. These functions |
7278 | are usually optimized to avoid constructing a QString object for |
7279 | the \c{const char *} data. For example, assuming \c str is a |
7280 | QString, |
7281 | |
7282 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 3 |
7283 | |
7284 | is much faster than |
7285 | |
7286 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 4 |
7287 | |
7288 | because it doesn't construct four temporary QString objects and |
7289 | make a deep copy of the character data. |
7290 | |
7291 | Applications that define \c QT_NO_CAST_FROM_ASCII (as explained |
7292 | in the QString documentation) don't have access to QString's |
7293 | \c{const char *} API. To provide an efficient way of specifying |
7294 | constant Latin-1 strings, Qt provides the QLatin1String, which is |
7295 | just a very thin wrapper around a \c{const char *}. Using |
7296 | QLatin1String, the example code above becomes |
7297 | |
7298 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 5 |
7299 | |
7300 | This is a bit longer to type, but it provides exactly the same |
7301 | benefits as the first version of the code, and is faster than |
7302 | converting the Latin-1 strings using QString::fromLatin1(). |
7303 | |
7304 | Thanks to the QString(const QLatin1String &) constructor, |
7305 | QLatin1String can be used everywhere a QString is expected. For |
7306 | example: |
7307 | |
7308 | \snippet doc/src/snippets/code/src_corelib_tools_qstring.cpp 6 |
7309 | |
7310 | \sa QString, QLatin1Char |
7311 | */ |
7312 | |
7313 | /*! \fn QLatin1String::QLatin1String(const char *str) |
7314 | |
7315 | Constructs a QLatin1String object that stores \a str. Note that if |
7316 | \a str is 0, an empty string is created; this case is handled by |
7317 | QString. |
7318 | |
7319 | The string data is \e not copied. The caller must be able to |
7320 | guarantee that \a str will not be deleted or modified as long as |
7321 | the QLatin1String object exists. |
7322 | |
7323 | \sa latin1() |
7324 | */ |
7325 | |
7326 | /*! |
7327 | \since 4.1 |
7328 | \fn QLatin1String &QLatin1String::operator=(const QLatin1String &other) |
7329 | |
7330 | Constructs a copy of \a other. |
7331 | */ |
7332 | |
7333 | /*! \fn const char *QLatin1String::latin1() const |
7334 | |
7335 | Returns the Latin-1 string stored in this object. |
7336 | */ |
7337 | |
7338 | /*! \fn bool QLatin1String::operator==(const QString &other) const |
7339 | |
7340 | Returns true if this string is equal to string \a other; |
7341 | otherwise returns false. |
7342 | |
7343 | The comparison is based exclusively on the numeric Unicode values |
7344 | of the characters and is very fast, but is not what a human would |
7345 | expect. Consider sorting user-interface strings with |
7346 | QString::localeAwareCompare(). |
7347 | */ |
7348 | |
7349 | /*! |
7350 | \fn bool QLatin1String::operator==(const char *other) const |
7351 | \since 4.3 |
7352 | \overload |
7353 | |
7354 | The \a other const char pointer is converted to a QString using |
7355 | the QString::fromAscii() function. |
7356 | |
7357 | You can disable this operator by defining \c |
7358 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
7359 | can be useful if you want to ensure that all user-visible strings |
7360 | go through QObject::tr(), for example. |
7361 | */ |
7362 | |
7363 | /*! \fn bool QLatin1String::operator!=(const QString &other) const |
7364 | |
7365 | Returns true if this string is not equal to string \a other; |
7366 | otherwise returns false. |
7367 | |
7368 | The comparison is based exclusively on the numeric Unicode values |
7369 | of the characters and is very fast, but is not what a human would |
7370 | expect. Consider sorting user-interface strings with |
7371 | QString::localeAwareCompare(). |
7372 | */ |
7373 | |
7374 | /*! |
7375 | \fn bool QLatin1String::operator!=(const char *other) const |
7376 | \since 4.3 |
7377 | \overload operator!=() |
7378 | |
7379 | The \a other const char pointer is converted to a QString using |
7380 | the QString::fromAscii() function. |
7381 | |
7382 | You can disable this operator by defining \c |
7383 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
7384 | can be useful if you want to ensure that all user-visible strings |
7385 | go through QObject::tr(), for example. |
7386 | */ |
7387 | |
7388 | /*! |
7389 | \fn bool QLatin1String::operator>(const QString &other) const |
7390 | |
7391 | Returns true if this string is lexically greater than string \a |
7392 | other; otherwise returns false. |
7393 | |
7394 | The comparison is based exclusively on the numeric Unicode values |
7395 | of the characters and is very fast, but is not what a human would |
7396 | expect. Consider sorting user-interface strings with |
7397 | QString::localeAwareCompare(). |
7398 | */ |
7399 | |
7400 | /*! |
7401 | \fn bool QLatin1String::operator>(const char *other) const |
7402 | \since 4.3 |
7403 | \overload |
7404 | |
7405 | The \a other const char pointer is converted to a QString using |
7406 | the QString::fromAscii() function. |
7407 | |
7408 | You can disable this operator by defining \c QT_NO_CAST_FROM_ASCII |
7409 | when you compile your applications. This can be useful if you want |
7410 | to ensure that all user-visible strings go through QObject::tr(), |
7411 | for example. |
7412 | */ |
7413 | |
7414 | /*! |
7415 | \fn bool QLatin1String::operator<(const QString &other) const |
7416 | |
7417 | Returns true if this string is lexically less than the \a other |
7418 | string; otherwise returns false. |
7419 | |
7420 | The comparison is based exclusively on the numeric Unicode values |
7421 | of the characters and is very fast, but is not what a human would |
7422 | expect. Consider sorting user-interface strings using the |
7423 | QString::localeAwareCompare() function. |
7424 | */ |
7425 | |
7426 | /*! |
7427 | \fn bool QLatin1String::operator<(const char *other) const |
7428 | \since 4.3 |
7429 | \overload |
7430 | |
7431 | The \a other const char pointer is converted to a QString using |
7432 | the QString::fromAscii() function. |
7433 | |
7434 | You can disable this operator by defining \c |
7435 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
7436 | can be useful if you want to ensure that all user-visible strings |
7437 | go through QObject::tr(), for example. |
7438 | */ |
7439 | |
7440 | /*! |
7441 | \fn bool QLatin1String::operator>=(const QString &other) const |
7442 | |
7443 | Returns true if this string is lexically greater than or equal |
7444 | to string \a other; otherwise returns false. |
7445 | |
7446 | The comparison is based exclusively on the numeric Unicode values |
7447 | of the characters and is very fast, but is not what a human would |
7448 | expect. Consider sorting user-interface strings with |
7449 | QString::localeAwareCompare(). |
7450 | */ |
7451 | |
7452 | /*! |
7453 | \fn bool QLatin1String::operator>=(const char *other) const |
7454 | \since 4.3 |
7455 | \overload |
7456 | |
7457 | The \a other const char pointer is converted to a QString using |
7458 | the QString::fromAscii() function. |
7459 | |
7460 | You can disable this operator by defining \c |
7461 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
7462 | can be useful if you want to ensure that all user-visible strings |
7463 | go through QObject::tr(), for example. |
7464 | */ |
7465 | |
7466 | /*! \fn bool QLatin1String::operator<=(const QString &other) const |
7467 | |
7468 | Returns true if this string is lexically less than or equal |
7469 | to string \a other; otherwise returns false. |
7470 | |
7471 | The comparison is based exclusively on the numeric Unicode values |
7472 | of the characters and is very fast, but is not what a human would |
7473 | expect. Consider sorting user-interface strings with |
7474 | QString::localeAwareCompare(). |
7475 | */ |
7476 | |
7477 | /*! |
7478 | \fn bool QLatin1String::operator<=(const char *other) const |
7479 | \since 4.3 |
7480 | \overload |
7481 | |
7482 | The \a other const char pointer is converted to a QString using |
7483 | the QString::fromAscii() function. |
7484 | |
7485 | You can disable this operator by defining \c |
7486 | QT_NO_CAST_FROM_ASCII when you compile your applications. This |
7487 | can be useful if you want to ensure that all user-visible strings |
7488 | go through QObject::tr(), for example. |
7489 | */ |
7490 | |
7491 | |
7492 | |
7493 | /* \fn bool operator==(const QLatin1String &s1, const QLatin1String &s2) |
7494 | \relates QLatin1String |
7495 | |
7496 | Returns true if string \a s1 is lexically equal to string \a s2; otherwise |
7497 | returns false. |
7498 | */ |
7499 | /* \fn bool operator!=(const QLatin1String &s1, const QLatin1String &s2) |
7500 | \relates QLatin1String |
7501 | |
7502 | Returns true if string \a s1 is lexically unequal to string \a s2; otherwise |
7503 | returns false. |
7504 | */ |
7505 | /* \fn bool operator<(const QLatin1String &s1, const QLatin1String &s2) |
7506 | \relates QLatin1String |
7507 | |
7508 | Returns true if string \a s1 is lexically smaller than string \a s2; otherwise |
7509 | returns false. |
7510 | */ |
7511 | /* \fn bool operator<=(const QLatin1String &s1, const QLatin1String &s2) |
7512 | \relates QLatin1String |
7513 | |
7514 | Returns true if string \a s1 is lexically smaller than or equal to string \a s2; otherwise |
7515 | returns false. |
7516 | */ |
7517 | /* \fn bool operator>(const QLatin1String &s1, const QLatin1String &s2) |
7518 | \relates QLatin1String |
7519 | |
7520 | Returns true if string \a s1 is lexically greater than string \a s2; otherwise |
7521 | returns false. |
7522 | */ |
7523 | /* \fn bool operator>=(const QLatin1String &s1, const QLatin1String &s2) |
7524 | \relates QLatin1String |
7525 | |
7526 | Returns true if string \a s1 is lexically greater than or equal to |
7527 | string \a s2; otherwise returns false. |
7528 | */ |
7529 | |
7530 | |
7531 | #if !defined(QT_NO_DATASTREAM) || (defined(QT_BOOTSTRAPPED) && !defined(QT_BUILD_QMAKE)) |
7532 | /*! |
7533 | \fn QDataStream &operator<<(QDataStream &stream, const QString &string) |
7534 | \relates QString |
7535 | |
7536 | Writes the given \a string to the specified \a stream. |
7537 | |
7538 | \sa {Serializing Qt Data Types} |
7539 | */ |
7540 | |
7541 | QDataStream &operator<<(QDataStream &out, const QString &str) |
7542 | { |
7543 | if (out.version() == 1) { |
7544 | out << str.toLatin1(); |
7545 | } else { |
7546 | if (!str.isNull() || out.version() < 3) { |
7547 | if ((out.byteOrder() == QDataStream::BigEndian) == (QSysInfo::ByteOrder == QSysInfo::BigEndian)) { |
7548 | out.writeBytes(reinterpret_cast<const char *>(str.unicode()), sizeof(QChar) * str.length()); |
7549 | } else { |
7550 | QVarLengthArray<ushort> buffer(str.length()); |
7551 | const ushort *data = reinterpret_cast<const ushort *>(str.constData()); |
7552 | for (int i = 0; i < str.length(); i++) { |
7553 | buffer[i] = qbswap(*data); |
7554 | ++data; |
7555 | } |
7556 | out.writeBytes(reinterpret_cast<const char *>(buffer.data()), sizeof(ushort) * buffer.size()); |
7557 | } |
7558 | } else { |
7559 | // write null marker |
7560 | out << (quint32)0xffffffff; |
7561 | } |
7562 | } |
7563 | return out; |
7564 | } |
7565 | |
7566 | /*! |
7567 | \fn QDataStream &operator>>(QDataStream &stream, QString &string) |
7568 | \relates QString |
7569 | |
7570 | Reads a string from the specified \a stream into the given \a string. |
7571 | |
7572 | \sa {Serializing Qt Data Types} |
7573 | */ |
7574 | |
7575 | QDataStream &operator>>(QDataStream &in, QString &str) |
7576 | { |
7577 | #ifdef QT_QSTRING_UCS_4 |
7578 | #if defined(Q_CC_GNU) |
7579 | #warning "operator>> not working properly" |
7580 | #endif |
7581 | #endif |
7582 | |
7583 | if (in.version() == 1) { |
7584 | QByteArray l; |
7585 | in >> l; |
7586 | str = QString::fromLatin1(l); |
7587 | } else { |
7588 | quint32 bytes = 0; |
7589 | in >> bytes; // read size of string |
7590 | if (bytes == 0xffffffff) { // null string |
7591 | str.clear(); |
7592 | } else if (bytes > 0) { // not empty |
7593 | if (bytes & 0x1) { |
7594 | str.clear(); |
7595 | in.setStatus(QDataStream::ReadCorruptData); |
7596 | return in; |
7597 | } |
7598 | |
7599 | const quint32 Step = 1024 * 1024; |
7600 | quint32 len = bytes / 2; |
7601 | quint32 allocated = 0; |
7602 | |
7603 | while (allocated < len) { |
7604 | int blockSize = qMin(Step, len - allocated); |
7605 | str.resize(allocated + blockSize); |
7606 | if (in.readRawData(reinterpret_cast<char *>(str.data()) + allocated * 2, |
7607 | blockSize * 2) != blockSize * 2) { |
7608 | str.clear(); |
7609 | in.setStatus(QDataStream::ReadPastEnd); |
7610 | return in; |
7611 | } |
7612 | allocated += blockSize; |
7613 | } |
7614 | |
7615 | if ((in.byteOrder() == QDataStream::BigEndian) |
7616 | != (QSysInfo::ByteOrder == QSysInfo::BigEndian)) { |
7617 | ushort *data = reinterpret_cast<ushort *>(str.data()); |
7618 | while (len--) { |
7619 | *data = qbswap(*data); |
7620 | ++data; |
7621 | } |
7622 | } |
7623 | } else { |
7624 | str = QLatin1String("" ); |
7625 | } |
7626 | } |
7627 | return in; |
7628 | } |
7629 | #endif // QT_NO_DATASTREAM |
7630 | |
7631 | /*! |
7632 | \fn void QString::setLength(int nl) |
7633 | |
7634 | Use resize() instead. |
7635 | */ |
7636 | |
7637 | /*! |
7638 | \fn QString QString::copy() const |
7639 | |
7640 | Use simple assignment instead. QString is implicitly shared so if |
7641 | a copy is modified only the copy is changed. |
7642 | */ |
7643 | |
7644 | /*! |
7645 | \fn QString &QString::remove(QChar c, bool cs) |
7646 | |
7647 | Use the remove(QChar, Qt::CaseSensitive) overload instead. |
7648 | */ |
7649 | |
7650 | /*! |
7651 | \fn QString &QString::remove(const QString &s, bool cs) |
7652 | |
7653 | Use the remove(QString, Qt::CaseSensitive) overload instead. |
7654 | */ |
7655 | |
7656 | /*! |
7657 | \fn QString &QString::replace(QChar c, const QString &after, bool cs) |
7658 | |
7659 | Use the replace(QChar, QString, Qt::CaseSensitive) overload instead. |
7660 | */ |
7661 | |
7662 | /*! |
7663 | \fn QString &QString::replace(const QString &before, const QString &after, bool cs) |
7664 | |
7665 | Use the replace(QString, QString, Qt::CaseSensitive) overload instead. |
7666 | */ |
7667 | |
7668 | /*! |
7669 | \fn QString &QString::replace(char c, const QString &after, bool cs) |
7670 | |
7671 | Use the replace(QChar, QString, Qt::CaseSensitive) overload instead. |
7672 | */ |
7673 | |
7674 | /*! |
7675 | \fn QString &QString::replace(char c, const QString &after, Qt::CaseSensitivity cs) |
7676 | |
7677 | Use the replace(QChar, QString, Qt::CaseSensitive) overload instead. |
7678 | */ |
7679 | |
7680 | /*! |
7681 | \fn int QString::find(QChar c, int i = 0, bool cs = true) const |
7682 | |
7683 | Use indexOf() instead. |
7684 | */ |
7685 | |
7686 | /*! |
7687 | \fn int QString::find(const QString &s, int i = 0, bool cs = true) const |
7688 | |
7689 | Use indexOf() instead. |
7690 | */ |
7691 | |
7692 | /*! |
7693 | \fn int QString::findRev(QChar c, int i = -1, bool cs = true) const |
7694 | |
7695 | Use lastIndexOf() instead. |
7696 | */ |
7697 | |
7698 | /*! |
7699 | \fn int QString::findRev(const QString &s, int i = -1, bool cs = true) const |
7700 | |
7701 | Use lastIndexOf() instead. |
7702 | */ |
7703 | |
7704 | /*! |
7705 | \fn int QString::find(const QRegExp &rx, int i=0) const |
7706 | |
7707 | Use indexOf() instead. |
7708 | */ |
7709 | |
7710 | /*! |
7711 | \fn int QString::find(QRegExp &rx, int i=0) const |
7712 | \internal |
7713 | \since 4.5 |
7714 | |
7715 | Use indexOf() instead. |
7716 | */ |
7717 | |
7718 | /*! |
7719 | \fn int QString::findRev(const QRegExp &rx, int i=-1) const |
7720 | |
7721 | Use lastIndexOf() instead. |
7722 | */ |
7723 | |
7724 | /*! |
7725 | \fn int QString::findRev(QRegExp &rx, int i=0) const |
7726 | \internal |
7727 | \since 4.5 |
7728 | |
7729 | Use lastIndexOf() instead. |
7730 | */ |
7731 | |
7732 | /*! |
7733 | \fn QBool QString::contains(QChar c, bool cs) const |
7734 | |
7735 | Use the contains(QChar, Qt::CaseSensitive) overload instead. |
7736 | */ |
7737 | |
7738 | /*! |
7739 | \fn QBool QString::contains(const QString &s, bool cs) const |
7740 | |
7741 | Use the contains(QString, Qt::CaseSensitive) overload instead. |
7742 | */ |
7743 | |
7744 | /*! |
7745 | \fn bool QString::startsWith(const QString &s, bool cs) const |
7746 | |
7747 | Use the startsWith(QString, Qt::CaseSensitive) overload instead. |
7748 | */ |
7749 | |
7750 | |
7751 | /*! |
7752 | \fn bool QString::endsWith(const QString &s, bool cs) const |
7753 | |
7754 | Use the endsWith(QString, Qt::CaseSensitive) overload instead. |
7755 | */ |
7756 | |
7757 | /*! |
7758 | \fn QString QString::leftJustify(int width, QChar fill = QLatin1Char(' '), bool trunc=false) const |
7759 | |
7760 | Use leftJustified() instead. |
7761 | */ |
7762 | |
7763 | /*! |
7764 | \fn QString QString::rightJustify(int width, QChar fill = QLatin1Char(' '), bool trunc=false) const |
7765 | |
7766 | Use rightJustified() instead. |
7767 | */ |
7768 | |
7769 | /*! |
7770 | \fn QString QString::lower() const |
7771 | |
7772 | Use toLower() instead. |
7773 | */ |
7774 | |
7775 | /*! |
7776 | \fn QString QString::upper() const |
7777 | |
7778 | Use toUpper() instead. |
7779 | */ |
7780 | |
7781 | /*! |
7782 | \fn QString QString::stripWhiteSpace() const |
7783 | |
7784 | Use trimmed() instead. |
7785 | */ |
7786 | |
7787 | /*! |
7788 | \fn QString QString::simplifyWhiteSpace() const |
7789 | |
7790 | Use simplified() instead. |
7791 | */ |
7792 | |
7793 | /*! |
7794 | \fn QString &QString::setUnicodeCodes(const ushort *unicode_as_ushorts, int size) |
7795 | |
7796 | Use setUtf16() instead. |
7797 | */ |
7798 | |
7799 | /*! |
7800 | \fn ushort *QString::ucs2() const |
7801 | |
7802 | Use utf16() instead. |
7803 | */ |
7804 | |
7805 | /*! |
7806 | \fn QString QString::fromUcs2(const ushort *unicode, int size = -1) |
7807 | |
7808 | Use fromUtf16() instead. |
7809 | */ |
7810 | |
7811 | /*! |
7812 | \fn QString &QString::setAscii(const char *str, int len = -1) |
7813 | |
7814 | Use fromAscii() instead. |
7815 | */ |
7816 | |
7817 | /*! |
7818 | \fn QString &QString::setLatin1(const char *str, int len = -1) |
7819 | |
7820 | Use fromLatin1() instead. |
7821 | */ |
7822 | |
7823 | /*! |
7824 | \fn QChar QString::constref(uint i) const |
7825 | |
7826 | Use at() instead. |
7827 | */ |
7828 | |
7829 | /*! |
7830 | \fn QChar &QString::ref(uint i); |
7831 | |
7832 | Use operator[]() instead. |
7833 | */ |
7834 | |
7835 | /*! |
7836 | \fn QString::operator const char *() const |
7837 | |
7838 | Use toAscii().constData() instead. |
7839 | */ |
7840 | |
7841 | /*! |
7842 | \class QConstString |
7843 | \brief The QConstString class is a wrapper for constant Unicode string data. |
7844 | \compat |
7845 | |
7846 | In Qt 4, QConstString is replaced by QString::fromRawData(), a |
7847 | static function that constructs a QString object based on Unicode |
7848 | string data. |
7849 | |
7850 | Because QString::fromRawData() has slightly more stringent |
7851 | constraints than QConstString had in Qt 3, the new QConstString |
7852 | class takes a deep copy of the string data. |
7853 | |
7854 | \sa QString::fromRawData() |
7855 | */ |
7856 | |
7857 | /*! |
7858 | \fn QConstString::QConstString(const QChar *unicode, int size) |
7859 | |
7860 | Use QString(\a unicode, \a size) or |
7861 | QString::fromRawData(\a unicode, \a size) instead. |
7862 | */ |
7863 | |
7864 | /*! |
7865 | \fn const QString &QConstString::string() const |
7866 | |
7867 | Returns \c *this. Not necessary in Qt 4. |
7868 | */ |
7869 | |
7870 | |
7871 | |
7872 | /*! |
7873 | \class QStringRef |
7874 | \since 4.3 |
7875 | \brief The QStringRef class provides a thin wrapper around QString substrings. |
7876 | \reentrant |
7877 | \ingroup tools |
7878 | \ingroup string-processing |
7879 | |
7880 | QStringRef provides a read-only subset of the QString API. |
7881 | |
7882 | A string reference explicitly references a portion of a string() |
7883 | with a given size(), starting at a specific position(). Calling |
7884 | toString() returns a copy of the data as a real QString instance. |
7885 | |
7886 | This class is designed to improve the performance of substring |
7887 | handling when manipulating substrings obtained from existing QString |
7888 | instances. QStringRef avoids the memory allocation and reference |
7889 | counting overhead of a standard QString by simply referencing a |
7890 | part of the original string. This can prove to be advantageous in |
7891 | low level code, such as that used in a parser, at the expense of |
7892 | potentially more complex code. |
7893 | |
7894 | For most users, there are no semantic benefits to using QStringRef |
7895 | instead of QString since QStringRef requires attention to be paid |
7896 | to memory management issues, potentially making code more complex |
7897 | to write and maintain. |
7898 | |
7899 | \warning A QStringRef is only valid as long as the referenced |
7900 | string exists. If the original string is deleted, the string |
7901 | reference points to an invalid memory location. |
7902 | |
7903 | We suggest that you only use this class in stable code where profiling |
7904 | has clearly identified that performance improvements can be made by |
7905 | replacing standard string operations with the optimized substring |
7906 | handling provided by this class. |
7907 | |
7908 | \sa {Implicitly Shared Classes} |
7909 | */ |
7910 | |
7911 | |
7912 | /*! |
7913 | \fn QStringRef::QStringRef() |
7914 | |
7915 | Constructs an empty string reference. |
7916 | */ |
7917 | |
7918 | /*! \fn QStringRef::QStringRef(const QString *string, int position, int length) |
7919 | |
7920 | Constructs a string reference to the range of characters in the given |
7921 | \a string specified by the starting \a position and \a length in characters. |
7922 | |
7923 | \warning This function exists to improve performance as much as possible, |
7924 | and performs no bounds checking. For program correctness, \a position and |
7925 | \a length must describe a valid substring of \a string. |
7926 | |
7927 | This means that the starting \a position must be positive or 0 and smaller |
7928 | than \a string's length, and \a length must be positive or 0 but smaller than |
7929 | the string's length minus the starting \a position; |
7930 | i.e, 0 <= position < string->length() and |
7931 | 0 <= length <= string->length() - position must both be satisfied. |
7932 | */ |
7933 | |
7934 | /*! \fn QStringRef::QStringRef(const QString *string) |
7935 | |
7936 | Constructs a string reference to the given \a string. |
7937 | */ |
7938 | |
7939 | /*! \fn QStringRef::QStringRef(const QStringRef &other) |
7940 | |
7941 | Constructs a copy of the \a other string reference. |
7942 | */ |
7943 | /*! |
7944 | \fn QStringRef::~QStringRef() |
7945 | |
7946 | Destroys the string reference. |
7947 | |
7948 | Since this class is only used to refer to string data, and does not take |
7949 | ownership of it, no memory is freed when instances are destroyed. |
7950 | */ |
7951 | |
7952 | |
7953 | /*! |
7954 | \fn int QStringRef::position() const |
7955 | |
7956 | Returns the starting position in the referenced string that is referred to |
7957 | by the string reference. |
7958 | |
7959 | \sa size(), string() |
7960 | */ |
7961 | |
7962 | /*! |
7963 | \fn int QStringRef::size() const |
7964 | |
7965 | Returns the number of characters referred to by the string reference. |
7966 | Equivalent to length() and count(). |
7967 | |
7968 | \sa position(), string() |
7969 | */ |
7970 | /*! |
7971 | \fn int QStringRef::count() const |
7972 | Returns the number of characters referred to by the string reference. |
7973 | Equivalent to size() and length(). |
7974 | |
7975 | \sa position(), string() |
7976 | */ |
7977 | /*! |
7978 | \fn int QStringRef::length() const |
7979 | Returns the number of characters referred to by the string reference. |
7980 | Equivalent to size() and count(). |
7981 | |
7982 | \sa position(), string() |
7983 | */ |
7984 | |
7985 | |
7986 | /*! |
7987 | \fn bool QStringRef::isEmpty() const |
7988 | |
7989 | Returns true if the string reference has no characters; otherwise returns |
7990 | false. |
7991 | |
7992 | A string reference is empty if its size is zero. |
7993 | |
7994 | \sa size() |
7995 | */ |
7996 | |
7997 | /*! |
7998 | \fn bool QStringRef::isNull() const |
7999 | |
8000 | Returns true if string() returns a null pointer or a pointer to a |
8001 | null string; otherwise returns true. |
8002 | |
8003 | \sa size() |
8004 | */ |
8005 | |
8006 | /*! |
8007 | \fn const QString *QStringRef::string() const |
8008 | |
8009 | Returns a pointer to the string referred to by the string reference, or |
8010 | 0 if it does not reference a string. |
8011 | |
8012 | \sa unicode() |
8013 | */ |
8014 | |
8015 | |
8016 | /*! |
8017 | \fn const QChar *QStringRef::unicode() const |
8018 | |
8019 | Returns a Unicode representation of the string reference. Since |
8020 | the data stems directly from the referenced string, it is not |
8021 | null-terminated unless the string reference includes the string's |
8022 | null terminator. |
8023 | |
8024 | \sa string() |
8025 | */ |
8026 | |
8027 | /*! |
8028 | \fn const QChar *QStringRef::data() const |
8029 | |
8030 | Same as unicode(). |
8031 | */ |
8032 | |
8033 | /*! |
8034 | \fn const QChar *QStringRef::constData() const |
8035 | |
8036 | Same as unicode(). |
8037 | */ |
8038 | |
8039 | /*! |
8040 | Returns a copy of the string reference as a QString object. |
8041 | |
8042 | If the string reference is not a complete reference of the string |
8043 | (meaning that position() is 0 and size() equals string()->size()), |
8044 | this function will allocate a new string to return. |
8045 | |
8046 | \sa string() |
8047 | */ |
8048 | |
8049 | QString QStringRef::toString() const { |
8050 | if (!m_string) |
8051 | return QString(); |
8052 | if (m_size && m_position == 0 && m_size == m_string->size()) |
8053 | return *m_string; |
8054 | return QString(m_string->unicode() + m_position, m_size); |
8055 | } |
8056 | |
8057 | |
8058 | /*! \relates QStringRef |
8059 | |
8060 | Returns true if string reference \a s1 is lexically equal to string reference \a s2; otherwise |
8061 | returns false. |
8062 | */ |
8063 | bool operator==(const QStringRef &s1,const QStringRef &s2) |
8064 | { return (s1.size() == s2.size() && |
8065 | qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size())); |
8066 | } |
8067 | |
8068 | /*! \relates QStringRef |
8069 | |
8070 | Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise |
8071 | returns false. |
8072 | */ |
8073 | bool operator==(const QString &s1,const QStringRef &s2) |
8074 | { return (s1.size() == s2.size() && |
8075 | qMemEquals((const ushort *)s1.unicode(), (const ushort *)s2.unicode(), s1.size())); |
8076 | } |
8077 | |
8078 | /*! \relates QStringRef |
8079 | |
8080 | Returns true if string \a s1 is lexically equal to string reference \a s2; otherwise |
8081 | returns false. |
8082 | */ |
8083 | bool operator==(const QLatin1String &s1, const QStringRef &s2) |
8084 | { |
8085 | const ushort *uc = reinterpret_cast<const ushort *>(s2.unicode()); |
8086 | const ushort *e = uc + s2.size(); |
8087 | const uchar *c = reinterpret_cast<const uchar *>(s1.latin1()); |
8088 | if (!c) |
8089 | return s2.isEmpty(); |
8090 | |
8091 | while (*c) { |
8092 | if (uc == e || *uc != *c) |
8093 | return false; |
8094 | ++uc; |
8095 | ++c; |
8096 | } |
8097 | return (uc == e); |
8098 | } |
8099 | |
8100 | /*! |
8101 | \relates QStringRef |
8102 | |
8103 | Returns true if string reference \a s1 is lexically less than |
8104 | string reference \a s2; otherwise returns false. |
8105 | |
8106 | The comparison is based exclusively on the numeric Unicode values |
8107 | of the characters and is very fast, but is not what a human would |
8108 | expect. Consider sorting user-interface strings using the |
8109 | QString::localeAwareCompare() function. |
8110 | */ |
8111 | bool operator<(const QStringRef &s1,const QStringRef &s2) |
8112 | { |
8113 | return ucstrcmp(s1.constData(), s1.length(), s2.constData(), s2.length()) < 0; |
8114 | } |
8115 | |
8116 | /*!\fn bool operator<=(const QStringRef &s1,const QStringRef &s2) |
8117 | |
8118 | \relates QStringRef |
8119 | |
8120 | Returns true if string reference \a s1 is lexically less than |
8121 | or equal to string reference \a s2; otherwise returns false. |
8122 | |
8123 | The comparison is based exclusively on the numeric Unicode values |
8124 | of the characters and is very fast, but is not what a human would |
8125 | expect. Consider sorting user-interface strings using the |
8126 | QString::localeAwareCompare() function. |
8127 | */ |
8128 | |
8129 | /*!\fn bool operator>=(const QStringRef &s1,const QStringRef &s2) |
8130 | |
8131 | \relates QStringRef |
8132 | |
8133 | Returns true if string reference \a s1 is lexically greater than |
8134 | or equal to string reference \a s2; otherwise returns false. |
8135 | |
8136 | The comparison is based exclusively on the numeric Unicode values |
8137 | of the characters and is very fast, but is not what a human would |
8138 | expect. Consider sorting user-interface strings using the |
8139 | QString::localeAwareCompare() function. |
8140 | */ |
8141 | |
8142 | /*!\fn bool operator>(const QStringRef &s1,const QStringRef &s2) |
8143 | |
8144 | \relates QStringRef |
8145 | |
8146 | Returns true if string reference \a s1 is lexically greater than |
8147 | string reference \a s2; otherwise returns false. |
8148 | |
8149 | The comparison is based exclusively on the numeric Unicode values |
8150 | of the characters and is very fast, but is not what a human would |
8151 | expect. Consider sorting user-interface strings using the |
8152 | QString::localeAwareCompare() function. |
8153 | */ |
8154 | |
8155 | |
8156 | /*! |
8157 | \fn const QChar QStringRef::at(int position) const |
8158 | |
8159 | Returns the character at the given index \a position in the |
8160 | string reference. |
8161 | |
8162 | The \a position must be a valid index position in the string |
8163 | (i.e., 0 <= \a position < size()). |
8164 | */ |
8165 | |
8166 | /*! |
8167 | \fn void QStringRef::clear() |
8168 | |
8169 | Clears the contents of the string reference by making it null and empty. |
8170 | |
8171 | \sa isEmpty(), isNull() |
8172 | */ |
8173 | |
8174 | /*! |
8175 | \fn QStringRef &QStringRef::operator=(const QStringRef &other) |
8176 | |
8177 | Assigns the \a other string reference to this string reference, and |
8178 | returns the result. |
8179 | */ |
8180 | |
8181 | /*! |
8182 | \fn QStringRef &QStringRef::operator=(const QString *string) |
8183 | |
8184 | Constructs a string reference to the given \a string and assigns it to |
8185 | this string reference, returning the result. |
8186 | */ |
8187 | |
8188 | /*! |
8189 | \typedef QString::DataPtr |
8190 | \internal |
8191 | */ |
8192 | |
8193 | /*! |
8194 | \fn DataPtr & QString::data_ptr() |
8195 | \internal |
8196 | */ |
8197 | |
8198 | |
8199 | |
8200 | /*! Appends the string reference to \a string, and returns a new |
8201 | reference to the combined string data. |
8202 | */ |
8203 | QStringRef QStringRef::appendTo(QString *string) const |
8204 | { |
8205 | if (!string) |
8206 | return QStringRef(); |
8207 | int pos = string->size(); |
8208 | string->insert(pos, unicode(), size()); |
8209 | return QStringRef(string, pos, size()); |
8210 | } |
8211 | |
8212 | /*! |
8213 | \fn int QStringRef::compare(const QStringRef &s1, const QString &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
8214 | \since 4.5 |
8215 | |
8216 | Compares the string \a s1 with the string \a s2 and returns an |
8217 | integer less than, equal to, or greater than zero if \a s1 |
8218 | is less than, equal to, or greater than \a s2. |
8219 | |
8220 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8221 | otherwise the comparison is case insensitive. |
8222 | */ |
8223 | |
8224 | /*! |
8225 | \fn int QStringRef::compare(const QStringRef &s1, const QStringRef &s2, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
8226 | \since 4.5 |
8227 | \overload |
8228 | |
8229 | Compares the string \a s1 with the string \a s2 and returns an |
8230 | integer less than, equal to, or greater than zero if \a s1 |
8231 | is less than, equal to, or greater than \a s2. |
8232 | |
8233 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8234 | otherwise the comparison is case insensitive. |
8235 | */ |
8236 | |
8237 | /*! |
8238 | \fn int QStringRef::compare(const QStringRef &s1, QLatin1String s2, Qt::CaseSensitivity cs = Qt::CaseSensitive) |
8239 | \since 4.5 |
8240 | \overload |
8241 | |
8242 | Compares the string \a s1 with the string \a s2 and returns an |
8243 | integer less than, equal to, or greater than zero if \a s1 |
8244 | is less than, equal to, or greater than \a s2. |
8245 | |
8246 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8247 | otherwise the comparison is case insensitive. |
8248 | */ |
8249 | |
8250 | /*! |
8251 | \overload |
8252 | \fn int QStringRef::compare(const QString &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8253 | \since 4.5 |
8254 | |
8255 | Compares this string with the \a other string and returns an |
8256 | integer less than, equal to, or greater than zero if this string |
8257 | is less than, equal to, or greater than the \a other string. |
8258 | |
8259 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8260 | otherwise the comparison is case insensitive. |
8261 | |
8262 | Equivalent to \c {compare(*this, other, cs)}. |
8263 | |
8264 | \sa QString::compare() |
8265 | */ |
8266 | |
8267 | /*! |
8268 | \overload |
8269 | \fn int QStringRef::compare(const QStringRef &other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8270 | \since 4.5 |
8271 | |
8272 | Compares this string with the \a other string and returns an |
8273 | integer less than, equal to, or greater than zero if this string |
8274 | is less than, equal to, or greater than the \a other string. |
8275 | |
8276 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8277 | otherwise the comparison is case insensitive. |
8278 | |
8279 | Equivalent to \c {compare(*this, other, cs)}. |
8280 | |
8281 | \sa QString::compare() |
8282 | */ |
8283 | |
8284 | /*! |
8285 | \overload |
8286 | \fn int QStringRef::compare(QLatin1String other, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8287 | \since 4.5 |
8288 | |
8289 | Compares this string with the \a other string and returns an |
8290 | integer less than, equal to, or greater than zero if this string |
8291 | is less than, equal to, or greater than the \a other string. |
8292 | |
8293 | If \a cs is Qt::CaseSensitive, the comparison is case sensitive; |
8294 | otherwise the comparison is case insensitive. |
8295 | |
8296 | Equivalent to \c {compare(*this, other, cs)}. |
8297 | |
8298 | \sa QString::compare() |
8299 | */ |
8300 | |
8301 | /*! |
8302 | \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QString & s2) |
8303 | \since 4.5 |
8304 | |
8305 | Compares \a s1 with \a s2 and returns an integer less than, equal |
8306 | to, or greater than zero if \a s1 is less than, equal to, or |
8307 | greater than \a s2. |
8308 | |
8309 | The comparison is performed in a locale- and also |
8310 | platform-dependent manner. Use this function to present sorted |
8311 | lists of strings to the user. |
8312 | |
8313 | On Mac OS X, this function compares according the |
8314 | "Order for sorted lists" setting in the International prefereces panel. |
8315 | |
8316 | \sa compare(), QTextCodec::locale() |
8317 | */ |
8318 | |
8319 | /*! |
8320 | \fn int QStringRef::localeAwareCompare(const QStringRef &s1, const QStringRef & s2) |
8321 | \since 4.5 |
8322 | \overload |
8323 | |
8324 | Compares \a s1 with \a s2 and returns an integer less than, equal |
8325 | to, or greater than zero if \a s1 is less than, equal to, or |
8326 | greater than \a s2. |
8327 | |
8328 | The comparison is performed in a locale- and also |
8329 | platform-dependent manner. Use this function to present sorted |
8330 | lists of strings to the user. |
8331 | |
8332 | */ |
8333 | |
8334 | /*! |
8335 | \fn int QStringRef::localeAwareCompare(const QString &other) const |
8336 | \since 4.5 |
8337 | \overload |
8338 | |
8339 | Compares this string with the \a other string and returns an |
8340 | integer less than, equal to, or greater than zero if this string |
8341 | is less than, equal to, or greater than the \a other string. |
8342 | |
8343 | The comparison is performed in a locale- and also |
8344 | platform-dependent manner. Use this function to present sorted |
8345 | lists of strings to the user. |
8346 | */ |
8347 | |
8348 | /*! |
8349 | \fn int QStringRef::localeAwareCompare(const QStringRef &other) const |
8350 | \since 4.5 |
8351 | \overload |
8352 | |
8353 | Compares this string with the \a other string and returns an |
8354 | integer less than, equal to, or greater than zero if this string |
8355 | is less than, equal to, or greater than the \a other string. |
8356 | |
8357 | The comparison is performed in a locale- and also |
8358 | platform-dependent manner. Use this function to present sorted |
8359 | lists of strings to the user. |
8360 | */ |
8361 | |
8362 | /*! |
8363 | \fn QString &QString::append(const QStringRef &reference) |
8364 | \since 4.4 |
8365 | |
8366 | Appends the given string \a reference to this string and returns the result. |
8367 | */ |
8368 | QString &QString::append(const QStringRef &str) |
8369 | { |
8370 | if (str.string() == this) { |
8371 | str.appendTo(this); |
8372 | } else if (str.string()) { |
8373 | int oldSize = size(); |
8374 | resize(oldSize + str.size()); |
8375 | memcpy(data() + oldSize, str.unicode(), str.size() * sizeof(QChar)); |
8376 | } |
8377 | return *this; |
8378 | } |
8379 | |
8380 | /*! |
8381 | \since 4.4 |
8382 | |
8383 | Returns a substring reference to the \a n leftmost characters |
8384 | of the string. |
8385 | |
8386 | If \a n is greater than size() or less than zero, a reference to the entire |
8387 | string is returned. |
8388 | |
8389 | \snippet doc/src/snippets/qstring/main.cpp leftRef |
8390 | |
8391 | \sa left(), rightRef(), midRef(), startsWith() |
8392 | */ |
8393 | QStringRef QString::leftRef(int n) const |
8394 | { |
8395 | if (n >= d->size || n < 0) |
8396 | n = d->size; |
8397 | return QStringRef(this, 0, n); |
8398 | } |
8399 | |
8400 | /*! |
8401 | \since 4.4 |
8402 | |
8403 | Returns a substring reference to the \a n rightmost characters |
8404 | of the string. |
8405 | |
8406 | If \a n is greater than size() or less than zero, a reference to the entire |
8407 | string is returned. |
8408 | |
8409 | \snippet doc/src/snippets/qstring/main.cpp rightRef |
8410 | |
8411 | \sa right(), leftRef(), midRef(), endsWith() |
8412 | */ |
8413 | QStringRef QString::rightRef(int n) const |
8414 | { |
8415 | if (n >= d->size || n < 0) |
8416 | n = d->size; |
8417 | return QStringRef(this, d->size - n, n); |
8418 | } |
8419 | |
8420 | /*! |
8421 | \since 4.4 |
8422 | |
8423 | Returns a substring reference to \a n characters of this string, |
8424 | starting at the specified \a position. |
8425 | |
8426 | If the \a position exceeds the length of the string, an empty |
8427 | reference is returned. |
8428 | |
8429 | If there are less than \a n characters available in the string, |
8430 | starting at the given \a position, or if \a n is -1 (default), the |
8431 | function returns all characters from the specified \a position |
8432 | onwards. |
8433 | |
8434 | Example: |
8435 | |
8436 | \snippet doc/src/snippets/qstring/main.cpp midRef |
8437 | |
8438 | \sa mid(), leftRef(), rightRef() |
8439 | */ |
8440 | |
8441 | QStringRef QString::midRef(int position, int n) const |
8442 | { |
8443 | if (d == &shared_null || position >= d->size) |
8444 | return QStringRef(); |
8445 | if (n < 0) |
8446 | n = d->size - position; |
8447 | if (position < 0) { |
8448 | n += position; |
8449 | position = 0; |
8450 | } |
8451 | if (n + position > d->size) |
8452 | n = d->size - position; |
8453 | return QStringRef(this, position, n); |
8454 | } |
8455 | |
8456 | /*! |
8457 | \since 4.8 |
8458 | |
8459 | Returns the index position of the first occurrence of the string \a |
8460 | str in this string reference, searching forward from index position |
8461 | \a from. Returns -1 if \a str is not found. |
8462 | |
8463 | If \a cs is Qt::CaseSensitive (default), the search is case |
8464 | sensitive; otherwise the search is case insensitive. |
8465 | |
8466 | If \a from is -1, the search starts at the last character; if it is |
8467 | -2, at the next to last character and so on. |
8468 | |
8469 | \sa QString::indexOf(), lastIndexOf(), contains(), count() |
8470 | */ |
8471 | int QStringRef::indexOf(const QString &str, int from, Qt::CaseSensitivity cs) const |
8472 | { |
8473 | return qFindString(unicode(), length(), from, str.unicode(), str.length(), cs); |
8474 | } |
8475 | |
8476 | /*! |
8477 | \since 4.8 |
8478 | \overload indexOf() |
8479 | |
8480 | Returns the index position of the first occurrence of the |
8481 | character \a ch in the string reference, searching forward from |
8482 | index position \a from. Returns -1 if \a ch could not be found. |
8483 | |
8484 | \sa QString::indexOf(), lastIndexOf(), contains(), count() |
8485 | */ |
8486 | int QStringRef::indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const |
8487 | { |
8488 | return findChar(unicode(), length(), ch, from, cs); |
8489 | } |
8490 | |
8491 | /*! |
8492 | \since 4.8 |
8493 | |
8494 | Returns the index position of the first occurrence of the string \a |
8495 | str in this string reference, searching forward from index position |
8496 | \a from. Returns -1 if \a str is not found. |
8497 | |
8498 | If \a cs is Qt::CaseSensitive (default), the search is case |
8499 | sensitive; otherwise the search is case insensitive. |
8500 | |
8501 | If \a from is -1, the search starts at the last character; if it is |
8502 | -2, at the next to last character and so on. |
8503 | |
8504 | \sa QString::indexOf(), lastIndexOf(), contains(), count() |
8505 | */ |
8506 | int QStringRef::indexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const |
8507 | { |
8508 | return qt_find_latin1_string(unicode(), size(), str, from, cs); |
8509 | } |
8510 | |
8511 | /*! |
8512 | \since 4.8 |
8513 | |
8514 | \overload indexOf() |
8515 | |
8516 | Returns the index position of the first occurrence of the string |
8517 | reference \a str in this string reference, searching forward from |
8518 | index position \a from. Returns -1 if \a str is not found. |
8519 | |
8520 | If \a cs is Qt::CaseSensitive (default), the search is case |
8521 | sensitive; otherwise the search is case insensitive. |
8522 | |
8523 | \sa QString::indexOf(), lastIndexOf(), contains(), count() |
8524 | */ |
8525 | int QStringRef::indexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const |
8526 | { |
8527 | return qFindString(unicode(), size(), from, str.unicode(), str.size(), cs); |
8528 | } |
8529 | |
8530 | /*! |
8531 | \since 4.8 |
8532 | |
8533 | Returns the index position of the last occurrence of the string \a |
8534 | str in this string reference, searching backward from index position |
8535 | \a from. If \a from is -1 (default), the search starts at the last |
8536 | character; if \a from is -2, at the next to last character and so |
8537 | on. Returns -1 if \a str is not found. |
8538 | |
8539 | If \a cs is Qt::CaseSensitive (default), the search is case |
8540 | sensitive; otherwise the search is case insensitive. |
8541 | |
8542 | \sa QString::lastIndexOf(), indexOf(), contains(), count() |
8543 | */ |
8544 | int QStringRef::lastIndexOf(const QString &str, int from, Qt::CaseSensitivity cs) const |
8545 | { |
8546 | const int sl = str.size(); |
8547 | if (sl == 1) |
8548 | return lastIndexOf(str.at(0), from, cs); |
8549 | |
8550 | const int l = size();; |
8551 | if (from < 0) |
8552 | from += l; |
8553 | int delta = l - sl; |
8554 | if (from == l && sl == 0) |
8555 | return from; |
8556 | if (from < 0 || from >= l || delta < 0) |
8557 | return -1; |
8558 | if (from > delta) |
8559 | from = delta; |
8560 | |
8561 | return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, |
8562 | reinterpret_cast<const ushort*>(str.unicode()), str.size(), cs); |
8563 | } |
8564 | |
8565 | /*! |
8566 | \since 4.8 |
8567 | \overload lastIndexOf() |
8568 | |
8569 | Returns the index position of the last occurrence of the character |
8570 | \a ch, searching backward from position \a from. |
8571 | |
8572 | \sa QString::lastIndexOf(), indexOf(), contains(), count() |
8573 | */ |
8574 | int QStringRef::lastIndexOf(QChar ch, int from, Qt::CaseSensitivity cs) const |
8575 | { |
8576 | return qt_last_index_of(unicode(), size(), ch, from, cs); |
8577 | } |
8578 | |
8579 | /*! |
8580 | \since 4.8 |
8581 | \overload lastIndexOf() |
8582 | |
8583 | Returns the index position of the last occurrence of the string \a |
8584 | str in this string reference, searching backward from index position |
8585 | \a from. If \a from is -1 (default), the search starts at the last |
8586 | character; if \a from is -2, at the next to last character and so |
8587 | on. Returns -1 if \a str is not found. |
8588 | |
8589 | If \a cs is Qt::CaseSensitive (default), the search is case |
8590 | sensitive; otherwise the search is case insensitive. |
8591 | |
8592 | \sa QString::lastIndexOf(), indexOf(), contains(), count() |
8593 | */ |
8594 | int QStringRef::lastIndexOf(QLatin1String str, int from, Qt::CaseSensitivity cs) const |
8595 | { |
8596 | const int sl = qstrlen(str.latin1()); |
8597 | if (sl == 1) |
8598 | return lastIndexOf(QLatin1Char(str.latin1()[0]), from, cs); |
8599 | |
8600 | const int l = size(); |
8601 | if (from < 0) |
8602 | from += l; |
8603 | int delta = l - sl; |
8604 | if (from == l && sl == 0) |
8605 | return from; |
8606 | if (from < 0 || from >= l || delta < 0) |
8607 | return -1; |
8608 | if (from > delta) |
8609 | from = delta; |
8610 | |
8611 | QVarLengthArray<ushort> s(sl); |
8612 | for (int i = 0; i < sl; ++i) |
8613 | s[i] = str.latin1()[i]; |
8614 | |
8615 | return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, s.data(), sl, cs); |
8616 | } |
8617 | |
8618 | /*! |
8619 | \since 4.8 |
8620 | \overload lastIndexOf() |
8621 | |
8622 | Returns the index position of the last occurrence of the string |
8623 | reference \a str in this string reference, searching backward from |
8624 | index position \a from. If \a from is -1 (default), the search |
8625 | starts at the last character; if \a from is -2, at the next to last |
8626 | character and so on. Returns -1 if \a str is not found. |
8627 | |
8628 | If \a cs is Qt::CaseSensitive (default), the search is case |
8629 | sensitive; otherwise the search is case insensitive. |
8630 | |
8631 | \sa QString::lastIndexOf(), indexOf(), contains(), count() |
8632 | */ |
8633 | int QStringRef::lastIndexOf(const QStringRef &str, int from, Qt::CaseSensitivity cs) const |
8634 | { |
8635 | const int sl = str.size(); |
8636 | if (sl == 1) |
8637 | return lastIndexOf(str.at(0), from, cs); |
8638 | |
8639 | const int l = size(); |
8640 | if (from < 0) |
8641 | from += l; |
8642 | int delta = l - sl; |
8643 | if (from == l && sl == 0) |
8644 | return from; |
8645 | if (from < 0 || from >= l || delta < 0) |
8646 | return -1; |
8647 | if (from > delta) |
8648 | from = delta; |
8649 | |
8650 | return lastIndexOfHelper(reinterpret_cast<const ushort*>(unicode()), from, |
8651 | reinterpret_cast<const ushort*>(str.unicode()), |
8652 | str.size(), cs); |
8653 | } |
8654 | |
8655 | /*! |
8656 | \since 4.8 |
8657 | Returns the number of (potentially overlapping) occurrences of |
8658 | the string \a str in this string reference. |
8659 | |
8660 | If \a cs is Qt::CaseSensitive (default), the search is |
8661 | case sensitive; otherwise the search is case insensitive. |
8662 | |
8663 | \sa QString::count(), contains(), indexOf() |
8664 | */ |
8665 | int QStringRef::count(const QString &str, Qt::CaseSensitivity cs) const |
8666 | { |
8667 | return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs); |
8668 | } |
8669 | |
8670 | /*! |
8671 | \since 4.8 |
8672 | \overload count() |
8673 | |
8674 | Returns the number of occurrences of the character \a ch in the |
8675 | string reference. |
8676 | |
8677 | If \a cs is Qt::CaseSensitive (default), the search is |
8678 | case sensitive; otherwise the search is case insensitive. |
8679 | |
8680 | \sa QString::count(), contains(), indexOf() |
8681 | */ |
8682 | int QStringRef::count(QChar ch, Qt::CaseSensitivity cs) const |
8683 | { |
8684 | return qt_string_count(unicode(), size(), ch, cs); |
8685 | } |
8686 | |
8687 | /*! |
8688 | \since 4.8 |
8689 | \overload count() |
8690 | |
8691 | Returns the number of (potentially overlapping) occurrences of the |
8692 | string reference \a str in this string reference. |
8693 | |
8694 | If \a cs is Qt::CaseSensitive (default), the search is |
8695 | case sensitive; otherwise the search is case insensitive. |
8696 | |
8697 | \sa QString::count(), contains(), indexOf() |
8698 | */ |
8699 | int QStringRef::count(const QStringRef &str, Qt::CaseSensitivity cs) const |
8700 | { |
8701 | return qt_string_count(unicode(), size(), str.unicode(), str.size(), cs); |
8702 | } |
8703 | |
8704 | /*! |
8705 | \since 4.8 |
8706 | |
8707 | Returns true if the string reference starts with \a str; otherwise |
8708 | returns false. |
8709 | |
8710 | If \a cs is Qt::CaseSensitive (default), the search is |
8711 | case sensitive; otherwise the search is case insensitive. |
8712 | |
8713 | \sa QString::startsWith(), endsWith() |
8714 | */ |
8715 | bool QStringRef::startsWith(const QString &str, Qt::CaseSensitivity cs) const |
8716 | { |
8717 | return qt_starts_with(isNull() ? 0 : unicode(), size(), |
8718 | str.isNull() ? 0 : str.unicode(), str.size(), cs); |
8719 | } |
8720 | |
8721 | /*! |
8722 | \since 4.8 |
8723 | \overload startsWith() |
8724 | \sa QString::startsWith(), endsWith() |
8725 | */ |
8726 | bool QStringRef::startsWith(QLatin1String str, Qt::CaseSensitivity cs) const |
8727 | { |
8728 | return qt_starts_with(isNull() ? 0 : unicode(), size(), str, cs); |
8729 | } |
8730 | |
8731 | /*! |
8732 | \since 4.8 |
8733 | \overload startsWith() |
8734 | \sa QString::startsWith(), endsWith() |
8735 | */ |
8736 | bool QStringRef::startsWith(const QStringRef &str, Qt::CaseSensitivity cs) const |
8737 | { |
8738 | return qt_starts_with(isNull() ? 0 : unicode(), size(), |
8739 | str.isNull() ? 0 : str.unicode(), str.size(), cs); |
8740 | } |
8741 | |
8742 | /*! |
8743 | \since 4.8 |
8744 | \overload startsWith() |
8745 | |
8746 | Returns true if the string reference starts with \a ch; otherwise |
8747 | returns false. |
8748 | |
8749 | If \a cs is Qt::CaseSensitive (default), the search is case |
8750 | sensitive; otherwise the search is case insensitive. |
8751 | |
8752 | \sa QString::startsWith(), endsWith() |
8753 | */ |
8754 | bool QStringRef::startsWith(QChar ch, Qt::CaseSensitivity cs) const |
8755 | { |
8756 | if (!isEmpty()) { |
8757 | const ushort *data = reinterpret_cast<const ushort*>(unicode()); |
8758 | return (cs == Qt::CaseSensitive |
8759 | ? data[0] == ch |
8760 | : foldCase(data[0]) == foldCase(ch.unicode())); |
8761 | } else { |
8762 | return false; |
8763 | } |
8764 | } |
8765 | |
8766 | /*! |
8767 | \since 4.8 |
8768 | Returns true if the string reference ends with \a str; otherwise |
8769 | returns false. |
8770 | |
8771 | If \a cs is Qt::CaseSensitive (default), the search is case |
8772 | sensitive; otherwise the search is case insensitive. |
8773 | |
8774 | \sa QString::endsWith(), startsWith() |
8775 | */ |
8776 | bool QStringRef::endsWith(const QString &str, Qt::CaseSensitivity cs) const |
8777 | { |
8778 | return qt_ends_with(isNull() ? 0 : unicode(), size(), |
8779 | str.isNull() ? 0 : str.unicode(), str.size(), cs); |
8780 | } |
8781 | |
8782 | /*! |
8783 | \since 4.8 |
8784 | \overload endsWith() |
8785 | |
8786 | Returns true if the string reference ends with \a ch; otherwise |
8787 | returns false. |
8788 | |
8789 | If \a cs is Qt::CaseSensitive (default), the search is case |
8790 | sensitive; otherwise the search is case insensitive. |
8791 | |
8792 | \sa QString::endsWith(), endsWith() |
8793 | */ |
8794 | bool QStringRef::endsWith(QChar ch, Qt::CaseSensitivity cs) const |
8795 | { |
8796 | if (!isEmpty()) { |
8797 | const ushort *data = reinterpret_cast<const ushort*>(unicode()); |
8798 | const int size = length(); |
8799 | return (cs == Qt::CaseSensitive |
8800 | ? data[size - 1] == ch |
8801 | : foldCase(data[size - 1]) == foldCase(ch.unicode())); |
8802 | } else { |
8803 | return false; |
8804 | } |
8805 | } |
8806 | |
8807 | /*! |
8808 | \since 4.8 |
8809 | \overload endsWith() |
8810 | \sa QString::endsWith(), endsWith() |
8811 | */ |
8812 | bool QStringRef::endsWith(QLatin1String str, Qt::CaseSensitivity cs) const |
8813 | { |
8814 | return qt_ends_with(isNull() ? 0 : unicode(), size(), str, cs); |
8815 | } |
8816 | |
8817 | /*! |
8818 | \since 4.8 |
8819 | \overload endsWith() |
8820 | \sa QString::endsWith(), endsWith() |
8821 | */ |
8822 | bool QStringRef::endsWith(const QStringRef &str, Qt::CaseSensitivity cs) const |
8823 | { |
8824 | return qt_ends_with(isNull() ? 0 : unicode(), size(), |
8825 | str.isNull() ? 0 : str.unicode(), str.size(), cs); |
8826 | } |
8827 | |
8828 | |
8829 | /*! \fn bool QStringRef::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8830 | |
8831 | \since 4.8 |
8832 | Returns true if this string reference contains an occurrence of |
8833 | the string \a str; otherwise returns false. |
8834 | |
8835 | If \a cs is Qt::CaseSensitive (default), the search is |
8836 | case sensitive; otherwise the search is case insensitive. |
8837 | |
8838 | \sa indexOf(), count() |
8839 | */ |
8840 | |
8841 | /*! \fn bool QStringRef::contains(QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8842 | |
8843 | \overload contains() |
8844 | \since 4.8 |
8845 | |
8846 | Returns true if this string contains an occurrence of the |
8847 | character \a ch; otherwise returns false. |
8848 | |
8849 | If \a cs is Qt::CaseSensitive (default), the search is |
8850 | case sensitive; otherwise the search is case insensitive. |
8851 | |
8852 | */ |
8853 | |
8854 | /*! \fn bool QStringRef::contains(const QStringRef &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const |
8855 | \overload contains() |
8856 | \since 4.8 |
8857 | |
8858 | Returns true if this string reference contains an occurrence of |
8859 | the string reference \a str; otherwise returns false. |
8860 | |
8861 | If \a cs is Qt::CaseSensitive (default), the search is |
8862 | case sensitive; otherwise the search is case insensitive. |
8863 | |
8864 | \sa indexOf(), count() |
8865 | */ |
8866 | |
8867 | /*! \fn bool QStringRef::contains(QLatin1String str, Qt::CaseSensitivity cs) const |
8868 | \since 4,8 |
8869 | \overload contains() |
8870 | |
8871 | Returns true if this string reference contains an occurrence of |
8872 | the string \a str; otherwise returns false. |
8873 | |
8874 | If \a cs is Qt::CaseSensitive (default), the search is |
8875 | case sensitive; otherwise the search is case insensitive. |
8876 | |
8877 | \sa indexOf(), count() |
8878 | */ |
8879 | |
8880 | static inline int qt_last_index_of(const QChar *haystack, int haystackLen, const QChar &needle, |
8881 | int from, Qt::CaseSensitivity cs) |
8882 | { |
8883 | ushort c = needle.unicode(); |
8884 | if (from < 0) |
8885 | from += haystackLen; |
8886 | if (from < 0 || from >= haystackLen) |
8887 | return -1; |
8888 | if (from >= 0) { |
8889 | const ushort *b = reinterpret_cast<const ushort*>(haystack); |
8890 | const ushort *n = b + from; |
8891 | if (cs == Qt::CaseSensitive) { |
8892 | for (; n >= b; --n) |
8893 | if (*n == c) |
8894 | return n - b; |
8895 | } else { |
8896 | c = foldCase(c); |
8897 | for (; n >= b; --n) |
8898 | if (foldCase(*n) == c) |
8899 | return n - b; |
8900 | } |
8901 | } |
8902 | return -1; |
8903 | |
8904 | |
8905 | } |
8906 | |
8907 | static inline int qt_string_count(const QChar *haystack, int haystackLen, |
8908 | const QChar *needle, int needleLen, |
8909 | Qt::CaseSensitivity cs) |
8910 | { |
8911 | int num = 0; |
8912 | int i = -1; |
8913 | if (haystackLen > 500 && needleLen > 5) { |
8914 | QStringMatcher matcher(needle, needleLen, cs); |
8915 | while ((i = matcher.indexIn(haystack, haystackLen, i + 1)) != -1) |
8916 | ++num; |
8917 | } else { |
8918 | while ((i = qFindString(haystack, haystackLen, i + 1, needle, needleLen, cs)) != -1) |
8919 | ++num; |
8920 | } |
8921 | return num; |
8922 | } |
8923 | |
8924 | static inline int qt_string_count(const QChar *unicode, int size, const QChar &ch, |
8925 | Qt::CaseSensitivity cs) |
8926 | { |
8927 | ushort c = ch.unicode(); |
8928 | int num = 0; |
8929 | const ushort *b = reinterpret_cast<const ushort*>(unicode); |
8930 | const ushort *i = b + size; |
8931 | if (cs == Qt::CaseSensitive) { |
8932 | while (i != b) |
8933 | if (*--i == c) |
8934 | ++num; |
8935 | } else { |
8936 | c = foldCase(c); |
8937 | while (i != b) |
8938 | if (foldCase(*(--i)) == c) |
8939 | ++num; |
8940 | } |
8941 | return num; |
8942 | } |
8943 | |
8944 | static inline int qt_find_latin1_string(const QChar *haystack, int size, |
8945 | const QLatin1String &needle, |
8946 | int from, Qt::CaseSensitivity cs) |
8947 | { |
8948 | const char *latin1 = needle.latin1(); |
8949 | int len = qstrlen(latin1); |
8950 | QVarLengthArray<ushort> s(len); |
8951 | for (int i = 0; i < len; ++i) |
8952 | s[i] = latin1[i]; |
8953 | |
8954 | return qFindString(haystack, size, from, |
8955 | reinterpret_cast<const QChar*>(s.constData()), len, cs); |
8956 | } |
8957 | |
8958 | static inline bool qt_starts_with(const QChar *haystack, int haystackLen, |
8959 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs) |
8960 | { |
8961 | if (!haystack) |
8962 | return !needle; |
8963 | if (haystackLen == 0) |
8964 | return needleLen == 0; |
8965 | if (needleLen > haystackLen) |
8966 | return false; |
8967 | |
8968 | const ushort *h = reinterpret_cast<const ushort*>(haystack); |
8969 | const ushort *n = reinterpret_cast<const ushort*>(needle); |
8970 | |
8971 | if (cs == Qt::CaseSensitive) { |
8972 | return qMemEquals(h, n, needleLen); |
8973 | } else { |
8974 | uint last = 0; |
8975 | uint olast = 0; |
8976 | for (int i = 0; i < needleLen; ++i) |
8977 | if (foldCase(h[i], last) != foldCase(n[i], olast)) |
8978 | return false; |
8979 | } |
8980 | return true; |
8981 | } |
8982 | |
8983 | static inline bool qt_starts_with(const QChar *haystack, int haystackLen, |
8984 | const QLatin1String &needle, Qt::CaseSensitivity cs) |
8985 | { |
8986 | if (!haystack) |
8987 | return !needle.latin1(); |
8988 | if (haystackLen == 0) |
8989 | return !needle.latin1() || *needle.latin1() == 0; |
8990 | const int slen = qstrlen(needle.latin1()); |
8991 | if (slen > haystackLen) |
8992 | return false; |
8993 | const ushort *data = reinterpret_cast<const ushort*>(haystack); |
8994 | const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1()); |
8995 | if (cs == Qt::CaseSensitive) { |
8996 | for (int i = 0; i < slen; ++i) |
8997 | if (data[i] != latin[i]) |
8998 | return false; |
8999 | } else { |
9000 | for (int i = 0; i < slen; ++i) |
9001 | if (foldCase(data[i]) != foldCase((ushort)latin[i])) |
9002 | return false; |
9003 | } |
9004 | return true; |
9005 | } |
9006 | |
9007 | static inline bool qt_ends_with(const QChar *haystack, int haystackLen, |
9008 | const QChar *needle, int needleLen, Qt::CaseSensitivity cs) |
9009 | { |
9010 | if (!haystack) |
9011 | return !needle; |
9012 | if (haystackLen == 0) |
9013 | return needleLen == 0; |
9014 | const int pos = haystackLen - needleLen; |
9015 | if (pos < 0) |
9016 | return false; |
9017 | |
9018 | const ushort *h = reinterpret_cast<const ushort*>(haystack); |
9019 | const ushort *n = reinterpret_cast<const ushort*>(needle); |
9020 | |
9021 | if (cs == Qt::CaseSensitive) { |
9022 | return qMemEquals(h + pos, n, needleLen); |
9023 | } else { |
9024 | uint last = 0; |
9025 | uint olast = 0; |
9026 | for (int i = 0; i < needleLen; i++) |
9027 | if (foldCase(h[pos+i], last) != foldCase(n[i], olast)) |
9028 | return false; |
9029 | } |
9030 | return true; |
9031 | } |
9032 | |
9033 | |
9034 | static inline bool qt_ends_with(const QChar *haystack, int haystackLen, |
9035 | const QLatin1String &needle, Qt::CaseSensitivity cs) |
9036 | { |
9037 | if (!haystack) |
9038 | return !needle.latin1(); |
9039 | if (haystackLen == 0) |
9040 | return !needle.latin1() || *needle.latin1() == 0; |
9041 | const int slen = qstrlen(needle.latin1()); |
9042 | int pos = haystackLen - slen; |
9043 | if (pos < 0) |
9044 | return false; |
9045 | const uchar *latin = reinterpret_cast<const uchar*>(needle.latin1()); |
9046 | const ushort *data = reinterpret_cast<const ushort*>(haystack); |
9047 | if (cs == Qt::CaseSensitive) { |
9048 | for (int i = 0; i < slen; i++) |
9049 | if (data[pos+i] != latin[i]) |
9050 | return false; |
9051 | } else { |
9052 | for (int i = 0; i < slen; i++) |
9053 | if (foldCase(data[pos+i]) != foldCase((ushort)latin[i])) |
9054 | return false; |
9055 | } |
9056 | return true; |
9057 | } |
9058 | |
9059 | /*! |
9060 | \since 4.8 |
9061 | |
9062 | Returns a Latin-1 representation of the string as a QByteArray. |
9063 | |
9064 | The returned byte array is undefined if the string contains non-Latin1 |
9065 | characters. Those characters may be suppressed or replaced with a |
9066 | question mark. |
9067 | |
9068 | \sa toAscii(), toUtf8(), toLocal8Bit(), QTextCodec |
9069 | */ |
9070 | QByteArray QStringRef::toLatin1() const |
9071 | { |
9072 | return toLatin1_helper(unicode(), length()); |
9073 | } |
9074 | |
9075 | /*! |
9076 | \since 4.8 |
9077 | |
9078 | Returns an 8-bit representation of the string as a QByteArray. |
9079 | |
9080 | If a codec has been set using QTextCodec::setCodecForCStrings(), |
9081 | it is used to convert Unicode to 8-bit char; otherwise this |
9082 | function does the same as toLatin1(). |
9083 | |
9084 | Note that, despite the name, this function does not necessarily return an US-ASCII |
9085 | (ANSI X3.4-1986) string and its result may not be US-ASCII compatible. |
9086 | |
9087 | \sa toLatin1(), toUtf8(), toLocal8Bit(), QTextCodec |
9088 | */ |
9089 | QByteArray QStringRef::toAscii() const |
9090 | { |
9091 | #ifndef QT_NO_TEXTCODEC |
9092 | if (QString::codecForCStrings) |
9093 | return QString::codecForCStrings->fromUnicode(unicode(), length()); |
9094 | #endif // QT_NO_TEXTCODEC |
9095 | return toLatin1(); |
9096 | } |
9097 | |
9098 | /*! |
9099 | \since 4.8 |
9100 | |
9101 | Returns the local 8-bit representation of the string as a |
9102 | QByteArray. The returned byte array is undefined if the string |
9103 | contains characters not supported by the local 8-bit encoding. |
9104 | |
9105 | QTextCodec::codecForLocale() is used to perform the conversion from |
9106 | Unicode. If the locale encoding could not be determined, this function |
9107 | does the same as toLatin1(). |
9108 | |
9109 | If this string contains any characters that cannot be encoded in the |
9110 | locale, the returned byte array is undefined. Those characters may be |
9111 | suppressed or replaced by another. |
9112 | |
9113 | \sa toAscii(), toLatin1(), toUtf8(), QTextCodec |
9114 | */ |
9115 | QByteArray QStringRef::toLocal8Bit() const |
9116 | { |
9117 | #ifndef QT_NO_TEXTCODEC |
9118 | if (QTextCodec::codecForLocale()) |
9119 | return QTextCodec::codecForLocale()->fromUnicode(unicode(), length()); |
9120 | #endif // QT_NO_TEXTCODEC |
9121 | return toLatin1(); |
9122 | } |
9123 | |
9124 | /*! |
9125 | \since 4.8 |
9126 | |
9127 | Returns a UTF-8 representation of the string as a QByteArray. |
9128 | |
9129 | UTF-8 is a Unicode codec and can represent all characters in a Unicode |
9130 | string like QString. |
9131 | |
9132 | However, in the Unicode range, there are certain codepoints that are not |
9133 | considered characters. The Unicode standard reserves the last two |
9134 | codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, |
9135 | U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF, |
9136 | inclusive, as non-characters. If any of those appear in the string, they |
9137 | may be discarded and will not appear in the UTF-8 representation, or they |
9138 | may be replaced by one or more replacement characters. |
9139 | |
9140 | \sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec |
9141 | */ |
9142 | QByteArray QStringRef::toUtf8() const |
9143 | { |
9144 | if (isNull()) |
9145 | return QByteArray(); |
9146 | |
9147 | return QUtf8::convertFromUnicode(constData(), length(), 0); |
9148 | } |
9149 | |
9150 | /*! |
9151 | \since 4.8 |
9152 | |
9153 | Returns a UCS-4/UTF-32 representation of the string as a QVector<uint>. |
9154 | |
9155 | UCS-4 is a Unicode codec and is lossless. All characters from this string |
9156 | can be encoded in UCS-4. |
9157 | |
9158 | \sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec |
9159 | */ |
9160 | QVector<uint> QStringRef::toUcs4() const |
9161 | { |
9162 | QVector<uint> v(length()); |
9163 | uint *a = v.data(); |
9164 | int len = toUcs4_helper<uint>(reinterpret_cast<const unsigned short *>(unicode()), length(), a); |
9165 | v.resize(len); |
9166 | return v; |
9167 | } |
9168 | |
9169 | QT_END_NAMESPACE |
9170 | |