1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt3Support module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "q3cstring.h"

    43 #include "qregexp.h"

    44 #include "qdatastream.h"

    45 

    46 #include <stdio.h>

    47 #include <stdarg.h>

    48 #include <stdlib.h>

    49 #include <ctype.h>

    50 #include <limits.h>

    51 

    52 QT_BEGIN_NAMESPACE

    53 

    54 /*****************************************************************************

    55   Q3CString member functions

    56  *****************************************************************************/

    57 

    58 /*!

    59     \class Q3CString

    60     \reentrant

    61     \brief The Q3CString class provides an abstraction of the classic C

    62     zero-terminated char array (char *).

    63 

    64     \compat

    65 

    66     Q3CString tries to behave like a more convenient \c{const char *}.

    67     The price of doing this is that some algorithms will perform

    68     badly. For example, append() is O(length()) since it scans for a

    69     null terminator. Although you might use Q3CString for text that is

    70     never exposed to the user, for most purposes, and especially for

    71     user-visible text, you should use QString. QString provides

    72     implicit sharing, Unicode and other internationalization support,

    73     and is well optimized.

    74 

    75     Note that for the Q3CString methods that take a \c{const char *}

    76     parameter the \c{const char *} must either be 0 (null) or not-null

    77     and '\0' (NUL byte) terminated; otherwise the results are

    78     undefined.

    79 

    80     A default constructed Q3CString is \e null, i.e. both the length

    81     and the data pointer are 0 and isNull() returns true.

    82     

    83     \note However, if you ask for the data pointer of a null Q3CString

    84     by calling data(), then because the internal representation of the

    85     null Q3CString is shared, it will be detached and replaced with a

    86     non-shared, empty representation, a non-null data pointer will be

    87     returned, and subsequent calls to isNull() will return false. But

    88     if you ask for the data pointer of a null Q3CString by calling

    89     constData(), the shared internal representation is not detached, a

    90     null data pointer is returned, and subsequent calls to isNull()

    91     will continue to return true.

    92 

    93     A Q3CString that references the empty string ("", a single '\0'

    94     char) is \e empty, i.e. isEmpty() returns true.  Both null and

    95     empty Q3CStrings are legal parameters to the methods.  Assigning

    96     \c{const char *} 0 to Q3CString produces a null Q3CString.

    97 

    98     The length() function returns the length of the string; resize()

    99     resizes the string and truncate() truncates the string. A string

   100     can be filled with a character using fill(). Strings can be left

   101     or right padded with characters using leftJustify() and

   102     rightJustify(). Characters, strings and regular expressions can be

   103     searched for using find() and findRev(), and counted using

   104     contains().

   105 

   106     Strings and characters can be inserted with insert() and appended

   107     with append(). A string can be prepended with prepend().

   108     Characters can be removed from the string with remove() and

   109     replaced with replace().

   110 

   111     Portions of a string can be extracted using left(), right() and

   112     mid(). Whitespace can be removed using stripWhiteSpace() and

   113     simplifyWhiteSpace(). Strings can be converted to uppercase or

   114     lowercase with upper() and lower() respectively.

   115 

   116     Strings that contain numbers can be converted to numbers with

   117     toShort(), toInt(), toLong(), toULong(), toFloat() and toDouble().

   118     Numbers can be converted to strings with setNum().

   119 

   120     Many operators are overloaded to work with Q3CStrings. Q3CString

   121     also supports some more obscure functions, e.g. sprintf(),

   122     setStr() and setExpand().

   123 

   124     \sidebar Note on Character Comparisons

   125 

   126     In Q3CString the notion of uppercase and lowercase and of which

   127     character is greater than or less than another character is locale

   128     dependent. This affects functions which support a case insensitive

   129     option or which compare or lowercase or uppercase their arguments.

   130     Case insensitive operations and comparisons will be accurate if

   131     both strings contain only ASCII characters. (If \c $LC_CTYPE is

   132     set, most Unix systems do "the right thing".) Functions that this

   133     affects include contains(), find(), findRev(), \l operator<(), \l

   134     operator<=(), \l operator>(), \l operator>=(), lower() and

   135     upper().

   136 

   137     This issue does not apply to \l{QString}s since they represent

   138     characters using Unicode.

   139     \endsidebar

   140 

   141     Performance note: The Q3CString methods for QRegExp searching are

   142     implemented by converting the Q3CString to a QString and performing

   143     the search on that. This implies a deep copy of the Q3CString data.

   144     If you are going to perform many QRegExp searches on a large

   145     Q3CString, you will get better performance by converting the

   146     Q3CString to a QString yourself, and then searching in the QString.

   147 */

   148 

   149 /*!

   150     \fn Q3CString Q3CString::left(uint len)  const

   151 

   152     \internal

   153 */

   154 

   155 /*!

   156     \fn Q3CString Q3CString::right(uint len) const

   157 

   158     \internal

   159 */

   160 

   161 /*!

   162     \fn Q3CString Q3CString::mid(uint index, uint len) const

   163 

   164     \internal

   165 */

   166 

   167 /*!

   168     \fn Q3CString  Q3CString::lower() const

   169 

   170     Use QByteArray::toLower() instead.

   171 */

   172 

   173 /*!

   174     \fn Q3CString  Q3CString::upper() const

   175 

   176     Use QByteArray::toUpper() instead.

   177 */

   178 

   179 /*!

   180     \fn Q3CString  Q3CString::stripWhiteSpace() const

   181 

   182     Use QByteArray::trimmed() instead.

   183 */

   184 

   185 /*!

   186     \fn Q3CString  Q3CString::simplifyWhiteSpace() const

   187 

   188     Use QByteArray::simplified() instead.

   189 */

   190 

   191 /*!

   192     \fn Q3CString& Q3CString::insert(uint index, const char *c)

   193 

   194     \internal

   195 */

   196 

   197 /*!

   198     \fn Q3CString& Q3CString::insert(uint index, char c)

   199 

   200     \internal

   201 */

   202 

   203 /*!

   204     \fn Q3CString& Q3CString::prepend(const char *c)

   205 

   206     \internal

   207 */

   208 

   209 /*!

   210     \fn Q3CString& Q3CString::remove(uint index, uint len)

   211 

   212     \internal

   213 */

   214 

   215 /*!

   216     \fn Q3CString& Q3CString::replace(uint index, uint len, const char *c)

   217 

   218     \internal

   219 */

   220 

   221 /*!

   222     \fn Q3CString& Q3CString::replace(char c, const Q3CString &after)

   223 

   224     \internal

   225 */

   226 

   227 /*!

   228     \fn Q3CString& Q3CString::replace(char c, const char *after)

   229 

   230     \internal

   231 */

   232 

   233 /*!

   234     \fn Q3CString& Q3CString::replace(const Q3CString &b, const Q3CString &a)

   235 

   236     \internal

   237 */

   238 

   239 /*!

   240     \fn Q3CString& Q3CString::replace(const char *b, const char *a)

   241 

   242     \internal

   243 */

   244 

   245 /*!

   246     \fn Q3CString& Q3CString::replace(char b, char a)

   247 

   248     \internal

   249 */

   250 

   251 /*!

   252     \fn Q3CString::Q3CString()

   253 

   254     Constructs a null string.

   255 

   256     \sa isNull()

   257 */

   258 

   259 /*!

   260     \fn Q3CString::Q3CString(const QByteArray &ba)

   261 

   262     Constructs a copy of \a ba.

   263 */

   264 

   265 /*!

   266     \fn Q3CString::Q3CString(const Q3CString &s)

   267 

   268     Constructs a shallow copy \a s.

   269 */

   270 

   271 /*! \fn Q3CString::Q3CString(int size)

   272     Constructs a string with room for \a size characters, including

   273     the '\0'-terminator. Makes a null string if \a size == 0.

   274 

   275     If \a size \> 0, then the first and last characters in the string

   276     are initialized to '\0'. All other characters are uninitialized.

   277 

   278     \sa resize(), isNull()

   279 */

   280 

   281 /*! \fn Q3CString::Q3CString(const char *str)

   282     Constructs a string that is a deep copy of \a str.

   283 

   284     If \a str is 0 a null string is created.

   285 

   286     \sa isNull()

   287 */

   288 

   289 

   290 /*! \fn Q3CString::Q3CString(const char *str, uint maxsize)

   291 

   292     Constructs a string that is a deep copy of \a str. The copy will

   293     be at most \a maxsize bytes long including the '\0'-terminator.

   294 

   295     Example:

   296     \snippet doc/src/snippets/code/src_qt3support_tools_q3cstring.cpp 0

   297 

   298     If \a str contains a 0 byte within the first \a maxsize bytes, the

   299     resulting Q3CString will be terminated by this 0. If \a str is 0 a

   300     null string is created.

   301 

   302     \sa isNull()

   303 */

   304 

   305 /*!

   306     \fn Q3CString &Q3CString::operator=(const QByteArray &ba)

   307 

   308     Assigns byte array \a ba to this Q3CString.

   309 */

   310 

   311 /*!

   312     \fn Q3CString &Q3CString::operator=(const Q3CString &s)

   313 

   314     Assigns a shallow copy of \a s to this string and returns a

   315     reference to this string.

   316 */

   317 

   318 /*!

   319     \fn Q3CString &Q3CString::operator=(const char *str)

   320     \overload

   321 

   322     Assigns a deep copy of \a str to this string and returns a

   323     reference to this string.

   324 

   325     If \a str is 0 a null string is created.

   326 

   327     \sa isNull()

   328 */

   329 

   330 /*

   331     \fn bool Q3CString::isNull() const

   332 

   333     Returns true if the string is null, i.e. if data() == 0; otherwise

   334     returns false. A null string is also an empty string.

   335 

   336     \note If you ask for the data pointer of a null Q3CString by

   337     calling data(), then because the internal representation of the

   338     null Q3CString is shared, it will be detached and replaced with a

   339     non-shared, empty representation, a non-null data pointer will be

   340     returned, and subsequent calls to isNull() will return false. But

   341     if you ask for the data pointer of a null Q3CString by calling

   342     constData(), the shared internal representation is not detached, a

   343     null data pointer is returned, and subsequent calls to isNull()

   344     will continue to return true.

   345 

   346     Example:

   347     \snippet doc/src/snippets/code/src.qt3support.tools.q3cstring.cpp 1

   348 

   349     \sa isEmpty(), length(), size()

   350 */

   351 

   352 /*

   353     \fn bool Q3CString::isEmpty() const

   354 

   355     Returns true if the string is empty, i.e. if length() == 0;

   356     otherwise returns false. An empty string is not always a null

   357     string.

   358 

   359     See example in isNull().

   360 

   361     \sa isNull(), length(), size()

   362 */

   363 

   364 /*

   365     \fn uint Q3CString::length() const

   366 

   367     Returns the length of the string, excluding the '\0'-terminator.

   368     Equivalent to calling \c strlen(data()).

   369 

   370     Null strings and empty strings have zero length.

   371 

   372     \sa size(), isNull(), isEmpty()

   373 */

   374 

   375 /*

   376     \fn bool Q3CString::truncate(uint pos)

   377 

   378     Truncates the string at position \a pos.

   379 

   380     Equivalent to calling \c resize(pos+1).

   381 

   382     Example:

   383     \snippet doc/src/snippets/code/src.qt3support.tools.q3cstring.cpp 2

   384 

   385     \sa resize()

   386 */

   387 

   388 

   389 

   390 /*!

   391     Implemented as a call to the native vsprintf() (see the manual for

   392     your C library).

   393 

   394     If the string is shorter than 256 characters, this sprintf() calls

   395     resize(256) to decrease the chance of memory corruption. The

   396     string is resized back to its actual length before sprintf()

   397     returns.

   398 

   399     Example:

   400     \snippet doc/src/snippets/code/src_qt3support_tools_q3cstring.cpp 3

   401 

   402     \warning All vsprintf() implementations will write past the end of

   403     the target string (*this) if the \a format specification and

   404     arguments happen to be longer than the target string, and some

   405     will also fail if the target string is longer than some arbitrary

   406     implementation limit.

   407 

   408     Giving user-supplied arguments to sprintf() is risky: Sooner or

   409     later someone will paste a huge line into your application.

   410 */

   411 

   412 Q3CString &Q3CString::sprintf(const char *format, ...)

   413 {

   414     detach();

   415     va_list ap;

   416     va_start(ap, format);

   417     if (size() < 256)

   418         resize(256);                // make string big enough

   419     qvsnprintf(data(), size(), format, ap);

   420     resize(qstrlen(constData()));

   421     va_end(ap);

   422     return *this;

   423 }

   424 

   425 

   426 

   427 /*!

   428     \fn Q3CString Q3CString::copy() const

   429 

   430     Returns a deep copy of this string.

   431 */

   432 

   433 

   434 /*!

   435     Returns a string of length \a width (plus one for the terminating

   436     '\0') that contains this string padded with the \a fill character.

   437 

   438     If the length of the string exceeds \a width and \a truncate is

   439     false (the default), then the returned string is a copy of the

   440     string. If the length of the string exceeds \a width and \a

   441     truncate is true, then the returned string is a left(\a width).

   442 

   443     Example:

   444     \snippet doc/src/snippets/code/src_qt3support_tools_q3cstring.cpp 4

   445 

   446     \sa rightJustify()

   447 */

   448 

   449 Q3CString Q3CString::leftJustify(uint width, char fill, bool truncate) const

   450 {

   451     Q3CString result;

   452     int len = qstrlen(constData());

   453     int padlen = width - len;

   454     if (padlen > 0) {

   455         result.resize(len+padlen);

   456         memcpy(result.data(), constData(), len);

   457         memset(result.data()+len, fill, padlen);

   458     } else {

   459         if (truncate)

   460             result = left(width);

   461         else

   462             result = *this;

   463     }

   464     return result;

   465 }

   466 

   467 /*!

   468     Returns a string of length \a width (plus one for the terminating

   469     '\0') that contains zero or more of the \a fill character followed

   470     by this string.

   471 

   472     If the length of the string exceeds \a width and \a truncate is

   473     false (the default), then the returned string is a copy of the

   474     string. If the length of the string exceeds \a width and \a

   475     truncate is true, then the returned string is a left(\a width).

   476 

   477     Example:

   478     \snippet doc/src/snippets/code/src_qt3support_tools_q3cstring.cpp 5

   479 

   480     \sa leftJustify()

   481 */

   482 

   483 Q3CString Q3CString::rightJustify(uint width, char fill, bool truncate) const

   484 {

   485     Q3CString result;

   486     int len = qstrlen(constData());

   487     int padlen = width - len;

   488     if (padlen > 0) {

   489         result.resize(len+padlen);

   490         memset(result.data(), fill, padlen);

   491         memcpy(result.data()+padlen, constData(), len);

   492     } else {

   493         if (truncate)

   494             result = left(width);

   495         else

   496             result = *this;

   497     }

   498     return result;

   499 }

   500 

   501 /*!

   502     Returns the string converted to a \c long value.

   503 

   504     If \a ok is not 0: *\a ok is set to false if the string is not a

   505     number, or if it has trailing garbage; otherwise *\a ok is set to

   506     true.

   507 */

   508 

   509 long Q3CString::toLong(bool *ok) const

   510 {

   511     const char *p = constData();

   512     long val=0;

   513     const long max_mult = 214748364;

   514     bool is_ok = false;

   515     int neg = 0;

   516     if (!p)

   517         goto bye;

   518     while (isspace((uchar) *p))                // skip leading space

   519         p++;

   520     if (*p == '-') {

   521         p++;

   522         neg = 1;

   523     } else if (*p == '+') {

   524         p++;

   525     }

   526     if (!isdigit((uchar) *p))

   527         goto bye;

   528     while (isdigit((uchar) *p)) {

   529         if (val > max_mult || (val == max_mult && (*p-'0') > 7+neg))

   530             goto bye;

   531         val = 10*val + (*p++ - '0');

   532     }

   533     if (neg)

   534         val = -val;

   535     while (isspace((uchar) *p))                // skip trailing space

   536         p++;

   537     if (*p == '\0')

   538         is_ok = true;

   539 bye:

   540     if (ok)

   541         *ok = is_ok;

   542     return is_ok ? val : 0;

   543 }

   544 

   545 /*!

   546     Returns the string converted to an \c{unsigned long} value.

   547 

   548     If \a ok is not 0: *\a ok is set to false if the string is not a

   549     number, or if it has trailing garbage; otherwise *\a ok is set to

   550     true.

   551 */

   552 

   553 ulong Q3CString::toULong(bool *ok) const

   554 {

   555     const char *p = constData();

   556     ulong val=0;

   557     const ulong max_mult = 429496729;

   558     bool is_ok = false;

   559     if (!p)

   560         goto bye;

   561     while (isspace((uchar) *p))                // skip leading space

   562         p++;

   563     if (*p == '+')

   564         p++;

   565     if (!isdigit((uchar) *p))

   566         goto bye;

   567     while (isdigit((uchar) *p)) {

   568         if (val > max_mult || (val == max_mult && (*p-'0') > 5))

   569             goto bye;

   570         val = 10*val + (*p++ - '0');

   571     }

   572     while (isspace((uchar) *p))                // skip trailing space

   573         p++;

   574     if (*p == '\0')

   575         is_ok = true;

   576 bye:

   577     if (ok)

   578         *ok = is_ok;

   579     return is_ok ? val : 0;

   580 }

   581 

   582 /*!

   583     Returns the string converted to a \c{short} value.

   584 

   585     If \a ok is not 0: *\a ok is set to false if the string is not a

   586     number, is out of range, or if it has trailing garbage; otherwise

   587     *\a ok is set to true.

   588 */

   589 

   590 short Q3CString::toShort(bool *ok) const

   591 {

   592     long v = toLong(ok);

   593     if (ok && *ok && (v < -32768 || v > 32767))

   594         *ok = false;

   595     return (short)v;

   596 }

   597 

   598 /*!

   599     Returns the string converted to an \c{unsigned short} value.

   600 

   601     If \a ok is not 0: *\a ok is set to false if the string is not a

   602     number, is out of range, or if it has trailing garbage; otherwise

   603     *\a ok is set to true.

   604 */

   605 

   606 ushort Q3CString::toUShort(bool *ok) const

   607 {

   608     ulong v = toULong(ok);

   609     if (ok && *ok && (v > 65535))

   610         *ok = false;

   611     return (ushort)v;

   612 }

   613 

   614 

   615 /*!

   616     Returns the string converted to a \c{int} value.

   617 

   618     If \a ok is not 0: *\a ok is set to false if the string is not a

   619     number, or if it has trailing garbage; otherwise *\a ok is set to

   620     true.

   621 */

   622 

   623 int Q3CString::toInt(bool *ok) const

   624 {

   625     return (int)toLong(ok);

   626 }

   627 

   628 /*!

   629     Returns the string converted to an \c{unsigned int} value.

   630 

   631     If \a ok is not 0: *\a ok is set to false if the string is not a

   632     number, or if it has trailing garbage; otherwise *\a ok is set to

   633     true.

   634 */

   635 

   636 uint Q3CString::toUInt(bool *ok) const

   637 {

   638     return (uint)toULong(ok);

   639 }

   640 

   641 /*!

   642     Returns the string converted to a \c{double} value.

   643 

   644     If \a ok is not 0: *\a ok is set to false if the string is not a

   645     number, or if it has trailing garbage; otherwise *\a ok is set to

   646     true.

   647 */

   648 

   649 double Q3CString::toDouble(bool *ok) const

   650 {

   651     char *end;

   652     double val = strtod(constData() ? constData() : "", &end);

   653     if (ok)

   654         *ok = (constData() && *constData() && (end == 0 || *end == '\0'));

   655     return val;

   656 }

   657 

   658 /*!

   659     Returns the string converted to a \c{float} value.

   660 

   661     If \a ok is not 0: *\a ok is set to false if the string is not a

   662     number, or if it has trailing garbage; otherwise *\a ok is set to

   663     true.

   664 */

   665 

   666 float Q3CString::toFloat(bool *ok) const

   667 {

   668     return (float)toDouble(ok);

   669 }

   670 

   671 

   672 /*! \fn Q3CString &Q3CString::setStr(const char *str)

   673     Makes a deep copy of \a str. Returns a reference to the string.

   674 */

   675 

   676 /*!

   677     \overload

   678 

   679     Sets the string to the string representation of the number \a n

   680     and returns a reference to the string.

   681 */

   682 

   683 Q3CString &Q3CString::setNum(long n)

   684 {

   685     data();

   686     char buf[20];

   687     register char *p = &buf[19];

   688     bool neg;

   689     if (n < 0) {

   690         neg = true;

   691         n = -n;

   692     } else {

   693         neg = false;

   694     }

   695     *p = '\0';

   696     do {

   697         *--p = ((int)(n%10)) + '0';

   698         n /= 10;

   699     } while (n);

   700     if (neg)

   701         *--p = '-';

   702     *this = p;

   703     return *this;

   704 }

   705 

   706 /*!

   707     \overload

   708 

   709     Sets the string to the string representation of the number \a n

   710     and returns a reference to the string.

   711 */

   712 

   713 Q3CString &Q3CString::setNum(ulong n)

   714 {

   715     data();

   716     char buf[20];

   717     register char *p = &buf[19];

   718     *p = '\0';

   719     do {

   720         *--p = ((int)(n%10)) + '0';

   721         n /= 10;

   722     } while (n);

   723     *this = p;

   724     return *this;

   725 }

   726 

   727 /*!

   728     \fn Q3CString &Q3CString::setNum(int n)

   729     \overload

   730 

   731     Sets the string to the string representation of the number \a n

   732     and returns a reference to the string.

   733 */

   734 

   735 /*!

   736     \fn Q3CString &Q3CString::setNum(uint n)

   737     \overload

   738 

   739     Sets the string to the string representation of the number \a n

   740     and returns a reference to the string.

   741 */

   742 

   743 /*!

   744     \fn Q3CString &Q3CString::setNum(short n)

   745     \overload

   746 

   747     Sets the string to the string representation of the number \a n

   748     and returns a reference to the string.

   749 */

   750 

   751 /*!

   752     \fn Q3CString &Q3CString::setNum(ushort n)

   753     \overload

   754 

   755     Sets the string to the string representation of the number \a n

   756     and returns a reference to the string.

   757 */

   758 

   759 /*!

   760     Sets the string to the string representation of the number \a n

   761     and returns a reference to the string.

   762 

   763     The format of the string representation is specified by the format

   764     character \a f, and the precision (number of digits after the

   765     decimal point) is specified with \a prec.

   766 

   767     The valid formats for \a f are 'e', 'E', 'f', 'g' and 'G'. The

   768     formats are the same as for sprintf(); they are explained in \l

   769     QString::arg().

   770 */

   771 

   772 Q3CString &Q3CString::setNum(double n, char f, int prec)

   773 {

   774 #ifndef QT_NO_DEBUG

   775     if (!(f=='f' || f=='F' || f=='e' || f=='E' || f=='g' || f=='G'))

   776         qWarning("Q3CString::setNum: Invalid format char '%c'", f);

   777 #endif

   778     char format[20];

   779     register char *fs = format;                        // generate format string

   780     *fs++ = '%';                                //   "%.<prec>l<f>"

   781     if (prec > 99)

   782         prec = 99;

   783     *fs++ = '.';

   784     if (prec >= 10) {

   785         *fs++ = prec / 10 + '0';

   786         *fs++ = prec % 10 + '0';

   787     } else {

   788         *fs++ = prec + '0';

   789     }

   790     *fs++ = 'l';

   791     *fs++ = f;

   792     *fs = '\0';

   793     return sprintf(format, n);

   794 }

   795 

   796 /*! \fn Q3CString &Q3CString::setNum(float n, char f, int prec)

   797     \overload

   798 */

   799 

   800 /*!

   801     Sets the character at position \a index to \a c and expands the

   802     string if necessary, padding with spaces.

   803 

   804     Returns false if \a index was out of range and the string could

   805     not be expanded; otherwise returns true.

   806 */

   807 

   808 bool Q3CString::setExpand(uint index, char c)

   809 {

   810     uint oldlen = length();

   811     if (index >= oldlen) {

   812         resize(index+1);

   813         if (index > oldlen)

   814             memset(data() + oldlen, ' ', index - oldlen);

   815     }

   816     *(data() + index) = c;

   817     return true;

   818 }

   819 

   820 

   821 /*

   822     \fn Q3CString::operator const char *() const

   823 

   824     Returns the string data.

   825 */

   826 

   827 

   828 /*!

   829     \fn Q3CString& Q3CString::append(const char *str)

   830 

   831     Appends string \a str to the string and returns a reference to the

   832     string. Equivalent to operator+=().

   833 */

   834 

   835 

   836 

   837 #ifndef QT_NO_DATASTREAM

   838 /*! \fn QDataStream &operator<<(QDataStream &s, const Q3CString &str)

   839     \relates Q3CString

   840 

   841     Writes string \a str to the stream \a s.

   842 

   843     \sa \link datastreamformat.html Format of the QDataStream operators \endlink

   844 */

   845 QDataStream &operator<<(QDataStream &d, const Q3CString &s)

   846 {

   847     if (d.version() >= QDataStream::Qt_4_0)

   848         return operator<<(d, static_cast<const QByteArray &>(s));

   849 

   850     // we need to add a NUL to keep compatibility with Qt 3's QByteArray

   851     QByteArray copy = s;

   852     copy.append('\0');

   853     return operator<<(d, copy);

   854 }

   855 

   856 /*!

   857   \fn QDataStream &operator>>(QDataStream &s, Q3CString &str)

   858     \relates Q3CString

   859 

   860     Reads a string into \a str from the stream \a s.

   861 

   862     \sa \link datastreamformat.html Format of the QDataStream operators \endlink

   863 */

   864 QDataStream &operator>>(QDataStream &d, Q3CString &s) {

   865     operator>>(d, static_cast<QByteArray &>(s));

   866     if (d.version() < QDataStream::Qt_4_0 && s.endsWith('\0'))

   867         s.chop(1);                  // ending NUL

   868     return d;

   869 }

   870 #endif

   871 

   872 /*****************************************************************************

   873   Documentation for related functions

   874  *****************************************************************************/

   875 

   876 /*!

   877     \fn bool operator==(const Q3CString &s1, const Q3CString &s2)

   878 

   879     \relates Q3CString

   880 

   881     Returns true if \a s1 and \a s2 are equal; otherwise returns false.

   882 

   883     Equivalent to qstrcmp(\a s1, \a s2) == 0.

   884 */

   885 

   886 /*!

   887     \fn bool operator==(const Q3CString &s1, const char *s2)

   888     \overload

   889 

   890     \relates Q3CString

   891 

   892     Returns true if \a s1 and \a s2 are equal; otherwise returns false.

   893 

   894     Equivalent to qstrcmp(\a s1, \a s2) == 0.

   895 */

   896 

   897 /*!

   898     \fn bool operator==(const char *s1, const Q3CString &s2)

   899     \overload

   900 

   901     \relates Q3CString

   902 

   903     Returns true if \a s1 and \a s2 are equal; otherwise returns false.

   904 

   905     Equivalent to qstrcmp(\a s1, \a s2) == 0.

   906 */

   907 

   908 /*!

   909     \fn bool operator!=(const Q3CString &s1, const Q3CString &s2)

   910 

   911     \relates Q3CString

   912 

   913     Returns true if \a s1 and \a s2 are different; otherwise returns false.

   914 

   915     Equivalent to qstrcmp(\a s1, \a s2) != 0.

   916 */

   917 

   918 /*!

   919     \fn bool operator!=(const Q3CString &s1, const char *s2)

   920     \overload

   921 

   922     \relates Q3CString

   923 

   924     Returns true if \a s1 and \a s2 are different; otherwise returns false.

   925 

   926     Equivalent to qstrcmp(\a s1, \a s2) != 0.

   927 */

   928 

   929 /*!

   930     \fn bool operator!=(const char *s1, const Q3CString &s2)

   931     \overload

   932 

   933     \relates Q3CString

   934 

   935     Returns true if \a s1 and \a s2 are different; otherwise returns false.

   936 

   937     Equivalent to qstrcmp(\a s1, \a s2) != 0.

   938 */

   939 

   940 /*!

   941     \fn bool operator<(const Q3CString &s1, const char *s2)

   942 

   943     \relates Q3CString

   944 

   945     Returns true if \a s1 is less than \a s2; otherwise returns false.

   946 

   947     Equivalent to qstrcmp(\a s1, \a s2) \< 0.

   948 */

   949 

   950 /*!

   951     \fn bool operator<(const char *s1, const Q3CString &s2)

   952     \overload

   953 

   954     \relates Q3CString

   955 

   956     Returns true if \a s1 is less than \a s2; otherwise returns false.

   957 

   958     Equivalent to qstrcmp(\a s1, \a s2) \< 0.

   959 */

   960 

   961 /*!

   962     \fn bool operator<=(const Q3CString &s1, const char *s2)

   963 

   964     \relates Q3CString

   965 

   966     Returns true if \a s1 is less than or equal to \a s2; otherwise

   967     returns false.

   968 

   969     Equivalent to qstrcmp(\a s1, \a s2) \<= 0.

   970 */

   971 

   972 /*!

   973     \fn bool operator<=(const char *s1, const Q3CString &s2)

   974     \overload

   975 

   976     \relates Q3CString

   977 

   978     Returns true if \a s1 is less than or equal to \a s2; otherwise

   979     returns false.

   980 

   981     Equivalent to qstrcmp(\a s1, \a s2) \<= 0.

   982 */

   983 

   984 /*!

   985     \fn bool operator>(const Q3CString &s1, const char *s2)

   986 

   987     \relates Q3CString

   988 

   989     Returns true if \a s1 is greater than \a s2; otherwise returns false.

   990 

   991     Equivalent to qstrcmp(\a s1, \a s2) \> 0.

   992 */

   993 

   994 /*!

   995     \fn bool operator>(const char *s1, const Q3CString &s2)

   996     \overload

   997 

   998     \relates Q3CString

   999 

  1000     Returns true if \a s1 is greater than \a s2; otherwise returns false.

  1001 

  1002     Equivalent to qstrcmp(\a s1, \a s2) \> 0.

  1003 */

  1004 

  1005 /*!

  1006     \fn bool operator>=(const Q3CString &s1, const char *s2)

  1007 

  1008     \relates Q3CString

  1009 

  1010     Returns true if \a s1 is greater than or equal to \a s2; otherwise

  1011     returns false.

  1012 

  1013     Equivalent to qstrcmp(\a s1, \a s2) \>= 0.

  1014 */

  1015 

  1016 /*!

  1017     \fn bool operator>=(const char *s1, const Q3CString &s2)

  1018     \overload

  1019 

  1020     \relates Q3CString

  1021 

  1022     Returns true if \a s1 is greater than or equal to \a s2; otherwise

  1023     returns false.

  1024 

  1025     Equivalent to qstrcmp(\a s1, \a s2) \>= 0.

  1026 */

  1027 

  1028 /*!

  1029     \fn const Q3CString operator+(const Q3CString &s1, const Q3CString &s2)

  1030 

  1031     \relates Q3CString

  1032 

  1033     Returns a string which consists of the concatenation of \a s1 and

  1034     \a s2.

  1035 */

  1036 

  1037 /*!

  1038     \fn const Q3CString operator+(const Q3CString &s1, const char *s2)

  1039     \overload

  1040 

  1041     \relates Q3CString

  1042 

  1043     Returns a string which consists of the concatenation of \a s1 and \a s2.

  1044 */

  1045 

  1046 /*!

  1047     \fn const Q3CString operator+(const char *s1, const Q3CString &s2)

  1048     \overload

  1049 

  1050     \relates Q3CString

  1051 

  1052     Returns a string which consists of the concatenation of \a s1 and \a s2.

  1053 */

  1054 

  1055 /*!

  1056     \fn const Q3CString operator+(const Q3CString &s, char c)

  1057     \overload

  1058 

  1059     \relates Q3CString

  1060 

  1061     Returns a string which consists of the concatenation of \a s and \a c.

  1062 */

  1063 

  1064 /*!

  1065     \fn const Q3CString operator+(char c, const Q3CString &s)

  1066     \overload

  1067 

  1068     \relates Q3CString

  1069     Returns a string which consists of the concatenation of \a c and \a s.

  1070 */

  1071 

  1072 QT_END_NAMESPACE