QString

NAME

SYNOPSIS

#include <qstring.h>

Public Members

Static Public Members

RELATED FUNCTION DOCUMENTATION

DESCRIPTION

QString uses implicit sharing, which makes it very efficient and easy to use.

In all of the QString methods that take const char * parameters, the const char * is interpreted as a classic C-style '&#92;0'-terminated ASCII string. It is legal for the const char * parameter to be 0. If the const char * is not '&#92;0'-terminated, the results are undefined. Functions that copy classic C strings into a QString will not copy the terminating '&#92;0' character. The QChar array of the QString (as returned by unicode()) is generally not terminated by a '&#92;0'. If you need to pass a QString to a function that requires a C '&#92;0'-terminated string use latin1().

A QString that has not been assigned to anything is null, i.e. both the length and data pointer is 0. A QString that references the empty string ("", a single '&#92;0' char) is empty. Both null and empty QStrings are legal parameters to the methods. Assigning (const char *) 0 to QString gives a null QString. For convenience, QString::null is a null QString. When sorting, empty strings come first, followed by non-empty strings, followed by null strings. We recommend using if ( !str.isNull() ) to check for a non-null string rather than if ( !str ); see operator!() for an explanation.

Note that if you find that you are mixing usage of QCString, QString, and QByteArray, this causes lots of unnecessary copying and might indicate that the true nature of the data you are dealing with is uncertain. If the data is '&#92;0'-terminated 8-bit data, use QCString; if it is unterminated (i.e. contains '&#92;0's) 8-bit data, use QByteArray; if it is text, use QString.

Lists of strings are handled by the QStringList class. You can split a string into a list of strings using QStringList::split(), and join a list of strings into a single string with an optional separator using QStringList::join(). You can obtain a list of strings from a string list that contain a particular substring or that match a particular regex using QStringList::grep().

Note for C programmers

Due to C++'s type system and the fact that QString is implicitly shared, QStrings can be treated like ints or other simple base types. For example:

    QString boolToString( bool b )


    {


        QString result;


        if ( b )


            result = "True";


        else


            result = "False";


        return result;


    }

The variable, result, is an auto variable allocated on the stack. When return is called, because we're returning by value, The copy constructor is called and a copy of the string is returned. (No actual copying takes place thanks to the implicit sharing, see below.)

Throughout Qt's source code you will encounter QString usages like this:

    QString func( const QString& input )


    {


        QString output = input;


        // process output


        return output;


    }

The 'copying' of input to output is almost as fast as copying a pointer because behind the scenes copying is achieved by incrementing a reference count. QString (like all Qt's implicitly shared classes) operates on a copy-on-write basis, only copying if an instance is actually changed.

If you wish to create a deep copy of a QString without losing any Unicode information then you should use QDeepCopy.

See also QChar, QCString, QByteArray, QConstString, Implicitly and Explicitly Shared Classes, Text Related Classes, and Non-GUI Classes.  

Member Type Documentation

QString::SectionFlags

QString::SectionDefault - Empty fields are counted, leading and trailing separators are not included, and the separator is compared case sensitively.

QString::SectionSkipEmpty - Treat empty fields as if they don't exist, i.e. they are not considered as far as start and end are concerned.

QString::SectionIncludeLeadingSep - Include the leading separator (if any) in the result string.

QString::SectionIncludeTrailingSep - Include the trailing separator (if any) in the result string.

QString::SectionCaseInsensitiveSeps - Compare the separator case-insensitively.

Any of the last four values can be OR-ed together to form a flag.

See also section().  

MEMBER FUNCTION DOCUMENTATION

QString::QString ()

See also isNull().  

QString::QString ( QChar ch )

QString::QString ( const QString & s )

QString::QString ( const QByteArray & ba )

QString::QString ( const QChar * unicode, uint length )

If unicode and length are 0, then a null string is created.

If only unicode is 0, the string is empty but has length characters of space preallocated: QString expands automatically anyway, but this may speed up some cases a little. We recommend using the plain constructor and setLength() for this purpose since it will result in more readable code.

See also isNull() and setLength().  

QString::QString ( const char * str )

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

This is a cast constructor, but it is perfectly safe: converting a Latin-1 const char * to QString preserves all the information. You can disable this constructor by defining QT_NO_CAST_ASCII when you compile your applications. You can also make QString objects by using setLatin1(), fromLatin1(), fromLocal8Bit(), and fromUtf8(). Or whatever encoding is appropriate for the 8-bit data you have.

See also isNull() and fromAscii().  

QString::QString ( const std::string & str )

This is the same as fromAscii(str).  

QString::~QString ()

QString & QString::append ( const QString & str )

        string = "Test";


        string.append( "ing" );        // string == "Testing"

Equivalent to operator+=().

Example: dirview/dirview.cpp.  

QString & QString::append ( char ch )

Appends character ch to the string and returns a reference to the result.

Equivalent to operator+=().  

QString & QString::append ( QChar ch )

Appends character ch to the string and returns a reference to the result.

Equivalent to operator+=().  

QString & QString::append ( const QByteArray & str )

Appends str to the string and returns a reference to the result.

Equivalent to operator+=().  

QString & QString::append ( const char * str )

Appends str to the string and returns a reference to the result.

Equivalent to operator+=().  

QString & QString::append ( const std::string & str )

Appends str to the string and returns a reference to the result.

Equivalent to operator+=().  

QString QString::arg ( const QString & a, int fieldWidth = 0 ) const

The fieldWidth value specifies the minimum amount of space that 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:

    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

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 (%1, %2, etc.), a warning message (qWarning()) is output and the result is undefined.

Warning: If any placeholder occurs more than once, the result is undefined.  

QString QString::arg ( long a, int fieldWidth = 0, int base = 10 ) const

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

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

The '%' can be followed by an 'L', in which case the sequence is replaced with a localized representation of a. The conversion uses the default locale. The default locale is determined from the system's locale settings at application startup. It can be changed using QLocale::setDefault(). The 'L' flag is ignored if base is not 10.

        QString str;


        str = QString( "Decimal 63 is %1 in hexadecimal" )


                .arg( 63, 0, 16 );


        // str == "Decimal 63 is 3f in hexadecimal"




        QLocale::setDefault(QLocale::English, QLocale::UnitedStates);


        str = QString( "%1 %L2 %L3" )


                .arg( 12345 )


                .arg( 12345 )


                .arg( 12345, 0, 16 );


        // str == "12345 12,345 3039"

QString QString::arg ( ulong a, int fieldWidth = 0, int base = 10 ) const

a is expressed in base base, which is 10 by default and must be between 2 and 36. If base is 10, the '%L' syntax can be used to produce localized strings.  

QString QString::arg ( Q_LLONG a, int fieldWidth = 0, int base = 10 ) const

a is expressed in base base, which is 10 by default and must be between 2 and 36. If base is 10, the '%L' syntax can be used to produce localized strings.  

QString QString::arg ( Q_ULLONG a, int fieldWidth = 0, int base = 10 ) const

a is expressed in base base, which is 10 by default and must be between 2 and 36. If base is 10, the '%L' syntax can be used to produce localized strings.  

QString QString::arg ( int a, int fieldWidth = 0, int base = 10 ) const

a is expressed in base base, which is 10 by default and must be between 2 and 36. If base is 10, the '%L' syntax can be used to produce localized strings.  

QString QString::arg ( uint a, int fieldWidth = 0, int base = 10 ) const

a is expressed in base base, which is 10 by default and must be between 2 and 36. If base is 10, the '%L' syntax can be used to produce localized strings.  

QString QString::arg ( short a, int fieldWidth = 0, int base = 10 ) const

a