qstring.cpp

Trolltech公司发布的图形界面操作系统。可在qt-embedded-2.3.10平台上编译为嵌入式图形界面操作系统。

*/
QString &QString::operator=( const QCString& cstr )
{
    return setAscii( cstr );
}


/*!
    \overload

    Assigns a deep copy of \a str, interpreted as a classic C string
    to this string and returns a reference to this string.

    If \a str is 0, then a null string is created.

    \sa isNull()
*/
QString &QString::operator=( const char *str )
{
    return setAscii(str);
}


/*!
    \fn bool QString::isNull() const

    Returns TRUE if the string is null; otherwise returns FALSE. A
    null string is always empty.

    \code
	QString a;          // a.unicode() == 0, a.length() == 0
	a.isNull();         // TRUE, because a.unicode() == 0
	a.isEmpty();        // TRUE, because a.length() == 0
    \endcode

    \sa isEmpty(), length()
*/

/*!
    \fn bool QString::isEmpty() const

    Returns TRUE if the string is empty, i.e. if length() == 0;
    otherwise returns FALSE. Null strings are also empty.

    \code
	QString a( "" );
	a.isEmpty();        // TRUE
	a.isNull();         // FALSE

	QString b;
	b.isEmpty();        // TRUE
	b.isNull();         // TRUE
    \endcode

    \sa isNull(), length()
*/

/*!
    \fn uint QString::length() const

    Returns the length of the string.

    Null strings and empty strings have zero length.

    \sa isNull(), isEmpty()
*/

/*!
    If \a newLen is less than the length of the string, then the
    string is truncated at position \a newLen. Otherwise nothing
    happens.

    \code
	QString s = "truncate me";
	s.truncate( 5 );            // s == "trunc"
    \endcode

    \sa setLength()
*/

void QString::truncate( uint newLen )
{
    if ( newLen < d->len )
	setLength( newLen );
}

/*!
    Ensures that at least \a newLen characters are allocated to the
    string, and sets the length of the string to \a newLen. Any new
    space allocated contains arbitrary data.

    \sa reserve(), truncate()
*/
void QString::setLength( uint newLen )
{
    if ( d->count != 1 || newLen > d->maxl ||
	 ( newLen * 4 < d->maxl && d->maxl > 4 ) ) {
	// detach, grow or shrink
	uint newMax = computeNewMax( newLen );
	QChar* nd = QT_ALLOC_QCHAR_VEC( newMax );
	if ( nd ) {
	    uint len = QMIN( d->len, newLen );
	    memcpy( nd, d->unicode, sizeof(QChar) * len );
	    deref();
	    d = new QStringData( nd, newLen, newMax );
	}
    } else {
	d->len = newLen;
	d->setDirty();
    }
}

/*!
    \fn uint QString::capacity() const

    Returns the number of characters this string can hold
    in the allocated memory.

    \sa reserve(), squeeze()
*/

/*!
    Ensures that at least \a minCapacity characters are allocated to
    the string.

    This function is useful for code that needs to build up a long
    string and wants to avoid repeated reallocation. In this example,
    we want to add to the string until some condition is true, and
    we're fairly sure that size is big enough:
    \code
	QString result;
	int len = 0;
	result.reserve(maxLen);
	while (...) {
	    result[len++] = ...         // fill part of the space
	}
	result.squeeze();
    \endcode

    If \e maxLen is an underestimate, the worst that will happen is
    that the loop will slow down.

    If it is not possible to allocate enough memory, the string
    remains unchanged.

    \sa capacity(), squeeze(), setLength()
*/

void QString::reserve( uint minCapacity )
{
    if ( d->maxl < minCapacity ) {
	QChar *nd = QT_ALLOC_QCHAR_VEC( minCapacity );
	if ( nd ) {
	    uint len = d->len;
	    if ( len )
		memcpy( nd, d->unicode, sizeof(QChar) * len );
	    deref();
	    d = new QStringData( nd, len, minCapacity );
	}
    }
}


/*!
    Squeezes the string's capacity to the current content.

    \sa capacity(), reserve()
*/
void QString::squeeze()
{
    if ( d->maxl > d->len ) {
	QChar *nd = QT_ALLOC_QCHAR_VEC( d->len );
	if ( nd ) {
	    uint len = d->len;
	    if ( len )
		memcpy( nd, d->unicode, sizeof(QChar) * len );
	    deref();
	    d = new QStringData( nd, len, len );
	}
    }
}

/*!
    \internal

    Like setLength, but doesn't shrink the allocated memory.
*/
void QString::grow( uint newLen )
{
    if ( d->count != 1 || newLen > d->maxl ) {
	setLength( newLen );
    } else {
	d->len = newLen;
	d->setDirty();
    }
}

/*!
    This function will return a string that replaces the lowest
    numbered occurrence of \c %1, \c %2, ..., \c %9 with \a a.

    The \a fieldWidth value specifies the minimum amount of space that
    \a a is padded to. A positive value will produce right-aligned
    text, whereas a negative value will produce left-aligned text.

    The following example shows how we could create a 'status' string
    when processing a list of files:
    \code
    QString status = QString( "Processing file %1 of %2: %3" )
			.arg( i )         // current file's number
			.arg( total )     // number of files to process
			.arg( fileName ); // current file's name
    \endcode

    It is generally fine to use filenames and numbers as we have done
    in the example above. But note that using arg() to construct
    natural language sentences does not usually translate well into
    other languages because sentence structure and word order often
    differ between languages.

    If there is no place marker (\c %1, \c %2, etc.), a warning
    message (qWarning()) is output and the result is undefined.
*/
QString QString::arg( const QString& a, int fieldWidth ) const
{
    QString paddedArg = a;
    if ( fieldWidth != 0 ) {
	int n = QABS( fieldWidth );
	if ( n > (int) a.length() ) {
	    QString padding;
	    while ( n > (int) a.length() ) {
		padding += ' ';
		n--;
	    }
	    if ( fieldWidth < 0 ) {
		paddedArg.append( padding );
	    } else {
		paddedArg.prepend( padding );
	    }
	}
    }

    register const QChar *uc = d->unicode;
    const int len = (int) length();
    const int end = len - 1;
    int numOccurrences = 0;
    int firstDigit = 10;
    int i;

    for ( i = 0; i < end; i++ ) {
	if ( uc[i] == '%' ) {
	    int digit = uc[i + 1].unicode() - '0';
	    if ( digit >= 0 && digit <= firstDigit ) {
		if ( digit < firstDigit ) {
		    firstDigit = digit;
		    numOccurrences = 0;
		}
		numOccurrences++;
	    }
	}
    }

    if ( firstDigit == 10 ) {
	qWarning( "QString::arg(): Argument missing: %s, %s", latin1(),
		  a.latin1() );
	return *this;
    } else {
	QString result;
	i = 0;
	while ( i < len ) {
	    if ( uc[i] == '%' && i != end ) {
		int digit = uc[i + 1].unicode() - '0';
		if ( digit == firstDigit ) {
		    result += paddedArg;
		    i += 2;
#if QT_VERSION >= 0x040000
		    // ### remove preprocessor in Qt 4.0
		    if ( --numOccurrences == 0 )
#endif
		    {
			result += mid( i );
			return result;
		    }
		    continue;
		}
	    }
	    result += uc[i++];
	}
	return result;
    }
}

/*!
    \fn QString QString::arg( const QString& a1, const QString& a2 ) const
    \overload

    This is the same as str.arg(\a a1).arg(\a a2), except that
    the strings are replaced in one pass. This can make a difference
    if \a a1 contains e.g. \c{%1}:

    \code
    QString str( "%1 %2" );
    str.arg( "Hello", "world" );        // returns "Hello world"
    str.arg( "Hello" ).arg( "world" );  // returns "Hello world"

    str.arg( "(%1)", "Hello" );           // returns "(%1) Hello"
    str.arg( "(%1)" ).arg( "Hello" );     // returns "(Hello) %2"
    \endcode
*/

/*!
    \fn QString QString::arg( const QString& a1, const QString& a2,
			      const QString& a3 ) const
    \overload

    This is the same as calling str.arg(\a a1).arg(\a a2).arg(\a a3),
    except that the strings are replaced in one pass.
*/

/*!
    \fn QString QString::arg( const QString& a1, const QString& a2,
			      const QString& a3, const QString& a4 ) const
    \overload

    This is the same as calling
    str.arg(\a a1).arg(\a a2).arg(\a a3).arg(\a a4),
    except that the strings are replaced in one pass.
*/

/*!
    \overload

    The \a fieldWidth value specifies the minimum amount of space that
    \a a is padded to. A positive value will produce a right-aligned
    number, whereas a negative value will produce a left-aligned
    number.

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.

    \code
	QString str;
	str = QString( "Decimal 63 is %1 in hexadecimal" )
		.arg( 63, 0, 16 );
	// str == "Decimal 63 is 3f in hexadecimal"
    \endcode
*/
QString QString::arg( long a, int fieldWidth, int base ) const
{
    return arg( QString::number(a, base), fieldWidth );
}

/*!
    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/
QString QString::arg( ulong a, int fieldWidth, int base ) const
{
    return arg( QString::number(a, base), fieldWidth );
}

/*!
    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/
QString QString::arg( Q_LLONG a, int fieldWidth, int base ) const
{
    return arg( QString::number(a, base), fieldWidth );
}

/*!
    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/
QString QString::arg( Q_ULLONG a, int fieldWidth, int base ) const
{
    return arg( QString::number(a, base), fieldWidth );
}

/*!
    \fn QString QString::arg( int a, int fieldWidth, int base ) const

    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/

/*!
    \fn QString QString::arg( uint a, int fieldWidth, int base ) const

    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/

/*!
    \fn QString QString::arg( short a, int fieldWidth, int base ) const

    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/

/*!
    \fn QString QString::arg( ushort a, int fieldWidth, int base ) const

    \overload

    \a a is expressed in base \a base, which is 10 by default and must
    be between 2 and 36.
*/


/*!
    \overload

    \a a is assumed to be in the Latin-1 character set.
*/
QString QString::arg( char a, int fieldWidth ) const
{
    QString c;
    c += a;
    return arg( c, fieldWidth );
}

/*!
    \overload
*/
QString QString::arg( QChar a, int fieldWidth ) const
{
    QString c;
    c += a;
    return arg( c, fieldWidth );
}

/*!
    \overload

    \target arg-formats

    Argument \a a is formatted according to the \a fmt format specified,
    which is 'g' by default and can be any of the following:

    \table
    \header \i Format \i Meaning
    \row \i \c e \i format as [-]9.9e[+|-]999
    \row \i \c E \i format as [-]9.9E[+|-]999
    \row \i \c f \i format as [-]9.9
    \row \i \c g \i use \c e or \c f format, whichever is the most concise
    \row \i \c G \i use \c E or \c f format, whichever is the most concise
    \endtable

    With 'e', 'E', and 'f', \a prec is the number of digits after the
    decimal point. With 'g' and 'G', \a prec is the maximum number of
    significant digits (trailing zeroes are omitted).

    \code
	double d = 12.34;
	QString ds = QString( "'E' format, precision 3, gives %1" )
			.arg( d, 0, 'E', 3 );
	// ds == "1.234E+001"
    \endcode
*/
QString QString::arg( double a, int fieldWidth, char fmt, int prec ) const
{
    return arg( QString::number( a, fmt, prec ), fieldWidth );
}

QString QString::multiArg( int numArgs, const QString& a1, const QString& a2,
			   const QString& a3, const QString& a4 ) const
{
    QString result;
    union {
	int digitUsed[10];
	int argForDigit[10];
    };
    register const QChar *uc = d->unicode;
    const QString *args[4];
    const int len = (int) length();
    const int end = len - 1;
    int lastDigit = -1;
    int i;

    memset( digitUsed, 0, sizeof(digitUsed) );
    args[0] = &a1;
    args[1] = &a2;
    args[2] = &a3;
    args[3] = &a4;

    for ( i = 0; i < end; i++ ) {
	if ( uc[i] == '%' ) {
	    int digit = uc[i + 1].unicode() - '0';
	    if ( digit >= 0 && digit <= 9 )
		digitUsed[digit]++;
	}
    }

    for ( i = 0; i < numArgs; i++ ) {
	do {
	    ++lastDigit;
	} while ( lastDigit < 10 && digitUsed[lastDigit] == 0 );

	if ( lastDigit == 10 ) {
	    qWarning( "QString::arg(): Argument missing: %s, %s",
		      latin1(), args[i]->latin1() );
	    numArgs = i;
	    lastDigit = 9;
	    break;
	}
	argForDigit[lastDigit] = i;
    }

    i = 0;
    while ( i < len ) {
	if ( uc[i] == '%' && i != end ) {
	    int digit = uc[i + 1].unicode() - '0';