1 /****************************************************************************
2 ** $Id: qt/qstring.cpp 3.3.8 edited Jan 11 16:03 $
3 **
4 ** Implementation of the QString class and related Unicode functions
5 **
6 ** Created : 920722
7 **
8 ** Copyright (C) 1992-2007 Trolltech ASA. All rights reserved.
9 **
10 ** This file is part of the tools module of the Qt GUI Toolkit.
11 **
12 ** This file may be distributed under the terms of the Q Public License
13 ** as defined by Trolltech ASA of Norway and appearing in the file
14 ** LICENSE.QPL included in the packaging of this file.
15 **
16 ** This file may be distributed and/or modified under the terms of the
17 ** GNU General Public License version 2 as published by the Free Software
18 ** Foundation and appearing in the file LICENSE.GPL included in the
19 ** packaging of this file.
20 **
21 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
22 ** licenses may use this file in accordance with the Qt Commercial License
23 ** Agreement provided with the Software.
24 **
25 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
26 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
27 **
28 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
29 ** information about Qt Commercial License Agreements.
30 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
31 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
32 **
33 ** Contact info@trolltech.com if any conditions of this licensing are
34 ** not clear to you.
35 **
36 **********************************************************************/
37
38 // Don't define it while compiling this module, or USERS of Qt will
39 // not be able to link.
40 #ifdef QT_NO_CAST_ASCII
41 #undef QT_NO_CAST_ASCII
42 #endif
43
44 #include "qstring.h"
45 #include "qregexp.h"
46 #include "qdatastream.h"
47 #ifndef QT_NO_TEXTCODEC
48 #include "qtextcodec.h"
49 #endif
50 #include "qlocale.h"
51 #include "qlocale_p.h"
52
53 #include "qunicodetables_p.h"
54 #include <limits.h>
55 #include <stdarg.h>
56 #include <stdio.h>
57 #include <stdlib.h>
58 #include <string.h>
59 #ifndef Q_OS_TEMP
60 #include <locale.h>
61 #endif
62 #if defined(Q_WS_WIN)
63 #include "qt_windows.h"
64 #endif
65 #if !defined( QT_NO_COMPONENT ) && !defined( QT_LITE_COMPONENT )
66 #include "qcleanuphandler.h"
67 #endif
68
69 #ifndef LLONG_MAX
70 #define LLONG_MAX Q_INT64_C(9223372036854775807)
71 #endif
72 #ifndef LLONG_MIN
73 #define LLONG_MIN (-LLONG_MAX - Q_INT64_C(1))
74 #endif
75 #ifndef ULLONG_MAX
76 #define ULLONG_MAX Q_UINT64_C(18446744073709551615)
77 #endif
78
ucstrcmp(const QString & as,const QString & bs)79 static int ucstrcmp( const QString &as, const QString &bs )
80 {
81 const QChar *a = as.unicode();
82 const QChar *b = bs.unicode();
83 if ( a == b )
84 return 0;
85 if ( a == 0 )
86 return 1;
87 if ( b == 0 )
88 return -1;
89 int l=QMIN(as.length(),bs.length());
90 while ( l-- && *a == *b )
91 a++,b++;
92 if ( l==-1 )
93 return ( as.length()-bs.length() );
94 return a->unicode() - b->unicode();
95 }
96
ucstrncmp(const QChar * a,const QChar * b,int l)97 static int ucstrncmp( const QChar *a, const QChar *b, int l )
98 {
99 while ( l-- && *a == *b )
100 a++,b++;
101 if ( l==-1 )
102 return 0;
103 return a->unicode() - b->unicode();
104 }
105
ucstrnicmp(const QChar * a,const QChar * b,int l)106 static int ucstrnicmp( const QChar *a, const QChar *b, int l )
107 {
108 while ( l-- && ::lower( *a ) == ::lower( *b ) )
109 a++,b++;
110 if ( l==-1 )
111 return 0;
112 return ::lower( *a ).unicode() - ::lower( *b ).unicode();
113 }
114
computeNewMax(uint len)115 static uint computeNewMax( uint len )
116 {
117 if (len >= 0x80000000)
118 return len;
119
120 uint newMax = 4;
121 while ( newMax < len )
122 newMax *= 2;
123 // try to save some memory
124 if ( newMax >= 1024 * 1024 && len <= newMax - (newMax >> 2) )
125 newMax -= newMax >> 2;
126 return newMax;
127 }
128
qIsUpper(char c)129 static bool qIsUpper(char c)
130 {
131 return c >= 'A' && c <= 'Z';
132 }
133
qIsDigit(char c)134 static bool qIsDigit(char c)
135 {
136 return c >= '0' && c <= '9';
137 }
138
qToLower(char c)139 static char qToLower(char c)
140 {
141 if (c >= 'A' && c <= 'Z')
142 return c - 'A' + 'a';
143 else
144 return c;
145 }
146
147 /*!
148 \class QCharRef qstring.h
149 \reentrant
150 \brief The QCharRef class is a helper class for QString.
151
152 \ingroup text
153
154 When you get an object of type QCharRef, if you can assign to it,
155 the assignment will apply to the character in the string from
156 which you got the reference. That is its whole purpose in life.
157 The QCharRef becomes invalid once modifications are made to the
158 string: if you want to keep the character, copy it into a QChar.
159
160 Most of the QChar member functions also exist in QCharRef.
161 However, they are not explicitly documented here.
162
163 \sa QString::operator[]() QString::at() QChar
164 */
165
166 /*!
167 \class QChar qstring.h
168 \reentrant
169 \brief The QChar class provides a lightweight Unicode character.
170
171 \ingroup text
172
173 Unicode characters are (so far) 16-bit entities without any markup
174 or structure. This class represents such an entity. It is
175 lightweight, so it can be used everywhere. Most compilers treat it
176 like a "short int". (In a few years it may be necessary to make
177 QChar 32-bit when more than 65536 Unicode code points have been
178 defined and come into use.)
179
180 QChar provides a full complement of testing/classification
181 functions, converting to and from other formats, converting from
182 composed to decomposed Unicode, and trying to compare and
183 case-convert if you ask it to.
184
185 The classification functions include functions like those in
186 ctype.h, but operating on the full range of Unicode characters.
187 They all return TRUE if the character is a certain type of
188 character; otherwise they return FALSE. These classification
189 functions are isNull() (returns TRUE if the character is U+0000),
190 isPrint() (TRUE if the character is any sort of printable
191 character, including whitespace), isPunct() (any sort of
192 punctation), isMark() (Unicode Mark), isLetter (a letter),
193 isNumber() (any sort of numeric character), isLetterOrNumber(),
194 and isDigit() (decimal digits). All of these are wrappers around
195 category() which return the Unicode-defined category of each
196 character.
197
198 QChar further provides direction(), which indicates the "natural"
199 writing direction of this character. The joining() function
200 indicates how the character joins with its neighbors (needed
201 mostly for Arabic) and finally mirrored(), which indicates whether
202 the character needs to be mirrored when it is printed in its
203 "unnatural" writing direction.
204
205 Composed Unicode characters (like å) can be converted to
206 decomposed Unicode ("a" followed by "ring above") by using
207 decomposition().
208
209 In Unicode, comparison is not necessarily possible and case
210 conversion is very difficult at best. Unicode, covering the
211 "entire" world, also includes most of the world's case and sorting
212 problems. Qt tries, but not very hard: operator==() and friends
213 will do comparison based purely on the numeric Unicode value (code
214 point) of the characters, and upper() and lower() will do case
215 changes when the character has a well-defined upper/lower-case
216 equivalent. There is no provision for locale-dependent case
217 folding rules or comparison; these functions are meant to be fast
218 so they can be used unambiguously in data structures. (See
219 QString::localeAwareCompare() though.)
220
221 The conversion functions include unicode() (to a scalar), latin1()
222 (to scalar, but converts all non-Latin-1 characters to 0), row()
223 (gives the Unicode row), cell() (gives the Unicode cell),
224 digitValue() (gives the integer value of any of the numerous digit
225 characters), and a host of constructors.
226
227 More information can be found in the document \link unicode.html
228 About Unicode. \endlink
229
230 \sa QString QCharRef
231 */
232
233 /*!
234 \enum QChar::Category
235
236 This enum maps the Unicode character categories.
237
238 The following characters are normative in Unicode:
239
240 \value Mark_NonSpacing Unicode class name Mn
241
242 \value Mark_SpacingCombining Unicode class name Mc
243
244 \value Mark_Enclosing Unicode class name Me
245
246 \value Number_DecimalDigit Unicode class name Nd
247
248 \value Number_Letter Unicode class name Nl
249
250 \value Number_Other Unicode class name No
251
252 \value Separator_Space Unicode class name Zs
253
254 \value Separator_Line Unicode class name Zl
255
256 \value Separator_Paragraph Unicode class name Zp
257
258 \value Other_Control Unicode class name Cc
259
260 \value Other_Format Unicode class name Cf
261
262 \value Other_Surrogate Unicode class name Cs
263
264 \value Other_PrivateUse Unicode class name Co
265
266 \value Other_NotAssigned Unicode class name Cn
267
268
269 The following categories are informative in Unicode:
270
271 \value Letter_Uppercase Unicode class name Lu
272
273 \value Letter_Lowercase Unicode class name Ll
274
275 \value Letter_Titlecase Unicode class name Lt
276
277 \value Letter_Modifier Unicode class name Lm
278
279 \value Letter_Other Unicode class name Lo
280
281 \value Punctuation_Connector Unicode class name Pc
282
283 \value Punctuation_Dash Unicode class name Pd
284
285 \value Punctuation_Open Unicode class name Ps
286
287 \value Punctuation_Close Unicode class name Pe
288
289 \value Punctuation_InitialQuote Unicode class name Pi
290
291 \value Punctuation_FinalQuote Unicode class name Pf
292
293 \value Punctuation_Other Unicode class name Po
294
295 \value Symbol_Math Unicode class name Sm
296
297 \value Symbol_Currency Unicode class name Sc
298
299 \value Symbol_Modifier Unicode class name Sk
300
301 \value Symbol_Other Unicode class name So
302
303
304 There are two categories that are specific to Qt:
305
306 \value NoCategory used when Qt is dazed and confused and cannot
307 make sense of anything.
308
309 \value Punctuation_Dask old typo alias for Punctuation_Dash
310
311 */
312
313 /*!
314 \enum QChar::Direction
315
316 This enum type defines the Unicode direction attributes. See \link
317 http://www.unicode.org/ the Unicode Standard\endlink for a
318 description of the values.
319
320 In order to conform to C/C++ naming conventions "Dir" is prepended
321 to the codes used in the Unicode Standard.
322 */
323
324 /*!
325 \enum QChar::Decomposition
326
327 This enum type defines the Unicode decomposition attributes. See
328 \link http://www.unicode.org/ the Unicode Standard\endlink for a
329 description of the values.
330 */
331
332 /*!
333 \enum QChar::Joining
334
335 This enum type defines the Unicode joining attributes. See \link
336 http://www.unicode.org/ the Unicode Standard\endlink for a
337 description of the values.
338 */
339
340 /*!
341 \enum QChar::CombiningClass
342
343 This enum type defines names for some of the Unicode combining
344 classes. See \link http://www.unicode.org/ the Unicode
345 Standard\endlink for a description of the values.
346 */
347
348 /*!
349 \fn void QChar::setCell( uchar cell )
350 \internal
351 */
352
353 /*!
354 \fn void QChar::setRow( uchar row )
355 \internal
356 */
357
358
359 /*!
360 \fn QChar::QChar()
361
362 Constructs a null QChar (one that isNull()).
363 */
364
365
366 /*!
367 \fn QChar::QChar( char c )
368
369 Constructs a QChar corresponding to ASCII/Latin-1 character \a c.
370 */
371
372
373 /*!
374 \fn QChar::QChar( uchar c )
375
376 Constructs a QChar corresponding to ASCII/Latin-1 character \a c.
377 */
378
379
380 /*!
381 \fn QChar::QChar( uchar c, uchar r )
382
383 Constructs a QChar for Unicode cell \a c in row \a r.
384 */
385
386
387 /*!
388 \fn QChar::QChar( const QChar& c )
389
390 Constructs a copy of \a c. This is a deep copy, if such a
391 lightweight object can be said to have deep copies.
392 */
393
394
395 /*!
396 \fn QChar::QChar( ushort rc )
397
398 Constructs a QChar for the character with Unicode code point \a rc.
399 */
400
401
402 /*!
403 \fn QChar::QChar( short rc )
404
405 Constructs a QChar for the character with Unicode code point \a rc.
406 */
407
408
409 /*!
410 \fn QChar::QChar( uint rc )
411
412 Constructs a QChar for the character with Unicode code point \a rc.
413 */
414
415
416 /*!
417 \fn QChar::QChar( int rc )
418
419 Constructs a QChar for the character with Unicode code point \a rc.
420 */
421
422
423 /*!
424 \fn bool QChar::networkOrdered ()
425
426 \obsolete
427
428 Returns TRUE if this character is in network byte order (MSB
429 first); otherwise returns FALSE. This is platform dependent.
430 */
431
432
433 /*!
434 \fn bool QChar::isNull() const
435
436 Returns TRUE if the character is the Unicode character 0x0000
437 (ASCII NUL); otherwise returns FALSE.
438 */
439
440 /*!
441 \fn uchar QChar::cell () const
442
443 Returns the cell (least significant byte) of the Unicode
444 character.
445 */
446
447 /*!
448 \fn uchar QChar::row () const
449
450 Returns the row (most significant byte) of the Unicode character.
451 */
452
453 /*!
454 Returns TRUE if the character is a printable character; otherwise
455 returns FALSE. This is any character not of category Cc or Cn.
456
457 Note that this gives no indication of whether the character is
458 available in a particular \link QFont font\endlink.
459 */
isPrint() const460 bool QChar::isPrint() const
461 {
462 Category c = ::category( *this );
463 return !(c == Other_Control || c == Other_NotAssigned);
464 }
465
466 /*!
467 Returns TRUE if the character is a separator character
468 (Separator_* categories); otherwise returns FALSE.
469 */
isSpace() const470 bool QChar::isSpace() const
471 {
472 return ::isSpace( *this );
473 }
474
475 /*!
476 Returns TRUE if the character is a mark (Mark_* categories);
477 otherwise returns FALSE.
478 */
isMark() const479 bool QChar::isMark() const
480 {
481 Category c = ::category( *this );
482 return c >= Mark_NonSpacing && c <= Mark_Enclosing;
483 }
484
485 /*!
486 Returns TRUE if the character is a punctuation mark (Punctuation_*
487 categories); otherwise returns FALSE.
488 */
isPunct() const489 bool QChar::isPunct() const
490 {
491 Category c = ::category( *this );
492 return (c >= Punctuation_Connector && c <= Punctuation_Other);
493 }
494
495 /*!
496 Returns TRUE if the character is a letter (Letter_* categories);
497 otherwise returns FALSE.
498 */
isLetter() const499 bool QChar::isLetter() const
500 {
501 Category c = ::category( *this );
502 return (c >= Letter_Uppercase && c <= Letter_Other);
503 }
504
505 /*!
506 Returns TRUE if the character is a number (of any sort - Number_*
507 categories); otherwise returns FALSE.
508
509 \sa isDigit()
510 */
isNumber() const511 bool QChar::isNumber() const
512 {
513 Category c = ::category( *this );
514 return c >= Number_DecimalDigit && c <= Number_Other;
515 }
516
517 /*!
518 Returns TRUE if the character is a letter or number (Letter_* or
519 Number_* categories); otherwise returns FALSE.
520 */
isLetterOrNumber() const521 bool QChar::isLetterOrNumber() const
522 {
523 Category c = ::category( *this );
524 return (c >= Letter_Uppercase && c <= Letter_Other)
525 || (c >= Number_DecimalDigit && c <= Number_Other);
526 }
527
528
529 /*!
530 Returns TRUE if the character is a decimal digit
531 (Number_DecimalDigit); otherwise returns FALSE.
532 */
isDigit() const533 bool QChar::isDigit() const
534 {
535 return (::category( *this ) == Number_DecimalDigit);
536 }
537
538
539 /*!
540 Returns TRUE if the character is a symbol (Symbol_* categories);
541 otherwise returns FALSE.
542 */
isSymbol() const543 bool QChar::isSymbol() const
544 {
545 Category c = ::category( *this );
546 return c >= Symbol_Math && c <= Symbol_Other;
547 }
548
549 /*!
550 Returns the numeric value of the digit, or -1 if the character is
551 not a digit.
552 */
digitValue() const553 int QChar::digitValue() const
554 {
555 #ifndef QT_NO_UNICODETABLES
556 register int pos = QUnicodeTables::decimal_info[row()];
557 if( !pos )
558 return -1;
559 return QUnicodeTables::decimal_info[(pos<<8) + cell()];
560 #else
561 // ##### just latin1
562 if ( ucs < '0' || ucs > '9' )
563 return -1;
564 else
565 return ucs - '0';
566 #endif
567 }
568
569 /*!
570 Returns the character category.
571
572 \sa Category
573 */
category() const574 QChar::Category QChar::category() const
575 {
576 return ::category( *this );
577 }
578
579 /*!
580 Returns the character's direction.
581
582 \sa Direction
583 */
direction() const584 QChar::Direction QChar::direction() const
585 {
586 return ::direction( *this );
587 }
588
589 /*!
590 \warning This function is not supported (it may change to use
591 Unicode character classes).
592
593 Returns information about the joining properties of the character
594 (needed for example, for Arabic).
595 */
joining() const596 QChar::Joining QChar::joining() const
597 {
598 return ::joining( *this );
599 }
600
601
602 /*!
603 Returns TRUE if the character is a mirrored character (one that
604 should be reversed if the text direction is reversed); otherwise
605 returns FALSE.
606 */
mirrored() const607 bool QChar::mirrored() const
608 {
609 return ::mirrored( *this );
610 }
611
612 /*!
613 Returns the mirrored character if this character is a mirrored
614 character, otherwise returns the character itself.
615 */
mirroredChar() const616 QChar QChar::mirroredChar() const
617 {
618 return ::mirroredChar( *this );
619 }
620
621 #ifndef QT_NO_UNICODETABLES
622 // ### REMOVE ME 4.0
623 static QString shared_decomp;
624 #endif
625 /*!
626 \nonreentrant
627
628 Decomposes a character into its parts. Returns QString::null if no
629 decomposition exists.
630 */
decomposition() const631 const QString &QChar::decomposition() const
632 {
633 #ifndef QT_NO_UNICODETABLES
634 register int pos = QUnicodeTables::decomposition_info[row()];
635 if(!pos) return QString::null;
636
637 pos = QUnicodeTables::decomposition_info[(pos<<8)+cell()];
638 if(!pos) return QString::null;
639 pos+=2;
640
641 QString s;
642 Q_UINT16 c;
643 while ( (c = QUnicodeTables::decomposition_map[pos++]) != 0 )
644 s += QChar( c );
645 // ### In 4.0, return s, and not shared_decomp. shared_decomp
646 // prevents this function from being reentrant.
647 shared_decomp = s;
648 return shared_decomp;
649 #else
650 return QString::null;
651 #endif
652 }
653
654 /*!
655 Returns the tag defining the composition of the character. Returns
656 QChar::Single if no decomposition exists.
657 */
decompositionTag() const658 QChar::Decomposition QChar::decompositionTag() const
659 {
660 #ifndef QT_NO_UNICODETABLES
661 register int pos = QUnicodeTables::decomposition_info[row()];
662 if(!pos) return QChar::Single;
663
664 pos = QUnicodeTables::decomposition_info[(pos<<8)+cell()];
665 if(!pos) return QChar::Single;
666
667 return (QChar::Decomposition) QUnicodeTables::decomposition_map[pos];
668 #else
669 return Single; // ########### FIX eg. just latin1
670 #endif
671 }
672
673 /*!
674 Returns the combining class for the character as defined in the
675 Unicode standard. This is mainly useful as a positioning hint for
676 marks attached to a base character.
677
678 The Qt text rendering engine uses this information to correctly
679 position non spacing marks around a base character.
680 */
combiningClass() const681 unsigned char QChar::combiningClass() const
682 {
683 return ::combiningClass( *this );
684 }
685
686
687 /*!
688 Returns the lowercase equivalent if the character is uppercase;
689 otherwise returns the character itself.
690 */
lower() const691 QChar QChar::lower() const
692 {
693 return ::lower( *this );
694 }
695
696 /*!
697 Returns the uppercase equivalent if the character is lowercase;
698 otherwise returns the character itself.
699 */
upper() const700 QChar QChar::upper() const
701 {
702 return ::upper( *this );
703 }
704
705 /*!
706 \fn QChar::operator char() const
707
708 Returns the Latin-1 character equivalent to the QChar, or 0. This
709 is mainly useful for non-internationalized software.
710
711 \sa unicode()
712 */
713
714 /*!
715 \fn ushort QChar::unicode() const
716
717 Returns the numeric Unicode value equal to the QChar. Normally,
718 you should use QChar objects as they are equivalent, but for some
719 low-level tasks (e.g. indexing into an array of Unicode
720 information), this function is useful.
721 */
722
723 /*!
724 \fn ushort & QChar::unicode()
725
726 \overload
727
728 Returns a reference to the numeric Unicode value equal to the
729 QChar.
730 */
731
732 /*****************************************************************************
733 Documentation of QChar related functions
734 *****************************************************************************/
735
736 /*!
737 \fn bool operator==( QChar c1, QChar c2 )
738
739 \relates QChar
740
741 Returns TRUE if \a c1 and \a c2 are the same Unicode character;
742 otherwise returns FALSE.
743 */
744
745 /*!
746 \fn bool operator==( char ch, QChar c )
747
748 \overload
749 \relates QChar
750
751 Returns TRUE if \a c is the ASCII/Latin-1 character \a ch;
752 otherwise returns FALSE.
753 */
754
755 /*!
756 \fn bool operator==( QChar c, char ch )
757
758 \overload
759 \relates QChar
760
761 Returns TRUE if \a c is the ASCII/Latin-1 character \a ch;
762 otherwise returns FALSE.
763 */
764
765 /*!
766 \fn int operator!=( QChar c1, QChar c2 )
767
768 \relates QChar
769
770 Returns TRUE if \a c1 and \a c2 are not the same Unicode
771 character; otherwise returns FALSE.
772 */
773
774 /*!
775 \fn int operator!=( char ch, QChar c )
776
777 \overload
778 \relates QChar
779
780 Returns TRUE if \a c is not the ASCII/Latin-1 character \a ch;
781 otherwise returns FALSE.
782 */
783
784 /*!
785 \fn int operator!=( QChar c, char ch )
786
787 \overload
788 \relates QChar
789
790 Returns TRUE if \a c is not the ASCII/Latin-1 character \a ch;
791 otherwise returns FALSE.
792 */
793
794 /*!
795 \fn int operator<=( QChar c1, QChar c2 )
796
797 \relates QChar
798
799 Returns TRUE if the numeric Unicode value of \a c1 is less than
800 that of \a c2, or they are the same Unicode character; otherwise
801 returns FALSE.
802 */
803
804 /*!
805 \fn int operator<=( QChar c, char ch )
806
807 \overload
808 \relates QChar
809
810 Returns TRUE if the numeric Unicode value of \a c is less than or
811 equal to that of the ASCII/Latin-1 character \a ch; otherwise
812 returns FALSE.
813 */
814
815 /*!
816 \fn int operator<=( char ch, QChar c )
817
818 \overload
819 \relates QChar
820
821 Returns TRUE if the numeric Unicode value of the ASCII/Latin-1
822 character \a ch is less than or equal to that of \a c; otherwise
823 returns FALSE.
824 */
825
826 /*!
827 \fn int operator>=( QChar c1, QChar c2 )
828
829 \relates QChar
830
831 Returns TRUE if the numeric Unicode value of \a c1 is greater than
832 that of \a c2, or they are the same Unicode character; otherwise
833 returns FALSE.
834 */
835
836 /*!
837 \fn int operator>=( QChar c, char ch )
838
839 \overload
840 \relates QChar
841
842 Returns TRUE if the numeric Unicode value of \a c is greater than
843 or equal to that of the ASCII/Latin-1 character \a ch; otherwise
844 returns FALSE.
845 */
846
847 /*!
848 \fn int operator>=( char ch, QChar c )
849
850 \overload
851 \relates QChar
852
853 Returns TRUE if the numeric Unicode value of the ASCII/Latin-1
854 character \a ch is greater than or equal to that of \a c;
855 otherwise returns FALSE.
856 */
857
858 /*!
859 \fn int operator<( QChar c1, QChar c2 )
860
861 \relates QChar
862
863 Returns TRUE if the numeric Unicode value of \a c1 is less than
864 that of \a c2; otherwise returns FALSE.
865 */
866
867 /*!
868 \fn int operator<( QChar c, char ch )
869
870 \overload
871 \relates QChar
872
873 Returns TRUE if the numeric Unicode value of \a c is less than that
874 of the ASCII/Latin-1 character \a ch; otherwise returns FALSE.
875 */
876
877 /*!
878 \fn int operator<( char ch, QChar c )
879
880 \overload
881 \relates QChar
882
883 Returns TRUE if the numeric Unicode value of the ASCII/Latin-1
884 character \a ch is less than that of \a c; otherwise returns
885 FALSE.
886 */
887
888 /*!
889 \fn int operator>( QChar c1, QChar c2 )
890
891 \relates QChar
892
893 Returns TRUE if the numeric Unicode value of \a c1 is greater than
894 that of \a c2; otherwise returns FALSE.
895 */
896
897 /*!
898 \fn int operator>( QChar c, char ch )
899
900 \overload
901 \relates QChar
902
903 Returns TRUE if the numeric Unicode value of \a c is greater than
904 that of the ASCII/Latin-1 character \a ch; otherwise returns FALSE.
905 */
906
907 /*!
908 \fn int operator>( char ch, QChar c )
909
910 \overload
911 \relates QChar
912
913 Returns TRUE if the numeric Unicode value of the ASCII/Latin-1
914 character \a ch is greater than that of \a c; otherwise returns
915 FALSE.
916 */
917
918 #ifndef QT_NO_UNICODETABLES
919
920 // small class used internally in QString::Compose()
921 class QLigature
922 {
923 public:
924 QLigature( QChar c );
925
first()926 Q_UINT16 first() { cur = ligatures; return cur ? *cur : 0; }
next()927 Q_UINT16 next() { return cur && *cur ? *(cur++) : 0; }
current()928 Q_UINT16 current() { return cur ? *cur : 0; }
929
930 int match(QString & str, unsigned int index);
931 QChar head();
932 QChar::Decomposition tag();
933
934 private:
935 Q_UINT16 *ligatures;
936 Q_UINT16 *cur;
937 };
938
QLigature(QChar c)939 QLigature::QLigature( QChar c )
940 {
941 register int pos = QUnicodeTables::ligature_info[c.row()];
942 if( !pos )
943 ligatures = 0;
944 else
945 {
946 pos = QUnicodeTables::ligature_info[(pos<<8)+c.cell()];
947 ligatures = (Q_UINT16 *)&(QUnicodeTables::ligature_map[pos]);
948 }
949 cur = ligatures;
950 }
951
head()952 QChar QLigature::head()
953 {
954 if(current())
955 return QChar(QUnicodeTables::decomposition_map[current()+1]);
956
957 return QChar::null;
958 }
959
tag()960 QChar::Decomposition QLigature::tag()
961 {
962 if(current())
963 return (QChar::Decomposition) QUnicodeTables::decomposition_map[current()];
964
965 return QChar::Canonical;
966 }
967
match(QString & str,unsigned int index)968 int QLigature::match(QString & str, unsigned int index)
969 {
970 unsigned int i=index;
971
972 if(!current()) return 0;
973
974 Q_UINT16 lig = current() + 2;
975 Q_UINT16 ch;
976
977 while ((i < str.length()) && (ch = QUnicodeTables::decomposition_map[lig])) {
978 if (str[(int)i] != QChar(ch))
979 return 0;
980 i++;
981 lig++;
982 }
983
984 if (!QUnicodeTables::decomposition_map[lig])
985 {
986 return i-index;
987 }
988 return 0;
989 }
990
991
992 // this function is just used in QString::compose()
format(QChar::Decomposition tag,QString & str,int index,int len)993 static inline bool format(QChar::Decomposition tag, QString & str,
994 int index, int len)
995 {
996 unsigned int l = index + len;
997 unsigned int r = index;
998
999 bool left = FALSE, right = FALSE;
1000
1001 left = ((l < str.length()) &&
1002 ((str[(int)l].joining() == QChar::Dual) ||
1003 (str[(int)l].joining() == QChar::Right)));
1004 if (r > 0) {
1005 r--;
1006 //printf("joining(right) = %d\n", str[(int)r].joining());
1007 right = (str[(int)r].joining() == QChar::Dual);
1008 }
1009
1010
1011 switch (tag) {
1012 case QChar::Medial:
1013 return (left & right);
1014 case QChar::Initial:
1015 return (left && !right);
1016 case QChar::Final:
1017 return (right);// && !left);
1018 case QChar::Isolated:
1019 default:
1020 return (!right && !left);
1021 }
1022 } // format()
1023 #endif
1024
1025 /*
1026 QString::compose() and visual() were developed by Gordon Tisher
1027 <tisher@uniserve.ca>, with input from Lars Knoll <knoll@mpi-hd.mpg.de>,
1028 who developed the unicode data tables.
1029 */
1030 /*!
1031 \warning This function is not supported in Qt 3.x. It is provided
1032 for experimental and illustrative purposes only. It is mainly of
1033 interest to those experimenting with Arabic and other
1034 composition-rich texts.
1035
1036 Applies possible ligatures to a QString. Useful when
1037 composition-rich text requires rendering with glyph-poor fonts,
1038 but it also makes compositions such as QChar(0x0041) ('A') and
1039 QChar(0x0308) (Unicode accent diaresis), giving QChar(0x00c4)
1040 (German A Umlaut).
1041 */
compose()1042 void QString::compose()
1043 {
1044 #ifndef QT_NO_UNICODETABLES
1045 unsigned int index=0, len;
1046 unsigned int cindex = 0;
1047
1048 QChar code, head;
1049
1050 QMemArray<QChar> dia;
1051
1052 QString composed = *this;
1053
1054 while (index < length()) {
1055 code = at(index);
1056 //printf("\n\nligature for 0x%x:\n", code.unicode());
1057 QLigature ligature(code);
1058 ligature.first();
1059 while ( ligature.current() ) {
1060 if ((len = ligature.match(*this, index)) != 0) {
1061 head = ligature.head();
1062 unsigned short code = head.unicode();
1063 // we exclude Arabic presentation forms A and a few
1064 // other ligatures, which are undefined in most fonts
1065 if(!(code > 0xfb50 && code < 0xfe80) &&
1066 !(code > 0xfb00 && code < 0xfb2a)) {
1067 // joining info is only needed for Arabic
1068 if (format(ligature.tag(), *this, index, len)) {
1069 //printf("using ligature 0x%x, len=%d\n",code,len);
1070 // replace letter
1071 composed.replace(cindex, len, QChar(head));
1072 index += len-1;
1073 // we continue searching in case we have a final
1074 // form because medial ones are preferred.
1075 if ( len != 1 || ligature.tag() !=QChar::Final )
1076 break;
1077 }
1078 }
1079 }
1080 ligature.next();
1081 }
1082 cindex++;
1083 index++;
1084 }
1085 *this = composed;
1086 #endif
1087 }
1088
1089
1090 // These macros are used for efficient allocation of QChar strings.
1091 // IMPORTANT! If you change these, make sure you also change the
1092 // "delete unicode" statement in ~QStringData() in qstring.h correspondingly!
1093
1094 #define QT_ALLOC_QCHAR_VEC( N ) (QChar*) new char[ sizeof(QChar)*( N ) ]
1095 #define QT_DELETE_QCHAR_VEC( P ) delete[] ((char*)( P ))
1096
1097
1098 /*!
1099 This utility function converts the 8-bit string \a ba to Unicode,
1100 returning the result.
1101
1102 The caller is responsible for deleting the return value with
1103 delete[].
1104 */
1105
latin1ToUnicode(const QByteArray & ba,uint * len)1106 QChar* QString::latin1ToUnicode( const QByteArray& ba, uint* len )
1107 {
1108 if ( ba.isNull() ) {
1109 *len = 0;
1110 return 0;
1111 }
1112 int l = 0;
1113 while ( l < (int)ba.size() && ba[l] )
1114 l++;
1115 char* str = ba.data();
1116 QChar *uc = new QChar[ l ]; // Can't use macro, since function is public
1117 QChar *result = uc;
1118 if ( len )
1119 *len = l;
1120 while (l--)
1121 *uc++ = *str++;
1122 return result;
1123 }
1124
internalLatin1ToUnicode(const QByteArray & ba,uint * len)1125 static QChar* internalLatin1ToUnicode( const QByteArray& ba, uint* len )
1126 {
1127 if ( ba.isNull() ) {
1128 *len = 0;
1129 return 0;
1130 }
1131 int l = 0;
1132 while ( l < (int)ba.size() && ba[l] )
1133 l++;
1134 char* str = ba.data();
1135 QChar *uc = QT_ALLOC_QCHAR_VEC( l );
1136 QChar *result = uc;
1137 if ( len )
1138 *len = l;
1139 while (l--)
1140 *uc++ = *str++;
1141 return result;
1142 }
1143
1144 /*!
1145 \overload
1146
1147 This utility function converts the '\0'-terminated 8-bit string \a
1148 str to Unicode, returning the result and setting \a *len to the
1149 length of the Unicode string.
1150
1151 The caller is responsible for deleting the return value with
1152 delete[].
1153 */
1154
latin1ToUnicode(const char * str,uint * len,uint maxlen)1155 QChar* QString::latin1ToUnicode( const char *str, uint* len, uint maxlen )
1156 {
1157 QChar* result = 0;
1158 uint l = 0;
1159 if ( str ) {
1160 if ( maxlen != (uint)-1 ) {
1161 while ( l < maxlen && str[l] )
1162 l++;
1163 } else {
1164 // Faster?
1165 l = int(strlen( str ));
1166 }
1167 QChar *uc = new QChar[ l ]; // Can't use macro since function is public
1168 result = uc;
1169 uint i = l;
1170 while ( i-- )
1171 *uc++ = *str++;
1172 }
1173 if ( len )
1174 *len = l;
1175 return result;
1176 }
1177
internalLatin1ToUnicode(const char * str,uint * len,uint maxlen=(uint)-1)1178 static QChar* internalLatin1ToUnicode( const char *str, uint* len,
1179 uint maxlen = (uint)-1 )
1180 {
1181 QChar* result = 0;
1182 uint l = 0;
1183 if ( str ) {
1184 if ( maxlen != (uint)-1 ) {
1185 while ( l < maxlen && str[l] )
1186 l++;
1187 } else {
1188 // Faster?
1189 l = int(strlen( str ));
1190 }
1191 QChar *uc = QT_ALLOC_QCHAR_VEC( l );
1192 result = uc;
1193 uint i = l;
1194 while ( i-- )
1195 *uc++ = *str++;
1196 }
1197 if ( len )
1198 *len = l;
1199 return result;
1200 }
1201
1202 /*!
1203 This utility function converts \a l 16-bit characters from \a uc
1204 to ASCII, returning a '\0'-terminated string.
1205
1206 The caller is responsible for deleting the resultant string with
1207 delete[].
1208 */
unicodeToLatin1(const QChar * uc,uint l)1209 char* QString::unicodeToLatin1(const QChar *uc, uint l)
1210 {
1211 if (!uc) {
1212 return 0;
1213 }
1214 char *a = new char[l+1];
1215 char *result = a;
1216 while (l--) {
1217 *a++ = (uc->unicode() > 0xff) ? '?' : (char)uc->unicode();
1218 uc++;
1219 }
1220 *a = '\0';
1221 return result;
1222 }
1223
1224 /*****************************************************************************
1225 QString member functions
1226 *****************************************************************************/
1227
1228 /*!
1229 \class QString qstring.h
1230 \reentrant
1231
1232 \brief The QString class provides an abstraction of Unicode text
1233 and the classic C '\0'-terminated char array.
1234
1235 \ingroup tools
1236 \ingroup shared
1237 \ingroup text
1238 \mainclass
1239
1240 QString uses \link shclass.html implicit sharing\endlink, which
1241 makes it very efficient and easy to use.
1242
1243 In all of the QString methods that take \c {const char *}
1244 parameters, the \c {const char *} is interpreted as a classic
1245 C-style '\0'-terminated ASCII string. It is legal for the \c
1246 {const char *} parameter to be 0. If the \c {const char *} is not
1247 '\0'-terminated, the results are undefined. Functions that copy
1248 classic C strings into a QString will not copy the terminating
1249 '\0' character. The QChar array of the QString (as returned by
1250 unicode()) is generally not terminated by a '\0'. If you need to
1251 pass a QString to a function that requires a C '\0'-terminated
1252 string use latin1().
1253
1254 \keyword QString::null
1255 A QString that has not been assigned to anything is \e null, i.e.
1256 both the length and data pointer is 0. A QString that references
1257 the empty string ("", a single '\0' char) is \e empty. Both null
1258 and empty QStrings are legal parameters to the methods. Assigning
1259 \c{(const char *) 0} to QString gives a null QString. For
1260 convenience, \c QString::null is a null QString. When sorting,
1261 empty strings come first, followed by non-empty strings, followed
1262 by null strings. We recommend using \c{if ( !str.isNull() )} to
1263 check for a non-null string rather than \c{if ( !str )}; see \l
1264 operator!() for an explanation.
1265
1266 Note that if you find that you are mixing usage of \l QCString,
1267 QString, and \l QByteArray, this causes lots of unnecessary
1268 copying and might indicate that the true nature of the data you
1269 are dealing with is uncertain. If the data is '\0'-terminated 8-bit
1270 data, use \l QCString; if it is unterminated (i.e. contains '\0's)
1271 8-bit data, use \l QByteArray; if it is text, use QString.
1272
1273 Lists of strings are handled by the QStringList class. You can
1274 split a string into a list of strings using QStringList::split(),
1275 and join a list of strings into a single string with an optional
1276 separator using QStringList::join(). You can obtain a list of
1277 strings from a string list that contain a particular substring or
1278 that match a particular \link qregexp.html regex\endlink using
1279 QStringList::grep().
1280
1281 <b>Note for C programmers</b>
1282
1283 Due to C++'s type system and the fact that QString is implicitly
1284 shared, QStrings can be treated like ints or other simple base
1285 types. For example:
1286
1287 \code
1288 QString boolToString( bool b )
1289 {
1290 QString result;
1291 if ( b )
1292 result = "True";
1293 else
1294 result = "False";
1295 return result;
1296 }
1297 \endcode
1298
1299 The variable, result, is an auto variable allocated on the stack.
1300 When return is called, because we're returning by value, The copy
1301 constructor is called and a copy of the string is returned. (No
1302 actual copying takes place thanks to the implicit sharing, see
1303 below.)
1304
1305 Throughout Qt's source code you will encounter QString usages like
1306 this:
1307 \code
1308 QString func( const QString& input )
1309 {
1310 QString output = input;
1311 // process output
1312 return output;
1313 }
1314 \endcode
1315
1316 The 'copying' of input to output is almost as fast as copying a
1317 pointer because behind the scenes copying is achieved by
1318 incrementing a reference count. QString (like all Qt's implicitly
1319 shared classes) operates on a copy-on-write basis, only copying if
1320 an instance is actually changed.
1321
1322 If you wish to create a deep copy of a QString without losing any
1323 Unicode information then you should use QDeepCopy.
1324
1325 \sa QChar QCString QByteArray QConstString
1326 */
1327
1328 /*! \enum Qt::ComparisonFlags
1329 \internal
1330 */
1331 /*!
1332 \enum Qt::StringComparisonMode
1333
1334 This enum type is used to set the string comparison mode when
1335 searching for an item. It is used by QListBox, QListView and
1336 QIconView, for example. We'll refer to the string being searched
1337 as the 'target' string.
1338
1339 \value CaseSensitive The strings must match case sensitively.
1340 \value ExactMatch The target and search strings must match exactly.
1341 \value BeginsWith The target string begins with the search string.
1342 \value EndsWith The target string ends with the search string.
1343 \value Contains The target string contains the search string.
1344
1345 If you OR these flags together (excluding \c CaseSensitive), the
1346 search criteria be applied in the following order: \c ExactMatch,
1347 \c BeginsWith, \c EndsWith, \c Contains.
1348
1349 Matching is case-insensitive unless \c CaseSensitive is set. \c
1350 CaseSensitive can be OR-ed with any combination of the other
1351 flags.
1352
1353 */
1354 Q_EXPORT QStringData *QString::shared_null = 0;
1355 QT_STATIC_CONST_IMPL QString QString::null;
1356 QT_STATIC_CONST_IMPL QChar QChar::null;
1357 QT_STATIC_CONST_IMPL QChar QChar::replacement((ushort)0xfffd);
1358 QT_STATIC_CONST_IMPL QChar QChar::byteOrderMark((ushort)0xfeff);
1359 QT_STATIC_CONST_IMPL QChar QChar::byteOrderSwapped((ushort)0xfffe);
1360 QT_STATIC_CONST_IMPL QChar QChar::nbsp((ushort)0x00a0);
1361
makeSharedNull()1362 QStringData* QString::makeSharedNull()
1363 {
1364 QString::shared_null = new QStringData;
1365 #if defined( Q_OS_MAC ) || defined(Q_OS_SOLARIS) || defined(Q_OS_HPUX) || defined(Q_OS_AIX)
1366 QString *that = const_cast<QString *>(&QString::null);
1367 that->d = QString::shared_null;
1368 #endif
1369 return QString::shared_null;
1370 }
1371
1372 /*!
1373 \fn QString::QString()
1374
1375 Constructs a null string, i.e. both the length and data pointer
1376 are 0.
1377
1378 \sa isNull()
1379 */
1380
1381 /*!
1382 Constructs a string of length one, containing the character \a ch.
1383 */
QString(QChar ch)1384 QString::QString( QChar ch )
1385 {
1386 d = new QStringData( QT_ALLOC_QCHAR_VEC( 1 ), 1, 1 );
1387 d->unicode[0] = ch;
1388 }
1389
1390 /*!
1391 Constructs an implicitly shared copy of \a s. This is very fast
1392 since it only involves incrementing a reference count.
1393 */
QString(const QString & s)1394 QString::QString( const QString &s ) :
1395 d(s.d)
1396 {
1397 d->ref();
1398 }
1399
1400 /*!
1401 \internal
1402
1403 Private function.
1404
1405 Constructs a string with preallocated space for \a size characters.
1406
1407 The string is empty.
1408
1409 \sa isNull()
1410 */
1411
QString(int size,bool)1412 QString::QString( int size, bool /*dummy*/ )
1413 {
1414 if ( size ) {
1415 int l = size;
1416 QChar* uc = QT_ALLOC_QCHAR_VEC( l );
1417 d = new QStringData( uc, 0, l );
1418 } else {
1419 d = shared_null ? shared_null : (shared_null=new QStringData);
1420 d->ref();
1421 }
1422 }
1423
1424 /*!
1425 Constructs a string that is a deep copy of \a ba interpreted as a
1426 classic C string.
1427 */
1428
QString(const QByteArray & ba)1429 QString::QString( const QByteArray& ba )
1430 {
1431 #ifndef QT_NO_TEXTCODEC
1432 if ( QTextCodec::codecForCStrings() ) {
1433 d = 0;
1434 *this = fromAscii( ba.data(), ba.size() );
1435 return;
1436 }
1437 #endif
1438 uint l;
1439 QChar *uc = internalLatin1ToUnicode(ba,&l);
1440 d = new QStringData(uc,l,l);
1441 }
1442
1443 /*!
1444 Constructs a string that is a deep copy of the first \a length
1445 characters in the QChar array.
1446
1447 If \a unicode and \a length are 0, then a null string is created.
1448
1449 If only \a unicode is 0, the string is empty but has \a length
1450 characters of space preallocated: QString expands automatically
1451 anyway, but this may speed up some cases a little. We recommend
1452 using the plain constructor and setLength() for this purpose since
1453 it will result in more readable code.
1454
1455 \sa isNull() setLength()
1456 */
1457
QString(const QChar * unicode,uint length)1458 QString::QString( const QChar* unicode, uint length )
1459 {
1460 if ( !unicode && !length ) {
1461 d = shared_null ? shared_null : makeSharedNull();
1462 d->ref();
1463 } else {
1464 QChar* uc = QT_ALLOC_QCHAR_VEC( length );
1465 if ( unicode )
1466 memcpy(uc, unicode, length*sizeof(QChar));
1467 d = new QStringData(uc,unicode ? length : 0,length);
1468 }
1469 }
1470
1471 /*!
1472 Constructs a string that is a deep copy of \a str, interpreted as
1473 a classic C string. The encoding is assumed to be Latin-1, unless
1474 you change it using QTextCodec::setCodecForCStrings().
1475
1476 If \a str is 0, then a null string is created.
1477
1478 This is a cast constructor, but it is perfectly safe: converting a
1479 Latin-1 \c{const char *} to QString preserves all the information. You
1480 can disable this constructor by defining \c QT_NO_CAST_ASCII when
1481 you compile your applications. You can also make QString objects
1482 by using setLatin1(), fromLatin1(), fromLocal8Bit(), and
1483 fromUtf8(). Or whatever encoding is appropriate for the 8-bit data
1484 you have.
1485
1486 \sa isNull(), fromAscii()
1487 */
1488
QString(const char * str)1489 QString::QString( const char *str )
1490 {
1491 #ifndef QT_NO_TEXTCODEC
1492 if ( QTextCodec::codecForCStrings() ) {
1493 d = 0;
1494 *this = fromAscii( str );
1495 return;
1496 }
1497 #endif
1498 uint l;
1499 QChar *uc = internalLatin1ToUnicode(str,&l);
1500 d = new QStringData(uc,l,l);
1501 }
1502
1503 #ifndef QT_NO_STL
1504 /*!
1505 Constructs a string that is a deep copy of \a str.
1506
1507 This is the same as fromAscii(\a str).
1508 */
1509
QString(const std::string & str)1510 QString::QString( const std::string &str )
1511 {
1512 #ifndef QT_NO_TEXTCODEC
1513 if ( QTextCodec::codecForCStrings() ) {
1514 d = 0;
1515 *this = fromAscii( str.c_str() );
1516 return;
1517 }
1518 #endif
1519 uint l;
1520 QChar *uc = internalLatin1ToUnicode(str.c_str(),&l);
1521 d = new QStringData(uc,l,l);
1522 }
1523 #endif
1524
1525 /*!
1526 \fn QString::~QString()
1527
1528 Destroys the string and frees the string's data if this is the
1529 last reference to the string.
1530 */
1531
1532
1533 /*!
1534 Deallocates any space reserved solely by this QString.
1535
1536 If the string does not share its data with another QString
1537 instance, nothing happens; otherwise the function creates a new,
1538 unique copy of this string. This function is called whenever the
1539 string is modified.
1540 */
1541
real_detach()1542 void QString::real_detach()
1543 {
1544 setLength( length() );
1545 }
1546
deref()1547 void QString::deref()
1548 {
1549 if ( d && d->deref() ) {
1550 if ( d != shared_null )
1551 delete d;
1552 d = 0;
1553 }
1554 }
1555
deleteSelf()1556 void QStringData::deleteSelf()
1557 {
1558 delete this;
1559 }
1560
1561 /*!
1562 \fn QString& QString::operator=( QChar c )
1563
1564 Sets the string to contain just the single character \a c.
1565 */
1566
1567 /*!
1568 \fn QString& QString::operator=( const std::string& s )
1569
1570 \overload
1571
1572 Makes a deep copy of \a s and returns a reference to the deep
1573 copy.
1574 */
1575
1576 /*!
1577 \fn QString& QString::operator=( char c )
1578
1579 \overload
1580
1581 Sets the string to contain just the single character \a c.
1582 */
1583
1584 /*!
1585 \overload
1586
1587 Assigns a shallow copy of \a s to this string and returns a
1588 reference to this string. This is very fast because the string
1589 isn't actually copied.
1590 */
operator =(const QString & s)1591 QString &QString::operator=( const QString &s )
1592 {
1593 s.d->ref();
1594 deref();
1595 d = s.d;
1596 return *this;
1597 }
1598
1599 /*!
1600 \overload
1601
1602 Assigns a deep copy of \a cstr, interpreted as a classic C
1603 string, to this string. Returns a reference to this string.
1604 */
operator =(const QCString & cstr)1605 QString &QString::operator=( const QCString& cstr )
1606 {
1607 return setAscii( cstr );
1608 }
1609
1610
1611 /*!
1612 \overload
1613
1614 Assigns a deep copy of \a str, interpreted as a classic C string
1615 to this string and returns a reference to this string.
1616
1617 If \a str is 0, then a null string is created.
1618
1619 \sa isNull()
1620 */
operator =(const char * str)1621 QString &QString::operator=( const char *str )
1622 {
1623 return setAscii(str);
1624 }
1625
1626
1627 /*!
1628 \fn bool QString::isNull() const
1629
1630 Returns TRUE if the string is null; otherwise returns FALSE. A
1631 null string is always empty.
1632
1633 \code
1634 QString a; // a.unicode() == 0, a.length() == 0
1635 a.isNull(); // TRUE, because a.unicode() == 0
1636 a.isEmpty(); // TRUE, because a.length() == 0
1637 \endcode
1638
1639 \sa isEmpty(), length()
1640 */
1641
1642 /*!
1643 \fn bool QString::isEmpty() const
1644
1645 Returns TRUE if the string is empty, i.e. if length() == 0;
1646 otherwise returns FALSE. Null strings are also empty.
1647
1648 \code
1649 QString a( "" );
1650 a.isEmpty(); // TRUE
1651 a.isNull(); // FALSE
1652
1653 QString b;
1654 b.isEmpty(); // TRUE
1655 b.isNull(); // TRUE
1656 \endcode
1657
1658 \sa isNull(), length()
1659 */
1660
1661 /*!
1662 \fn uint QString::length() const
1663
1664 Returns the length of the string.
1665
1666 Null strings and empty strings have zero length.
1667
1668 \sa isNull(), isEmpty()
1669 */
1670
1671 /*!
1672 If \a newLen is less than the length of the string, then the
1673 string is truncated at position \a newLen. Otherwise nothing
1674 happens.
1675
1676 \code
1677 QString s = "truncate me";
1678 s.truncate( 5 ); // s == "trunc"
1679 \endcode
1680
1681 \sa setLength()
1682 */
1683
truncate(uint newLen)1684 void QString::truncate( uint newLen )
1685 {
1686 if ( newLen < d->len )
1687 setLength( newLen );
1688 }
1689
1690 /*!
1691 Ensures that at least \a newLen characters are allocated to the
1692 string, and sets the length of the string to \a newLen. Any new
1693 space allocated contains arbitrary data.
1694
1695 \sa reserve(), truncate()
1696 */
setLength(uint newLen)1697 void QString::setLength( uint newLen )
1698 {
1699 if ( d->count != 1 || newLen > d->maxl ||
1700 ( newLen * 4 < d->maxl && d->maxl > 4 ) ) {
1701 // detach, grow or shrink
1702 uint newMax = computeNewMax( newLen );
1703 QChar* nd = QT_ALLOC_QCHAR_VEC( newMax );
1704 if ( nd ) {
1705 uint len = QMIN( d->len, newLen );
1706 memcpy( nd, d->unicode, sizeof(QChar) * len );
1707 deref();
1708 d = new QStringData( nd, newLen, newMax );
1709 }
1710 } else {
1711 d->len = newLen;
1712 d->setDirty();
1713 }
1714 }
1715
1716 /*!
1717 \fn uint QString::capacity() const
1718
1719 Returns the number of characters this string can hold
1720 in the allocated memory.
1721
1722 \sa reserve(), squeeze()
1723 */
1724
1725 /*!
1726 Ensures that at least \a minCapacity characters are allocated to
1727 the string.
1728
1729 This function is useful for code that needs to build up a long
1730 string and wants to avoid repeated reallocation. In this example,
1731 we want to add to the string until some condition is true, and
1732 we're fairly sure that size is big enough:
1733 \code
1734 QString result;
1735 int len = 0;
1736 result.reserve(maxLen);
1737 while (...) {
1738 result[len++] = ... // fill part of the space
1739 }
1740 result.squeeze();
1741 \endcode
1742
1743 If \e maxLen is an underestimate, the worst that will happen is
1744 that the loop will slow down.
1745
1746 If it is not possible to allocate enough memory, the string
1747 remains unchanged.
1748
1749 \sa capacity(), squeeze(), setLength()
1750 */
1751
reserve(uint minCapacity)1752 void QString::reserve( uint minCapacity )
1753 {
1754 if ( d->maxl < minCapacity ) {
1755 QChar *nd = QT_ALLOC_QCHAR_VEC( minCapacity );
1756 if ( nd ) {
1757 uint len = d->len;
1758 if ( len )
1759 memcpy( nd, d->unicode, sizeof(QChar) * len );
1760 deref();
1761 d = new QStringData( nd, len, minCapacity );
1762 }
1763 }
1764 }
1765
1766
1767 /*!
1768 Squeezes the string's capacity to the current content.
1769
1770 \sa capacity(), reserve()
1771 */
squeeze()1772 void QString::squeeze()
1773 {
1774 if ( d->maxl > d->len ) {
1775 QChar *nd = QT_ALLOC_QCHAR_VEC( d->len );
1776 if ( nd ) {
1777 uint len = d->len;
1778 if ( len )
1779 memcpy( nd, d->unicode, sizeof(QChar) * len );
1780 deref();
1781 d = new QStringData( nd, len, len );
1782 }
1783 }
1784 }
1785
1786 /*!
1787 \internal
1788
1789 Like setLength, but doesn't shrink the allocated memory.
1790 */
grow(uint newLen)1791 void QString::grow( uint newLen )
1792 {
1793 if ( d->count != 1 || newLen > d->maxl ) {
1794 setLength( newLen );
1795 } else {
1796 d->len = newLen;
1797 d->setDirty();
1798 }
1799 }
1800
1801 struct ArgEscapeData
1802 {
1803 uint min_escape; // lowest escape sequence number
1804 uint occurrences; // number of occurences of the lowest escape
1805 // sequence number
1806 uint locale_occurrences; // number of occurences of the lowest escape
1807 // sequence number which contain 'L'
1808 uint escape_len; // total length of escape sequences which will
1809 // be replaced
1810 };
1811
findArgEscapes(const QString & s)1812 static ArgEscapeData findArgEscapes(const QString &s)
1813 {
1814 const QChar *uc_begin = s.unicode();
1815 const QChar *uc_end = uc_begin + s.length();
1816
1817 ArgEscapeData d;
1818
1819 d.min_escape = 10;
1820 d.occurrences = 0;
1821 d.escape_len = 0;
1822 d.locale_occurrences = 0;
1823
1824 const QChar *c = uc_begin;
1825 while (c != uc_end) {
1826 while (c != uc_end && c->unicode() != '%')
1827 ++c;
1828
1829 if (c == uc_end || ++c == uc_end)
1830 break;
1831
1832 bool locale_arg = FALSE;
1833 if (c->unicode() == 'L') {
1834 locale_arg = TRUE;
1835 if (++c == uc_end)
1836 break;
1837 }
1838
1839 if (c->unicode() < '0' || c->unicode() > '9')
1840 continue;
1841
1842 uint escape = c->unicode() - '0';
1843 ++c;
1844
1845 if (escape > d.min_escape)
1846 continue;
1847
1848 if (escape < d.min_escape) {
1849 d.min_escape = escape;
1850 d.occurrences = 0;
1851 d.escape_len = 0;
1852 d.locale_occurrences = 0;
1853 }
1854
1855 #if QT_VERSION < 0x040000
1856 // ### remove preprocessor in Qt 4.0
1857 /* Since in Qt < 4.0 only the first instance is replaced,
1858 escape_len should hold the length of only the first escape
1859 sequence */
1860 if (d.occurrences == 0)
1861 #endif
1862 {
1863 ++d.occurrences;
1864 if (locale_arg) {
1865 ++d.locale_occurrences;
1866 d.escape_len += 3;
1867 }
1868 else
1869 d.escape_len += 2;
1870 }
1871 }
1872
1873 return d;
1874 }
1875
replaceArgEscapes(const QString & s,const ArgEscapeData & d,int field_width,const QString & arg,const QString & larg)1876 static QString replaceArgEscapes(const QString &s, const ArgEscapeData &d, int field_width,
1877 const QString &arg, const QString &larg)
1878 {
1879 const QChar *uc_begin = s.unicode();
1880 const QChar *uc_end = uc_begin + s.length();
1881
1882 uint abs_field_width = QABS(field_width);
1883 uint result_len = s.length()
1884 - d.escape_len
1885 + (d.occurrences - d.locale_occurrences)
1886 *QMAX(abs_field_width, arg.length())
1887 + d.locale_occurrences
1888 *QMAX(abs_field_width, larg.length());
1889
1890 QString result;
1891 result.setLength(result_len);
1892 QChar *result_buff = (QChar*) result.unicode();
1893
1894 QChar *rc = result_buff;
1895 const QChar *c = uc_begin;
1896 uint repl_cnt = 0;
1897 while (c != uc_end) {
1898 /* We don't have to check if we run off the end of the string with c,
1899 because as long as d.occurrences > 0 we KNOW there are valid escape
1900 sequences. */
1901
1902 const QChar *text_start = c;
1903
1904 while (c->unicode() != '%')
1905 ++c;
1906
1907 const QChar *escape_start = c++;
1908
1909 bool locale_arg = FALSE;
1910 if (c->unicode() == 'L') {
1911 locale_arg = TRUE;
1912 ++c;
1913 }
1914
1915 if (c->unicode() != '0' + d.min_escape) {
1916 memcpy(rc, text_start, (c - text_start)*sizeof(QChar));
1917 rc += c - text_start;
1918 }
1919 else {
1920 ++c;
1921
1922 memcpy(rc, text_start, (escape_start - text_start)*sizeof(QChar));
1923 rc += escape_start - text_start;
1924
1925 uint pad_chars;
1926 if (locale_arg)
1927 pad_chars = QMAX(abs_field_width, larg.length()) - larg.length();
1928 else
1929 pad_chars = QMAX(abs_field_width, arg.length()) - arg.length();
1930
1931 if (field_width > 0) { // left padded
1932 for (uint i = 0; i < pad_chars; ++i)
1933 (rc++)->unicode() = ' ';
1934 }
1935
1936 if (locale_arg) {
1937 memcpy(rc, larg.unicode(), larg.length()*sizeof(QChar));
1938 rc += larg.length();
1939 }
1940 else {
1941 memcpy(rc, arg.unicode(), arg.length()*sizeof(QChar));
1942 rc += arg.length();
1943 }
1944
1945 if (field_width < 0) { // right padded
1946 for (uint i = 0; i < pad_chars; ++i)
1947 (rc++)->unicode() = ' ';
1948 }
1949
1950 if (++repl_cnt == d.occurrences) {
1951 memcpy(rc, c, (uc_end - c)*sizeof(QChar));
1952 rc += uc_end - c;
1953 Q_ASSERT(rc - result_buff == (int)result_len);
1954 c = uc_end;
1955 }
1956 }
1957 }
1958
1959 return result;
1960 }
1961
1962 /*!
1963 This function will return a string that replaces the lowest
1964 numbered occurrence of \c %1, \c %2, ..., \c %9 with \a a.
1965
1966 The \a fieldWidth value specifies the minimum amount of space that
1967 \a a is padded to. A positive value will produce right-aligned
1968 text, whereas a negative value will produce left-aligned text.
1969
1970 The following example shows how we could create a 'status' string
1971 when processing a list of files:
1972 \code
1973 QString status = QString( "Processing file %1 of %2: %3" )
1974 .arg( i ) // current file's number
1975 .arg( total ) // number of files to process
1976 .arg( fileName ); // current file's name
1977 \endcode
1978
1979 It is generally fine to use filenames and numbers as we have done
1980 in the example above. But note that using arg() to construct
1981 natural language sentences does not usually translate well into
1982 other languages because sentence structure and word order often
1983 differ between languages.
1984
1985 If there is no place marker (\c %1, \c %2, etc.), a warning
1986 message (qWarning()) is output and the result is undefined.
1987
1988 \warning If any placeholder occurs more than once, the result is undefined.
1989
1990 */
arg(const QString & a,int fieldWidth) const1991 QString QString::arg( const QString& a, int fieldWidth ) const
1992 {
1993 ArgEscapeData d = findArgEscapes(*this);
1994
1995 if (d.occurrences == 0) {
1996 qWarning( "QString::arg(): Argument missing: %s, %s", latin1(),
1997 a.latin1() );
1998 return *this;
1999 }
2000
2001 return replaceArgEscapes(*this, d, fieldWidth, a, a);
2002 }
2003
2004 /*!
2005 \fn QString QString::arg( const QString& a1, const QString& a2 ) const
2006
2007 \overload
2008
2009 This is the same as str.arg(\a a1).arg(\a a2), except that
2010 the strings are replaced in one pass. This can make a difference
2011 if \a a1 contains e.g. \c{%1}:
2012
2013 \code
2014 QString str( "%1 %2" );
2015 str.arg( "Hello", "world" ); // returns "Hello world"
2016 str.arg( "Hello" ).arg( "world" ); // returns "Hello world"
2017
2018 str.arg( "(%1)", "Hello" ); // returns "(%1) Hello"
2019 str.arg( "(%1)" ).arg( "Hello" ); // returns "(Hello) %2"
2020 \endcode
2021 */
2022
2023 /*!
2024 \fn QString QString::arg( const QString& a1, const QString& a2,
2025 const QString& a3 ) const
2026 \overload
2027
2028 This is the same as calling str.arg(\a a1).arg(\a a2).arg(\a a3),
2029 except that the strings are replaced in one pass.
2030 */
2031
2032 /*!
2033 \fn QString QString::arg( const QString& a1, const QString& a2,
2034 const QString& a3, const QString& a4 ) const
2035 \overload
2036
2037 This is the same as calling
2038 str.arg(\a a1).arg(\a a2).arg(\a a3).arg(\a a4),
2039 except that the strings are replaced in one pass.
2040 */
2041
2042 /*!
2043 \overload
2044
2045 The \a fieldWidth value specifies the minimum amount of space that
2046 \a a is padded to. A positive value will produce a right-aligned
2047 number, whereas a negative value will produce a left-aligned
2048 number.
2049
2050 \a a is expressed in base \a base, which is 10 by default and must
2051 be between 2 and 36.
2052
2053 The '%' can be followed by an 'L', in which case the sequence is
2054 replaced with a localized representation of \a a. The conversion
2055 uses the default locale. The default locale is determined from the
2056 system's locale settings at application startup. It can be changed
2057 using QLocale::setDefault(). The 'L' flag is ignored if \a base is
2058 not 10.
2059
2060 \code
2061 QString str;
2062 str = QString( "Decimal 63 is %1 in hexadecimal" )
2063 .arg( 63, 0, 16 );
2064 // str == "Decimal 63 is 3f in hexadecimal"
2065
2066 QLocale::setDefault(QLocale::English, QLocale::UnitedStates);
2067 str = QString( "%1 %L2 %L3" )
2068 .arg( 12345 )
2069 .arg( 12345 )
2070 .arg( 12345, 0, 16 );
2071 // str == "12345 12,345 3039"
2072 \endcode
2073 */
arg(long a,int fieldWidth,int base) const2074 QString QString::arg( long a, int fieldWidth, int base ) const
2075 {
2076 return arg((Q_LLONG)a, fieldWidth, base);
2077 }
2078
2079 /*!
2080 \overload
2081
2082 \a a is expressed in base \a base, which is 10 by default and must
2083 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2084 to produce localized strings.
2085 */
arg(ulong a,int fieldWidth,int base) const2086 QString QString::arg( ulong a, int fieldWidth, int base ) const
2087 {
2088 return arg((Q_ULLONG)a, fieldWidth, base);
2089 }
2090
2091 /*!
2092 \overload
2093
2094 \a a is expressed in base \a base, which is 10 by default and must
2095 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2096 to produce localized strings.
2097 */
arg(Q_LLONG a,int fieldWidth,int base) const2098 QString QString::arg( Q_LLONG a, int fieldWidth, int base ) const
2099 {
2100 ArgEscapeData d = findArgEscapes(*this);
2101
2102 if (d.occurrences == 0) {
2103 qWarning( "QString::arg(): Argument missing: %s, %lld", latin1(),
2104 a );
2105 return *this;
2106 }
2107
2108 QString arg;
2109 if (d.occurrences > d.locale_occurrences)
2110 arg = number(a, base);
2111
2112 QString locale_arg;
2113 if (d.locale_occurrences > 0) {
2114 QLocale locale;
2115 locale_arg = locale.d->longLongToString(a, -1, base, -1, QLocalePrivate::ThousandsGroup);
2116 }
2117
2118 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg);
2119 }
2120
2121 /*!
2122 \overload
2123
2124 \a a is expressed in base \a base, which is 10 by default and must
2125 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2126 to produce localized strings.
2127 */
arg(Q_ULLONG a,int fieldWidth,int base) const2128 QString QString::arg( Q_ULLONG a, int fieldWidth, int base ) const
2129 {
2130 ArgEscapeData d = findArgEscapes(*this);
2131
2132 if (d.occurrences == 0) {
2133 qWarning( "QString::arg(): Argument missing: %s, %llu", latin1(),
2134 a );
2135 return *this;
2136 }
2137
2138 QString arg;
2139 if (d.occurrences > d.locale_occurrences)
2140 arg = number(a, base);
2141
2142 QString locale_arg;
2143 if (d.locale_occurrences > 0) {
2144 QLocale locale;
2145 locale_arg = locale.d->unsLongLongToString(a, -1, base, -1, QLocalePrivate::ThousandsGroup);
2146 }
2147
2148 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg);
2149 }
2150
2151 /*!
2152 \fn QString QString::arg( int a, int fieldWidth, int base ) const
2153
2154 \overload
2155
2156 \a a is expressed in base \a base, which is 10 by default and must
2157 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2158 to produce localized strings.
2159 */
2160
2161 /*!
2162 \fn QString QString::arg( uint a, int fieldWidth, int base ) const
2163
2164 \overload
2165
2166 \a a is expressed in base \a base, which is 10 by default and must
2167 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2168 to produce localized strings.
2169 */
2170
2171 /*!
2172 \fn QString QString::arg( short a, int fieldWidth, int base ) const
2173
2174 \overload
2175
2176 \a a is expressed in base \a base, which is 10 by default and must
2177 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2178 to produce localized strings.
2179 */
2180
2181 /*!
2182 \fn QString QString::arg( ushort a, int fieldWidth, int base ) const
2183
2184 \overload
2185
2186 \a a is expressed in base \a base, which is 10 by default and must
2187 be between 2 and 36. If \a base is 10, the '%L' syntax can be used
2188 to produce localized strings.
2189 */
2190
2191
2192 /*!
2193 \overload
2194
2195 \a a is assumed to be in the Latin-1 character set.
2196 */
arg(char a,int fieldWidth) const2197 QString QString::arg( char a, int fieldWidth ) const
2198 {
2199 QString c;
2200 c += a;
2201 return arg( c, fieldWidth );
2202 }
2203
2204 /*!
2205 \overload
2206 */
arg(QChar a,int fieldWidth) const2207 QString QString::arg( QChar a, int fieldWidth ) const
2208 {
2209 QString c;
2210 c += a;
2211 return arg( c, fieldWidth );
2212 }
2213
2214 /*!
2215 \overload
2216
2217 \target arg-formats
2218
2219 Argument \a a is formatted according to the \a fmt format specified,
2220 which is 'g' by default and can be any of the following:
2221
2222 \table
2223 \header \i Format \i Meaning
2224 \row \i \c e \i format as [-]9.9e[+|-]999
2225 \row \i \c E \i format as [-]9.9E[+|-]999
2226 \row \i \c f \i format as [-]9.9
2227 \row \i \c g \i use \c e or \c f format, whichever is the most concise
2228 \row \i \c G \i use \c E or \c f format, whichever is the most concise
2229 \endtable
2230
2231 With 'e', 'E', and 'f', \a prec is the number of digits after the
2232 decimal point. With 'g' and 'G', \a prec is the maximum number of
2233 significant digits (trailing zeroes are omitted).
2234
2235 \code
2236 double d = 12.34;
2237 QString ds = QString( "'E' format, precision 3, gives %1" )
2238 .arg( d, 0, 'E', 3 );
2239 // ds == "'E' format, precision 3, gives 1.234E+01"
2240 \endcode
2241
2242 The '%L' syntax can be used to produce localized strings.
2243 */
arg(double a,int fieldWidth,char fmt,int prec) const2244 QString QString::arg( double a, int fieldWidth, char fmt, int prec ) const
2245 {
2246 ArgEscapeData d = findArgEscapes(*this);
2247
2248 if (d.occurrences == 0) {
2249 qWarning( "QString::arg(): Argument missing: %s, %g", latin1(),
2250 a );
2251 return *this;
2252 }
2253
2254 QString arg;
2255 if (d.occurrences > d.locale_occurrences)
2256 arg = number(a, fmt, prec);
2257
2258 QString locale_arg;
2259 if (d.locale_occurrences > 0) {
2260 QLocale locale;
2261
2262 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
2263 uint flags = 0;
2264
2265 if (qIsUpper(fmt))
2266 flags = QLocalePrivate::CapitalEorX;
2267 fmt = qToLower(fmt);
2268
2269 switch (fmt) {
2270 case 'f':
2271 form = QLocalePrivate::DFDecimal;
2272 break;
2273 case 'e':
2274 form = QLocalePrivate::DFExponent;
2275 break;
2276 case 'g':
2277 form = QLocalePrivate::DFSignificantDigits;
2278 break;
2279 default:
2280 #if defined(QT_CHECK_RANGE)
2281 qWarning( "QString::setNum: Invalid format char '%c'", fmt );
2282 #endif
2283 break;
2284 }
2285
2286 flags |= QLocalePrivate::ThousandsGroup;
2287
2288 locale_arg = locale.d->doubleToString(a, prec, form, -1, flags);
2289 }
2290
2291 return replaceArgEscapes(*this, d, fieldWidth, arg, locale_arg);
2292 }
2293
multiArg(int numArgs,const QString & a1,const QString & a2,const QString & a3,const QString & a4) const2294 QString QString::multiArg( int numArgs, const QString& a1, const QString& a2,
2295 const QString& a3, const QString& a4 ) const
2296 {
2297 QString result;
2298 union {
2299 int digitUsed[10];
2300 int argForDigit[10];
2301 };
2302 register const QChar *uc = d->unicode;
2303 const QString *args[4];
2304 const int len = (int) length();
2305 const int end = len - 1;
2306 int lastDigit = -1;
2307 int i;
2308
2309 memset( digitUsed, 0, sizeof(digitUsed) );
2310 args[0] = &a1;
2311 args[1] = &a2;
2312 args[2] = &a3;
2313 args[3] = &a4;
2314
2315 for ( i = 0; i < end; i++ ) {
2316 if ( uc[i] == '%' ) {
2317 int digit = uc[i + 1].unicode() - '0';
2318 if ( digit >= 0 && digit <= 9 )
2319 digitUsed[digit]++;
2320 }
2321 }
2322
2323 for ( i = 0; i < numArgs; i++ ) {
2324 do {
2325 ++lastDigit;
2326 } while ( lastDigit < 10 && digitUsed[lastDigit] == 0 );
2327
2328 if ( lastDigit == 10 ) {
2329 qWarning( "QString::arg(): Argument missing: %s, %s",
2330 latin1(), args[i]->latin1() );
2331 numArgs = i;
2332 lastDigit = 9;
2333 break;
2334 }
2335 argForDigit[lastDigit] = i;
2336 }
2337
2338 i = 0;
2339 while ( i < len ) {
2340 if ( uc[i] == '%' && i != end ) {
2341 int digit = uc[i + 1].unicode() - '0';
2342 if ( digit >= 0 && digit <= lastDigit ) {
2343 result += *args[argForDigit[digit]];
2344 i += 2;
2345 continue;
2346 }
2347 }
2348 result += uc[i++];
2349 }
2350 return result;
2351 }
2352
2353
2354 /*!
2355 Safely builds a formatted string from the format string \a cformat
2356 and an arbitrary list of arguments. The format string supports all
2357 the escape sequences of printf() in the standard C library.
2358
2359 The %s escape sequence expects a utf8() encoded string. The format
2360 string \e cformat is expected to be in latin1. If you need a
2361 Unicode format string, use arg() instead. For typesafe string
2362 building, with full Unicode support, you can use QTextOStream like
2363 this:
2364
2365 \code
2366 QString str;
2367 QString s = ...;
2368 int x = ...;
2369 QTextOStream( &str ) << s << " : " << x;
2370 \endcode
2371
2372 For \link QObject::tr() translations,\endlink especially if the
2373 strings contains more than one escape sequence, you should
2374 consider using the arg() function instead. This allows the order
2375 of the replacements to be controlled by the translator, and has
2376 Unicode support.
2377
2378 The %lc escape sequence expects a unicode character of type ushort
2379 (as returned by QChar::unicode()).
2380 The %ls escape sequence expects a pointer to a zero-terminated
2381 array of unicode characters of type ushort (as returned by
2382 QString::ucs2()).
2383
2384 \sa arg()
2385 */
2386
2387 #ifndef QT_NO_SPRINTF
sprintf(const char * cformat,...)2388 QString &QString::sprintf( const char* cformat, ... )
2389 {
2390 QLocale locale(QLocale::C);
2391
2392 va_list ap;
2393 va_start( ap, cformat );
2394
2395 if ( !cformat || !*cformat ) {
2396 // Qt 1.x compat
2397 *this = fromLatin1( "" );
2398 return *this;
2399 }
2400
2401 // Parse cformat
2402
2403 QString result;
2404 const char *c = cformat;
2405 for (;;) {
2406 // Copy non-escape chars to result
2407 while (*c != '\0' && *c != '%')
2408 result.append(*c++);
2409
2410 if (*c == '\0')
2411 break;
2412
2413 // Found '%'
2414 const char *escape_start = c;
2415 ++c;
2416
2417 if (*c == '\0') {
2418 result.append('%'); // a % at the end of the string - treat as non-escape text
2419 break;
2420 }
2421 if (*c == '%') {
2422 result.append('%'); // %%
2423 ++c;
2424 continue;
2425 }
2426
2427 // Parse flag characters
2428 unsigned flags = 0;
2429 bool no_more_flags = FALSE;
2430 do {
2431 switch (*c) {
2432 case '#': flags |= QLocalePrivate::Alternate; break;
2433 case '0': flags |= QLocalePrivate::ZeroPadded; break;
2434 case '-': flags |= QLocalePrivate::LeftAdjusted; break;
2435 case ' ': flags |= QLocalePrivate::BlankBeforePositive; break;
2436 case '+': flags |= QLocalePrivate::AlwaysShowSign; break;
2437 case '\'': flags |= QLocalePrivate::ThousandsGroup; break;
2438 default: no_more_flags = TRUE; break;
2439 }
2440
2441 if (!no_more_flags)
2442 ++c;
2443 } while (!no_more_flags);
2444
2445 if (*c == '\0') {
2446 result.append(escape_start); // incomplete escape, treat as non-escape text
2447 break;
2448 }
2449
2450 // Parse field width
2451 int width = -1; // -1 means unspecified
2452 if (qIsDigit(*c)) {
2453 QString width_str;
2454 while (*c != '\0' && qIsDigit(*c))
2455 width_str.append(*c++);
2456
2457 // can't be negative - started with a digit
2458 // contains at least one digit
2459 width = width_str.toInt();
2460 }
2461 else if (*c == '*') {
2462 width = va_arg(ap, int);
2463 if (width < 0)
2464 width = -1; // treat all negative numbers as unspecified
2465 ++c;
2466 }
2467
2468 if (*c == '\0') {
2469 result.append(escape_start); // incomplete escape, treat as non-escape text
2470 break;
2471 }
2472
2473 // Parse precision
2474 int precision = -1; // -1 means unspecified
2475 if (*c == '.') {
2476 ++c;
2477 if (qIsDigit(*c)) {
2478 QString precision_str;
2479 while (*c != '\0' && qIsDigit(*c))
2480 precision_str.append(*c++);
2481
2482 // can't be negative - started with a digit
2483 // contains at least one digit
2484 precision = precision_str.toInt();
2485 }
2486 else if (*c == '*') {
2487 precision = va_arg(ap, int);
2488 if (precision < 0)
2489 precision = -1; // treat all negative numbers as unspecified
2490 ++c;
2491 }
2492 }
2493
2494 if (*c == '\0') {
2495 result.append(escape_start); // incomplete escape, treat as non-escape text
2496 break;
2497 }
2498
2499 // Parse the length modifier
2500 enum LengthMod { lm_none, lm_hh, lm_h, lm_l, lm_ll, lm_L, lm_j, lm_z, lm_t };
2501 LengthMod length_mod = lm_none;
2502 switch (*c) {
2503 case 'h':
2504 ++c;
2505 if (*c == 'h') {
2506 length_mod = lm_hh;
2507 ++c;
2508 }
2509 else
2510 length_mod = lm_h;
2511 break;
2512
2513 case 'l':
2514 ++c;
2515 if (*c == 'l') {
2516 length_mod = lm_ll;
2517 ++c;
2518 }
2519 else
2520 length_mod = lm_l;
2521 break;
2522
2523 case 'L':
2524 ++c;
2525 length_mod = lm_L;
2526 break;
2527
2528 case 'j':
2529 ++c;
2530 length_mod = lm_j;
2531 break;
2532
2533 case 'z':
2534 case 'Z':
2535 ++c;
2536 length_mod = lm_z;
2537 break;
2538
2539 case 't':
2540 ++c;
2541 length_mod = lm_t;
2542 break;
2543
2544 default: break;
2545 }
2546
2547 if (*c == '\0') {
2548 result.append(escape_start); // incomplete escape, treat as non-escape text
2549 break;
2550 }
2551
2552 // Parse the conversion specifier and do the conversion
2553 QString subst;
2554 switch (*c) {
2555 case 'd':
2556 case 'i': {
2557 Q_LLONG i;
2558 switch (length_mod) {
2559 case lm_none: i = va_arg(ap, int); break;
2560 case lm_hh: i = va_arg(ap, int); break;
2561 case lm_h: i = va_arg(ap, int); break;
2562 case lm_l: i = va_arg(ap, long int); break;
2563 case lm_ll: i = va_arg(ap, Q_LLONG); break;
2564 case lm_j: i = va_arg(ap, long int); break;
2565 case lm_z: i = va_arg(ap, size_t); break;
2566 case lm_t: i = va_arg(ap, int); break;
2567 default: i = 0; break;
2568 }
2569 subst = locale.d->longLongToString(i, precision, 10, width, flags);
2570 ++c;
2571 break;
2572 }
2573 case 'o':
2574 case 'u':
2575 case 'x':
2576 case 'X': {
2577 Q_ULLONG u;
2578 switch (length_mod) {
2579 case lm_none: u = va_arg(ap, unsigned int); break;
2580 case lm_hh: u = va_arg(ap, unsigned int); break;
2581 case lm_h: u = va_arg(ap, unsigned int); break;
2582 case lm_l: u = va_arg(ap, unsigned long int); break;
2583 case lm_ll: u = va_arg(ap, Q_ULLONG); break;
2584 default: u = 0; break;
2585 }
2586
2587 if (qIsUpper(*c))
2588 flags |= QLocalePrivate::CapitalEorX;
2589
2590 int base = 10;
2591 switch (qToLower(*c)) {
2592 case 'o':
2593 base = 8; break;
2594 case 'u':
2595 base = 10; break;
2596 case 'x':
2597 base = 16; break;
2598 default: break;
2599 }
2600 subst = locale.d->unsLongLongToString(u, precision, base, width, flags);
2601 ++c;
2602 break;
2603 }
2604 case 'E':
2605 case 'e':
2606 case 'F':
2607 case 'f':
2608 case 'G':
2609 case 'g':
2610 case 'A':
2611 case 'a': {
2612 double d;
2613 if (length_mod == lm_L)
2614 d = va_arg(ap, long double); // not supported - converted to a double
2615 else
2616 d = va_arg(ap, double);
2617
2618 if (qIsUpper(*c))
2619 flags |= QLocalePrivate::CapitalEorX;
2620
2621 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
2622 switch (qToLower(*c)) {
2623 case 'e': form = QLocalePrivate::DFExponent; break;
2624 case 'a': // not supported - decimal form used instead
2625 case 'f': form = QLocalePrivate::DFDecimal; break;
2626 case 'g': form = QLocalePrivate::DFSignificantDigits; break;
2627 default: break;
2628 }
2629 subst = locale.d->doubleToString(d, precision, form, width, flags);
2630 ++c;
2631 break;
2632 }
2633 case 'c': {
2634 if (length_mod == lm_l)
2635 subst = QChar((ushort) va_arg(ap, int));
2636 else
2637 subst = (uchar) va_arg(ap, int);
2638 ++c;
2639 break;
2640 }
2641 case 's': {
2642 if (length_mod == lm_l) {
2643 const ushort *buff = va_arg(ap, const ushort*);
2644 const ushort *ch = buff;
2645 while (*ch != 0)
2646 ++ch;
2647 subst.setUnicodeCodes(buff, ch - buff);
2648 } else
2649 subst = QString::fromUtf8(va_arg(ap, const char*));
2650 if (precision != -1)
2651 subst.truncate(precision);
2652 ++c;
2653 break;
2654 }
2655 case 'p': {
2656 Q_ULLONG i;
2657 #ifdef Q_OS_WIN64
2658 i = (Q_ULLONG) va_arg(ap, void*);
2659 #else
2660 i = (Q_ULONG) va_arg(ap, void*);
2661 #endif
2662
2663 #ifdef Q_OS_WIN32
2664 flags |= QLocalePrivate::CapitalEorX; // Windows does 1234ABCD
2665 #else
2666 flags |= QLocalePrivate::Alternate; // Unix and Mac do 0x1234abcd
2667 #endif
2668
2669 subst = locale.d->unsLongLongToString(i, precision, 16, width, flags);
2670 ++c;
2671 break;
2672 }
2673 case 'n':
2674 switch (length_mod) {
2675 case lm_hh: {
2676 signed char *n = va_arg(ap, signed char*);
2677 *n = result.length();
2678 break;
2679 }
2680 case lm_h: {
2681 short int *n = va_arg(ap, short int*);
2682 *n = result.length();
2683 break;
2684 }
2685 case lm_l: {
2686 long int *n = va_arg(ap, long int*);
2687 *n = result.length();
2688 break;
2689 }
2690 case lm_ll: {
2691 Q_LLONG *n = va_arg(ap, Q_LLONG*);
2692 volatile uint tmp = result.length(); // egcs-2.91.66 gets internal
2693 *n = tmp; // compiler error without volatile
2694 break;
2695 }
2696 default: {
2697 int *n = va_arg(ap, int*);
2698 *n = result.length();
2699 break;
2700 }
2701 }
2702 ++c;
2703 break;
2704
2705 default: // bad escape, treat as non-escape text
2706 for (const char *cc = escape_start; cc != c; ++cc)
2707 result.append(*cc);
2708 continue;
2709 }
2710
2711 if (flags & QLocalePrivate::LeftAdjusted)
2712 result.append(subst.leftJustify(width));
2713 else
2714 result.append(subst.rightJustify(width));
2715 }
2716
2717 va_end(ap);
2718 *this = result;
2719
2720 return *this;
2721 }
2722 #endif
2723
2724 /*!
2725 Fills the string with \a len characters of value \a c, and returns
2726 a reference to the string.
2727
2728 If \a len is negative (the default), the current string length is
2729 used.
2730
2731 \code
2732 QString str;
2733 str.fill( 'g', 5 ); // string == "ggggg"
2734 \endcode
2735 */
2736
fill(QChar c,int len)2737 QString& QString::fill( QChar c, int len )
2738 {
2739 if ( len < 0 )
2740 len = length();
2741 if ( len == 0 ) {
2742 *this = "";
2743 } else {
2744 deref();
2745 QChar * nd = QT_ALLOC_QCHAR_VEC( len );
2746 d = new QStringData(nd,len,len);
2747 while (len--) *nd++ = c;
2748 }
2749 return *this;
2750 }
2751
2752
2753 /*!
2754 \fn QString QString::copy() const
2755
2756 \obsolete
2757
2758 In Qt 2.0 and later, all calls to this function are needless. Just
2759 remove them.
2760 */
2761
2762 /*!
2763 \overload
2764
2765 Finds the first occurrence of the character \a c, starting at
2766 position \a index. If \a index is -1, the search starts at the
2767 last character; if -2, at the next to last character and so on.
2768 (See findRev() for searching backwards.)
2769
2770 If \a cs is TRUE (the default), the search is case sensitive;
2771 otherwise the search is case insensitive.
2772
2773 Returns the position of \a c or -1 if \a c could not be found.
2774 */
2775
find(QChar c,int index,bool cs) const2776 int QString::find( QChar c, int index, bool cs ) const
2777 {
2778 const uint l = length();
2779 if ( index < 0 )
2780 index += l;
2781 if ( (uint)index >= l )
2782 return -1;
2783 register const QChar *uc = unicode()+index;
2784 const QChar *end = unicode() + l;
2785 if ( cs ) {
2786 while ( uc < end && *uc != c )
2787 uc++;
2788 } else {
2789 c = ::lower( c );
2790 while ( uc < end && ::lower( *uc ) != c )
2791 uc++;
2792 }
2793 if ( uint(uc - unicode()) >= l )
2794 return -1;
2795 return (int)(uc - unicode());
2796 }
2797
2798 /* an implementation of the Boyer-Moore search algorithm
2799 */
2800
2801 /* initializes the skiptable to know haw far ahead we can skip on a wrong match
2802 */
bm_init_skiptable(const QString & pattern,uint * skiptable,bool cs)2803 static void bm_init_skiptable( const QString &pattern, uint *skiptable, bool cs )
2804 {
2805 int i = 0;
2806 register uint *st = skiptable;
2807 int l = pattern.length();
2808 while ( i++ < 0x100/8 ) {
2809 *(st++) = l;
2810 *(st++) = l;
2811 *(st++) = l;
2812 *(st++) = l;
2813 *(st++) = l;
2814 *(st++) = l;
2815 *(st++) = l;
2816 *(st++) = l;
2817 }
2818 const QChar *uc = pattern.unicode();
2819 if ( cs ) {
2820 while ( l-- ) {
2821 skiptable[ uc->cell() ] = l;
2822 uc++;
2823 }
2824 } else {
2825 while ( l-- ) {
2826 skiptable[ ::lower( *uc ).cell() ] = l;
2827 uc++;
2828 }
2829 }
2830 }
2831
bm_find(const QString & str,int index,const QString & pattern,uint * skiptable,bool cs)2832 static int bm_find( const QString &str, int index, const QString &pattern, uint *skiptable, bool cs )
2833 {
2834 const uint l = str.length();
2835 if ( pattern.isEmpty() )
2836 return index > (int)l ? -1 : index;
2837
2838 const QChar *uc = str.unicode();
2839 const QChar *puc = pattern.unicode();
2840 const uint pl = pattern.length();
2841 const uint pl_minus_one = pl - 1;
2842
2843 register const QChar *current = uc + index + pl_minus_one;
2844 const QChar *end = uc + l;
2845 if ( cs ) {
2846 while ( current < end ) {
2847 uint skip = skiptable[ current->cell() ];
2848 if ( !skip ) {
2849 // possible match
2850 while ( skip < pl ) {
2851 if ( *(current - skip ) != puc[pl_minus_one-skip] )
2852 break;
2853 skip++;
2854 }
2855 if ( skip > pl_minus_one ) { // we have a match
2856 return (current - uc) - skip + 1;
2857 }
2858 // in case we don't have a match we are a bit inefficient as we only skip by one
2859 // when we have the non matching char in the string.
2860 if ( skiptable[ (current-skip)->cell() ] == pl )
2861 skip = pl - skip;
2862 else
2863 skip = 1;
2864 }
2865 current += skip;
2866 }
2867 } else {
2868 while ( current < end ) {
2869 uint skip = skiptable[ ::lower( *current ).cell() ];
2870 if ( !skip ) {
2871 // possible match
2872 while ( skip < pl ) {
2873 if ( ::lower( *(current - skip) ) != ::lower( puc[pl_minus_one-skip] ) )
2874 break;
2875 skip++;
2876 }
2877 if ( skip > pl_minus_one ) // we have a match
2878 return (current - uc) - skip + 1;
2879 // in case we don't have a match we are a bit inefficient as we only skip by one
2880 // when we have the non matching char in the string.
2881 if ( skiptable[ ::lower(*(current - skip)).cell() ] == pl )
2882 skip = pl - skip;
2883 else
2884 skip = 1;
2885 }
2886 current += skip;
2887 }
2888 }
2889 // not found
2890 return -1;
2891 }
2892
2893
2894 #define REHASH( a ) \
2895 if ( sl_minus_1 < sizeof(uint) * CHAR_BIT ) \
2896 hashHaystack -= (a) << sl_minus_1; \
2897 hashHaystack <<= 1
2898
2899 /*!
2900 \overload
2901
2902 Finds the first occurrence of the string \a str, starting at
2903 position \a index. If \a index is -1, the search starts at the
2904 last character, if it is -2, at the next to last character and so
2905 on. (See findRev() for searching backwards.)
2906
2907 If \a cs is TRUE (the default), the search is case sensitive;
2908 otherwise the search is case insensitive.
2909
2910 Returns the position of \a str or -1 if \a str could not be found.
2911 */
2912
find(const QString & str,int index,bool cs) const2913 int QString::find( const QString& str, int index, bool cs ) const
2914 {
2915 const uint l = length();
2916 const uint sl = str.length();
2917 if ( index < 0 )
2918 index += l;
2919 if ( sl + index > l )
2920 return -1;
2921 if ( !sl )
2922 return index;
2923 if (!l)
2924 return -1;
2925
2926 #if defined(Q_OS_MACX) && defined(QT_MACOSX_VERSION) && QT_MACOSX_VERSION >= 0x1020
2927 if ( sl == 1 )
2928 return find( *str.unicode(), index, cs );
2929 #endif
2930
2931 // we use the Boyer-Moore algorithm in cases where the overhead
2932 // for the hash table should pay off, otherwise we use a simple
2933 // hash function
2934 if ( l > 500 && sl > 5 ) {
2935 uint skiptable[0x100];
2936 bm_init_skiptable( str, skiptable, cs );
2937 return bm_find( *this, index, str, skiptable, cs );
2938 }
2939
2940 /*
2941 We use some hashing for efficiency's sake. Instead of
2942 comparing strings, we compare the hash value of str with that of
2943 a part of this QString. Only if that matches, we call ucstrncmp
2944 or ucstrnicmp.
2945 */
2946 const QChar* needle = str.unicode();
2947 const QChar* haystack = unicode() + index;
2948 const QChar* end = unicode() + (l-sl);
2949 const uint sl_minus_1 = sl-1;
2950 uint hashNeedle = 0, hashHaystack = 0, i;
2951
2952 if ( cs ) {
2953 for ( i = 0; i < sl; ++i ) {
2954 hashNeedle = ((hashNeedle<<1) + needle[i].unicode() );
2955 hashHaystack = ((hashHaystack<<1) + haystack[i].unicode() );
2956 }
2957 hashHaystack -= (haystack+sl_minus_1)->unicode();
2958
2959 while ( haystack <= end ) {
2960 hashHaystack += (haystack+sl_minus_1)->unicode();
2961 if ( hashHaystack == hashNeedle
2962 && ucstrncmp( needle, haystack, sl ) == 0 )
2963 return haystack-unicode();
2964
2965 REHASH( haystack->unicode() );
2966 ++haystack;
2967 }
2968 } else {
2969 for ( i = 0; i < sl; ++i ) {
2970 hashNeedle = ((hashNeedle<<1) +
2971 ::lower( needle[i].unicode() ).unicode() );
2972 hashHaystack = ((hashHaystack<<1) +
2973 ::lower( haystack[i].unicode() ).unicode() );
2974 }
2975
2976 hashHaystack -= ::lower(*(haystack+sl_minus_1)).unicode();
2977 while ( haystack <= end ) {
2978 hashHaystack += ::lower(*(haystack+sl_minus_1)).unicode();
2979 if ( hashHaystack == hashNeedle
2980 && ucstrnicmp( needle, haystack, sl ) == 0 )
2981 return haystack-unicode();
2982
2983 REHASH( ::lower(*haystack).unicode() );
2984 ++haystack;
2985 }
2986 }
2987 return -1;
2988 }
2989
2990 /*!
2991 \fn int QString::findRev( const char* str, int index ) const
2992
2993 Equivalent to findRev(QString(\a str), \a index).
2994 */
2995
2996 /*!
2997 \fn int QString::find( const char* str, int index ) const
2998
2999 \overload
3000
3001 Equivalent to find(QString(\a str), \a index).
3002 */
3003
3004 /*!
3005 \overload
3006
3007 Finds the first occurrence of the character \a c, starting at
3008 position \a index and searching backwards. If the index is -1, the
3009 search starts at the last character, if it is -2, at the next to
3010 last character and so on.
3011
3012 Returns the position of \a c or -1 if \a c could not be found.
3013
3014 If \a cs is TRUE (the default), the search is case sensitive;
3015 otherwise the search is case insensitive.
3016
3017 \code
3018 QString string( "bananas" );
3019 int i = string.findRev( 'a' ); // i == 5
3020 \endcode
3021 */
3022
findRev(QChar c,int index,bool cs) const3023 int QString::findRev( QChar c, int index, bool cs ) const
3024 {
3025 #if defined(Q_OS_MACX) && defined(QT_MACOSX_VERSION) && QT_MACOSX_VERSION < 0x1020
3026 return findRev( QString( c ), index, cs );
3027 #else
3028 const uint l = length();
3029 if ( index < 0 )
3030 index += l;
3031 if ( (uint)index >= l )
3032 return -1;
3033 const QChar *end = unicode();
3034 register const QChar *uc = end + index;
3035 if ( cs ) {
3036 while ( uc >= end && *uc != c )
3037 uc--;
3038 } else {
3039 c = ::lower( c );
3040 while ( uc >= end && ::lower( *uc ) != c )
3041 uc--;
3042 }
3043 return uc - end;
3044 #endif
3045 }
3046
3047 /*!
3048 \overload
3049
3050 Finds the first occurrence of the string \a str, starting at
3051 position \a index and searching backwards. If the index is -1, the
3052 search starts at the last character, if it is -2, at the next to
3053 last character and so on.
3054
3055 Returns the position of \a str or -1 if \a str could not be found.
3056
3057 If \a cs is TRUE (the default), the search is case sensitive;
3058 otherwise the search is case insensitive.
3059
3060 \code
3061 QString string("bananas");
3062 int i = string.findRev( "ana" ); // i == 3
3063 \endcode
3064 */
3065
findRev(const QString & str,int index,bool cs) const3066 int QString::findRev( const QString& str, int index, bool cs ) const
3067 {
3068 /*
3069 See QString::find() for explanations.
3070 */
3071 const uint l = length();
3072 if ( index < 0 )
3073 index += l;
3074 const uint sl = str.length();
3075 int delta = l-sl;
3076 if ( index < 0 || index > (int)l || delta < 0 )
3077 return -1;
3078 if ( index > delta )
3079 index = delta;
3080
3081 #if defined(Q_OS_MACX) && defined(QT_MACOSX_VERSION) && QT_MACOSX_VERSION >= 0x1020
3082 if ( sl == 1 )
3083 return findRev( *str.unicode(), index, cs );
3084 #endif
3085
3086 const QChar* needle = str.unicode();
3087 const QChar* haystack = unicode() + index;
3088 const QChar* end = unicode();
3089 const uint sl_minus_1 = sl-1;
3090 const QChar* n = needle+sl_minus_1;
3091 const QChar* h = haystack+sl_minus_1;
3092 uint hashNeedle = 0, hashHaystack = 0, i;
3093
3094 if ( cs ) {
3095 for ( i = 0; i < sl; ++i ) {
3096 hashNeedle = ((hashNeedle<<1) + (n-i)->unicode() );
3097 hashHaystack = ((hashHaystack<<1) + (h-i)->unicode() );
3098 }
3099 hashHaystack -= haystack->unicode();
3100
3101 while ( haystack >= end ) {
3102 hashHaystack += haystack->unicode();
3103 if ( hashHaystack == hashNeedle
3104 && ucstrncmp( needle, haystack, sl ) == 0 )
3105 return haystack-unicode();
3106 --haystack;
3107 REHASH( (haystack+sl)->unicode() );
3108 }
3109 } else {
3110 for ( i = 0; i < sl; ++i ) {
3111 hashNeedle = ((hashNeedle<<1)
3112 + ::lower( (n-i)->unicode() ).unicode() );
3113 hashHaystack = ((hashHaystack<<1)
3114 + ::lower( (h-i)->unicode() ).unicode() );
3115 }
3116 hashHaystack -= ::lower(*haystack).unicode();
3117
3118 while ( haystack >= end ) {
3119 hashHaystack += ::lower(*haystack).unicode();
3120 if ( hashHaystack == hashNeedle
3121 && ucstrnicmp( needle, haystack, sl ) == 0 )
3122 return haystack-unicode();
3123 --haystack;
3124 REHASH( ::lower(*(haystack+sl)).unicode() );
3125 }
3126 }
3127 return -1;
3128 }
3129
3130 #undef REHASH
3131
3132 /*!
3133 \enum QString::SectionFlags
3134
3135 \value SectionDefault Empty fields are counted, leading and
3136 trailing separators are not included, and the separator is
3137 compared case sensitively.
3138
3139 \value SectionSkipEmpty Treat empty fields as if they don't exist,
3140 i.e. they are not considered as far as \e start and \e end are
3141 concerned.
3142
3143 \value SectionIncludeLeadingSep Include the leading separator (if
3144 any) in the result string.
3145
3146 \value SectionIncludeTrailingSep Include the trailing separator
3147 (if any) in the result string.
3148
3149 \value SectionCaseInsensitiveSeps Compare the separator
3150 case-insensitively.
3151
3152 Any of the last four values can be OR-ed together to form a flag.
3153
3154 \sa section()
3155 */
3156
3157 /*!
3158 \fn QString QString::section( QChar sep, int start, int end = 0xffffffff, int flags = SectionDefault ) const
3159
3160 This function returns a section of the string.
3161
3162 This string is treated as a sequence of fields separated by the
3163 character, \a sep. The returned string consists of the fields from
3164 position \a start to position \a end inclusive. If \a end is not
3165 specified, all fields from position \a start to the end of the
3166 string are included. Fields are numbered 0, 1, 2, etc., counting
3167 from the left, and -1, -2, etc., counting from right to left.
3168
3169 The \a flags argument can be used to affect some aspects of the
3170 function's behaviour, e.g. whether to be case sensitive, whether
3171 to skip empty fields and how to deal with leading and trailing
3172 separators; see \l{SectionFlags}.
3173
3174 \code
3175 QString csv( "forename,middlename,surname,phone" );
3176 QString s = csv.section( ',', 2, 2 ); // s == "surname"
3177
3178 QString path( "/usr/local/bin/myapp" ); // First field is empty
3179 QString s = path.section( '/', 3, 4 ); // s == "bin/myapp"
3180 QString s = path.section( '/', 3, 3, SectionSkipEmpty ); // s == "myapp"
3181 \endcode
3182
3183 If \a start or \a end is negative, we count fields from the right
3184 of the string, the right-most field being -1, the one from
3185 right-most field being -2, and so on.
3186
3187 \code
3188 QString csv( "forename,middlename,surname,phone" );
3189 QString s = csv.section( ',', -3, -2 ); // s == "middlename,surname"
3190
3191 QString path( "/usr/local/bin/myapp" ); // First field is empty
3192 QString s = path.section( '/', -1 ); // s == "myapp"
3193 \endcode
3194
3195 \sa QStringList::split()
3196 */
3197
3198 /*!
3199 \overload
3200
3201 This function returns a section of the string.
3202
3203 This string is treated as a sequence of fields separated by the
3204 string, \a sep. The returned string consists of the fields from
3205 position \a start to position \a end inclusive. If \a end is not
3206 specified, all fields from position \a start to the end of the
3207 string are included. Fields are numbered 0, 1, 2, etc., counting
3208 from the left, and -1, -2, etc., counting from right to left.
3209
3210 The \a flags argument can be used to affect some aspects of the
3211 function's behaviour, e.g. whether to be case sensitive, whether
3212 to skip empty fields and how to deal with leading and trailing
3213 separators; see \l{SectionFlags}.
3214
3215 \code
3216 QString data( "forename**middlename**surname**phone" );
3217 QString s = data.section( "**", 2, 2 ); // s == "surname"
3218 \endcode
3219
3220 If \a start or \a end is negative, we count fields from the right
3221 of the string, the right-most field being -1, the one from
3222 right-most field being -2, and so on.
3223
3224 \code
3225 QString data( "forename**middlename**surname**phone" );
3226 QString s = data.section( "**", -3, -2 ); // s == "middlename**surname"
3227 \endcode
3228
3229 \sa QStringList::split()
3230 */
3231
section(const QString & sep,int start,int end,int flags) const3232 QString QString::section( const QString &sep, int start, int end, int flags ) const
3233 {
3234 QStringList sections = QStringList::split(sep, *this, TRUE);
3235 if(sections.isEmpty())
3236 return QString();
3237 if(!(flags & SectionSkipEmpty)) {
3238 if(start < 0)
3239 start += int(sections.count());
3240 if(end < 0)
3241 end += int(sections.count());
3242 } else {
3243 int skip = 0;
3244 for(QStringList::Iterator it = sections.begin(); it != sections.end(); ++it) {
3245 if((*it).isEmpty())
3246 skip++;
3247 }
3248 if(start < 0)
3249 start += int(sections.count()) - skip;
3250 if(end < 0)
3251 end += int(sections.count()) - skip;
3252 }
3253 int x = 0, run = 0;
3254 QString ret;
3255 for(QStringList::Iterator it = sections.begin(); x <= end && it != sections.end(); ++it) {
3256 if(x >= start) {
3257 if((*it).isEmpty()) {
3258 run++;
3259 } else {
3260 if(!ret.isEmpty() || !(flags & SectionSkipEmpty)) {
3261 int i_end = run;
3262 if(!ret.isEmpty() && !(flags & SectionIncludeTrailingSep))
3263 i_end++;
3264 if((flags & SectionIncludeLeadingSep) && it != sections.begin() && x == start)
3265 i_end++;
3266 for(int i = 0; i < i_end; i++)
3267 ret += sep;
3268 } else if((flags & SectionIncludeLeadingSep) && it != sections.begin()) {
3269 ret += sep;
3270 }
3271 run = 0;
3272 ret += (*it);
3273 if((flags & SectionIncludeTrailingSep) && it != sections.end())
3274 ret += sep;
3275 }
3276 }
3277 if(!(*it).isEmpty() || !(flags & SectionSkipEmpty))
3278 x++;
3279 }
3280 return ret;
3281 }
3282
3283 #ifndef QT_NO_REGEXP
3284 class section_chunk {
3285 public:
section_chunk(int l,QString s)3286 section_chunk(int l, QString s) { length = l; string = s; }
3287 int length;
3288 QString string;
3289 };
3290 /*!
3291 \overload
3292
3293 This function returns a section of the string.
3294
3295 This string is treated as a sequence of fields separated by the
3296 regular expression, \a reg. The returned string consists of the
3297 fields from position \a start to position \a end inclusive. If \a
3298 end is not specified, all fields from position \a start to the end
3299 of the string are included. Fields are numbered 0, 1, 2, etc., counting
3300 from the left, and -1, -2, etc., counting from right to left.
3301
3302 The \a flags argument can be used to affect some aspects of the
3303 function's behaviour, e.g. whether to be case sensitive, whether
3304 to skip empty fields and how to deal with leading and trailing
3305 separators; see \l{SectionFlags}.
3306
3307 \code
3308 QString line( "forename\tmiddlename surname \t \t phone" );
3309 QRegExp sep( "\s+" );
3310 QString s = line.section( sep, 2, 2 ); // s == "surname"
3311 \endcode
3312
3313 If \a start or \a end is negative, we count fields from the right
3314 of the string, the right-most field being -1, the one from
3315 right-most field being -2, and so on.
3316
3317 \code
3318 QString line( "forename\tmiddlename surname \t \t phone" );
3319 QRegExp sep( "\\s+" );
3320 QString s = line.section( sep, -3, -2 ); // s == "middlename surname"
3321 \endcode
3322
3323 \warning Using this QRegExp version is much more expensive than
3324 the overloaded string and character versions.
3325
3326 \sa QStringList::split() simplifyWhiteSpace()
3327 */
3328
section(const QRegExp & reg,int start,int end,int flags) const3329 QString QString::section( const QRegExp ®, int start, int end, int flags ) const
3330 {
3331 const QChar *uc = unicode();
3332 if(!uc)
3333 return QString();
3334
3335 QRegExp sep(reg);
3336 sep.setCaseSensitive(!(flags & SectionCaseInsensitiveSeps));
3337
3338 QPtrList<section_chunk> l;
3339 l.setAutoDelete(TRUE);
3340 int n = length(), m = 0, last_m = 0, last = 0, last_len = 0;
3341
3342 while ( ( m = sep.search( *this, m ) ) != -1 ) {
3343 l.append(new section_chunk(last_len, QString(uc + last_m, m - last_m)));
3344 last_m = m;
3345 last_len = sep.matchedLength();
3346 if((m += QMAX(sep.matchedLength(), 1)) >= n) {
3347 last = 1;
3348 break;
3349 }
3350 }
3351 if(!last)
3352 l.append(new section_chunk(last_len, QString(uc + last_m, n - last_m)));
3353
3354 if(start < 0)
3355 start = l.count() + start;
3356 if(end == -1)
3357 end = l.count();
3358 else if(end < 0)
3359 end = l.count() + end;
3360
3361 int i = 0;
3362 QString ret;
3363 for ( section_chunk *chk=l.first(); chk; chk=l.next(), i++ ) {
3364 if((flags & SectionSkipEmpty) && chk->length == (int)chk->string.length()) {
3365 if(i <= start)
3366 start++;
3367 end++;
3368 }
3369 if(i == start) {
3370 ret = (flags & SectionIncludeLeadingSep) ? chk->string : chk->string.mid(chk->length);
3371 } else if(i > start) {
3372 ret += chk->string;
3373 }
3374 if(i == end) {
3375 if((chk=l.next()) && flags & SectionIncludeTrailingSep)
3376 ret += chk->string.left(chk->length);
3377 break;
3378 }
3379 }
3380 return ret;
3381 }
3382 #endif
3383
3384 /*!
3385 \fn QString QString::section( char sep, int start, int end = 0xffffffff, int flags = SectionDefault ) const
3386
3387 \overload
3388 */
3389
3390 /*!
3391 \fn QString QString::section( const char *sep, int start, int end = 0xffffffff, int flags = SectionDefault ) const
3392
3393 \overload
3394 */
3395
3396
3397 /*!
3398 Returns the number of times the character \a c occurs in the
3399 string.
3400
3401 If \a cs is TRUE (the default), the search is case sensitive;
3402 otherwise the search is case insensitive.
3403
3404 \code
3405 QString string( "Trolltech and Qt" );
3406 int n = string.contains( 't', FALSE );
3407 // n == 3
3408 \endcode
3409 */
3410
contains(QChar c,bool cs) const3411 int QString::contains( QChar c, bool cs ) const
3412 {
3413 int count = 0;
3414 const QChar *uc = unicode();
3415 if ( !uc )
3416 return 0;
3417 int n = length();
3418 if ( cs ) {
3419 while ( n-- ) {
3420 if ( *uc == c )
3421 count++;
3422 uc++;
3423 }
3424 } else {
3425 c = ::lower( c );
3426 while ( n-- ) {
3427 if ( ::lower( *uc ) == c )
3428 count++;
3429 uc++;
3430 }
3431 }
3432 return count;
3433 }
3434
3435 /*!
3436 \overload
3437
3438 Returns the number of times the string \a str occurs in the string.
3439
3440 If \a cs is TRUE (the default), the search is case sensitive;
3441 otherwise the search is case insensitive.
3442 */
contains(const char * str,bool cs) const3443 int QString::contains( const char* str, bool cs ) const
3444 {
3445 return contains( QString(str), cs );
3446 }
3447
3448 /*!
3449 \fn int QString::contains( char c, bool cs ) const
3450
3451 \overload
3452 */
3453
3454 /*!
3455 \fn int QString::find( char c, int index, bool cs ) const
3456
3457 \overload
3458
3459 Find character \a c starting from position \a index.
3460
3461 If \a cs is TRUE (the default), the search is case sensitive;
3462 otherwise the search is case insensitive.
3463 */
3464
3465 /*!
3466 \fn int QString::findRev( char c, int index, bool cs ) const
3467
3468 \overload
3469
3470 Find character \a c starting from position \a index and working
3471 backwards.
3472
3473 If \a cs is TRUE (the default), the search is case sensitive;
3474 otherwise the search is case insensitive.
3475 */
3476
3477 /*!
3478 \overload
3479
3480 Returns the number of times \a str occurs in the string.
3481
3482 If \a cs is TRUE (the default), the search is case sensitive;
3483 otherwise the search is case insensitive.
3484
3485 This function counts overlapping strings, so in the example below,
3486 there are two instances of "ana" in "bananas".
3487
3488 \code
3489 QString str( "bananas" );
3490 int i = str.contains( "ana" ); // i == 2
3491 \endcode
3492
3493 \sa findRev()
3494 */
3495
contains(const QString & str,bool cs) const3496 int QString::contains( const QString &str, bool cs ) const
3497 {
3498 if ( isNull() )
3499 return 0;
3500 int count = 0;
3501 uint skiptable[0x100];
3502 bm_init_skiptable( str, skiptable, cs );
3503 int i = -1;
3504 // use boyer-moore for the ultimate speed experience
3505 while ( ( i = bm_find( *this, i + 1, str, skiptable, cs ) ) != -1 )
3506 count++;
3507 return count;
3508 }
3509
3510 /*!
3511 Returns a substring that contains the \a len leftmost characters
3512 of the string.
3513
3514 The whole string is returned if \a len exceeds the length of the
3515 string.
3516
3517 \code
3518 QString s = "Pineapple";
3519 QString t = s.left( 4 ); // t == "Pine"
3520 \endcode
3521
3522 \sa right(), mid(), isEmpty()
3523 */
3524
left(uint len) const3525 QString QString::left( uint len ) const
3526 {
3527 if ( isEmpty() ) {
3528 return QString();
3529 } else if ( len == 0 ) { // ## just for 1.x compat:
3530 return fromLatin1( "" );
3531 } else if ( len >= length() ) {
3532 return *this;
3533 } else {
3534 QString s( len, TRUE );
3535 memcpy( s.d->unicode, d->unicode, len * sizeof(QChar) );
3536 s.d->len = len;
3537 return s;
3538 }
3539 }
3540
3541 /*!
3542 Returns a string that contains the \a len rightmost characters of
3543 the string.
3544
3545 If \a len is greater than the length of the string then the whole
3546 string is returned.
3547
3548 \code
3549 QString string( "Pineapple" );
3550 QString t = string.right( 5 ); // t == "apple"
3551 \endcode
3552
3553 \sa left(), mid(), isEmpty()
3554 */
3555
right(uint len) const3556 QString QString::right( uint len ) const
3557 {
3558 if ( isEmpty() ) {
3559 return QString();
3560 } else if ( len == 0 ) { // ## just for 1.x compat:
3561 return fromLatin1( "" );
3562 } else {
3563 uint l = length();
3564 if ( len >= l )
3565 return *this;
3566 QString s( len, TRUE );
3567 memcpy( s.d->unicode, d->unicode+(l-len), len*sizeof(QChar) );
3568 s.d->len = len;
3569 return s;
3570 }
3571 }
3572
3573 /*!
3574 Returns a string that contains the \a len characters of this
3575 string, starting at position \a index.
3576
3577 Returns a null string if the string is empty or \a index is out of
3578 range. Returns the whole string from \a index if \a index + \a len
3579 exceeds the length of the string.
3580
3581 \code
3582 QString s( "Five pineapples" );
3583 QString t = s.mid( 5, 4 ); // t == "pine"
3584 \endcode
3585
3586 \sa left(), right()
3587 */
3588
mid(uint index,uint len) const3589 QString QString::mid( uint index, uint len ) const
3590 {
3591 uint slen = length();
3592 if ( isEmpty() || index >= slen ) {
3593 return QString();
3594 } else if ( len == 0 ) { // ## just for 1.x compat:
3595 return fromLatin1( "" );
3596 } else {
3597 if ( len > slen-index )
3598 len = slen - index;
3599 if ( index == 0 && len == slen )
3600 return *this;
3601 register const QChar *p = unicode()+index;
3602 QString s( len, TRUE );
3603 memcpy( s.d->unicode, p, len * sizeof(QChar) );
3604 s.d->len = len;
3605 return s;
3606 }
3607 }
3608
3609 /*!
3610 Returns a string of length \a width that contains this string
3611 padded by the \a fill character.
3612
3613 If \a truncate is FALSE and the length of the string is more than
3614 \a width, then the returned string is a copy of the string.
3615
3616 If \a truncate is TRUE and the length of the string is more than
3617 \a width, then any characters in a copy of the string after length
3618 \a width are removed, and the copy is returned.
3619
3620 \code
3621 QString s( "apple" );
3622 QString t = s.leftJustify( 8, '.' ); // t == "apple..."
3623 \endcode
3624
3625 \sa rightJustify()
3626 */
3627
leftJustify(uint width,QChar fill,bool truncate) const3628 QString QString::leftJustify( uint width, QChar fill, bool truncate ) const
3629 {
3630 QString result;
3631 int len = length();
3632 int padlen = width - len;
3633 if ( padlen > 0 ) {
3634 result.setLength(len+padlen);
3635 if ( len )
3636 memcpy( result.d->unicode, unicode(), sizeof(QChar)*len );
3637 QChar* uc = result.d->unicode + len;
3638 while (padlen--)
3639 *uc++ = fill;
3640 } else {
3641 if ( truncate )
3642 result = left( width );
3643 else
3644 result = *this;
3645 }
3646 return result;
3647 }
3648
3649 /*!
3650 Returns a string of length \a width that contains the \a fill
3651 character followed by the string.
3652
3653 If \a truncate is FALSE and the length of the string is more than
3654 \a width, then the returned string is a copy of the string.
3655
3656 If \a truncate is TRUE and the length of the string is more than
3657 \a width, then the resulting string is truncated at position \a
3658 width.
3659
3660 \code
3661 QString string( "apple" );
3662 QString t = string.rightJustify( 8, '.' ); // t == "...apple"
3663 \endcode
3664
3665 \sa leftJustify()
3666 */
3667
rightJustify(uint width,QChar fill,bool truncate) const3668 QString QString::rightJustify( uint width, QChar fill, bool truncate ) const
3669 {
3670 QString result;
3671 int len = length();
3672 int padlen = width - len;
3673 if ( padlen > 0 ) {
3674 result.setLength( len+padlen );
3675 QChar* uc = result.d->unicode;
3676 while (padlen--)
3677 *uc++ = fill;
3678 if ( len )
3679 memcpy( uc, unicode(), sizeof(QChar)*len );
3680 } else {
3681 if ( truncate )
3682 result = left( width );
3683 else
3684 result = *this;
3685 }
3686 return result;
3687 }
3688
3689 /*!
3690 Returns a lowercase copy of the string.
3691
3692 \code
3693 QString string( "TROlltECH" );
3694 str = string.lower(); // str == "trolltech"
3695 \endcode
3696
3697 \sa upper()
3698 */
3699
lower() const3700 QString QString::lower() const
3701 {
3702 int l = length();
3703 register QChar *p = d->unicode;
3704 while ( l ) {
3705 if ( *p != ::lower(*p) ) {
3706 QString s( *this );
3707 s.real_detach();
3708 p = s.d->unicode + ( p - d->unicode );
3709 while ( l ) {
3710 *p = ::lower( *p );
3711 l--;
3712 p++;
3713 }
3714 return s;
3715 }
3716 l--;
3717 p++;
3718 }
3719 return *this;
3720 }
3721
3722 /*!
3723 Returns an uppercase copy of the string.
3724
3725 \code
3726 QString string( "TeXt" );
3727 str = string.upper(); // t == "TEXT"
3728 \endcode
3729
3730 \sa lower()
3731 */
3732
upper() const3733 QString QString::upper() const
3734 {
3735 int l = length();
3736 register QChar *p = d->unicode;
3737 while ( l ) {
3738 if ( *p != ::upper(*p) ) {
3739 QString s( *this );
3740 s.real_detach();
3741 p = s.d->unicode + ( p - d->unicode );
3742 while ( l ) {
3743 *p = ::upper( *p );
3744 l--;
3745 p++;
3746 }
3747 return s;
3748 }
3749 l--;
3750 p++;
3751 }
3752 return *this;
3753 }
3754
3755
3756 /*!
3757 Returns a string that has whitespace removed from the start and
3758 the end.
3759
3760 Whitespace means any character for which QChar::isSpace() returns
3761 TRUE. This includes Unicode characters with decimal values 9
3762 (TAB), 10 (LF), 11 (VT), 12 (FF), 13 (CR) and 32 (Space), and may
3763 also include other Unicode characters.
3764
3765 \code
3766 QString string = " white space ";
3767 QString s = string.stripWhiteSpace(); // s == "white space"
3768 \endcode
3769
3770 \sa simplifyWhiteSpace()
3771 */
3772
stripWhiteSpace() const3773 QString QString::stripWhiteSpace() const
3774 {
3775 if ( isEmpty() ) // nothing to do
3776 return *this;
3777 register const QChar *s = unicode();
3778 if ( !s->isSpace() && !s[length()-1].isSpace() )
3779 return *this;
3780
3781 int start = 0;
3782 int end = length() - 1;
3783 while ( start<=end && s[start].isSpace() ) // skip white space from start
3784 start++;
3785 if ( start <= end ) { // only white space
3786 while ( end && s[end].isSpace() ) // skip white space from end
3787 end--;
3788 }
3789 int l = end - start + 1;
3790 if ( l <= 0 )
3791 return QString::fromLatin1("");
3792
3793 QString result( l, TRUE );
3794 memcpy( result.d->unicode, &s[start], sizeof(QChar)*l );
3795 result.d->len = l;
3796 return result;
3797 }
3798
3799
3800 /*!
3801 Returns a string that has whitespace removed from the start and
3802 the end, and which has each sequence of internal whitespace
3803 replaced with a single space.
3804
3805 Whitespace means any character for which QChar::isSpace() returns
3806 TRUE. This includes Unicode characters with decimal values 9
3807 (TAB), 10 (LF), 11 (VT), 12 (FF), 13 (CR), and 32 (Space).
3808
3809 \code
3810 QString string = " lots\t of\nwhite space ";
3811 QString t = string.simplifyWhiteSpace();
3812 // t == "lots of white space"
3813 \endcode
3814
3815 \sa stripWhiteSpace()
3816 */
3817
simplifyWhiteSpace() const3818 QString QString::simplifyWhiteSpace() const
3819 {
3820 if ( isEmpty() )
3821 return *this;
3822 QString result;
3823 result.setLength( length() );
3824 const QChar *from = unicode();
3825 const QChar *fromend = from+length();
3826 int outc=0;
3827 QChar *to = result.d->unicode;
3828 for (;;) {
3829 while ( from!=fromend && from->isSpace() )
3830 from++;
3831 while ( from!=fromend && !from->isSpace() )
3832 to[outc++] = *from++;
3833 if ( from!=fromend )
3834 to[outc++] = ' ';
3835 else
3836 break;
3837 }
3838 if ( outc > 0 && to[outc-1] == ' ' )
3839 outc--;
3840 result.truncate( outc );
3841 return result;
3842 }
3843
3844
3845 /*!
3846 Inserts \a s into the string at position \a index.
3847
3848 If \a index is beyond the end of the string, the string is
3849 extended with spaces to length \a index and \a s is then appended
3850 and returns a reference to the string.
3851
3852 \code
3853 QString string( "I like fish" );
3854 str = string.insert( 2, "don't " );
3855 // str == "I don't like fish"
3856 \endcode
3857
3858 \sa remove(), replace()
3859 */
3860
insert(uint index,const QString & s)3861 QString &QString::insert( uint index, const QString &s )
3862 {
3863 // the sub function takes care of &s == this case.
3864 return insert( index, s.unicode(), s.length() );
3865 }
3866
3867 /*! \fn QString &QString::insert( uint index, const QByteArray &s )
3868 \overload
3869
3870 Inserts \a s into the string at position \a index and returns
3871 a reference to the string.
3872 */
3873
3874 /*! \fn QString &QString::insert( uint index, const char *s )
3875 \overload
3876
3877 Inserts \a s into the string at position \a index and returns
3878 a reference to the string.
3879 */
3880
3881 #ifndef QT_NO_CAST_ASCII
insertHelper(uint index,const char * s,uint len)3882 QString &QString::insertHelper( uint index, const char *s, uint len )
3883 {
3884 if ( s ) {
3885 #ifndef QT_NO_TEXTCODEC
3886 if ( QTextCodec::codecForCStrings() )
3887 return insert( index, fromAscii( s, len ) );
3888 #endif
3889 if ( len == UINT_MAX )
3890 len = int(strlen( s ));
3891 if ( len == 0 )
3892 return *this;
3893
3894 uint olen = length();
3895 int nlen = olen + len;
3896
3897 if ( index >= olen ) { // insert after end of string
3898 grow( len + index );
3899 int n = index - olen;
3900 QChar* uc = d->unicode + olen;
3901 while ( n-- )
3902 *uc++ = ' ';
3903
3904 uc = d->unicode + index;
3905 while ( len-- )
3906 *uc++ = *s++;
3907 } else { // normal insert
3908 grow( nlen );
3909 memmove( d->unicode + index + len, unicode() + index,
3910 sizeof(QChar) * (olen - index) );
3911
3912 QChar* uc = d->unicode + index;
3913 while ( len-- )
3914 *uc++ = *s++;
3915 }
3916 }
3917 return *this;
3918 }
3919 #endif
3920
3921 /*!
3922 \overload
3923
3924 Inserts the first \a len characters in \a s into the string at
3925 position \a index and returns a reference to the string.
3926 */
3927
insert(uint index,const QChar * s,uint len)3928 QString &QString::insert( uint index, const QChar* s, uint len )
3929 {
3930 if ( len == 0 )
3931 return *this;
3932 uint olen = length();
3933 int nlen = olen + len;
3934
3935 if ( s >= d->unicode && (uint)(s - d->unicode) < d->maxl ) {
3936 // Part of me - take a copy.
3937 QChar *tmp = QT_ALLOC_QCHAR_VEC( len );
3938 memcpy(tmp,s,len*sizeof(QChar));
3939 insert(index,tmp,len);
3940 QT_DELETE_QCHAR_VEC( tmp );
3941 return *this;
3942 }
3943
3944 if ( index >= olen ) { // insert after end of string
3945 grow( len + index );
3946 int n = index - olen;
3947 QChar* uc = d->unicode+olen;
3948 while (n--)
3949 *uc++ = ' ';
3950 memcpy( d->unicode+index, s, sizeof(QChar)*len );
3951 } else { // normal insert
3952 grow( nlen );
3953 memmove( d->unicode + index + len, unicode() + index,
3954 sizeof(QChar) * (olen - index) );
3955 memcpy( d->unicode + index, s, sizeof(QChar) * len );
3956 }
3957 return *this;
3958 }
3959
3960 /*!
3961 \overload
3962
3963 Insert \a c into the string at position \a index and returns a
3964 reference to the string.
3965
3966 If \a index is beyond the end of the string, the string is
3967 extended with spaces (ASCII 32) to length \a index and \a c is
3968 then appended.
3969 */
3970
insert(uint index,QChar c)3971 QString &QString::insert( uint index, QChar c ) // insert char
3972 {
3973 QString s( c );
3974 return insert( index, s );
3975 }
3976
3977 /*!
3978 \fn QString& QString::insert( uint index, char c )
3979
3980 \overload
3981
3982 Insert character \a c at position \a index.
3983 */
3984
3985 /*!
3986 \fn QString &QString::prepend( const QString &s )
3987
3988 Inserts \a s at the beginning of the string and returns a
3989 reference to the string.
3990
3991 Equivalent to insert(0, \a s).
3992
3993 \code
3994 QString string = "42";
3995 string.prepend( "The answer is " );
3996 // string == "The answer is 42"
3997 \endcode
3998
3999 \sa insert()
4000 */
4001
4002 /*!
4003 \fn QString& QString::prepend( char ch )
4004
4005 \overload
4006
4007 Inserts \a ch at the beginning of the string and returns a
4008 reference to the string.
4009
4010 Equivalent to insert(0, \a ch).
4011
4012 \sa insert()
4013 */
4014
4015 /*!
4016 \fn QString& QString::prepend( QChar ch )
4017
4018 \overload
4019
4020 Inserts \a ch at the beginning of the string and returns a
4021 reference to the string.
4022
4023 Equivalent to insert(0, \a ch).
4024
4025 \sa insert()
4026 */
4027
4028 /*! \fn QString& QString::prepend( const QByteArray &s )
4029 \overload
4030
4031 Inserts \a s at the beginning of the string and returns a reference to the string.
4032
4033 Equivalent to insert(0, \a s).
4034
4035 \sa insert()
4036 */
4037
4038 /*! \fn QString& QString::prepend( const std::string &s )
4039 \overload
4040
4041 Inserts \a s at the beginning of the string and returns a reference to the string.
4042
4043 Equivalent to insert(0, \a s).
4044
4045 \sa insert()
4046 */
4047
4048 /*!
4049 \overload
4050
4051 Inserts \a s at the beginning of the string and returns a reference to the string.
4052
4053 Equivalent to insert(0, \a s).
4054
4055 \sa insert()
4056 */
prepend(const char * s)4057 QString &QString::prepend( const char *s )
4058 {
4059 return insert( 0, QString(s) );
4060 }
4061
4062 /*!
4063 Removes \a len characters from the string starting at position \a
4064 index, and returns a reference to the string.
4065
4066 If \a index is beyond the length of the string, nothing happens.
4067 If \a index is within the string, but \a index + \a len is beyond
4068 the end of the string, the string is truncated at position \a
4069 index.
4070
4071 \code
4072 QString string( "Montreal" );
4073 string.remove( 1, 4 ); // string == "Meal"
4074 \endcode
4075
4076 \sa insert(), replace()
4077 */
4078
remove(uint index,uint len)4079 QString &QString::remove( uint index, uint len )
4080 {
4081 uint olen = length();
4082 if ( index >= olen ) {
4083 // range problems
4084 } else if ( index + len >= olen ) { // index ok
4085 setLength( index );
4086 } else if ( len != 0 ) {
4087 real_detach();
4088 memmove( d->unicode+index, d->unicode+index+len,
4089 sizeof(QChar)*(olen-index-len) );
4090 setLength( olen-len );
4091 }
4092 return *this;
4093 }
4094
4095 /*! \overload
4096
4097 Removes every occurrence of the character \a c in the string.
4098 Returns a reference to the string.
4099
4100 This is the same as replace(\a c, "").
4101 */
remove(QChar c)4102 QString &QString::remove( QChar c )
4103 {
4104 int i = 0;
4105 while ( i < (int) length() ) {
4106 if ( constref(i) == c ) {
4107 remove( i, 1 );
4108 } else {
4109 i++;
4110 }
4111 }
4112 return *this;
4113 }
4114
4115 /*! \overload
4116
4117 \fn QString &QString::remove( char c )
4118
4119 Removes every occurrence of the character \a c in the string.
4120 Returns a reference to the string.
4121
4122 This is the same as replace(\a c, "").
4123 */
4124
4125 /*! \overload
4126
4127 Removes every occurrence of \a str in the string. Returns a
4128 reference to the string.
4129
4130 If \a cs is TRUE (the default), the search is case sensitive;
4131 otherwise the search is case insensitive.
4132
4133 This is the same as replace(\a str, "", \a cs).
4134 */
remove(const QString & str,bool cs)4135 QString &QString::remove( const QString & str, bool cs )
4136 {
4137 if ( str.isEmpty() ) {
4138 if ( isNull() )
4139 real_detach();
4140 } else {
4141 int index = 0;
4142 while ( (index = find(str, index, cs)) != -1 )
4143 remove( index, str.length() );
4144 }
4145 return *this;
4146 }
4147
remove(const QString & str)4148 QString &QString::remove( const QString & str )
4149 {
4150 return remove( str, TRUE );
4151 }
4152
4153 /*! \overload
4154
4155 Replaces every occurrence of \a c1 with the char \a c2. Returns a
4156 reference to the string.
4157 */
replace(QChar c1,QChar c2)4158 QString &QString::replace( QChar c1, QChar c2 )
4159 {
4160 if ( isEmpty() )
4161 return *this;
4162
4163 real_detach();
4164 uint i = 0;
4165 while ( i < d->len ) {
4166 if ( d->unicode[i] == c1 )
4167 d->unicode[i] = c2;
4168 i++;
4169 }
4170 return *this;
4171 }
4172
4173 #ifndef QT_NO_REGEXP_CAPTURE
4174
4175 /*! \overload
4176
4177 Removes every occurrence of the regular expression \a rx in the
4178 string. Returns a reference to the string.
4179
4180 This is the same as replace(\a rx, "").
4181 */
4182
remove(const QRegExp & rx)4183 QString &QString::remove( const QRegExp & rx )
4184 {
4185 return replace( rx, QString::null );
4186 }
4187
4188 #endif
4189
4190 /*!
4191 \overload
4192
4193 Removes every occurrence of \a str in the string. Returns a
4194 reference to the string.
4195 */
remove(const char * str)4196 QString &QString::remove( const char *str )
4197 {
4198 return remove( QString::fromAscii(str), TRUE );
4199 }
4200
4201 /*!
4202 Replaces \a len characters from the string with \a s, starting at
4203 position \a index, and returns a reference to the string.
4204
4205 If \a index is beyond the length of the string, nothing is deleted
4206 and \a s is appended at the end of the string. If \a index is
4207 valid, but \a index + \a len is beyond the end of the string,
4208 the string is truncated at position \a index, then \a s is
4209 appended at the end.
4210
4211 \code
4212 QString string( "Say yes!" );
4213 string = string.replace( 4, 3, "NO" );
4214 // string == "Say NO!"
4215 \endcode
4216
4217 \warning Qt 3.3.3 and earlier had different semantics for the
4218 case \a index >= length(), which contradicted the documentation.
4219 To avoid portability problems between Qt 3 versions and with Qt
4220 4, we recommend that you never call the function with \a index >=
4221 length().
4222
4223 \sa insert(), remove()
4224 */
4225
replace(uint index,uint len,const QString & s)4226 QString &QString::replace( uint index, uint len, const QString &s )
4227 {
4228 return replace( index, len, s.unicode(), s.length() );
4229 }
4230
4231 /*! \overload
4232
4233 This is the same as replace(\a index, \a len, QString(\a c)).
4234 */
replace(uint index,uint len,QChar c)4235 QString &QString::replace( uint index, uint len, QChar c )
4236 {
4237 return replace( index, len, &c, 1 );
4238 }
4239
4240 /*! \overload
4241 \fn QString &QString::replace( uint index, uint len, char c )
4242
4243 This is the same as replace(\a index, \a len, QChar(\a c)).
4244 */
4245
4246 /*!
4247 \overload
4248
4249 Replaces \a len characters with \a slen characters of QChar data
4250 from \a s, starting at position \a index, and returns a reference
4251 to the string.
4252
4253 \sa insert(), remove()
4254 */
4255
replace(uint index,uint len,const QChar * s,uint slen)4256 QString &QString::replace( uint index, uint len, const QChar* s, uint slen )
4257 {
4258 if (index > length())
4259 index = length();
4260 real_detach();
4261 if ( len == slen && index + len <= length() ) {
4262 // Optimized common case: replace without size change
4263 memcpy( d->unicode+index, s, len * sizeof(QChar) );
4264 } else if ( s >= d->unicode && (uint)(s - d->unicode) < d->maxl ) {
4265 // Part of me - take a copy.
4266 QChar *tmp = QT_ALLOC_QCHAR_VEC( slen );
4267 memcpy( tmp, s, slen * sizeof(QChar) );
4268 replace( index, len, tmp, slen );
4269 QT_DELETE_QCHAR_VEC( tmp );
4270 } else {
4271 remove( index, len );
4272 insert( index, s, slen );
4273 }
4274 return *this;
4275 }
4276
4277 /*! \overload
4278
4279 Replaces every occurrence of the character \a c in the string
4280 with \a after. Returns a reference to the string.
4281
4282 If \a cs is TRUE (the default), the search is case sensitive;
4283 otherwise the search is case insensitive.
4284
4285 Example:
4286 \code
4287 QString s = "a,b,c";
4288 s.replace( QChar(','), " or " );
4289 // s == "a or b or c"
4290 \endcode
4291 */
replace(QChar c,const QString & after,bool cs)4292 QString &QString::replace( QChar c, const QString & after, bool cs )
4293 {
4294 return replace( QString( c ), after, cs );
4295 }
4296
replace(QChar c,const QString & after)4297 QString &QString::replace( QChar c, const QString & after )
4298 {
4299 return replace( QString( c ), after, TRUE );
4300 }
4301
4302 /*! \overload
4303 \fn QString &QString::replace( char c, const QString & after, bool cs )
4304
4305 Replaces every occurrence of the character \a c in the string
4306 with \a after. Returns a reference to the string.
4307
4308 If \a cs is TRUE (the default), the search is case sensitive;
4309 otherwise the search is case insensitive.
4310 */
4311
4312 /*! \overload
4313
4314 Replaces every occurrence of the string \a before in the string
4315 with the string \a after. Returns a reference to the string.
4316
4317 If \a cs is TRUE (the default), the search is case sensitive;
4318 otherwise the search is case insensitive.
4319
4320 Example:
4321 \code
4322 QString s = "Greek is Greek";
4323 s.replace( "Greek", "English" );
4324 // s == "English is English"
4325 \endcode
4326 */
replace(const QString & before,const QString & after,bool cs)4327 QString &QString::replace( const QString & before, const QString & after,
4328 bool cs )
4329 {
4330 if ( isEmpty() ) {
4331 if ( !before.isEmpty() )
4332 return *this;
4333 } else {
4334 if ( cs && before == after )
4335 return *this;
4336 }
4337
4338 real_detach();
4339
4340 int index = 0;
4341 uint skiptable[256];
4342 bm_init_skiptable( before, skiptable, cs );
4343 const int bl = before.length();
4344 const int al = after.length();
4345
4346 if ( bl == al ) {
4347 if ( bl ) {
4348 const QChar *auc = after.unicode();
4349 while ( (index = bm_find(*this, index, before, skiptable, cs) ) != -1 ) {
4350 memcpy( d->unicode + index, auc, al * sizeof(QChar) );
4351 index += bl;
4352 }
4353 }
4354 } else if ( al < bl ) {
4355 const QChar *auc = after.unicode();
4356 uint to = 0;
4357 uint movestart = 0;
4358 uint num = 0;
4359 while ( (index = bm_find(*this, index, before, skiptable, cs)) != -1 ) {
4360 if ( num ) {
4361 int msize = index - movestart;
4362 if ( msize > 0 ) {
4363 memmove( d->unicode + to, d->unicode + movestart, msize*sizeof(QChar) );
4364 to += msize;
4365 }
4366 } else {
4367 to = index;
4368 }
4369 if ( al ) {
4370 memcpy( d->unicode+to, auc, al*sizeof(QChar) );
4371 to += al;
4372 }
4373 index += bl;
4374 movestart = index;
4375 num++;
4376 }
4377 if ( num ) {
4378 int msize = d->len - movestart;
4379 if ( msize > 0 )
4380 memmove( d->unicode + to, d->unicode + movestart, msize*sizeof(QChar) );
4381 setLength( d->len - num*(bl-al) );
4382 }
4383 } else {
4384 // the most complex case. We don't want to loose performance by doing repeated
4385 // copies and reallocs of the string.
4386 while ( index != -1 ) {
4387 uint indices[4096];
4388 uint pos = 0;
4389 while ( pos < 4095 ) {
4390 index = bm_find( *this, index, before, skiptable, cs );
4391 if ( index == -1 )
4392 break;
4393 indices[pos++] = index;
4394 index += bl;
4395 // avoid infinite loop
4396 if ( !bl )
4397 index++;
4398 }
4399 if ( !pos )
4400 break;
4401
4402 // we have a table of replacement positions, use them for fast replacing
4403 int adjust = pos*(al-bl);
4404 // index has to be adjusted in case we get back into the loop above.
4405 if ( index != -1 )
4406 index += adjust;
4407 uint newlen = d->len + adjust;
4408 int moveend = d->len;
4409 if ( newlen > d->len )
4410 setLength( newlen );
4411
4412 while ( pos ) {
4413 pos--;
4414 int movestart = indices[pos] + bl;
4415 int insertstart = indices[pos] + pos*(al-bl);
4416 int moveto = insertstart + al;
4417 memmove( d->unicode + moveto, d->unicode + movestart, (moveend - movestart)*sizeof(QChar) );
4418 memcpy( d->unicode + insertstart, after.unicode(), al*sizeof(QChar) );
4419 moveend = movestart-bl;
4420 }
4421 }
4422 }
4423 return *this;
4424 }
4425
replace(const QString & before,const QString & after)4426 QString &QString::replace( const QString & before, const QString & after )
4427 {
4428 return replace( before, after, TRUE );
4429 }
4430
4431 #ifndef QT_NO_REGEXP_CAPTURE
4432 /*! \overload
4433
4434 Replaces every occurrence of the regexp \a rx in the string with
4435 \a after. Returns a reference to the string. For example:
4436 \code
4437 QString s = "banana";
4438 s.replace( QRegExp("an"), "" );
4439 // s == "ba"
4440 \endcode
4441
4442 For regexps containing \link qregexp.html#capturing-text capturing
4443 parentheses \endlink, occurrences of <b>\\1</b>, <b>\\2</b>, ...,
4444 in \a after are replaced with \a{rx}.cap(1), cap(2), ...
4445
4446 \code
4447 QString t = "A <i>bon mot</i>.";
4448 t.replace( QRegExp("<i>([^<]*)</i>"), "\\emph{\\1}" );
4449 // t == "A \\emph{bon mot}."
4450 \endcode
4451
4452 \sa find(), findRev(), QRegExp::cap()
4453 */
4454
replace(const QRegExp & rx,const QString & after)4455 QString &QString::replace( const QRegExp &rx, const QString &after )
4456 {
4457 QRegExp rx2 = rx;
4458
4459 if ( isEmpty() && rx2.search(*this) == -1 )
4460 return *this;
4461
4462 real_detach();
4463
4464 int index = 0;
4465 int numCaptures = rx2.numCaptures();
4466 int al = after.length();
4467 QRegExp::CaretMode caretMode = QRegExp::CaretAtZero;
4468
4469 if ( numCaptures > 0 ) {
4470 if ( numCaptures > 9 )
4471 numCaptures = 9;
4472
4473 const QChar *uc = after.unicode();
4474 int numBackRefs = 0;
4475
4476 for ( int i = 0; i < al - 1; i++ ) {
4477 if ( uc[i] == '\\' ) {
4478 int no = uc[i + 1].digitValue();
4479 if ( no > 0 && no <= numCaptures )
4480 numBackRefs++;
4481 }
4482 }
4483
4484 /*
4485 This is the harder case where we have back-references.
4486 We don't try to optimize it.
4487 */
4488 if ( numBackRefs > 0 ) {
4489 int *capturePositions = new int[numBackRefs];
4490 int *captureNumbers = new int[numBackRefs];
4491 int j = 0;
4492
4493 for ( int i = 0; i < al - 1; i++ ) {
4494 if ( uc[i] == '\\' ) {
4495 int no = uc[i + 1].digitValue();
4496 if ( no > 0 && no <= numCaptures ) {
4497 capturePositions[j] = i;
4498 captureNumbers[j] = no;
4499 j++;
4500 }
4501 }
4502 }
4503
4504 while ( index <= (int)length() ) {
4505 index = rx2.search( *this, index, caretMode );
4506 if ( index == -1 )
4507 break;
4508
4509 QString after2 = after;
4510 for ( j = numBackRefs - 1; j >= 0; j-- )
4511 after2.replace( capturePositions[j], 2,
4512 rx2.cap(captureNumbers[j]) );
4513
4514 replace( index, rx2.matchedLength(), after2 );
4515 index += after2.length();
4516
4517 if ( rx2.matchedLength() == 0 ) {
4518 // avoid infinite loop on 0-length matches (e.g., [a-z]*)
4519 index++;
4520 }
4521 caretMode = QRegExp::CaretWontMatch;
4522 }
4523 delete[] capturePositions;
4524 delete[] captureNumbers;
4525 return *this;
4526 }
4527 }
4528
4529 /*
4530 This is the simple and optimized case where we don't have
4531 back-references.
4532 */
4533 while ( index != -1 ) {
4534 struct {
4535 int pos;
4536 int length;
4537 } replacements[2048];
4538
4539 uint pos = 0;
4540 int adjust = 0;
4541 while ( pos < 2047 ) {
4542 index = rx2.search( *this, index, caretMode );
4543 if ( index == -1 )
4544 break;
4545 int ml = rx2.matchedLength();
4546 replacements[pos].pos = index;
4547 replacements[pos++].length = ml;
4548 index += ml;
4549 adjust += al - ml;
4550 // avoid infinite loop
4551 if ( !ml )
4552 index++;
4553 }
4554 if ( !pos )
4555 break;
4556 replacements[pos].pos = d->len;
4557 uint newlen = d->len + adjust;
4558
4559 // to continue searching at the right position after we did
4560 // the first round of replacements
4561 if ( index != -1 )
4562 index += adjust;
4563 QChar *newuc = QT_ALLOC_QCHAR_VEC( newlen + 1 );
4564 QChar *uc = newuc;
4565 int copystart = 0;
4566 uint i = 0;
4567 while ( i < pos ) {
4568 int copyend = replacements[i].pos;
4569 int size = copyend - copystart;
4570 memcpy( uc, d->unicode + copystart, size * sizeof(QChar) );
4571 uc += size;
4572 memcpy( uc, after.unicode(), al * sizeof(QChar) );
4573 uc += al;
4574 copystart = copyend + replacements[i].length;
4575 i++;
4576 }
4577 memcpy( uc, d->unicode + copystart,
4578 (d->len - copystart) * sizeof(QChar) );
4579 QT_DELETE_QCHAR_VEC( d->unicode );
4580 d->unicode = newuc;
4581 d->len = newlen;
4582 d->maxl = newlen + 1;
4583 d->setDirty();
4584 caretMode = QRegExp::CaretWontMatch;
4585 }
4586 return *this;
4587 }
4588 #endif
4589
4590 #ifndef QT_NO_REGEXP
4591 /*!
4592 Finds the first match of the regular expression \a rx, starting
4593 from position \a index. If \a index is -1, the search starts at
4594 the last character; if -2, at the next to last character and so
4595 on. (See findRev() for searching backwards.)
4596
4597 Returns the position of the first match of \a rx or -1 if no match
4598 was found.
4599
4600 \code
4601 QString string( "bananas" );
4602 int i = string.find( QRegExp("an"), 0 ); // i == 1
4603 \endcode
4604
4605 \sa findRev() replace() contains()
4606 */
4607
find(const QRegExp & rx,int index) const4608 int QString::find( const QRegExp &rx, int index ) const
4609 {
4610 return rx.search( *this, index );
4611 }
4612
4613 /*!
4614 \overload
4615
4616 Finds the first match of the regexp \a rx, starting at position \a
4617 index and searching backwards. If the index is -1, the search
4618 starts at the last character, if it is -2, at the next to last
4619 character and so on. (See findRev() for searching backwards.)
4620
4621 Returns the position of the match or -1 if no match was found.
4622
4623 \code
4624 QString string( "bananas" );
4625 int i = string.findRev( QRegExp("an") ); // i == 3
4626 \endcode
4627
4628 \sa find()
4629 */
4630
findRev(const QRegExp & rx,int index) const4631 int QString::findRev( const QRegExp &rx, int index ) const
4632 {
4633 return rx.searchRev( *this, index );
4634 }
4635
4636 /*!
4637 \overload
4638
4639 Returns the number of times the regexp, \a rx, matches in the
4640 string.
4641
4642 This function counts overlapping matches, so in the example below,
4643 there are four instances of "ana" or "ama".
4644
4645 \code
4646 QString str = "banana and panama";
4647 QRegExp rxp = QRegExp( "a[nm]a", TRUE, FALSE );
4648 int i = str.contains( rxp ); // i == 4
4649 \endcode
4650
4651 \sa find() findRev()
4652 */
4653
contains(const QRegExp & rx) const4654 int QString::contains( const QRegExp &rx ) const
4655 {
4656 int count = 0;
4657 int index = -1;
4658 int len = length();
4659 while ( index < len - 1 ) { // count overlapping matches
4660 index = rx.search( *this, index + 1 );
4661 if ( index == -1 )
4662 break;
4663 count++;
4664 }
4665 return count;
4666 }
4667
4668 #endif //QT_NO_REGEXP
4669
4670 /*!
4671 Returns the string converted to a \c long using base \a
4672 base, which is 10 by default and must be between 2 and 36 or 0. If
4673 \a base is 0, the base is determined automatically using the
4674 following rules:
4675 <ul>
4676 <li>If the string begins with "0x", it is assumed to
4677 be hexadecimal;
4678 <li>If it begins with "0", it is assumed to be octal;
4679 <li>Otherwise it is assumed to be decimal.
4680 </ul>
4681
4682 Returns 0 if the conversion fails.
4683
4684 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4685 FALSE; otherwise \a *ok is set to TRUE.
4686
4687 Leading and trailing whitespace is ignored by this function.
4688
4689 For information on how string-to-number functions in QString handle
4690 localized input, see toDouble().
4691
4692 \sa number()
4693 */
4694
toLong(bool * ok,int base) const4695 long QString::toLong( bool *ok, int base ) const
4696 {
4697 Q_LLONG v = toLongLong( ok, base );
4698 if ( v < LONG_MIN || v > LONG_MAX ) {
4699 if ( ok )
4700 *ok = FALSE;
4701 v = 0;
4702 }
4703 return long(v);
4704 }
4705
4706 /*!
4707 Returns the string converted to a \c {long long} using base \a
4708 base, which is 10 by default and must be between 2 and 36 or 0. If
4709 \a base is 0, the base is determined automatically using the
4710 following rules:
4711 <ul>
4712 <li>If the string begins with "0x", it is assumed to
4713 be hexadecimal;
4714 <li>If it begins with "0", it is assumed to be octal;
4715 <li>Otherwise it is assumed to be decimal.
4716 </ul>
4717
4718 Returns 0 if the conversion fails.
4719
4720 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4721 FALSE; otherwise \a *ok is set to TRUE.
4722
4723 Leading and trailing whitespace is ignored by this function.
4724
4725 For information on how string-to-number functions in QString handle
4726 localized input, see toDouble().
4727
4728 \sa number()
4729 */
4730
toLongLong(bool * ok,int base) const4731 Q_LLONG QString::toLongLong( bool *ok, int base ) const
4732 {
4733 #if defined(QT_CHECK_RANGE)
4734 if ( base != 0 && (base < 2 || base > 36) ) {
4735 qWarning( "QString::toLongLong: Invalid base (%d)", base );
4736 base = 10;
4737 }
4738 #endif
4739
4740 bool my_ok;
4741 QLocale def_locale;
4742 Q_LLONG result = def_locale.d->stringToLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
4743 if (my_ok) {
4744 if (ok != 0)
4745 *ok = TRUE;
4746 return result;
4747 }
4748
4749 // If the default was not "C", try the "C" locale
4750 if (def_locale.language() == QLocale::C) {
4751 if (ok != 0)
4752 *ok = FALSE;
4753 return 0;
4754 }
4755
4756 QLocale c_locale(QLocale::C);
4757 return c_locale.d->stringToLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
4758 }
4759
4760 /*!
4761 Returns the string converted to an \c {unsigned long} using base \a
4762 base, which is 10 by default and must be between 2 and 36 or 0. If
4763 \a base is 0, the base is determined automatically using the
4764 following rules:
4765 <ul>
4766 <li>If the string begins with "0x", it is assumed to
4767 be hexadecimal;
4768 <li>If it begins with "0", it is assumed to be octal;
4769 <li>Otherwise it is assumed to be decimal.
4770 </ul>
4771
4772 Returns 0 if the conversion fails.
4773
4774 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4775 FALSE; otherwise \a *ok is set to TRUE.
4776
4777 Leading and trailing whitespace is ignored by this function.
4778
4779 For information on how string-to-number functions in QString handle
4780 localized input, see toDouble().
4781
4782 \sa number()
4783 */
4784
toULong(bool * ok,int base) const4785 ulong QString::toULong( bool *ok, int base ) const
4786 {
4787 Q_ULLONG v = toULongLong( ok, base );
4788 if ( v > ULONG_MAX ) {
4789 if ( ok )
4790 *ok = FALSE;
4791 v = 0;
4792 }
4793 return ulong(v);
4794 }
4795
4796 /*!
4797 Returns the string converted to an \c {unsigned long long} using base \a
4798 base, which is 10 by default and must be between 2 and 36 or 0. If
4799 \a base is 0, the base is determined automatically using the
4800 following rules:
4801 <ul>
4802 <li>If the string begins with "0x", it is assumed to
4803 be hexadecimal;
4804 <li>If it begins with "0", it is assumed to be octal;
4805 <li>Otherwise it is assumed to be decimal.
4806 </ul>
4807
4808 Returns 0 if the conversion fails.
4809
4810 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4811 FALSE; otherwise \a *ok is set to TRUE.
4812
4813 Leading and trailing whitespace is ignored by this function.
4814
4815 For information on how string-to-number functions in QString handle
4816 localized input, see toDouble().
4817
4818 \sa number()
4819 */
4820
toULongLong(bool * ok,int base) const4821 Q_ULLONG QString::toULongLong( bool *ok, int base ) const
4822 {
4823 #if defined(QT_CHECK_RANGE)
4824 if ( base != 0 && (base < 2 || base > 36) ) {
4825 qWarning( "QString::toULongLong: Invalid base %d", base );
4826 base = 10;
4827 }
4828 #endif
4829
4830 bool my_ok;
4831 QLocale def_locale;
4832 Q_ULLONG result = def_locale.d->stringToUnsLongLong(*this, base, &my_ok, QLocalePrivate::FailOnGroupSeparators);
4833 if (my_ok) {
4834 if (ok != 0)
4835 *ok = TRUE;
4836 return result;
4837 }
4838
4839 // If the default was not "C", try the "C" locale
4840 if (def_locale.language() == QLocale::C) {
4841 if (ok != 0)
4842 *ok = FALSE;
4843 return 0;
4844 }
4845
4846 QLocale c_locale(QLocale::C);
4847 return c_locale.d->stringToUnsLongLong(*this, base, ok, QLocalePrivate::FailOnGroupSeparators);
4848 }
4849
4850 /*!
4851 Returns the string converted to a \c short using base \a
4852 base, which is 10 by default and must be between 2 and 36 or 0. If
4853 \a base is 0, the base is determined automatically using the
4854 following rules:
4855 <ul>
4856 <li>If the string begins with "0x", it is assumed to
4857 be hexadecimal;
4858 <li>If it begins with "0", it is assumed to be octal;
4859 <li>Otherwise it is assumed to be decimal.
4860 </ul>
4861
4862
4863 Returns 0 if the conversion fails.
4864
4865 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4866 FALSE; otherwise \a *ok is set to TRUE.
4867
4868 Leading and trailing whitespace is ignored by this function.
4869
4870 For information on how string-to-number functions in QString handle
4871 localized input, see toDouble().
4872
4873 \sa number()
4874 */
4875
4876
toShort(bool * ok,int base) const4877 short QString::toShort( bool *ok, int base ) const
4878 {
4879 Q_LLONG v = toLongLong( ok, base );
4880 if ( v < SHRT_MIN || v > SHRT_MAX ) {
4881 if ( ok )
4882 *ok = FALSE;
4883 v = 0;
4884 }
4885 return (short)v;
4886 }
4887
4888 /*!
4889 Returns the string converted to an \c {unsigned short} using base \a
4890 base, which is 10 by default and must be between 2 and 36 or 0. If
4891 \a base is 0, the base is determined automatically using the
4892 following rules:
4893 <ul>
4894 <li>If the string begins with "0x", it is assumed to
4895 be hexadecimal;
4896 <li>If it begins with "0", it is assumed to be octal;
4897 <li>Otherwise it is assumed to be decimal.
4898 </ul>
4899
4900
4901 Returns 0 if the conversion fails.
4902
4903 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4904 FALSE; otherwise \a *ok is set to TRUE.
4905
4906 Leading and trailing whitespace is ignored by this function.
4907
4908 For information on how string-to-number functions in QString handle
4909 localized input, see toDouble().
4910
4911 \sa number()
4912 */
4913
toUShort(bool * ok,int base) const4914 ushort QString::toUShort( bool *ok, int base ) const
4915 {
4916 Q_ULLONG v = toULongLong( ok, base );
4917 if ( v > USHRT_MAX ) {
4918 if ( ok )
4919 *ok = FALSE;
4920 v = 0;
4921 }
4922 return (ushort)v;
4923 }
4924
4925
4926 /*!
4927 Returns the string converted to an \c int using base \a
4928 base, which is 10 by default and must be between 2 and 36 or 0. If
4929 \a base is 0, the base is determined automatically using the
4930 following rules:
4931 <ul>
4932 <li>If the string begins with "0x", it is assumed to
4933 be hexadecimal;
4934 <li>If it begins with "0", it is assumed to be octal;
4935 <li>Otherwise it is assumed to be decimal.
4936 </ul>
4937
4938
4939 Returns 0 if the conversion fails.
4940
4941 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4942 FALSE; otherwise \a *ok is set to TRUE.
4943
4944 \code
4945 QString str( "FF" );
4946 bool ok;
4947 int hex = str.toInt( &ok, 16 ); // hex == 255, ok == TRUE
4948 int dec = str.toInt( &ok, 10 ); // dec == 0, ok == FALSE
4949 \endcode
4950
4951 Leading and trailing whitespace is ignored by this function.
4952
4953 For information on how string-to-number functions in QString handle
4954 localized input, see toDouble().
4955
4956 \sa number()
4957 */
4958
toInt(bool * ok,int base) const4959 int QString::toInt( bool *ok, int base ) const
4960 {
4961 Q_LLONG v = toLongLong( ok, base );
4962 if ( v < INT_MIN || v > INT_MAX ) {
4963 if ( ok )
4964 *ok = FALSE;
4965 v = 0;
4966 }
4967 return (int)v;
4968 }
4969
4970 /*!
4971 Returns the string converted to an \c {unsigned int} using base \a
4972 base, which is 10 by default and must be between 2 and 36 or 0. If
4973 \a base is 0, the base is determined automatically using the
4974 following rules:
4975 <ul>
4976 <li>If the string begins with "0x", it is assumed to
4977 be hexadecimal;
4978 <li>If it begins with "0", it is assumed to be octal;
4979 <li>Otherwise it is assumed to be decimal.
4980 </ul>
4981
4982 Returns 0 if the conversion fails.
4983
4984 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
4985 FALSE; otherwise \a *ok is set to TRUE.
4986
4987 Leading and trailing whitespace is ignored by this function.
4988
4989 For information on how string-to-number functions in QString handle
4990 localized input, see toDouble().
4991
4992 \sa number()
4993 */
4994
toUInt(bool * ok,int base) const4995 uint QString::toUInt( bool *ok, int base ) const
4996 {
4997 Q_ULLONG v = toULongLong( ok, base );
4998 if ( v > UINT_MAX ) {
4999 if ( ok )
5000 *ok = FALSE;
5001 v = 0;
5002 }
5003 return (uint)v;
5004 }
5005
5006 /*!
5007 Returns the string converted to a \c double value.
5008
5009 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
5010 FALSE; otherwise \a *ok is set to TRUE.
5011
5012 \code
5013 QString string( "1234.56" );
5014 double a = string.toDouble(); // a == 1234.56
5015 \endcode
5016
5017 The string-to-number functions:
5018 \list
5019 \i toShort()
5020 \i toUShort()
5021 \i toInt()
5022 \i toUInt()
5023 \i toLong()
5024 \i toULong()
5025 \i toLongLong()
5026 \i toULongLong()
5027 \i toFloat()
5028 \i toDouble()
5029 \endlist
5030 can handle numbers
5031 represented in various locales. These representations may use different
5032 characters for the decimal point, thousands group sepearator
5033 and even individual digits. QString's functions try to interpret
5034 the string according to the current locale. The current locale is
5035 determined from the system at application startup and can be changed
5036 by calling QLocale::setDefault(). If the string cannot be interpreted
5037 according to the current locale, this function falls back
5038 on the "C" locale.
5039
5040 \code
5041 bool ok;
5042 double d;
5043
5044 QLocale::setDefault(QLocale::C);
5045 d = QString( "1234,56" ).toDouble(&ok); // ok == false
5046 d = QString( "1234.56" ).toDouble(&ok); // ok == true, d == 1234.56
5047
5048 QLocale::setDefault(QLocale::German);
5049 d = QString( "1234,56" ).toDouble(&ok); // ok == true, d == 1234.56
5050 d = QString( "1234.56" ).toDouble(&ok); // ok == true, d == 1234.56
5051 \endcode
5052
5053 Due to the ambiguity between the decimal point and thousands group
5054 separator in various locales, these functions do not handle
5055 thousands group separators. If you need to convert such numbers,
5056 use the corresponding function in QLocale.
5057
5058 \code
5059 bool ok;
5060 QLocale::setDefault(QLocale::C);
5061 double d = QString( "1,234,567.89" ).toDouble(&ok); // ok == false
5062 \endcode
5063
5064 \warning If the string contains trailing whitespace this function
5065 will fail, and set \a *ok to false if \a ok is not 0. Leading
5066 whitespace is ignored.
5067
5068 \sa number() QLocale::setDefault() QLocale::toDouble() stripWhiteSpace()
5069 */
5070
toDouble(bool * ok) const5071 double QString::toDouble( bool *ok ) const
5072 {
5073 // If there is trailing whitespace, set ok to false but return the correct
5074 // result anyway to preserve behavour of pervious versions of Qt
5075 if (length() > 0 && unicode()[length() - 1].isSpace()) {
5076 QString tmp = stripWhiteSpace();
5077 if (ok != 0)
5078 *ok = FALSE;
5079 return tmp.toDouble();
5080 }
5081
5082 // Try the default locale
5083 bool my_ok;
5084 QLocale def_locale;
5085 double result = def_locale.d->stringToDouble(*this, &my_ok, QLocalePrivate::FailOnGroupSeparators);
5086 if (my_ok) {
5087 if (ok != 0)
5088 *ok = TRUE;
5089 return result;
5090 }
5091
5092 // If the default was not "C", try the "C" locale
5093 if (def_locale.language() == QLocale::C) {
5094 if (ok != 0)
5095 *ok = FALSE;
5096 return 0.0;
5097 }
5098
5099 QLocale c_locale(QLocale::C);
5100 return c_locale.d->stringToDouble(*this, ok, QLocalePrivate::FailOnGroupSeparators);
5101 }
5102
5103 /*!
5104 Returns the string converted to a \c float value.
5105
5106 Returns 0.0 if the conversion fails.
5107
5108 If \a ok is not 0: if a conversion error occurs, \a *ok is set to
5109 FALSE; otherwise \a *ok is set to TRUE.
5110
5111 For information on how string-to-number functions in QString handle
5112 localized input, see toDouble().
5113
5114 \warning If the string contains trailing whitespace this function
5115 will fail, settings \a *ok to false if \a ok is not 0.
5116 Leading whitespace is ignored.
5117
5118 \sa number()
5119 */
5120
5121 #define QT_MAX_FLOAT 3.4028234663852886e+38
5122
toFloat(bool * ok) const5123 float QString::toFloat( bool *ok ) const
5124 {
5125 bool myOk;
5126 double d = toDouble(&myOk);
5127 if (!myOk || d > QT_MAX_FLOAT || d < -QT_MAX_FLOAT) {
5128 if (ok != 0)
5129 *ok = FALSE;
5130 return 0.0;
5131 }
5132 if (ok != 0)
5133 *ok = TRUE;
5134 return (float) d;
5135 }
5136
5137 /*!
5138 Sets the string to the printed value of \a n in base \a base and
5139 returns a reference to the string. The returned string is in "C" locale.
5140
5141 The base is 10 by default and must be between 2 and 36.
5142
5143 \code
5144 QString string;
5145 string = string.setNum( 1234 ); // string == "1234"
5146 \endcode
5147 */
5148
setNum(Q_LLONG n,int base)5149 QString &QString::setNum( Q_LLONG n, int base )
5150 {
5151 #if defined(QT_CHECK_RANGE)
5152 if ( base < 2 || base > 36 ) {
5153 qWarning( "QString::setNum: Invalid base %d", base );
5154 base = 10;
5155 }
5156 #endif
5157 QLocale locale(QLocale::C);
5158 *this = locale.d->longLongToString(n, -1, base);
5159 return *this;
5160 }
5161
5162 /*!
5163 \overload
5164
5165 Sets the string to the printed value of \a n in base \a base and
5166 returns a reference to the string.
5167
5168 The base is 10 by default and must be between 2 and 36.
5169 */
5170
setNum(Q_ULLONG n,int base)5171 QString &QString::setNum( Q_ULLONG n, int base )
5172 {
5173 #if defined(QT_CHECK_RANGE)
5174 if ( base < 2 || base > 36 ) {
5175 qWarning( "QString::setNum: Invalid base %d", base );
5176 base = 10;
5177 }
5178 #endif
5179 QLocale locale(QLocale::C);
5180 *this = locale.d->unsLongLongToString(n, -1, base);
5181 return *this;
5182 }
5183
5184 /*!
5185 \fn QString &QString::setNum( long n, int base )
5186
5187 \overload
5188 */
5189 // ### 4.0: inline
setNum(long n,int base)5190 QString &QString::setNum( long n, int base )
5191 {
5192 return setNum( (Q_LLONG)n, base );
5193 }
5194
5195 /*!
5196 \fn QString &QString::setNum( ulong n, int base )
5197
5198 \overload
5199 */
5200 // ### 4.0: inline
setNum(ulong n,int base)5201 QString &QString::setNum( ulong n, int base )
5202 {
5203 return setNum( (Q_ULLONG)n, base );
5204 }
5205
5206 /*!
5207 \fn QString &QString::setNum( int n, int base )
5208
5209 \overload
5210
5211 Sets the string to the printed value of \a n in base \a base and
5212 returns a reference to the string.
5213
5214 The base is 10 by default and must be between 2 and 36.
5215 */
5216
5217 /*!
5218 \fn QString &QString::setNum( uint n, int base )
5219
5220 \overload
5221
5222 Sets the string to the printed value of \a n in base \a base and
5223 returns a reference to the string.
5224
5225 The base is 10 by default and must be between 2 and 36.
5226 */
5227
5228 /*!
5229 \fn QString &QString::setNum( short n, int base )
5230
5231 \overload
5232
5233 Sets the string to the printed value of \a n in base \a base and
5234 returns a reference to the string.
5235
5236 The base is 10 by default and must be between 2 and 36.
5237 */
5238
5239 /*!
5240 \fn QString &QString::setNum( ushort n, int base )
5241
5242 \overload
5243
5244 Sets the string to the printed value of \a n in base \a base and
5245 returns a reference to the string.
5246
5247 The base is 10 by default and must be between 2 and 36.
5248 */
5249
5250 /*!
5251 \overload
5252
5253 Sets the string to the printed value of \a n, formatted in format
5254 \a f with precision \a prec, and returns a reference to the
5255 string.
5256
5257 The format \a f can be 'f', 'F', 'e', 'E', 'g' or 'G'. See \link
5258 #arg-formats arg \endlink() for an explanation of the formats.
5259 */
5260
setNum(double n,char f,int prec)5261 QString &QString::setNum( double n, char f, int prec )
5262 {
5263 QLocalePrivate::DoubleForm form = QLocalePrivate::DFDecimal;
5264 uint flags = 0;
5265
5266 if (qIsUpper(f))
5267 flags = QLocalePrivate::CapitalEorX;
5268 f = qToLower(f);
5269
5270 switch (f) {
5271 case 'f':
5272 form = QLocalePrivate::DFDecimal;
5273 break;
5274 case 'e':
5275 form = QLocalePrivate::DFExponent;
5276 break;
5277 case 'g':
5278 form = QLocalePrivate::DFSignificantDigits;
5279 break;
5280 default:
5281 #if defined(QT_CHECK_RANGE)
5282 qWarning( "QString::setNum: Invalid format char '%c'", f );
5283 #endif
5284 break;
5285 }
5286
5287 QLocale locale(QLocale::C);
5288 *this = locale.d->doubleToString(n, prec, form, -1, flags);
5289 return *this;
5290 }
5291
5292 /*!
5293 \fn QString &QString::setNum( float n, char f, int prec )
5294
5295 \overload
5296
5297 Sets the string to the printed value of \a n, formatted in format
5298 \a f with precision \a prec, and returns a reference to the
5299 string.
5300
5301 The format \a f can be 'f', 'F', 'e', 'E', 'g' or 'G'. See \link
5302 #arg-formats arg \endlink() for an explanation of the formats.
5303 */
5304
5305
5306 /*!
5307 A convenience function that returns a string equivalent of the
5308 number \a n to base \a base, which is 10 by default and must be
5309 between 2 and 36. The returned string is in "C" locale.
5310
5311 \code
5312 long a = 63;
5313 QString str = QString::number( a, 16 ); // str == "3f"
5314 QString str = QString::number( a, 16 ).upper(); // str == "3F"
5315 \endcode
5316
5317 \sa setNum()
5318 */
number(long n,int base)5319 QString QString::number( long n, int base )
5320 {
5321 QString s;
5322 s.setNum( n, base );
5323 return s;
5324 }
5325
5326 /*!
5327 \overload
5328
5329 \sa setNum()
5330 */
number(ulong n,int base)5331 QString QString::number( ulong n, int base )
5332 {
5333 QString s;
5334 s.setNum( n, base );
5335 return s;
5336 }
5337
5338 /*!
5339 \overload
5340
5341 \sa setNum()
5342 */
number(Q_LLONG n,int base)5343 QString QString::number( Q_LLONG n, int base )
5344 {
5345 QString s;
5346 s.setNum( n, base );
5347 return s;
5348 }
5349
5350 /*!
5351 \overload
5352
5353 \sa setNum()
5354 */
number(Q_ULLONG n,int base)5355 QString QString::number( Q_ULLONG n, int base )
5356 {
5357 QString s;
5358 s.setNum( n, base );
5359 return s;
5360 }
5361
5362 /*!
5363 \overload
5364
5365 \sa setNum()
5366 */
number(int n,int base)5367 QString QString::number( int n, int base )
5368 {
5369 QString s;
5370 s.setNum( n, base );
5371 return s;
5372 }
5373
5374 /*!
5375 \overload
5376
5377 A convenience factory function that returns a string
5378 representation of the number \a n to the base \a base, which is 10
5379 by default and must be between 2 and 36.
5380
5381 \sa setNum()
5382 */
number(uint n,int base)5383 QString QString::number( uint n, int base )
5384 {
5385 QString s;
5386 s.setNum( n, base );
5387 return s;
5388 }
5389
5390 /*!
5391 \overload
5392
5393 Argument \a n is formatted according to the \a f format specified,
5394 which is \c g by default, and can be any of the following:
5395
5396 \table
5397 \header \i Format \i Meaning
5398 \row \i \c e \i format as [-]9.9e[+|-]999
5399 \row \i \c E \i format as [-]9.9E[+|-]999
5400 \row \i \c f \i format as [-]9.9
5401 \row \i \c g \i use \c e or \c f format, whichever is the most concise
5402 \row \i \c G \i use \c E or \c f format, whichever is the most concise
5403 \endtable
5404
5405 With 'e', 'E', and 'f', \a prec is the number of digits after the
5406 decimal point. With 'g' and 'G', \a prec is the maximum number of
5407 significant digits (trailing zeroes are omitted).
5408
5409 \code
5410 double d = 12.34;
5411 QString ds = QString( "'E' format, precision 3, gives %1" )
5412 .arg( d, 0, 'E', 3 );
5413 // ds == "1.234E+001"
5414 \endcode
5415
5416 \sa setNum()
5417 */
number(double n,char f,int prec)5418 QString QString::number( double n, char f, int prec )
5419 {
5420 QString s;
5421 s.setNum( n, f, prec );
5422 return s;
5423 }
5424
5425
5426 /*! \obsolete
5427
5428 Sets the character at position \a index to \a c and expands the
5429 string if necessary, filling with spaces.
5430
5431 This method is redundant in Qt 3.x, because operator[] will expand
5432 the string as necessary.
5433 */
5434
setExpand(uint index,QChar c)5435 void QString::setExpand( uint index, QChar c )
5436 {
5437 int spaces = index - d->len;
5438 at(index) = c;
5439 while (spaces-->0)
5440 d->unicode[--index]=' ';
5441 }
5442
5443
5444 /*!
5445 \fn const char* QString::data() const
5446
5447 \obsolete
5448
5449 Returns a pointer to a '\0'-terminated classic C string.
5450
5451 In Qt 1.x, this returned a char* allowing direct manipulation of the
5452 string as a sequence of bytes. In Qt 2.x where QString is a Unicode
5453 string, char* conversion constructs a temporary string, and hence
5454 direct character operations are meaningless.
5455 */
5456
5457 /*!
5458 \fn bool QString::operator!() const
5459
5460 Returns TRUE if this is a null string; otherwise returns FALSE.
5461
5462 \code
5463 QString name = getName();
5464 if ( !name )
5465 name = "Rodney";
5466 \endcode
5467
5468 Note that if you say
5469
5470 \code
5471 QString name = getName();
5472 if ( name )
5473 doSomethingWith(name);
5474 \endcode
5475
5476 It will call "operator const char*()", which is inefficent; you
5477 may wish to define the macro \c QT_NO_ASCII_CAST when writing code
5478 which you wish to remain Unicode-clean.
5479
5480 When you want the above semantics, use:
5481
5482 \code
5483 QString name = getName();
5484 if ( !name.isNull() )
5485 doSomethingWith(name);
5486 \endcode
5487
5488 \sa isEmpty()
5489 */
5490
5491
5492 /*!
5493 \fn QString& QString::append( const QString& str )
5494
5495 Appends \a str to the string and returns a reference to the
5496 result.
5497
5498 \code
5499 string = "Test";
5500 string.append( "ing" ); // string == "Testing"
5501 \endcode
5502
5503 Equivalent to operator+=().
5504 */
5505
5506 /*!
5507 \fn QString& QString::append( char ch )
5508
5509 \overload
5510
5511 Appends character \a ch to the string and returns a reference to
5512 the result.
5513
5514 Equivalent to operator+=().
5515 */
5516
5517 /*!
5518 \fn QString& QString::append( QChar ch )
5519
5520 \overload
5521
5522 Appends character \a ch to the string and returns a reference to
5523 the result.
5524
5525 Equivalent to operator+=().
5526 */
5527
5528 /*! \fn QString& QString::append( const QByteArray &str )
5529 \overload
5530
5531 Appends \a str to the string and returns a reference to the result.
5532
5533 Equivalent to operator+=().
5534 */
5535
5536 /*! \fn QString& QString::append( const std::string &str )
5537 \overload
5538
5539 Appends \a str to the string and returns a reference to the result.
5540
5541 Equivalent to operator+=().
5542 */
5543
5544 /*! \fn QString& QString::append( const char *str )
5545 \overload
5546
5547 Appends \a str to the string and returns a reference to the result.
5548
5549 Equivalent to operator+=().
5550 */
5551
5552 /*!
5553 Appends \a str to the string and returns a reference to the string.
5554 */
operator +=(const QString & str)5555 QString& QString::operator+=( const QString &str )
5556 {
5557 uint len1 = length();
5558 uint len2 = str.length();
5559 if ( len2 ) {
5560 if ( isEmpty() ) {
5561 operator=( str );
5562 } else {
5563 grow( len1+len2 );
5564 memcpy( d->unicode+len1, str.unicode(), sizeof(QChar)*len2 );
5565 }
5566 } else if ( isNull() && !str.isNull() ) { // ## just for 1.x compat:
5567 *this = fromLatin1( "" );
5568 }
5569 return *this;
5570 }
5571
5572 #ifndef QT_NO_CAST_ASCII
operatorPlusEqHelper(const char * s,uint len2)5573 QString &QString::operatorPlusEqHelper( const char *s, uint len2 )
5574 {
5575 if ( s ) {
5576 #ifndef QT_NO_TEXTCODEC
5577 if ( QTextCodec::codecForCStrings() )
5578 return operator+=( fromAscii( s, len2 ) );
5579 #endif
5580
5581 uint len1 = length();
5582 if ( len2 == UINT_MAX )
5583 len2 = int(strlen( s ));
5584 if ( len2 ) {
5585 grow( len1 + len2 );
5586 QChar* uc = d->unicode + len1;
5587 while ( len2-- )
5588 *uc++ = *s++;
5589 } else if ( isNull() ) { // ## just for 1.x compat:
5590 *this = fromLatin1( "" );
5591 }
5592 }
5593 return *this;
5594 }
5595 #endif
5596
5597 /*!
5598 \overload
5599
5600 Appends \a str to the string and returns a reference to the string.
5601 */
5602 #ifndef QT_NO_CAST_ASCII
operator +=(const char * str)5603 QString& QString::operator+=( const char *str )
5604 {
5605 // ### Qt 4: make this function inline
5606 return operatorPlusEqHelper( str );
5607 }
5608 #endif
5609
5610 /*! \overload
5611
5612 Appends \a c to the string and returns a reference to the string.
5613 */
5614
operator +=(QChar c)5615 QString &QString::operator+=( QChar c )
5616 {
5617 grow( length()+1 );
5618 d->unicode[length()-1] = c;
5619 return *this;
5620 }
5621
5622 /*!
5623 \overload
5624
5625 Appends \a c to the string and returns a reference to the string.
5626 */
5627
operator +=(char c)5628 QString &QString::operator+=( char c )
5629 {
5630 #ifndef QT_NO_TEXTCODEC
5631 if ( QTextCodec::codecForCStrings() )
5632 return operator+=( fromAscii( &c, 1 ) );
5633 #endif
5634 grow( length()+1 );
5635 d->unicode[length()-1] = c;
5636 return *this;
5637 }
5638
5639 /*!
5640 \fn QString &QString::operator+=( const QByteArray &str )
5641 \overload
5642
5643 Appends \a str to the string and returns a reference to the string.
5644 */
5645
5646 /*!
5647 \fn QString &QString::operator+=( const std::string &str )
5648 \overload
5649
5650 Appends \a str to the string and returns a reference to the string.
5651 */
5652
5653 /*!
5654 \fn char QChar::latin1() const
5655
5656 Returns the Latin-1 value of this character, or 0 if it
5657 cannot be represented in Latin-1.
5658 */
5659
5660
5661 /*!
5662 Returns a Latin-1 representation of the string. The
5663 returned value is undefined if the string contains non-Latin-1
5664 characters. If you want to convert strings into formats other than
5665 Unicode, see the QTextCodec classes.
5666
5667 This function is mainly useful for boot-strapping legacy code to
5668 use Unicode.
5669
5670 The result remains valid so long as one unmodified copy of the
5671 source string exists.
5672
5673 \sa fromLatin1(), ascii(), utf8(), local8Bit()
5674 */
latin1() const5675 const char* QString::latin1() const
5676 {
5677 if ( !d->ascii || !d->islatin1 ) {
5678 delete [] d->ascii;
5679 d->ascii = unicodeToLatin1( d->unicode, d->len );
5680 d->islatin1 = TRUE;
5681 }
5682 return d->ascii;
5683 }
5684
5685 /*!
5686 Returns an 8-bit ASCII representation of the string.
5687
5688 If a codec has been set using QTextCodec::codecForCStrings(),
5689 it is used to convert Unicode to 8-bit char. Otherwise, this function
5690 does the same as latin1().
5691
5692 \sa fromAscii(), latin1(), utf8(), local8Bit()
5693 */
ascii() const5694 const char* QString::ascii() const
5695 {
5696 #ifndef QT_NO_TEXTCODEC
5697 if ( QTextCodec::codecForCStrings() ) {
5698 if ( !d->ascii || d->islatin1 ) {
5699 delete [] d->ascii;
5700 if (d->unicode) {
5701 QCString s = QTextCodec::codecForCStrings()->fromUnicode( *this );
5702 d->ascii = new char[s.length() + 1];
5703 memcpy(d->ascii, s.data(), s.length() + 1);
5704 } else {
5705 d->ascii = 0;
5706 }
5707 d->islatin1 = FALSE;
5708 }
5709 return d->ascii;
5710 }
5711 #endif // QT_NO_TEXTCODEC
5712 return latin1();
5713 }
5714
5715 /*!
5716 Returns the string encoded in UTF-8 format.
5717
5718 See QTextCodec for more diverse coding/decoding of Unicode strings.
5719
5720 \sa fromUtf8(), ascii(), latin1(), local8Bit()
5721 */
utf8() const5722 QCString QString::utf8() const
5723 {
5724 int l = length();
5725 int rlen = l*3+1;
5726 QCString rstr(rlen);
5727 uchar* cursor = (uchar*)rstr.data();
5728 const QChar *ch = d->unicode;
5729 for (int i=0; i < l; i++) {
5730 uint u = ch->unicode();
5731 if ( u < 0x80 ) {
5732 *cursor++ = (uchar)u;
5733 } else {
5734 if ( u < 0x0800 ) {
5735 *cursor++ = 0xc0 | ((uchar) (u >> 6));
5736 } else {
5737 if (u >= 0xd800 && u < 0xdc00 && i < l-1) {
5738 unsigned short low = ch[1].unicode();
5739 if (low >= 0xdc00 && low < 0xe000) {
5740 ++ch;
5741 ++i;
5742 u = (u - 0xd800)*0x400 + (low - 0xdc00) + 0x10000;
5743 }
5744 }
5745 if (u > 0xffff) {
5746 // if people are working in utf8, but strings are encoded in eg. latin1, the resulting
5747 // name might be invalid utf8. This and the corresponding code in fromUtf8 takes care
5748 // we can handle this without loosing information. This can happen with latin filenames
5749 // and a utf8 locale under Unix.
5750 if (u > 0x10fe00 && u < 0x10ff00) {
5751 *cursor++ = (u - 0x10fe00);
5752 ++ch;
5753 continue;
5754 } else {
5755 *cursor++ = 0xf0 | ((uchar) (u >> 18));
5756 *cursor++ = 0x80 | ( ((uchar) (u >> 12)) & 0x3f);
5757 }
5758 } else {
5759 *cursor++ = 0xe0 | ((uchar) (u >> 12));
5760 }
5761 *cursor++ = 0x80 | ( ((uchar) (u >> 6)) & 0x3f);
5762 }
5763 *cursor++ = 0x80 | ((uchar) (u&0x3f));
5764 }
5765 ++ch;
5766 }
5767 rstr.truncate( cursor - (uchar*)rstr.data() );
5768 return rstr;
5769 }
5770
addOne(QChar * qch,QString & str)5771 static QChar *addOne(QChar *qch, QString &str)
5772 {
5773 long sidx = qch - str.unicode();
5774 str.setLength(str.length()+1);
5775 return (QChar *)str.unicode() + sidx;
5776 }
5777
5778 /*!
5779 Returns the Unicode string decoded from the first \a len
5780 bytes of \a utf8, ignoring the rest of \a utf8. If \a len is
5781 -1 then the length of \a utf8 is used. If \a len is bigger than
5782 the length of \a utf8 then it will use the length of \a utf8.
5783
5784 \code
5785 QString str = QString::fromUtf8( "123456789", 5 );
5786 // str == "12345"
5787 \endcode
5788
5789 See QTextCodec for more diverse coding/decoding of Unicode strings.
5790 */
fromUtf8(const char * utf8,int len)5791 QString QString::fromUtf8( const char* utf8, int len )
5792 {
5793 if ( !utf8 )
5794 return QString::null;
5795
5796 int slen = 0;
5797 if (len >= 0) {
5798 while (slen < len && utf8[slen])
5799 slen++;
5800 } else {
5801 slen = int(strlen(utf8));
5802 }
5803 len = len < 0 ? slen : QMIN(slen, len);
5804 QString result;
5805 result.setLength( len ); // worst case
5806 QChar *qch = (QChar *)result.unicode();
5807 uint uc = 0;
5808 int need = 0;
5809 int error = -1;
5810 uchar ch;
5811 for (int i=0; i<len; i++) {
5812 ch = utf8[i];
5813 if (need) {
5814 if ( (ch&0xc0) == 0x80 ) {
5815 uc = (uc << 6) | (ch & 0x3f);
5816 need--;
5817 if ( !need ) {
5818 if (uc > 0xffff) {
5819 // surrogate pair
5820 uc -= 0x10000;
5821 unsigned short high = uc/0x400 + 0xd800;
5822 unsigned short low = uc%0x400 + 0xdc00;
5823 *qch++ = QChar(high);
5824 *qch++ = QChar(low);
5825 } else {
5826 *qch++ = uc;
5827 }
5828 }
5829 } else {
5830 // See QString::utf8() for explanation.
5831 //
5832 // The surrogate below corresponds to a Unicode value of (0x10fe00+ch) which
5833 // is in one of the private use areas of Unicode.
5834 i = error;
5835 qch = addOne(qch, result);
5836 *qch++ = QChar(0xdbff);
5837 *qch++ = QChar(0xde00+((uchar)utf8[i]));
5838 need = 0;
5839 }
5840 } else {
5841 if ( ch < 128 ) {
5842 *qch++ = ch;
5843 } else if ((ch & 0xe0) == 0xc0) {
5844 uc = ch & 0x1f;
5845 need = 1;
5846 error = i;
5847 } else if ((ch & 0xf0) == 0xe0) {
5848 uc = ch & 0x0f;
5849 need = 2;
5850 error = i;
5851 } else if ((ch&0xf8) == 0xf0) {
5852 uc = ch & 0x07;
5853 need = 3;
5854 error = i;
5855 } else {
5856 // Error
5857 qch = addOne(qch, result);
5858 *qch++ = QChar(0xdbff);
5859 *qch++ = QChar(0xde00+((uchar)utf8[i]));
5860 }
5861 }
5862 }
5863 if (need) {
5864 // we have some invalid characters remaining we need to add to the string
5865 for (int i = error; i < len; ++i) {
5866 qch = addOne(qch, result);
5867 *qch++ = QChar(0xdbff);
5868 *qch++ = QChar(0xde00+((uchar)utf8[i]));
5869 }
5870 }
5871
5872 result.truncate( qch - result.unicode() );
5873 return result;
5874 }
5875
5876 /*!
5877 Returns the Unicode string decoded from the first \a len
5878 bytes of \a ascii, ignoring the rest of \a ascii. If \a len
5879 is -1 then the length of \a ascii is used. If \a len is bigger
5880 than the length of \a ascii then it will use the length of \a
5881 ascii.
5882
5883 If a codec has been set using QTextCodec::codecForCStrings(),
5884 it is used to convert the string from 8-bit characters to Unicode.
5885 Otherwise, this function does the same as fromLatin1().
5886
5887 This is the same as the QString(const char*) constructor, but you
5888 can make that constructor invisible if you compile with the define
5889 \c QT_NO_CAST_ASCII, in which case you can explicitly create a
5890 QString from 8-bit ASCII text using this function.
5891
5892 \code
5893 QString str = QString::fromAscii( "123456789", 5 );
5894 // str == "12345"
5895 \endcode
5896 */
fromAscii(const char * ascii,int len)5897 QString QString::fromAscii( const char* ascii, int len )
5898 {
5899 #ifndef QT_NO_TEXTCODEC
5900 if ( QTextCodec::codecForCStrings() ) {
5901 if ( !ascii )
5902 return QString::null;
5903 if ( len < 0 )
5904 len = (int)strlen( ascii );
5905 if ( len == 0 || *ascii == '\0' )
5906 return QString::fromLatin1( "" );
5907 return QTextCodec::codecForCStrings()->toUnicode( ascii, len );
5908 }
5909 #endif
5910 return fromLatin1( ascii, len );
5911 }
5912
5913
5914 /*!
5915 Returns the Unicode string decoded from the first \a len
5916 bytes of \a chars, ignoring the rest of \a chars. If \a len
5917 is -1 then the length of \a chars is used. If \a len is bigger
5918 than the length of \a chars then it will use the length of \a
5919 chars.
5920
5921 \sa fromAscii()
5922 */
fromLatin1(const char * chars,int len)5923 QString QString::fromLatin1( const char* chars, int len )
5924 {
5925 uint l;
5926 QChar *uc;
5927 if ( len < 0 )
5928 len = -1;
5929 uc = internalLatin1ToUnicode( chars, &l, len );
5930 return QString( new QStringData(uc, l, l), TRUE );
5931 }
5932
5933 /*!
5934 \fn const QChar* QString::unicode() const
5935
5936 Returns the Unicode representation of the string. The result
5937 remains valid until the string is modified.
5938 */
5939
5940 /*!
5941 Returns the string encoded in a locale-specific format. On X11,
5942 this is the QTextCodec::codecForLocale(). On Windows, it is a
5943 system-defined encoding. On Mac OS X, this always uses UTF-8 as
5944 the encoding.
5945
5946 See QTextCodec for more diverse coding/decoding of Unicode
5947 strings.
5948
5949 \sa fromLocal8Bit(), ascii(), latin1(), utf8()
5950 */
5951
local8Bit() const5952 QCString QString::local8Bit() const
5953 {
5954 #ifdef QT_NO_TEXTCODEC
5955 return latin1();
5956 #else
5957 #ifdef Q_WS_X11
5958 QTextCodec* codec = QTextCodec::codecForLocale();
5959 return codec
5960 ? codec->fromUnicode(*this)
5961 : QCString(latin1());
5962 #endif
5963 #if defined( Q_WS_MACX )
5964 return utf8();
5965 #endif
5966 #if defined( Q_WS_MAC9 )
5967 return QCString(latin1()); //I'm evil..
5968 #endif
5969 #ifdef Q_WS_WIN
5970 return isNull() ? QCString("") : qt_winQString2MB( *this );
5971 #endif
5972 #ifdef Q_WS_QWS
5973 return utf8(); // ### if there is any 8 bit format supported?
5974 #endif
5975 #endif
5976 }
5977
5978 /*!
5979 Returns the Unicode string decoded from the first \a len
5980 bytes of \a local8Bit, ignoring the rest of \a local8Bit. If
5981 \a len is -1 then the length of \a local8Bit is used. If \a len is
5982 bigger than the length of \a local8Bit then it will use the length
5983 of \a local8Bit.
5984
5985 \code
5986 QString str = QString::fromLocal8Bit( "123456789", 5 );
5987 // str == "12345"
5988 \endcode
5989
5990 \a local8Bit is assumed to be encoded in a locale-specific format.
5991
5992 See QTextCodec for more diverse coding/decoding of Unicode strings.
5993 */
fromLocal8Bit(const char * local8Bit,int len)5994 QString QString::fromLocal8Bit( const char* local8Bit, int len )
5995 {
5996 #ifdef QT_NO_TEXTCODEC
5997 return fromLatin1( local8Bit, len );
5998 #else
5999
6000 if ( !local8Bit )
6001 return QString::null;
6002 #ifdef Q_WS_X11
6003 QTextCodec* codec = QTextCodec::codecForLocale();
6004 if ( len < 0 )
6005 len = strlen( local8Bit );
6006 return codec
6007 ? codec->toUnicode( local8Bit, len )
6008 : fromLatin1( local8Bit, len );
6009 #endif
6010 #if defined( Q_WS_MAC )
6011 return fromUtf8(local8Bit,len);
6012 #endif
6013 // Should this be OS_WIN32?
6014 #ifdef Q_WS_WIN
6015 if ( len >= 0 ) {
6016 QCString s(local8Bit,len+1);
6017 return qt_winMB2QString(s);
6018 }
6019 return qt_winMB2QString( local8Bit );
6020 #endif
6021 #ifdef Q_WS_QWS
6022 return fromUtf8(local8Bit,len);
6023 #endif
6024 #endif // QT_NO_TEXTCODEC
6025 }
6026
6027 /*!
6028 \fn QString::operator const char *() const
6029
6030 Returns ascii(). Be sure to see the warnings documented in the
6031 ascii() function. Note that for new code which you wish to be
6032 strictly Unicode-clean, you can define the macro \c
6033 QT_NO_ASCII_CAST when compiling your code to hide this function so
6034 that automatic casts are not done. This has the added advantage
6035 that you catch the programming error described in operator!().
6036 */
6037
6038 /*!
6039 \fn QString::operator std::string() const
6040
6041 Returns ascii() as a std::string.
6042
6043 \warning The function may cause an application to crash if a static C run-time is in use.
6044 This can happen in Microsoft Visual C++ if Qt is configured as single-threaded. A safe
6045 alternative is to call ascii() directly and construct a std::string manually.
6046 */
6047
6048 /*!
6049 Returns the QString as a zero terminated array of unsigned shorts
6050 if the string is not null; otherwise returns zero.
6051
6052 The result remains valid so long as one unmodified
6053 copy of the source string exists.
6054 */
ucs2() const6055 const unsigned short *QString::ucs2() const
6056 {
6057 if ( ! d->unicode )
6058 return 0;
6059 unsigned int len = d->len;
6060 if ( d->maxl < len + 1 ) {
6061 // detach, grow or shrink
6062 uint newMax = computeNewMax( len + 1 );
6063 QChar* nd = QT_ALLOC_QCHAR_VEC( newMax );
6064 if ( nd ) {
6065 if ( d->unicode )
6066 memcpy( nd, d->unicode, sizeof(QChar)*len );
6067 ((QString *)this)->deref();
6068 ((QString *)this)->d = new QStringData( nd, len, newMax );
6069 }
6070 }
6071 d->unicode[len] = 0;
6072 return (unsigned short *) d->unicode;
6073 }
6074
6075 /*!
6076 Constructs a string that is a deep copy of \a str, interpreted as a
6077 UCS2 encoded, zero terminated, Unicode string.
6078
6079 If \a str is 0, then a null string is created.
6080
6081 \sa isNull()
6082 */
fromUcs2(const unsigned short * str)6083 QString QString::fromUcs2( const unsigned short *str )
6084 {
6085 if ( !str ) {
6086 return QString::null;
6087 } else {
6088 int length = 0;
6089 while ( str[length] != 0 )
6090 length++;
6091 QChar* uc = QT_ALLOC_QCHAR_VEC( length );
6092 memcpy( uc, str, length*sizeof(QChar) );
6093 return QString( new QStringData( uc, length, length ), TRUE );
6094 }
6095 }
6096
6097 /*!
6098 \fn QChar QString::at( uint ) const
6099
6100 Returns the character at index \a i, or 0 if \a i is beyond the
6101 length of the string.
6102
6103 \code
6104 const QString string( "abcdefgh" );
6105 QChar ch = string.at( 4 );
6106 // ch == 'e'
6107 \endcode
6108
6109 If the QString is not const (i.e. const QString) or const& (i.e.
6110 const QString &), then the non-const overload of at() will be used
6111 instead.
6112 */
6113
6114 /*!
6115 \fn QChar QString::constref(uint i) const
6116
6117 Returns the QChar at index \a i by value.
6118
6119 Equivalent to at(\a i).
6120
6121 \sa ref()
6122 */
6123
6124 /*!
6125 \fn QChar& QString::ref(uint i)
6126
6127 Returns the QChar at index \a i by reference, expanding the string
6128 with QChar::null if necessary. The resulting reference can be
6129 assigned to, or otherwise used immediately, but becomes invalid
6130 once furher modifications are made to the string.
6131
6132 \code
6133 QString string("ABCDEF");
6134 QChar ch = string.ref( 3 ); // ch == 'D'
6135 \endcode
6136
6137 \sa constref()
6138 */
6139
6140 /*!
6141 \fn QChar QString::operator[]( int ) const
6142
6143 Returns the character at index \a i, or QChar::null if \a i is
6144 beyond the length of the string.
6145
6146 If the QString is not const (i.e., const QString) or const\&
6147 (i.e., const QString\&), then the non-const overload of operator[]
6148 will be used instead.
6149 */
6150
6151 /*!
6152 \fn QCharRef QString::operator[]( int )
6153
6154 \overload
6155
6156 The function returns a reference to the character at index \a i.
6157 The resulting reference can then be assigned to, or used
6158 immediately, but it will become invalid once further modifications
6159 are made to the original string.
6160
6161 If \a i is beyond the length of the string then the string is
6162 expanded with QChar::nulls, so that the QCharRef references a
6163 valid (null) character in the string.
6164
6165 The QCharRef internal class can be used much like a constant
6166 QChar, but if you assign to it, you change the original string
6167 (which will detach itself because of QString's copy-on-write
6168 semantics). You will get compilation errors if you try to use the
6169 result as anything but a QChar.
6170 */
6171
6172 /*!
6173 \fn QCharRef QString::at( uint i )
6174
6175 \overload
6176
6177 The function returns a reference to the character at index \a i.
6178 The resulting reference can then be assigned to, or used
6179 immediately, but it will become invalid once further modifications
6180 are made to the original string.
6181
6182 If \a i is beyond the length of the string then the string is
6183 expanded with QChar::null.
6184 */
6185
6186 /*
6187 Internal chunk of code to handle the
6188 uncommon cases of at() above.
6189 */
subat(uint i)6190 void QString::subat( uint i )
6191 {
6192 uint olen = d->len;
6193 if ( i >= olen ) {
6194 setLength( i+1 ); // i is index; i+1 is needed length
6195 for ( uint j=olen; j<=i; j++ )
6196 d->unicode[j] = QChar::null;
6197 } else {
6198 // Just be sure to detach
6199 real_detach();
6200 }
6201 }
6202
6203
6204 /*!
6205 Resizes the string to \a len characters and copies \a unicode into
6206 the string. If \a unicode is 0, nothing is copied, but the
6207 string is still resized to \a len. If \a len is zero, then the
6208 string becomes a \link isNull() null\endlink string.
6209
6210 \sa setLatin1(), isNull()
6211 */
6212
setUnicode(const QChar * unicode,uint len)6213 QString& QString::setUnicode( const QChar *unicode, uint len )
6214 {
6215 if ( len == 0 ) { // set to null string
6216 if ( d != shared_null ) { // beware of nullstring being set to nullstring
6217 deref();
6218 d = shared_null ? shared_null : makeSharedNull();
6219 d->ref();
6220 }
6221 } else if ( d->count != 1 || len > d->maxl ||
6222 ( len * 4 < d->maxl && d->maxl > 4 ) ) {
6223 // detach, grown or shrink
6224 uint newMax = computeNewMax( len );
6225 QChar* nd = QT_ALLOC_QCHAR_VEC( newMax );
6226 if ( unicode )
6227 memcpy( nd, unicode, sizeof(QChar)*len );
6228 deref();
6229 d = new QStringData( nd, len, newMax );
6230 } else {
6231 d->len = len;
6232 d->setDirty();
6233 if ( unicode )
6234 memcpy( d->unicode, unicode, sizeof(QChar)*len );
6235 }
6236 return *this;
6237 }
6238
6239 /*!
6240 Resizes the string to \a len characters and copies \a
6241 unicode_as_ushorts into the string (on some X11 client platforms
6242 this will involve a byte-swapping pass).
6243
6244 If \a unicode_as_ushorts is 0, nothing is copied, but the string
6245 is still resized to \a len. If \a len is zero, the string becomes
6246 a \link isNull() null\endlink string.
6247
6248 \sa setLatin1(), isNull()
6249 */
setUnicodeCodes(const ushort * unicode_as_ushorts,uint len)6250 QString& QString::setUnicodeCodes( const ushort* unicode_as_ushorts, uint len )
6251 {
6252 return setUnicode((const QChar*)unicode_as_ushorts, len);
6253 }
6254
6255
6256 /*!
6257 Sets this string to \a str, interpreted as a classic 8-bit ASCII C
6258 string. If \a len is -1 (the default), then it is set to
6259 strlen(str).
6260
6261 If \a str is 0 a null string is created. If \a str is "", an empty
6262 string is created.
6263
6264 \sa isNull(), isEmpty()
6265 */
6266
setAscii(const char * str,int len)6267 QString &QString::setAscii( const char *str, int len )
6268 {
6269 #ifndef QT_NO_TEXTCODEC
6270 if ( QTextCodec::codecForCStrings() ) {
6271 *this = QString::fromAscii( str, len );
6272 return *this;
6273 }
6274 #endif // QT_NO_TEXTCODEC
6275 return setLatin1( str, len );
6276 }
6277
6278 /*!
6279 Sets this string to \a str, interpreted as a classic Latin-1 C
6280 string. If \a len is -1 (the default), then it is set to
6281 strlen(str).
6282
6283 If \a str is 0 a null string is created. If \a str is "", an empty
6284 string is created.
6285
6286 \sa isNull(), isEmpty()
6287 */
6288
setLatin1(const char * str,int len)6289 QString &QString::setLatin1( const char *str, int len )
6290 {
6291 if ( str == 0 )
6292 return setUnicode(0,0);
6293 if ( len < 0 )
6294 len = int(strlen( str ));
6295 if ( len == 0 ) { // won't make a null string
6296 *this = QString::fromLatin1( "" );
6297 } else {
6298 setUnicode( 0, len ); // resize but not copy
6299 QChar *p = d->unicode;
6300 while ( len-- )
6301 *p++ = *str++;
6302 }
6303 return *this;
6304 }
6305
6306 /*! \internal
6307 */
checkSimpleText() const6308 void QString::checkSimpleText() const
6309 {
6310 QChar *p = d->unicode;
6311 QChar *end = p + d->len;
6312 while ( p < end ) {
6313 ushort uc = p->unicode();
6314 // sort out regions of complex text formatting
6315 if ( uc > 0x058f && ( uc < 0x1100 || uc > 0xfb0f ) ) {
6316 d->issimpletext = FALSE;
6317 return;
6318 }
6319 p++;
6320 }
6321 d->issimpletext = TRUE;
6322 }
6323
6324 /*! \fn bool QString::simpleText() const
6325 \internal
6326 */
6327
6328 /*! \internal
6329 */
isRightToLeft() const6330 bool QString::isRightToLeft() const
6331 {
6332 int len = length();
6333 QChar *p = d->unicode;
6334 while ( len-- ) {
6335 switch( ::direction( *p ) )
6336 {
6337 case QChar::DirL:
6338 case QChar::DirLRO:
6339 case QChar::DirLRE:
6340 return FALSE;
6341 case QChar::DirR:
6342 case QChar::DirAL:
6343 case QChar::DirRLO:
6344 case QChar::DirRLE:
6345 return TRUE;
6346 default:
6347 break;
6348 }
6349 ++p;
6350 }
6351 return FALSE;
6352 }
6353
6354
6355 /*!
6356 \fn int QString::compare( const QString & s1, const QString & s2 )
6357
6358 Lexically compares \a s1 with \a s2 and returns an integer less
6359 than, equal to, or greater than zero if \a s1 is less than, equal
6360 to, or greater than \a s2.
6361
6362 The comparison is based exclusively on the numeric Unicode values
6363 of the characters and is very fast, but is not what a human would
6364 expect. Consider sorting user-interface strings with
6365 QString::localeAwareCompare().
6366
6367 \code
6368 int a = QString::compare( "def", "abc" ); // a > 0
6369 int b = QString::compare( "abc", "def" ); // b < 0
6370 int c = QString::compare( "abc", "abc" ); // c == 0
6371 \endcode
6372 */
6373
6374 /*!
6375 \overload
6376
6377 Lexically compares this string with \a s and returns an integer
6378 less than, equal to, or greater than zero if it is less than, equal
6379 to, or greater than \a s.
6380 */
compare(const QString & s) const6381 int QString::compare( const QString& s ) const
6382 {
6383 return ucstrcmp( *this, s );
6384 }
6385
6386 /*!
6387 \fn int QString::localeAwareCompare( const QString & s1, const QString & s2 )
6388
6389 Compares \a s1 with \a s2 and returns an integer less than, equal
6390 to, or greater than zero if \a s1 is less than, equal to, or
6391 greater than \a s2.
6392
6393 The comparison is performed in a locale- and also
6394 platform-dependent manner. Use this function to present sorted
6395 lists of strings to the user.
6396
6397 \sa QString::compare() QTextCodec::locale()
6398 */
6399
6400 /*!
6401 \overload
6402
6403 Compares this string with \a s.
6404 */
6405
6406 #if !defined(CSTR_LESS_THAN)
6407 #define CSTR_LESS_THAN 1
6408 #define CSTR_EQUAL 2
6409 #define CSTR_GREATER_THAN 3
6410 #endif
6411
localeAwareCompare(const QString & s) const6412 int QString::localeAwareCompare( const QString& s ) const
6413 {
6414 // do the right thing for null and empty
6415 if ( isEmpty() || s.isEmpty() )
6416 return compare( s );
6417
6418 #if defined(Q_WS_WIN)
6419 int res;
6420 QT_WA( {
6421 const TCHAR* s1 = (TCHAR*)ucs2();
6422 const TCHAR* s2 = (TCHAR*)s.ucs2();
6423 res = CompareStringW( LOCALE_USER_DEFAULT, 0, s1, length(), s2, s.length() );
6424 } , {
6425 QCString s1 = local8Bit();
6426 QCString s2 = s.local8Bit();
6427 res = CompareStringA( LOCALE_USER_DEFAULT, 0, s1.data(), s1.length(), s2.data(), s2.length() );
6428 } );
6429
6430 switch ( res ) {
6431 case CSTR_LESS_THAN:
6432 return -1;
6433 case CSTR_GREATER_THAN:
6434 return 1;
6435 default:
6436 return 0;
6437 }
6438 #elif defined(Q_WS_MACX)
6439 int delta = 0;
6440 #if !defined(QT_NO_TEXTCODEC)
6441 QTextCodec *codec = QTextCodec::codecForLocale();
6442 if (codec)
6443 delta = strcoll(codec->fromUnicode(*this), codec->fromUnicode(s));
6444 if (delta == 0)
6445 #endif
6446 delta = ucstrcmp(*this, s);
6447 return delta;
6448 #elif defined(Q_WS_X11)
6449 // declared in <string.h>
6450 int delta = strcoll( local8Bit(), s.local8Bit() );
6451 if ( delta == 0 )
6452 delta = ucstrcmp( *this, s );
6453 return delta;
6454 #else
6455 return ucstrcmp( *this, s );
6456 #endif
6457 }
6458
operator ==(const QString & s1,const QString & s2)6459 bool operator==( const QString &s1, const QString &s2 )
6460 {
6461 if ( s1.unicode() == s2.unicode() )
6462 return TRUE;
6463 return (s1.length() == s2.length()) && s1.isNull() == s2.isNull() &&
6464 (memcmp((char*)s1.unicode(),(char*)s2.unicode(),
6465 s1.length()*sizeof(QChar)) == 0 );
6466 }
6467
operator !=(const QString & s1,const QString & s2)6468 bool operator!=( const QString &s1, const QString &s2 )
6469 { return !(s1==s2); }
6470
operator <(const QString & s1,const QString & s2)6471 bool operator<( const QString &s1, const QString &s2 )
6472 { return ucstrcmp(s1,s2) < 0; }
6473
operator <=(const QString & s1,const QString & s2)6474 bool operator<=( const QString &s1, const QString &s2 )
6475 { return ucstrcmp(s1,s2) <= 0; }
6476
operator >(const QString & s1,const QString & s2)6477 bool operator>( const QString &s1, const QString &s2 )
6478 { return ucstrcmp(s1,s2) > 0; }
6479
operator >=(const QString & s1,const QString & s2)6480 bool operator>=( const QString &s1, const QString &s2 )
6481 { return ucstrcmp(s1,s2) >= 0; }
6482
6483
operator ==(const QString & s1,const char * s2)6484 bool operator==( const QString &s1, const char *s2 )
6485 {
6486 if ( !s2 )
6487 return s1.isNull();
6488
6489 int len = s1.length();
6490 const QChar *uc = s1.unicode();
6491 while ( len ) {
6492 if ( !(*s2) || uc->unicode() != (uchar) *s2 )
6493 return FALSE;
6494 ++uc;
6495 ++s2;
6496 --len;
6497 }
6498 return !*s2;
6499 }
6500
operator ==(const char * s1,const QString & s2)6501 bool operator==( const char *s1, const QString &s2 )
6502 { return (s2 == s1); }
6503
operator !=(const QString & s1,const char * s2)6504 bool operator!=( const QString &s1, const char *s2 )
6505 { return !(s1==s2); }
6506
operator !=(const char * s1,const QString & s2)6507 bool operator!=( const char *s1, const QString &s2 )
6508 { return !(s1==s2); }
6509
operator <(const QString & s1,const char * s2)6510 bool operator<( const QString &s1, const char *s2 )
6511 { return ucstrcmp(s1,s2) < 0; }
6512
operator <(const char * s1,const QString & s2)6513 bool operator<( const char *s1, const QString &s2 )
6514 { return ucstrcmp(s1,s2) < 0; }
6515
operator <=(const QString & s1,const char * s2)6516 bool operator<=( const QString &s1, const char *s2 )
6517 { return ucstrcmp(s1,s2) <= 0; }
6518
operator <=(const char * s1,const QString & s2)6519 bool operator<=( const char *s1, const QString &s2 )
6520 { return ucstrcmp(s1,s2) <= 0; }
6521
operator >(const QString & s1,const char * s2)6522 bool operator>( const QString &s1, const char *s2 )
6523 { return ucstrcmp(s1,s2) > 0; }
6524
operator >(const char * s1,const QString & s2)6525 bool operator>( const char *s1, const QString &s2 )
6526 { return ucstrcmp(s1,s2) > 0; }
6527
operator >=(const QString & s1,const char * s2)6528 bool operator>=( const QString &s1, const char *s2 )
6529 { return ucstrcmp(s1,s2) >= 0; }
6530
operator >=(const char * s1,const QString & s2)6531 bool operator>=( const char *s1, const QString &s2 )
6532 { return ucstrcmp(s1,s2) >= 0; }
6533
6534
6535 /*****************************************************************************
6536 Documentation for QString related functions
6537 *****************************************************************************/
6538
6539 /*!
6540 \fn bool operator==( const QString &s1, const QString &s2 )
6541
6542 \relates QString
6543
6544 Returns TRUE if \a s1 is equal to \a s2; otherwise returns FALSE.
6545 Note that a null string is not equal to a not-null empty string.
6546
6547 Equivalent to compare(\a s1, \a s2) == 0.
6548
6549 \sa isNull(), isEmpty()
6550 */
6551
6552 /*!
6553 \fn bool operator==( const QString &s1, const char *s2 )
6554
6555 \overload
6556 \relates QString
6557
6558 Returns TRUE if \a s1 is equal to \a s2; otherwise returns FALSE.
6559 Note that a null string is not equal to a not-null empty string.
6560
6561 Equivalent to compare(\a s1, \a s2) == 0.
6562
6563 \sa isNull(), isEmpty()
6564 */
6565
6566 /*!
6567 \fn bool operator==( const char *s1, const QString &s2 )
6568
6569 \overload
6570 \relates QString
6571
6572 Returns TRUE if \a s1 is equal to \a s2; otherwise returns FALSE.
6573 Note that a null string is not equal to a not-null empty string.
6574
6575 Equivalent to compare(\a s1, \a s2) == 0.
6576
6577 \sa isNull(), isEmpty()
6578 */
6579
6580 /*!
6581 \fn bool operator!=( const QString &s1, const QString &s2 )
6582
6583 \relates QString
6584
6585 Returns TRUE if \a s1 is not equal to \a s2; otherwise returns FALSE.
6586 Note that a null string is not equal to a not-null empty string.
6587
6588 Equivalent to compare(\a s1, \a s2) != 0.
6589
6590 \sa isNull(), isEmpty()
6591 */
6592
6593 /*!
6594 \fn bool operator!=( const QString &s1, const char *s2 )
6595
6596 \overload
6597 \relates QString
6598
6599 Returns TRUE if \a s1 is not equal to \a s2; otherwise returns FALSE.
6600 Note that a null string is not equal to a not-null empty string.
6601
6602 Equivalent to compare(\a s1, \a s2) != 0.
6603
6604 \sa isNull(), isEmpty()
6605 */
6606
6607 /*!
6608 \fn bool operator!=( const char *s1, const QString &s2 )
6609
6610 \overload
6611 \relates QString
6612
6613 Returns TRUE if \a s1 is not equal to \a s2; otherwise returns FALSE.
6614 Note that a null string is not equal to a not-null empty string.
6615
6616 Equivalent to compare(\a s1, \a s2) != 0.
6617
6618 \sa isNull(), isEmpty()
6619 */
6620
6621 /*!
6622 \fn bool operator<( const QString &s1, const char *s2 )
6623
6624 \relates QString
6625
6626 Returns TRUE if \a s1 is lexically less than \a s2; otherwise returns FALSE.
6627 The comparison is case sensitive.
6628
6629 Equivalent to compare(\a s1, \a s2) \< 0.
6630 */
6631
6632 /*!
6633 \fn bool operator<( const char *s1, const QString &s2 )
6634
6635 \overload
6636 \relates QString
6637
6638 Returns TRUE if \a s1 is lexically less than \a s2; otherwise returns FALSE.
6639 The comparison is case sensitive.
6640
6641 Equivalent to compare(\a s1, \a s2) \< 0.
6642 */
6643
6644 /*!
6645 \fn bool operator<=( const QString &s1, const char *s2 )
6646
6647 \relates QString
6648
6649 Returns TRUE if \a s1 is lexically less than or equal to \a s2;
6650 otherwise returns FALSE.
6651 The comparison is case sensitive.
6652 Note that a null string is not equal to a not-null empty string.
6653
6654 Equivalent to compare(\a s1,\a s2) \<= 0.
6655
6656 \sa isNull(), isEmpty()
6657 */
6658
6659 /*!
6660 \fn bool operator<=( const char *s1, const QString &s2 )
6661
6662 \overload
6663 \relates QString
6664
6665 Returns TRUE if \a s1 is lexically less than or equal to \a s2;
6666 otherwise returns FALSE.
6667 The comparison is case sensitive.
6668 Note that a null string is not equal to a not-null empty string.
6669
6670 Equivalent to compare(\a s1, \a s2) \<= 0.
6671
6672 \sa isNull(), isEmpty()
6673 */
6674
6675 /*!
6676 \fn bool operator>( const QString &s1, const char *s2 )
6677
6678 \relates QString
6679
6680 Returns TRUE if \a s1 is lexically greater than \a s2; otherwise
6681 returns FALSE.
6682 The comparison is case sensitive.
6683
6684 Equivalent to compare(\a s1, \a s2) \> 0.
6685 */
6686
6687 /*!
6688 \fn bool operator>( const char *s1, const QString &s2 )
6689
6690 \overload
6691 \relates QString
6692
6693 Returns TRUE if \a s1 is lexically greater than \a s2; otherwise
6694 returns FALSE.
6695 The comparison is case sensitive.
6696
6697 Equivalent to compare(\a s1, \a s2) \> 0.
6698 */
6699
6700 /*!
6701 \fn bool operator>=( const QString &s1, const char *s2 )
6702
6703 \relates QString
6704
6705 Returns TRUE if \a s1 is lexically greater than or equal to \a s2;
6706 otherwise returns FALSE.
6707 The comparison is case sensitive.
6708 Note that a null string is not equal to a not-null empty string.
6709
6710 Equivalent to compare(\a s1, \a s2) \>= 0.
6711
6712 \sa isNull(), isEmpty()
6713 */
6714
6715 /*!
6716 \fn bool operator>=( const char *s1, const QString &s2 )
6717
6718 \overload
6719 \relates QString
6720
6721 Returns TRUE if \a s1 is lexically greater than or equal to \a s2;
6722 otherwise returns FALSE.
6723 The comparison is case sensitive.
6724 Note that a null string is not equal to a not-null empty string.
6725
6726 Equivalent to compare(\a s1, \a s2) \>= 0.
6727
6728 \sa isNull(), isEmpty()
6729 */
6730
6731 /*!
6732 \fn const QString operator+( const QString &s1, const QString &s2 )
6733
6734 \relates QString
6735
6736 Returns a string which is the result of concatenating the string
6737 \a s1 and the string \a s2.
6738
6739 Equivalent to \a {s1}.append(\a s2).
6740 */
6741
6742 /*!
6743 \fn const QString operator+( const QString &s1, const char *s2 )
6744
6745 \overload
6746 \relates QString
6747
6748 Returns a string which is the result of concatenating the string
6749 \a s1 and character \a s2.
6750
6751 Equivalent to \a {s1}.append(\a s2).
6752 */
6753
6754 /*!
6755 \fn const QString operator+( const char *s1, const QString &s2 )
6756
6757 \overload
6758 \relates QString
6759
6760 Returns a string which is the result of concatenating the
6761 character \a s1 and string \a s2.
6762 */
6763
6764 /*!
6765 \fn const QString operator+( const QString &s, char c )
6766
6767 \overload
6768 \relates QString
6769
6770 Returns a string which is the result of concatenating the string
6771 \a s and character \a c.
6772
6773 Equivalent to \a {s}.append(\a c).
6774 */
6775
6776 /*!
6777 \fn const QString operator+( char c, const QString &s )
6778
6779 \overload
6780 \relates QString
6781
6782 Returns a string which is the result of concatenating the
6783 character \a c and string \a s.
6784
6785 Equivalent to \a {s}.prepend(\a c).
6786 */
6787
6788
6789 /*****************************************************************************
6790 QString stream functions
6791 *****************************************************************************/
6792 #ifndef QT_NO_DATASTREAM
6793 /*!
6794 \relates QString
6795
6796 Writes the string \a str to the stream \a s.
6797
6798 See also \link datastreamformat.html Format of the QDataStream operators \endlink
6799 */
6800
operator <<(QDataStream & s,const QString & str)6801 QDataStream &operator<<( QDataStream &s, const QString &str )
6802 {
6803 if ( s.version() == 1 ) {
6804 QCString l( str.latin1() );
6805 s << l;
6806 }
6807 else {
6808 int byteOrder = s.byteOrder();
6809 const QChar* ub = str.unicode();
6810 if ( ub || s.version() < 3 ) {
6811 static const uint auto_size = 1024;
6812 char t[auto_size];
6813 char *b;
6814 if ( str.length()*sizeof(QChar) > auto_size ) {
6815 b = new char[str.length()*sizeof(QChar)];
6816 } else {
6817 b = t;
6818 }
6819 int l = str.length();
6820 char *c=b;
6821 while ( l-- ) {
6822 if ( byteOrder == QDataStream::BigEndian ) {
6823 *c++ = (char)ub->row();
6824 *c++ = (char)ub->cell();
6825 } else {
6826 *c++ = (char)ub->cell();
6827 *c++ = (char)ub->row();
6828 }
6829 ub++;
6830 }
6831 s.writeBytes( b, sizeof(QChar)*str.length() );
6832 if ( str.length()*sizeof(QChar) > auto_size )
6833 delete [] b;
6834 } else {
6835 // write null marker
6836 s << (Q_UINT32)0xffffffff;
6837 }
6838 }
6839 return s;
6840 }
6841
6842 /*!
6843 \relates QString
6844
6845 Reads a string from the stream \a s into string \a str.
6846
6847 See also \link datastreamformat.html Format of the QDataStream operators \endlink
6848 */
6849
operator >>(QDataStream & s,QString & str)6850 QDataStream &operator>>( QDataStream &s, QString &str )
6851 {
6852 #ifdef QT_QSTRING_UCS_4
6853 #if defined(Q_CC_GNU)
6854 #warning "operator>> not working properly"
6855 #endif
6856 #endif
6857 if ( s.version() == 1 ) {
6858 QCString l;
6859 s >> l;
6860 str = QString( l );
6861 }
6862 else {
6863 Q_UINT32 bytes = 0;
6864 s >> bytes; // read size of string
6865 if ( bytes == 0xffffffff ) { // null string
6866 str = QString::null;
6867 } else if ( bytes > 0 ) { // not empty
6868 int byteOrder = s.byteOrder();
6869 str.setLength( bytes/2 );
6870 QChar* ch = str.d->unicode;
6871 static const uint auto_size = 1024;
6872 char t[auto_size];
6873 char *b;
6874 if ( bytes > auto_size ) {
6875 b = new char[bytes];
6876 } else {
6877 b = t;
6878 }
6879 s.readRawBytes( b, bytes );
6880 int bt = bytes/2;
6881 char *oldb = b;
6882 while ( bt-- ) {
6883 if ( byteOrder == QDataStream::BigEndian )
6884 *ch++ = (ushort) (((ushort)b[0])<<8) | (uchar)b[1];
6885 else
6886 *ch++ = (ushort) (((ushort)b[1])<<8) | (uchar)b[0];
6887 b += 2;
6888 }
6889 if ( bytes > auto_size )
6890 delete [] oldb;
6891 } else {
6892 str = "";
6893 }
6894 }
6895 return s;
6896 }
6897 #endif // QT_NO_DATASTREAM
6898
6899 /*****************************************************************************
6900 QConstString member functions
6901 *****************************************************************************/
6902
6903 /*!
6904 \class QConstString qstring.h
6905 \reentrant
6906 \ingroup text
6907 \brief The QConstString class provides string objects using constant Unicode data.
6908
6909 In order to minimize copying, highly optimized applications can
6910 use QConstString to provide a QString-compatible object from
6911 existing Unicode data. It is then the programmer's responsibility
6912 to ensure that the Unicode data exists for the entire lifetime of
6913 the QConstString object.
6914
6915 A QConstString is created with the QConstString constructor. The
6916 string held by the object can be obtained by calling string().
6917 */
6918
6919 /*!
6920 Constructs a QConstString that uses the first \a length Unicode
6921 characters in the array \a unicode. Any attempt to modify copies
6922 of the string will cause it to create a copy of the data, thus it
6923 remains forever unmodified.
6924
6925 The data in \a unicode is not copied. The caller must be able to
6926 guarantee that \a unicode will not be deleted or modified.
6927 */
QConstString(const QChar * unicode,uint length)6928 QConstString::QConstString( const QChar* unicode, uint length ) :
6929 QString( new QStringData( (QChar*)unicode, length, length ), TRUE )
6930 {
6931 }
6932
6933 /*!
6934 Destroys the QConstString, creating a copy of the data if other
6935 strings are still using it.
6936 */
~QConstString()6937 QConstString::~QConstString()
6938 {
6939 if ( d->count > 1 ) {
6940 QChar* cp = QT_ALLOC_QCHAR_VEC( d->len );
6941 memcpy( cp, d->unicode, d->len*sizeof(QChar) );
6942 d->unicode = cp;
6943 } else {
6944 d->unicode = 0;
6945 }
6946
6947 // The original d->unicode is now unlinked.
6948 }
6949
6950 /*!
6951 \fn const QString& QConstString::string() const
6952
6953 Returns a constant string referencing the data passed during
6954 construction.
6955 */
6956
6957 /*!
6958 Returns TRUE if the string starts with \a s; otherwise returns
6959 FALSE.
6960
6961 If \a cs is TRUE (the default), the search is case sensitive;
6962 otherwise the search is case insensitive.
6963
6964 \code
6965 QString str( "Bananas" );
6966 str.startsWith( "Ban" ); // returns TRUE
6967 str.startsWith( "Car" ); // returns FALSE
6968 \endcode
6969
6970 \sa endsWith()
6971 */
startsWith(const QString & s,bool cs) const6972 bool QString::startsWith( const QString& s, bool cs ) const
6973 {
6974 if ( isNull() )
6975 return s.isNull();
6976 if ( s.length() > length() )
6977 return FALSE;
6978 if ( cs ) {
6979 return memcmp((char*)d->unicode, (char*)s.d->unicode, s.length()*sizeof(QChar)) == 0;
6980 } else {
6981 for ( int i = 0; i < (int) s.length(); i++ ) {
6982 if ( ::lower(d->unicode[i]) != ::lower(s.d->unicode[i]) )
6983 return FALSE;
6984 }
6985 }
6986 return TRUE;
6987 }
6988
startsWith(const QString & s) const6989 bool QString::startsWith( const QString& s ) const
6990 {
6991 return startsWith( s, TRUE );
6992 }
6993
6994 /*!
6995 Returns TRUE if the string ends with \a s; otherwise returns
6996 FALSE.
6997
6998 If \a cs is TRUE (the default), the search is case sensitive;
6999 otherwise the search is case insensitive.
7000
7001 \code
7002 QString str( "Bananas" );
7003 str.endsWith( "anas" ); // returns TRUE
7004 str.endsWith( "pple" ); // returns FALSE
7005 \endcode
7006
7007 \sa startsWith()
7008 */
endsWith(const QString & s,bool cs) const7009 bool QString::endsWith( const QString& s, bool cs ) const
7010 {
7011 if ( isNull() )
7012 return s.isNull();
7013 int pos = length() - s.length();
7014 if ( pos < 0 )
7015 return FALSE;
7016 if ( cs ) {
7017 return memcmp((char*)&d->unicode[pos], (char*)s.d->unicode, s.length()*sizeof(QChar)) == 0;
7018 } else {
7019 for ( int i = 0; i < (int) s.length(); i++ ) {
7020 if ( ::lower(d->unicode[pos + i]) != ::lower(s.d->unicode[i]) )
7021 return FALSE;
7022 }
7023 }
7024 return TRUE;
7025 }
7026
endsWith(const QString & s) const7027 bool QString::endsWith( const QString& s ) const
7028 {
7029 return endsWith( s, TRUE );
7030 }
7031
7032 /*! \fn void QString::detach()
7033 If the string does not share its data with another QString instance,
7034 nothing happens; otherwise the function creates a new, unique copy of
7035 this string. This function is called whenever the string is modified. The
7036 implicit sharing mechanism is implemented this way.
7037 */
7038
7039 #if defined(Q_OS_WIN32)
7040
7041 #include <windows.h>
7042
7043 /*!
7044 \obsolete
7045
7046 Returns a static Windows TCHAR* from a QString, adding NUL if \a
7047 addnul is TRUE.
7048
7049 The lifetime of the return value is until the next call to this function,
7050 or until the last copy of str is deleted, whatever comes first.
7051
7052 Use ucs2() instead.
7053 */
qt_winTchar(const QString & str,bool)7054 const void* qt_winTchar(const QString& str, bool)
7055 {
7056 // So that the return value lives long enough.
7057 static QString str_cache;
7058 str_cache = str;
7059 #ifdef UNICODE
7060 return str_cache.ucs2();
7061 #else
7062 return str_cache.latin1();
7063 #endif
7064 }
7065
7066 /*!
7067 Makes a new '\0'-terminated Windows TCHAR* from a QString.
7068 */
qt_winTchar_new(const QString & str)7069 void* qt_winTchar_new(const QString& str)
7070 {
7071 if ( str.isNull() )
7072 return 0;
7073 int l = str.length()+1;
7074 TCHAR *tc = new TCHAR[ l ];
7075 #ifdef UNICODE
7076 memcpy( tc, str.ucs2(), sizeof(TCHAR)*l );
7077 #else
7078 memcpy( tc, str.latin1(), sizeof(TCHAR)*l );
7079 #endif
7080 return tc;
7081 }
7082
7083 /*!
7084 Makes a QString from a Windows TCHAR*.
7085 */
qt_winQString(void * tc)7086 QString qt_winQString(void* tc)
7087 {
7088 #ifdef UNICODE
7089 return QString::fromUcs2( (ushort*)tc );
7090 #else
7091 return QString::fromLatin1( (TCHAR *)tc );
7092 #endif
7093 }
7094
qt_winQString2MB(const QString & s,int uclen)7095 QCString qt_winQString2MB( const QString& s, int uclen )
7096 {
7097 if ( uclen < 0 )
7098 uclen = s.length();
7099 if ( s.isNull() )
7100 return QCString();
7101 if ( uclen == 0 )
7102 return QCString("");
7103 BOOL used_def;
7104 QCString mb(4096);
7105 int len;
7106 while ( !(len=WideCharToMultiByte(CP_ACP, 0, (const WCHAR*)s.unicode(), uclen,
7107 mb.data(), mb.size()-1, 0, &used_def)) )
7108 {
7109 int r = GetLastError();
7110 if ( r == ERROR_INSUFFICIENT_BUFFER ) {
7111 mb.resize(1+WideCharToMultiByte( CP_ACP, 0,
7112 (const WCHAR*)s.unicode(), uclen,
7113 0, 0, 0, &used_def));
7114 // and try again...
7115 } else {
7116 #ifndef QT_NO_DEBUG
7117 // Fail.
7118 qWarning("WideCharToMultiByte cannot convert multibyte text (error %d): %s (UTF8)",
7119 r, s.utf8().data());
7120 #endif
7121 break;
7122 }
7123 }
7124 mb[len]='\0';
7125 return mb;
7126 }
7127
7128 // WATCH OUT: mblen must include the NUL (or just use -1)
qt_winMB2QString(const char * mb,int mblen)7129 QString qt_winMB2QString( const char* mb, int mblen )
7130 {
7131 if ( !mb || !mblen )
7132 return QString::null;
7133 const int wclen_auto = 4096;
7134 WCHAR wc_auto[wclen_auto];
7135 int wclen = wclen_auto;
7136 WCHAR *wc = wc_auto;
7137 int len;
7138 while ( !(len=MultiByteToWideChar( CP_ACP, MB_PRECOMPOSED,
7139 mb, mblen, wc, wclen )) )
7140 {
7141 int r = GetLastError();
7142 if ( r == ERROR_INSUFFICIENT_BUFFER ) {
7143 if ( wc != wc_auto ) {
7144 qWarning("Size changed in MultiByteToWideChar");
7145 break;
7146 } else {
7147 wclen = MultiByteToWideChar( CP_ACP, MB_PRECOMPOSED,
7148 mb, mblen, 0, 0 );
7149 wc = new WCHAR[wclen];
7150 // and try again...
7151 }
7152 } else {
7153 // Fail.
7154 qWarning("MultiByteToWideChar cannot convert multibyte text");
7155 break;
7156 }
7157 }
7158 if ( len <= 0 )
7159 return QString::null;
7160 QString s( (QChar*)wc, len - 1 ); // len - 1: we don't want terminator
7161 if ( wc != wc_auto )
7162 delete [] wc;
7163 return s;
7164 }
7165
7166 #endif // Q_OS_WIN32
7167