Contents

• Public Types
• Public Functions
• Static Public Members
• Related Non-Members
• Macros
• Detailed Description
• Initializing a String
• Manipulating String Data
• Querying String Data
• Converting Between 8-Bit Strings and Unicode Strings
• Distinction Between Null and Empty Strings
• Argument Formats
• More Efficient String Construction

Detailed Description

TheQString class provides a Unicode character string.

QString stores a string of 16-bitQChars, where eachQChar corresponds one Unicode 4.0 character. (Unicode characters with code values above 65535 are stored using surrogate pairs, i.e., two consecutiveQChars.)

Unicode is an international standard that supports most of the writing systems in use today. It is a superset of US-ASCII (ANSI X3.4-1986) and Latin-1 (ISO 8859-1), and all the US-ASCII/Latin-1 characters are available at the same code positions.

Behind the scenes,QString usesimplicit sharing (copy-on-write) to reduce memory usage and to avoid the needless copying of data. This also helps reduce the inherent overhead of storing 16-bit characters instead of 8-bit characters.

In addition toQString, Qt also provides theQByteArray class to store raw bytes and traditional 8-bit '\0'-terminated strings. For most purposes,QString is the class you want to use. It is used throughout the Qt API, and the Unicode support ensures that your applications will be easy to translate if you want to expand your application's market at some point. The two main cases whereQByteArray is appropriate are when you need to store raw binary data, and when memory conservation is critical (e.g., withQt for Embedded Linux).

Initializing a String

One way to initialize aQString is simply to pass aconst char * to its constructor. For example, the following code creates aQString of size 5 containing the data "Hello":

QString str="Hello";

QString converts theconst char * data into Unicode using thefromAscii() function. By default,fromAscii() treats character above 128 as Latin-1 characters, but this can be changed by callingQTextCodec::setCodecForCStrings().

In all of theQString functions that takeconst char * parameters, theconst char * is interpreted as a classic C-style '\0'-terminated string. It is legal for theconst char * parameter to be 0.

You can also provide string data as an array ofQChars:

staticconstQChar data[4]= {0x0055,0x006e,0x10e3,0x03a3 };QString str(data,4);

QString makes a deep copy of theQChar data, so you can modify it later without experiencing side effects. (If for performance reasons you don't want to take a deep copy of the character data, useQString::fromRawData() instead.)

Another approach is to set the size of the string usingresize() and to initialize the data character per character.QString uses 0-based indexes, just like C++ arrays. To access the character at a particular index position, you can useoperator[](). On non-const strings,operator[]() returns a reference to a character that can be used on the left side of an assignment. For example:

QString str;str.resize(4);str[0]=QChar('U');str[1]=QChar('n');str[2]=QChar(0x10e3);str[3]=QChar(0x03a3);

For read-only access, an alternative syntax is to use theat() function:

QString str;for (int i=0; i< str.size();++i) {if (str.at(i)>=QChar('a')&& str.at(i)<=QChar('f'))qDebug()<<"Found character in range [a-f]";}

Theat() function can be faster thanoperator[](), because it never causes adeep copy to occur. Alternatively, use theleft(),right(), ormid() functions to extract several characters at a time.

AQString can embed '\0' characters (QChar::Null). Thesize() function always returns the size of the whole string, including embedded '\0' characters.

After a call to theresize() function, newly allocated characters have undefined values. To set all the characters in the string to a particular value, use thefill() function.

QString provides dozens of overloads designed to simplify string usage. For example, if you want to compare aQString with a string literal, you can write code like this and it will work as expected:

QString str;if (str=="auto"|| str=="extern"|| str=="static"|| str=="register") {// ...}

You can also pass string literals to functions that take QStrings as arguments, invoking theQString(const char *) constructor. Similarly, you can pass aQString to a function that takes aconst char * argument using theqPrintable() macro which returns the givenQString as aconst char *. This is equivalent to calling <QString>.toLocal8Bit().constData().

Manipulating String Data

QString provides the following basic functions for modifying the character data:append(),prepend(),insert(),replace(), andremove(). For example:

QString str="and";str.prepend("rock ");// str == "rock and"str.append(" roll");// str == "rock and roll"str.replace(5,3,"&");// str == "rock & roll"

If you are building aQString gradually and know in advance approximately how many characters theQString will contain, you can callreserve(), askingQString to preallocate a certain amount of memory. You can also callcapacity() to find out how much memoryQString actually allocated.

Thereplace() andremove() functions' first two arguments are the position from which to start erasing and the number of characters that should be erased. If you want to replace all occurrences of a particular substring with another, use one of the two-parameterreplace() overloads.

A frequent requirement is to remove whitespace characters from a string ('\n', '\t', ' ', etc.). If you want to remove whitespace from both ends of aQString, use thetrimmed() function. If you want to remove whitespace from both ends and replace multiple consecutive whitespaces with a single space character within the string, usesimplified().

If you want to find all occurrences of a particular character or substring in aQString, use theindexOf() orlastIndexOf() functions. The former searches forward starting from a given index position, the latter searches backward. Both return the index position of the character or substring if they find it; otherwise, they return -1. For example, here's a typical loop that finds all occurrences of a particular substring:

QString str="We must be <b>bold</b>, very <b>bold</b>";int j=0;while ((j= str.indexOf("<b>", j))!=-1) {qDebug()<<"Found <b> tag at index position"<< j;++j;}

QString provides many functions for converting numbers into strings and strings into numbers. See thearg() functions, thesetNum() functions, thenumber() static functions, and thetoInt(),toDouble(), and similar functions.

To get an upper- or lowercase version of a string usetoUpper() ortoLower().

Lists of strings are handled by theQStringList class. You can split a string into a list of strings using thesplit() function, and join a list of strings into a single string with an optional separator usingQStringList::join(). You can obtain a list of strings from a string list that contain a particular substring or that match a particularQRegExp using theQStringList::filter() function.

Querying String Data

If you want to see if aQString starts or ends with a particular substring usestartsWith() orendsWith(). If you simply want to check whether aQString contains a particular character or substring, use thecontains() function. If you want to find out how many times a particular character or substring occurs in the string, usecount().

QStrings can be compared using overloaded operators such asoperator<(),operator<=(),operator==(),operator>=(), and so on. Note that the comparison is based exclusively on the numeric Unicode values of the characters. It is very fast, but is not what a human would expect; theQString::localeAwareCompare() function is a better choice for sorting user-interface strings.

To obtain a pointer to the actual character data, calldata() orconstData(). These functions return a pointer to the beginning of theQChar data. The pointer is guaranteed to remain valid until a non-const function is called on theQString.

Converting Between 8-Bit Strings and Unicode Strings

QString provides the following four functions that return aconst char * version of the string asQByteArray:toAscii(),toLatin1(),toUtf8(), andtoLocal8Bit().

• toAscii() returns an 8-bit string encoded using the codec specified byQTextCodec::codecForCStrings (by default, that is Latin 1).
• toLatin1() returns a Latin-1 (ISO 8859-1) encoded 8-bit string.
• toUtf8() returns a UTF-8 encoded 8-bit string. UTF-8 is a superset of US-ASCII (ANSI X3.4-1986) that supports the entire Unicode character set through multibyte sequences.
• toLocal8Bit() returns an 8-bit string using the system's local encoding.

To convert from one of these encodings,QString providesfromAscii(),fromLatin1(),fromUtf8(), andfromLocal8Bit(). Other encodings are supported through theQTextCodec class.

As mentioned above,QString provides a lot of functions and operators that make it easy to interoperate withconst char * strings. But this functionality is a double-edged sword: It makesQString more convenient to use if all strings are US-ASCII or Latin-1, but there is always the risk that an implicit conversion from or toconst char * is done using the wrong 8-bit encoding. To minimize these risks, you can turn off these implicit conversions by defining the following two preprocessor symbols:

• QT_NO_CAST_FROM_ASCII disables automatic conversions from C string literals and pointers to Unicode.
• QT_NO_CAST_TO_ASCII disables automatic conversion fromQString to C strings.

One way to define these preprocessor symbols globally for your application is to add the following entry to yourqmake project file:

DEFINES+= QT_NO_CAST_FROM_ASCII \           QT_NO_CAST_TO_ASCII

You then need to explicitly callfromAscii(),fromLatin1(),fromUtf8(), orfromLocal8Bit() to construct aQString from an 8-bit string, or use the lightweightQLatin1String class, for example:

QString url= QLatin1String("http://www.unicode.org/");

Similarly, you must calltoAscii(),toLatin1(),toUtf8(), ortoLocal8Bit() explicitly to convert theQString to an 8-bit string. (Other encodings are supported through theQTextCodec class.)

QString Widget::boolToString(bool b){QString result;if (b)        result="True";else        result="False";return result;}

Distinction Between Null and Empty Strings

For historical reasons,QString distinguishes between a null string and an empty string. Anull string is a string that is initialized usingQString's default constructor or by passing (const char *)0 to the constructor. Anempty string is any string with size 0. A null string is always empty, but an empty string isn't necessarily null:

QString().isNull();// returns trueQString().isEmpty();// returns trueQString("").isNull();// returns falseQString("").isEmpty();// returns trueQString("abc").isNull();// returns falseQString("abc").isEmpty();// returns false

All functions exceptisNull() treat null strings the same as empty strings. For example,toAscii().constData() returns a pointer to a '\0' character for a null string (not a null pointer), andQString() compares equal toQString(""). We recommend that you always use theisEmpty() function and avoidisNull().

Argument Formats

In member functions where an argumentformat can be specified (e.g.,arg(),number()), the argumentformat can be one of the following:

Aprecision is also specified with the argumentformat. For the 'e', 'E', and 'f' formats, theprecision represents the number of digitsafter the decimal point. For the 'g' and 'G' formats, theprecision represents the maximum number of significant digits (trailing zeroes are omitted).

More Efficient String Construction

Using theQString'+' operator, it is easy to construct a complex string from multiple substrings. You will often write code like this:

QString foo;QString type="long";    foo->setText(QLatin1String("vector<")+ type+ QLatin1String(">::iterator"));if (foo.startsWith("("+ type+") 0x"))...

There is nothing wrong with either of these string constructions, but there are a few hidden inefficiencies. Beginning with Qt 4.6, you can eliminate them.

First, multiple uses of the'+' operator usually means multiple memory allocations. When concatenatingn substrings, wheren > 2, there can be as many asn - 1 calls to the memory allocator.

Second,QLatin1String does not store its length internally but callsqstrlen() when it needs to know its length.

In 4.6, an internal template classQStringBuilder has been added along with a few helper functions. This class is marked internal and does not appear in the documentation, because you aren't meant to instantiate it in your code. Its use will be automatic, as described below. The class is found insrc/corelib/tools/qstringbuilder.cpp if you want to have a look at it.

QStringBuilder uses expression templates and reimplements the'%' operator so that when you use'%' for string concatenation instead of'+', multiple substring concatenations will be postponed until the final result is about to be assigned to aQString. At this point, the amount of memory required for the final result is known. The memory allocator is then calledonce to get the required space, and the substrings are copied into it one by one.

QLatin1Literal is a second internal class that can replaceQLatin1String, which can't be changed for compatibility reasons.QLatin1Literal stores its length, thereby saving time whenQStringBuilder computes the amount of memory required for the final string.

Additional efficiency is gained by inlining and reduced reference counting (theQString created from aQStringBuilder typically has a ref count of 1, whereasQString::append() needs an extra test).

There are three ways you can access this improved method of string construction. The straightforward way is to includeQStringBuilder wherever you want to use it, and use the'%' operator instead of'+' when concatenating strings:

#include <QStringBuilder>QString hello("hello");QStringRef el(&hello,2,3);    QLatin1String world("world");QString message=  hello% el% world%QChar('!');

A more global approach which is the most convenient but not entirely source compatible, is to this define in your .pro file:

    DEFINES*= QT_USE_QSTRINGBUILDER

and the'+' will automatically be performed as theQStringBuilder'%' everywhere.

Member Type Documentation

typedef QString::ConstIterator

Qt-style synonym forQString::const_iterator.

typedef QString::Iterator

Qt-style synonym forQString::iterator.

enum QString::NormalizationForm

This enum describes the various normalized forms of Unicode text.

See alsonormalized() andUnicode Standard Annex #15.

enum QString::SectionFlag
flags QString::SectionFlags

This enum specifies flags that can be used to affect various aspects of thesection() function's behavior with respect to separators and empty fields.

The SectionFlags type is a typedef forQFlags<SectionFlag>. It stores an OR combination of SectionFlag values.

See alsosection().

enum QString::SplitBehavior

This enum specifies how thesplit() function should behave with respect to empty strings.

See alsosplit().

typedef QString::const_iterator

The QString::const_iterator typedef provides an STL-style const iterator forQString.

See alsoQString::iterator.

typedef QString::const_reference

The QString::const_reference typedef provides an STL-style const reference forQString.

This typedef was introduced in Qt 4.8.

typedef QString::iterator

The QString::iterator typedef provides an STL-style non-const iterator forQString.

See alsoQString::const_iterator.

typedef QString::reference

TheQString::const_reference typedef provides an STL-style reference forQString.

This typedef was introduced in Qt 4.8.

typedef QString::value_type

TheQString::const_reference typedef provides an STL-style value type forQString.

This typedef was introduced in Qt 4.8.

Member Function Documentation

QString::QString()

Constructs a null string. Null strings are also empty.

See alsoisEmpty().

QString::QString(constQChar * unicode,int size)

Constructs a string initialized with the firstsize characters of theQChar arrayunicode.

QString makes a deep copy of the string data. The unicode data is copied as is and the Byte Order Mark is preserved if present.

QString::QString(constQChar * unicode)

Constructs a string initialized with the characters of theQChar arrayunicode, which must be terminated with a 0.

QString makes a deep copy of the string data. The unicode data is copied as is and the Byte Order Mark is preserved if present.

This function was introduced in Qt 4.7.

QString::QString(QChar ch)

Constructs a string of size 1 containing the characterch.

QString::QString(int size,QChar ch)

Constructs a string of the givensize with every character set toch.

See alsofill().

QString::QString(constQLatin1String & str)

Constructs a copy of the Latin-1 stringstr.

See alsofromLatin1().

QString::QString(constQString & other)

Constructs a copy ofother.

This operation takesconstant time, becauseQString isimplicitly shared. This makes returning aQString from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takeslinear time.

See alsooperator=().

QString::QString(constchar * str)

Constructs a string initialized with the 8-bit stringstr. The given const char pointer is converted to Unicode using thefromAscii() function.

You can disable this constructor by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

See alsofromAscii(),fromLatin1(),fromLocal8Bit(), andfromUtf8().

QString::QString(constQByteArray & ba)

Constructs a string initialized with the byte arrayba. The given byte array is converted to Unicode usingfromAscii(). Stops copying at the first 0 character, otherwise copies the entire byte array.

You can disable this constructor by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

See alsofromAscii(),fromLatin1(),fromLocal8Bit(), andfromUtf8().

QString::~QString()

Destroys the string.

QString & QString::append(constQString & str)

Appends the stringstr onto the end of this string.

Example:

QString x="free";QString y="dom";x.append(y);// x == "freedom"

This is the same as using theinsert() function:

x.insert(x.size(), y);

The append() function is typically very fast (constant time), becauseQString preallocates extra space at the end of the string data so it can grow without reallocating the entire string each time.

See alsooperator+=(),prepend(), andinsert().

QString & QString::append(constQStringRef & reference)

Appends the given stringreference to this string and returns the result.

This function was introduced in Qt 4.4.

QString & QString::append(constQLatin1String & str)

This function overloadsappend().

Appends the Latin-1 stringstr to this string.

QString & QString::append(constQByteArray & ba)

This function overloadsappend().

Appends the byte arrayba to this string. The given byte array is converted to Unicode using thefromAscii() function.

You can disable this function by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

QString & QString::append(constchar * str)

This function overloadsappend().

Appends the stringstr to this string. The given const char pointer is converted to Unicode using thefromAscii() function.

You can disable this function by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

QString & QString::append(QChar ch)

This function overloadsappend().

Appends the characterch to this string.

QString QString::arg(constQString & a,int fieldWidth = 0, constQChar & fillChar = QLatin1Char( ' ' )) const

Returns a copy of this string with the lowest numbered place marker replaced by stringa, i.e.,%1,%2, ...,%99.

fieldWidth specifies the minimum amount of space that argumenta shall occupy. Ifa requires less space thanfieldWidth, it is padded tofieldWidth with characterfillChar. A positivefieldWidth produces right-aligned text. A negativefieldWidth produces left-aligned text.

This example shows how we might create astatus string for reporting progress while processing a list of files:

QString i;// current file's numberQString total;// number of files to processQString fileName;// current file's nameQString status=QString("Processing file %1 of %2: %3").arg(i).arg(total).arg(fileName);

First,arg(i) replaces%1. Thenarg(total) replaces%2. Finally,arg(fileName) replaces%3.

One advantage of using arg() oversprintf() is that the order of the numbered place markers can change, if the application's strings are translated into other languages, but each arg() will still replace the lowest numbered unreplaced place marker, no matter where it appears. Also, if place marker%i appears more than once in the string, the arg() replaces all of them.

If there is no unreplaced place marker remaining, a warning message is output and the result is undefined. Place marker numbers must be in the range 1 to 99.

QString QString::arg(constQString & a1, constQString & a2) const

This function overloadsarg().

This is the same asstr.arg(a1).arg(a2), except that the stringsa1 anda2 are replaced in one pass. This can make a difference ifa1 contains e.g.%1:

QString str;str="%1 %2";str.arg("%1f","Hello");// returns "%1f Hello"str.arg("%1f").arg("Hello");// returns "Hellof %2"

QString QString::arg(constQString & a1, constQString & a2, constQString & a3) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3), except that the stringsa1,a2 anda3 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4), except that the stringsa1,a2,a3 anda4 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4, constQString & a5) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5), except that the stringsa1,a2,a3,a4, anda5 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4, constQString & a5, constQString & a6) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6)), except that the stringsa1,a2,a3,a4,a5, anda6 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4, constQString & a5, constQString & a6, constQString & a7) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7), except that the stringsa1,a2,a3,a4,a5,a6, anda7 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4, constQString & a5, constQString & a6, constQString & a7, constQString & a8) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8), except that the stringsa1,a2,a3,a4,a5,a6,a7, anda8 are replaced in one pass.

QString QString::arg(constQString & a1, constQString & a2, constQString & a3, constQString & a4, constQString & a5, constQString & a6, constQString & a7, constQString & a8, constQString & a9) const

This function overloadsarg().

This is the same as callingstr.arg(a1).arg(a2).arg(a3).arg(a4).arg(a5).arg(a6).arg(a7).arg(a8).arg(a9), except that the stringsa1,a2,a3,a4,a5,a6,a7,a8, anda9 are replaced in one pass.

QString QString::arg(int a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

Thea argument is expressed in basebase, which is 10 by default and must be between 2 and 36. For bases other than 10,a is treated as an unsigned integer.

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

The '%' can be followed by an 'L', in which case the sequence is replaced with a localized representation ofa. The conversion uses the default locale, set byQLocale::setDefault(). If no default locale was specified, the "C" locale is used. The 'L' flag is ignored ifbase 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(QLocale::English,QLocale::UnitedStates));str=QString("%1 %L2 %L3").arg(12345).arg(12345).arg(12345,0,16);// str == "12345 12,345 3039"

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(uint a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

Thebase argument specifies the base to use when converting the integera into a string. The base must be between 2 and 36.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(long a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thea argument is expressed in the givenbase, 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 ofa. The conversion uses the default locale. The default locale is determined from the system's locale settings at application startup. It can be changed usingQLocale::setDefault(). The 'L' flag is ignored ifbase 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(QLocale::English,QLocale::UnitedStates));str=QString("%1 %L2 %L3").arg(12345).arg(12345).arg(12345,0,16);// str == "12345 12,345 3039"

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(ulong a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thebase argument specifies the base to use when converting the integera to a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(qlonglong a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thebase argument specifies the base to use when converting the integera into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(qulonglong a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thebase argument specifies the base to use when converting the integera into a string.base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(short a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thebase argument specifies the base to use when converting the integera into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(ushort a,int fieldWidth = 0,int base = 10, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

Thebase argument specifies the base to use when converting the integera into a string. The base must be between 2 and 36, with 8 giving octal, 10 decimal, and 16 hexadecimal numbers.

IffillChar is '0' (the number 0, ASCII 48), the locale's zero is used. For negative numbers, zero padding might appear before the minus sign.

QString QString::arg(QChar a,int fieldWidth = 0, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

QString QString::arg(char a,int fieldWidth = 0, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

Thea argument is interpreted as a Latin-1 character.

QString QString::arg(double a,int fieldWidth = 0,char format = 'g',int precision = -1, constQChar & fillChar = QLatin1Char( ' ' )) const

This function overloadsarg().

Argumenta is formatted according to the specifiedformat andprecision. SeeArgument Formats for details.

fieldWidth specifies the minimum amount of space thata is padded to and filled with the characterfillChar. A positive value produces right-aligned text; a negative value produces left-aligned text.

double d=12.34;QString str=QString("delta: %1").arg(d,0,'E',3);// str == "delta: 1.234E+01"

The '%' can be followed by an 'L', in which case the sequence is replaced with a localized representation ofa. The conversion uses the default locale, set by QLocale::setDefaultLocale(). If no default locale was specified, the "C" locale is used.

IffillChar is '0' (the number 0, ASCII 48), this function will use the locale's zero to pad. For negative numbers, the zero padding will probably appear before the minus sign.

See alsoQLocale::toString().

constQChar QString::at(int position) const

Returns the character at the given indexposition in the string.

Theposition must be a valid index position in the string (i.e., 0 <=position <size()).

See alsooperator[]().

iterator QString::begin()

Returns an STL-style iterator pointing to the first character in the string.

See alsoconstBegin() andend().

const_iterator QString::begin() const

This function overloadsbegin().

int QString::capacity() const

Returns the maximum number of characters that can be stored in the string without forcing a reallocation.

The sole purpose of this function is to provide a means of fine tuningQString's memory usage. In general, you will rarely ever need to call this function. If you want to know how many characters are in the string, callsize().

See alsoreserve() andsqueeze().

void QString::chop(int n)

Removesn characters from the end of the string.

Ifn is greater thansize(), the result is an empty string.

Example:

QString str("LOGOUT\r\n");str.chop(2);// str == "LOGOUT"

If you want to remove characters from thebeginning of the string, useremove() instead.

See alsotruncate(),resize(), andremove().

void QString::clear()

Clears the contents of the string and makes it empty.

See alsoresize() andisEmpty().

[static]int QString::compare(constQString & s1, constQString & s2,Qt::CaseSensitivity cs)

Comparess1 withs2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

Ifcs isQt::CaseSensitive, the comparison is case sensitive; otherwise the comparison is case insensitive.

Case sensitive comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. Consider sorting user-visible strings withlocaleAwareCompare().

int x=QString::compare("aUtO","AuTo",Qt::CaseInsensitive);// x == 0int y=QString::compare("auto","Car",Qt::CaseSensitive);// y > 0int z=QString::compare("auto","Car",Qt::CaseInsensitive);// z < 0

This function was introduced in Qt 4.2.

See alsooperator==(),operator<(), andoperator>().

[static]int QString::compare(constQString & s1, constQString & s2)

This function overloadscompare().

Performs a case sensitive compare ofs1 ands2.

[static]int QString::compare(constQString & s1, constQLatin1String & s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadscompare().

Performs a comparison ofs1 ands2, using the case sensitivity settingcs.

This function was introduced in Qt 4.2.

[static]int QString::compare(constQLatin1String & s1, constQString & s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadscompare().

Performs a comparison ofs1 ands2, using the case sensitivity settingcs.

This function was introduced in Qt 4.2.

int QString::compare(constQString & other) const

This function overloadscompare().

Lexically compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than the other string.

Equivalent tocompare(*this, other).

int QString::compare(constQString & other,Qt::CaseSensitivity cs) const

This function overloadscompare().

Same as compare(*this,other,cs).

This function was introduced in Qt 4.2.

int QString::compare(constQLatin1String & other,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscompare().

Same as compare(*this,other,cs).

This function was introduced in Qt 4.2.

int QString::compare(constQStringRef & ref,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscompare().

Compares the string reference,ref, with the string and returns an integer less than, equal to, or greater than zero if the string is less than, equal to, or greater thanref.

[static]int QString::compare(constQString & s1, constQStringRef & s2,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadscompare().

const_iterator QString::constBegin() const

Returns a const STL-style iterator pointing to the first character in the string.

See alsobegin() andconstEnd().

constQChar * QString::constData() const

Returns a pointer to the data stored in theQString. The pointer can be used to access the characters that compose the string. For convenience, the data is '\0'-terminated.

Note that the pointer remains valid only as long as the string is not modified.

See alsodata() andoperator[]().

const_iterator QString::constEnd() const

Returns a const STL-style iterator pointing to the imaginary item after the last item in the list.

See alsoconstBegin() andend().

bool QString::contains(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if this string contains an occurrence of the stringstr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString str="Peter Pan";str.contains("peter",Qt::CaseInsensitive);// returns true

See alsoindexOf() andcount().

bool QString::contains(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if this string contains an occurrence of the string referencestr; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoindexOf() andcount().

bool QString::contains(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscontains().

Returns true if this string contains an occurrence of the characterch; otherwise returns false.

bool QString::contains(constQRegExp & rx) const

This function overloadscontains().

Returns true if the regular expressionrx matches somewhere in this string; otherwise returns false.

bool QString::contains(QRegExp & rx) const

This function overloadscontains().

Returns true if the regular expressionrx matches somewhere in this string; otherwise returns false.

If there is a match, therx regular expression will contain the matched captures (seeQRegExp::matchedLength,QRegExp::cap).

This function was introduced in Qt 4.5.

int QString::count(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the number of (potentially overlapping) occurrences of the stringstr in this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

See alsocontains() andindexOf().

int QString::count(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscount().

Returns the number of occurrences of characterch in the string.

int QString::count(constQStringRef & str,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadscount().

Returns the number of (potentially overlapping) occurrences of the string referencestr in this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsocontains() andindexOf().

int QString::count(constQRegExp & rx) const

This function overloadscount().

Returns the number of times the regular expressionrx matches in the string.

This function counts overlapping matches, so in the example below, there are four instances of "ana" or "ama":

QString str="banana and panama";str.count(QRegExp("a[nm]a"));// returns 4

int QString::count() const

This function overloadscount().

Same assize().

QChar * QString::data()

Returns a pointer to the data stored in theQString. The pointer can be used to access and modify the characters that compose the string. For convenience, the data is '\0'-terminated.

Example:

QString str="Hello world";QChar*data= str.data();while (!data->isNull()) {qDebug()<< data->unicode();++data;}

Note that the pointer remains valid only as long as the string is not modified by other means. For read-only access,constData() is faster because it never causes adeep copy to occur.

See alsoconstData() andoperator[]().

constQChar * QString::data() const

This is an overloaded function.

iterator QString::end()

Returns an STL-style iterator pointing to the imaginary character after the last character in the string.

See alsobegin() andconstEnd().

const_iterator QString::end() const

This function overloadsend().

bool QString::endsWith(constQString & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if the string ends withs; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

QString str="Bananas";str.endsWith("anas");// returns truestr.endsWith("pple");// returns false

See alsostartsWith().

bool QString::endsWith(constQStringRef & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsendsWith().

Returns true if the string ends with the string references; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsostartsWith().

bool QString::endsWith(constQLatin1String & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsendsWith().

bool QString::endsWith(constQChar & c,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if the string ends withc; otherwise returns false.

This function overloadsendsWith().

QString & QString::fill(QChar ch,int size = -1)

Sets every character in the string to characterch. Ifsize is different from -1 (default), the string is resized tosize beforehand.

Example:

QString str="Berlin";str.fill('z');// str == "zzzzzz"str.fill('A',2);// str == "AA"

See alsoresize().

[static]QString QString::fromAscii(constchar * str,int size = -1)

Returns aQString initialized with the firstsize characters from the stringstr.

Ifsize is -1 (default), it is taken to be qstrlen(str).

Note that, despite the name, this function actually uses the codec defined byQTextCodec::setCodecForCStrings() to convertstr to Unicode. Depending on the codec, it may not accept valid US-ASCII (ANSI X3.4-1986) input. If no codec has been set, this function does the same asfromLatin1().

See alsotoAscii(),fromLatin1(),fromUtf8(), andfromLocal8Bit().

[static]QString QString::fromLatin1(constchar * str,int size = -1)

Returns aQString initialized with the firstsize characters of the Latin-1 stringstr.

Ifsize is -1 (default), it is taken to be qstrlen(str).

See alsotoLatin1(),fromAscii(),fromUtf8(), andfromLocal8Bit().

[static]QString QString::fromLocal8Bit(constchar * str,int size = -1)

Returns aQString initialized with the firstsize characters of the 8-bit stringstr.

Ifsize is -1 (default), it is taken to be qstrlen(str).

QTextCodec::codecForLocale() is used to perform the conversion.

See alsotoLocal8Bit(),fromAscii(),fromLatin1(), andfromUtf8().

[static]QString QString::fromRawData(constQChar * unicode,int size)

Constructs aQString that uses the firstsize Unicode characters in the arrayunicode. The data inunicode isnot copied. The caller must be able to guarantee thatunicode will not be deleted or modified as long as theQString (or an unmodified copy of it) exists.

Any attempts to modify theQString or copies of it will cause it to create a deep copy of the data, ensuring that the raw data isn't modified.

Here's an example of how we can use aQRegExp on raw data in memory without requiring to copy the data into aQString:

QRegExp pattern;staticconstQChar unicode[]= {0x005A,0x007F,0x00A4,0x0060,0x1009,0x0020,0x0020};int size=sizeof(unicode)/sizeof(QChar);QString str=QString::fromRawData(unicode, size);if (str.contains(QRegExp(pattern))) {// ...}

Warning: A string created with fromRawData() isnot '\0'-terminated, unless the raw data contains a '\0' character at positionsize. This meansunicode() willnot return a '\0'-terminated string (althoughutf16() does, at the cost of copying the raw data).

See alsofromUtf16() andsetRawData().

[static]QString QString::fromStdString(conststd::string & str)

Returns a copy of thestr string. The given string is converted to Unicode using thefromAscii() function.

This constructor is only available if Qt is configured with STL compatibility enabled.

See alsofromAscii(),fromLatin1(),fromLocal8Bit(), andfromUtf8().

[static]QString QString::fromStdWString(conststd::wstring & str)

Returns a copy of thestr string. The given string is assumed to be encoded in utf16 if the size of wchar_t is 2 bytes (e.g. on windows) and ucs4 if the size of wchar_t is 4 bytes (most Unix systems).

This method is only available if Qt is configured with STL compatibility enabled.

See alsofromUtf16(),fromLatin1(),fromLocal8Bit(),fromUtf8(), andfromUcs4().

[static]QString QString::fromUcs4(constuint * unicode,int size = -1)

Returns aQString initialized with the firstsize characters of the Unicode stringunicode (ISO-10646-UCS-4 encoded).

Ifsize is -1 (default),unicode must be terminated with a 0.

This function was introduced in Qt 4.2.

See alsotoUcs4(),fromUtf16(),utf16(),setUtf16(), andfromWCharArray().

[static]QString QString::fromUtf8(constchar * str,int size = -1)

Returns aQString initialized with the firstsize bytes of the UTF-8 stringstr.

Ifsize is -1 (default), it is taken to be qstrlen(str).

UTF-8 is a Unicode codec and can represent all characters in a Unicode string likeQString. However, invalid sequences are possible with UTF-8 and, if any such are found, they will be replaced with one or more "replacement characters", or suppressed. These include non-Unicode sequences, non-characters, overlong sequences or surrogate codepoints encoded into UTF-8.

Non-characters are codepoints that the Unicode standard reserves and must not be used in text interchange. They are the last two codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF, inclusive.

See alsotoUtf8(),fromAscii(),fromLatin1(), andfromLocal8Bit().

[static]QString QString::fromUtf16(constushort * unicode,int size = -1)

Returns aQString initialized with the firstsize characters of the Unicode stringunicode (ISO-10646-UTF-16 encoded).

Ifsize is -1 (default),unicode must be terminated with a 0.

This function checks for a Byte Order Mark (BOM). If it is missing, host byte order is assumed.

This function is slow compared to the other Unicode conversions. UseQString(constQChar *, int) orQString(constQChar *) if possible.

QString makes a deep copy of the Unicode data.

See alsoutf16() andsetUtf16().

[static]QString QString::fromWCharArray(constwchar_t * string,int size = -1)

Returns a copy of thestring, where the encoding ofstring depends on the size of wchar. If wchar is 4 bytes, thestring is interpreted as ucs-4, if wchar is 2 bytes it is interpreted as ucs-2.

Ifsize is -1 (default), thestring has to be 0 terminated.

This function was introduced in Qt 4.2.

See alsofromUtf16(),fromLatin1(),fromLocal8Bit(),fromUtf8(),fromUcs4(), andfromStdWString().

int QString::indexOf(constQString & str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the first occurrence of the stringstr in this string, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString x="sticky question";QString y="sti";x.indexOf(y);// returns 0x.indexOf(y,1);// returns 10x.indexOf(y,10);// returns 10x.indexOf(y,11);// returns -1

Iffrom is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

See alsolastIndexOf(),contains(), andcount().

int QString::indexOf(constQLatin1String & str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the first occurrence of the stringstr in this string, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString x="sticky question";QString y="sti";x.indexOf(y);// returns 0x.indexOf(y,1);// returns 10x.indexOf(y,10);// returns 10x.indexOf(y,11);// returns -1

Iffrom is -1, the search starts at the last character; if it is -2, at the next to last character and so on.

This function was introduced in Qt 4.5.

See alsolastIndexOf(),contains(), andcount().

int QString::indexOf(QChar ch,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsindexOf().

Returns the index position of the first occurrence of the characterch in the string, searching forward from index positionfrom. Returns -1 ifch could not be found.

int QString::indexOf(constQStringRef & str,int from = 0,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsindexOf().

Returns the index position of the first occurrence of the string referencestr in this string, searching forward from index positionfrom. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

int QString::indexOf(constQRegExp & rx,int from = 0) const

This function overloadsindexOf().

Returns the index position of the first match of the regular expressionrx in the string, searching forward from index positionfrom. Returns -1 ifrx didn't match anywhere.

Example:

QString str="the minimum";str.indexOf(QRegExp("m[aeiou]"),0);// returns 4

int QString::indexOf(QRegExp & rx,int from = 0) const

This function overloadsindexOf().

Returns the index position of the first match of the regular expressionrx in the string, searching forward from index positionfrom. Returns -1 ifrx didn't match anywhere.

If there is a match, therx regular expression will contain the matched captures (seeQRegExp::matchedLength,QRegExp::cap).

Example:

QString str="the minimum";str.indexOf(QRegExp("m[aeiou]"),0);// returns 4

This function was introduced in Qt 4.5.

QString & QString::insert(int position, constQString & str)

Inserts the stringstr at the given indexposition and returns a reference to this string.

Example:

QString str="Meal";str.insert(1,QString("ontr"));// str == "Montreal"

If the givenposition is greater thansize(), the array is first extended usingresize().

See alsoappend(),prepend(),replace(), andremove().

QString & QString::insert(int position, constQLatin1String & str)

This function overloadsinsert().

Inserts the Latin-1 stringstr at the given indexposition.

QString & QString::insert(int position, constQChar * unicode,int size)

This function overloadsinsert().

Inserts the firstsize characters of theQChar arrayunicode at the given indexposition in the string.

QString & QString::insert(int position,QChar ch)

This function overloadsinsert().

Insertsch at the given indexposition in the string.

bool QString::isEmpty() const

Returns true if the string has no characters; otherwise returns false.

Example:

QString().isEmpty();// returns trueQString("").isEmpty();// returns trueQString("x").isEmpty();// returns falseQString("abc").isEmpty();// returns false

See alsosize().

bool QString::isNull() const

Returns true if this string is null; otherwise returns false.

Example:

QString().isNull();// returns trueQString("").isNull();// returns falseQString("abc").isNull();// returns false

Qt makes a distinction between null strings and empty strings for historical reasons. For most applications, what matters is whether or not a string contains any data, and this can be determined using theisEmpty() function.

See alsoisEmpty().

bool QString::isRightToLeft() const

Returns true if the string is read right to left.

int QString::lastIndexOf(constQString & str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the last occurrence of the stringstr in this string, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString x="crazy azimuths";QString y="az";x.lastIndexOf(y);// returns 6x.lastIndexOf(y,6);// returns 6x.lastIndexOf(y,5);// returns 2x.lastIndexOf(y,1);// returns -1

See alsoindexOf(),contains(), andcount().

int QString::lastIndexOf(constQLatin1String & str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the stringstr in this string, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString x="crazy azimuths";QString y="az";x.lastIndexOf(y);// returns 6x.lastIndexOf(y,6);// returns 6x.lastIndexOf(y,5);// returns 2x.lastIndexOf(y,1);// returns -1

This function was introduced in Qt 4.5.

See alsoindexOf(),contains(), andcount().

int QString::lastIndexOf(QChar ch,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the characterch, searching backward from positionfrom.

int QString::lastIndexOf(constQStringRef & str,int from = -1,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadslastIndexOf().

Returns the index position of the last occurrence of the string referencestr in this string, searching backward from index positionfrom. Iffrom is -1 (default), the search starts at the last character; iffrom is -2, at the next to last character and so on. Returns -1 ifstr is not found.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoindexOf(),contains(), andcount().

int QString::lastIndexOf(constQRegExp & rx,int from = -1) const

This function overloadslastIndexOf().

Returns the index position of the last match of the regular expressionrx in the string, searching backward from index positionfrom. Returns -1 ifrx didn't match anywhere.

Example:

QString str="the minimum";str.lastIndexOf(QRegExp("m[aeiou]"));// returns 8

int QString::lastIndexOf(QRegExp & rx,int from = -1) const

This function overloadslastIndexOf().

Returns the index position of the last match of the regular expressionrx in the string, searching backward from index positionfrom. Returns -1 ifrx didn't match anywhere.

If there is a match, therx regular expression will contain the matched captures (seeQRegExp::matchedLength,QRegExp::cap).

Example:

QString str="the minimum";str.lastIndexOf(QRegExp("m[aeiou]"));// returns 8

This function was introduced in Qt 4.5.

QString QString::left(int n) const

Returns a substring that contains then leftmost characters of the string.

The entire string is returned ifn is greater thansize() or less than zero.

QString x="Pineapple";QString y= x.left(4);// y == "Pine"

See alsoright(),mid(), andstartsWith().

QString QString::leftJustified(int width,QChar fill = QLatin1Char( ' ' ),bool truncate = false) const

Returns a string of sizewidth that contains this string padded by thefill character.

Iftruncate is false and thesize() of the string is more thanwidth, then the returned string is a copy of the string.

QString s="apple";QString t= s.leftJustified(8,'.');// t == "apple..."

Iftruncate is true and thesize() of the string is more thanwidth, then any characters in a copy of the string after positionwidth are removed, and the copy is returned.

QString str="Pineapple";str= str.leftJustified(5,'.',true);// str == "Pinea"

See alsorightJustified().

QStringRef QString::leftRef(int n) const

Returns a substring reference to then leftmost characters of the string.

Ifn is greater thansize() or less than zero, a reference to the entire string is returned.

QString x="Pineapple";QStringRef y= x.leftRef(4);// y == "Pine"

This function was introduced in Qt 4.4.

See alsoleft(),rightRef(),midRef(), andstartsWith().

int QString::length() const

Returns the number of characters in this string. Equivalent tosize().

See alsosetLength() andresize().

[static]int QString::localeAwareCompare(constQString & s1, constQString & s2)

Comparess1 withs2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

On Mac OS X since Qt 4.3, this function compares according the "Order for sorted lists" setting in the International prefereces panel.

See alsocompare() andQTextCodec::locale().

int QString::localeAwareCompare(constQStringRef & other) const

This function overloadslocaleAwareCompare().

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

Same aslocaleAwareCompare(*this, other).

This function was introduced in Qt 4.5.

[static]int QString::localeAwareCompare(constQString & s1, constQStringRef & s2)

This function overloadslocaleAwareCompare().

Comparess1 withs2 and returns an integer less than, equal to, or greater than zero ifs1 is less than, equal to, or greater thans2.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

This function was introduced in Qt 4.5.

int QString::localeAwareCompare(constQString & other) const

This function overloadslocaleAwareCompare().

Compares this string with theother string and returns an integer less than, equal to, or greater than zero if this string is less than, equal to, or greater than theother string.

The comparison is performed in a locale- and also platform-dependent manner. Use this function to present sorted lists of strings to the user.

Same aslocaleAwareCompare(*this, other).

QString QString::mid(int position,int n = -1) const

Returns a string that containsn characters of this string, starting at the specifiedposition index.

Returns a null string if theposition index exceeds the length of the string. If there are less thann characters available in the string starting at the givenposition, or ifn is -1 (default), the function returns all characters that are available from the specifiedposition.

Example:

QString x="Nine pineapples";QString y= x.mid(5,4);// y == "pine"QString z= x.mid(5);// z == "pineapples"

See alsoleft() andright().

QStringRef QString::midRef(int position,int n = -1) const

Returns a substring reference ton characters of this string, starting at the specifiedposition.

If theposition exceeds the length of the string, an empty reference is returned.

If there are less thann characters available in the string, starting at the givenposition, or ifn is -1 (default), the function returns all characters from the specifiedposition onwards.

Example:

QString x="Nine pineapples";QStringRef y= x.midRef(5,4);// y == "pine"QStringRef z= x.midRef(5);// z == "pineapples"

This function was introduced in Qt 4.4.

See alsomid(),leftRef(), andrightRef().

QString QString::normalized(NormalizationForm mode) const

Returns the string in the given Unicode normalizationmode.

QString QString::normalized(NormalizationForm mode,QChar::UnicodeVersion version) const

This is an overloaded function.

Returns the string in the given Unicode normalizationmode, according to the givenversion of the Unicode standard.

[static]QString QString::number(long n,int base = 10)

Returns a string equivalent of the numbern according to the specifiedbase.

The base is 10 by default and must be between 2 and 36. For bases other than 10,n is treated as an unsigned integer.

long a=63;QString s=QString::number(a,16);// s == "3f"QString t=QString::number(a,16).toUpper();// t == "3F"

See alsosetNum().

[static]QString QString::number(double n,char format = 'g',int precision = 6)

Returns a string equivalent of the numbern, formatted according to the specifiedformat andprecision. SeeArgument Formats for details.

UnlikeQLocale::toString(), this function does not honor the user's locale settings.

See alsosetNum() andQLocale::toString().

[static]QString QString::number(ulong n,int base = 10)

This is an overloaded function.

[static]QString QString::number(int n,int base = 10)

This is an overloaded function.

[static]QString QString::number(uint n,int base = 10)

This is an overloaded function.

[static]QString QString::number(qlonglong n,int base = 10)

This is an overloaded function.

[static]QString QString::number(qulonglong n,int base = 10)

This is an overloaded function.

QString & QString::prepend(constQString & str)

Prepends the stringstr to the beginning of this string and returns a reference to this string.

Example:

QString x="ship";QString y="air";x.prepend(y);// x == "airship"

See alsoappend() andinsert().

QString & QString::prepend(constQLatin1String & str)

This function overloadsprepend().

Prepends the Latin-1 stringstr to this string.

QString & QString::prepend(constQByteArray & ba)

This function overloadsprepend().

Prepends the byte arrayba to this string. The byte array is converted to Unicode using thefromAscii() function.

You can disable this function by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

QString & QString::prepend(constchar * str)

This function overloadsprepend().

Prepends the stringstr to this string. The const char pointer is converted to Unicode using thefromAscii() function.

You can disable this function by definingQT_NO_CAST_FROM_ASCII when you compile your applications. This can be useful if you want to ensure that all user-visible strings go throughQObject::tr(), for example.

QString & QString::prepend(QChar ch)

This function overloadsprepend().

Prepends the characterch to this string.

void QString::push_back(constQString & other)

This function is provided for STL compatibility, appending the givenother string onto the end of this string. It is equivalent toappend(other).

See alsoappend().

void QString::push_back(QChar ch)

This is an overloaded function.

Appends the givench character onto the end of this string.

void QString::push_front(constQString & other)

This function is provided for STL compatibility, prepending the givenother string to the beginning of this string. It is equivalent toprepend(other).

See alsoprepend().

void QString::push_front(QChar ch)

This is an overloaded function.

Prepends the givench character to the beginning of this string.

QString & QString::remove(int position,int n)

Removesn characters from the string, starting at the givenposition index, and returns a reference to the string.

If the specifiedposition index is within the string, butposition +n is beyond the end of the string, the string is truncated at the specifiedposition.

QString s="Montreal";s.remove(1,4);// s == "Meal"

See alsoinsert() andreplace().

QString & QString::remove(QChar ch,Qt::CaseSensitivity cs = Qt::CaseSensitive)

Removes every occurrence of the characterch in this string, and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString t="Ali Baba";t.remove(QChar('a'),Qt::CaseInsensitive);// t == "li Bb"

This is the same asreplace(ch, "", cs).

See alsoreplace().

QString & QString::remove(constQString & str,Qt::CaseSensitivity cs = Qt::CaseSensitive)

Removes every occurrence of the givenstr string in this string, and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This is the same asreplace(str, "", cs).

See alsoreplace().

QString & QString::remove(constQRegExp & rx)

Removes every occurrence of the regular expressionrx in the string, and returns a reference to the string. For example:

QString r="Telephone";r.remove(QRegExp("[aeiou]."));// r == "The"

See alsoindexOf(),lastIndexOf(), andreplace().

QString QString::repeated(int times) const

Returns a copy of this string repeated the specified number oftimes.

Iftimes is less than 1, an empty string is returned.

Example:

QString str("ab");str.repeated(4);// returns "abababab"

This function was introduced in Qt 4.5.

QString & QString::replace(int position,int n, constQString & after)

Replacesn characters beginning at indexposition with the stringafter and returns a reference to this string.

Example:

QString x="Say yes!";QString y="no";x.replace(4,3, y);// x == "Say no!"

See alsoinsert() andremove().

QString & QString::replace(int position,int n, constQChar * unicode,int size)

This function overloadsreplace().

Replacesn characters beginning at indexposition with the firstsize characters of theQChar arrayunicode and returns a reference to this string.

QString & QString::replace(int position,int n,QChar after)

This function overloadsreplace().

Replacesn characters beginning at indexposition with the characterafter and returns a reference to this string.

QString & QString::replace(constQString & before, constQString & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the stringbefore with the stringafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Example:

QString str="colour behaviour flavour neighbour";str.replace(QString("ou"),QString("o"));// str == "color behavior flavor neighbor"

Note:The replacement text is not rescanned after it is inserted.

Example:

QString equis="xxxxxx";equis.replace("xx","x");// equis == "xxx"

QString & QString::replace(constQChar * before,int blen, constQChar * after,int alen,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces each occurrence in this string of the firstblen characters ofbefore with the firstalen characters ofafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.5.

QString & QString::replace(QChar ch, constQString & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the characterch in the string withafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

QString & QString::replace(QChar before,QChar after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the characterbefore with the characterafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

QString & QString::replace(constQLatin1String & before, constQLatin1String & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the stringbefore with the stringafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Note:The text is not rescanned after a replacement.

This function was introduced in Qt 4.5.

QString & QString::replace(constQLatin1String & before, constQString & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the stringbefore with the stringafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Note:The text is not rescanned after a replacement.

This function was introduced in Qt 4.5.

QString & QString::replace(constQString & before, constQLatin1String & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the stringbefore with the stringafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Note:The text is not rescanned after a replacement.

This function was introduced in Qt 4.5.

QString & QString::replace(QChar c, constQLatin1String & after,Qt::CaseSensitivity cs = Qt::CaseSensitive)

This function overloadsreplace().

Replaces every occurrence of the characterc with the stringafter and returns a reference to this string.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

Note:The text is not rescanned after a replacement.

This function was introduced in Qt 4.5.

QString & QString::replace(constQRegExp & rx, constQString & after)

This function overloadsreplace().

Replaces every occurrence of the regular expressionrx in the string withafter. Returns a reference to the string. For example:

QString s="Banana";s.replace(QRegExp("a[mn]"),"ox");// s == "Boxoxa"

For regular expressions containingcapturing parentheses, occurrences of\1,\2, ..., inafter are replaced withrx.cap(1), cap(2), ...

QString t="A <i>bon mot</i>.";t.replace(QRegExp("<i>([^<]*)</i>"),"\\emph{\\1}");// t == "A \\emph{bon mot}."

See alsoindexOf(),lastIndexOf(),remove(), andQRegExp::cap().

void QString::reserve(int size)

Attempts to allocate memory for at leastsize characters. If you know in advance how large the string will be, you can call this function, and if you resize the string often you are likely to get better performance. Ifsize is an underestimate, the worst that will happen is that theQString will be a bit slower.

The sole purpose of this function is to provide a means of fine tuningQString's memory usage. In general, you will rarely ever need to call this function. If you want to change the size of the string, callresize().

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 large enough to make a call to reserve() worthwhile:

QString result;int maxSize;bool condition;QChar nextChar;result.reserve(maxSize);while (condition)    result.append(nextChar);result.squeeze();

See alsosqueeze() andcapacity().

void QString::resize(int size)

Sets the size of the string tosize characters.

Ifsize is greater than the current size, the string is extended to make itsize characters long with the extra characters added to the end. The new characters are uninitialized.

Ifsize is less than the current size, characters are removed from the end.

Example:

QString s="Hello world";s.resize(5);// s == "Hello"s.resize(8);// s == "Hello???" (where ? stands for any character)

If you want to append a certain number of identical characters to the string, useoperator+=() as follows rather than resize():

QString t="Hello";t+=QString(10,'X');// t == "HelloXXXXXXXXXX"

If you want to expand the string so that it reaches a certain width and fill the new positions with a particular character, use theleftJustified() function:

Ifsize is negative, it is equivalent to passing zero.

QString r="Hello";r= r.leftJustified(10,' ');// r == "Hello     "

See alsotruncate() andreserve().

QString QString::right(int n) const

Returns a substring that contains then rightmost characters of the string.

The entire string is returned ifn is greater thansize() or less than zero.

QString x="Pineapple";QString y= x.right(5);// y == "apple"

See alsoleft(),mid(), andendsWith().

QString QString::rightJustified(int width,QChar fill = QLatin1Char( ' ' ),bool truncate = false) const

Returns a string ofsize()width that contains thefill character followed by the string. For example:

QString s="apple";QString t= s.rightJustified(8,'.');// t == "...apple"

Iftruncate is false and thesize() of the string is more thanwidth, then the returned string is a copy of the string.

Iftruncate is true and thesize() of the string is more thanwidth, then the resulting string is truncated at positionwidth.

QString str="Pineapple";str= str.rightJustified(5,'.',true);// str == "Pinea"

See alsoleftJustified().

QStringRef QString::rightRef(int n) const

Returns a substring reference to then rightmost characters of the string.

Ifn is greater thansize() or less than zero, a reference to the entire string is returned.

QString x="Pineapple";QStringRef y= x.rightRef(5);// y == "apple"

This function was introduced in Qt 4.4.

See alsoright(),leftRef(),midRef(), andendsWith().

QString QString::section(QChar sep,int start,int end = -1,SectionFlags flags = SectionDefault) const

This function returns a section of the string.

This string is treated as a sequence of fields separated by the character,sep. The returned string consists of the fields from positionstart to positionend inclusive. Ifend is not specified, all fields from positionstart to the end of the string are included. Fields are numbered 0, 1, 2, etc., counting from the left, and -1, -2, etc., counting from right to left.

Theflags argument can be used to affect some aspects of the function's behavior, e.g. whether to be case sensitive, whether to skip empty fields and how to deal with leading and trailing separators; seeSectionFlags.

QString str;QString csv="forename,middlename,surname,phone";QString path="/usr/local/bin/myapp";// First field is emptyQString::SectionFlag flag=QString::SectionSkipEmpty;str= csv.section(',',2,2);// str == "surname"str= path.section('/',3,4);// str == "bin/myapp"str= path.section('/',3,3, flag);// str == "myapp"

Ifstart orend is negative, we count fields from the right of the string, the right-most field being -1, the one from right-most field being -2, and so on.

str= csv.section(',',-3,-2);// str == "middlename,surname"str= path.section('/',-1);// str == "myapp"

See alsosplit().

QString QString::section(constQString & sep,int start,int end = -1,SectionFlags flags = SectionDefault) const

This function overloadssection().

QString str;QString data="forename**middlename**surname**phone";str= data.section("**",2,2);// str == "surname"str= data.section("**",-3,-2);// str == "middlename**surname"

See alsosplit().

QString QString::section(constQRegExp & reg,int start,int end = -1,SectionFlags flags = SectionDefault) const

This function overloadssection().

This string is treated as a sequence of fields separated by the regular expression,reg.

QString line="forename\tmiddlename  surname \t \t phone";QRegExp sep("\\s+");str= line.section(sep,2,2);// s == "surname"str= line.section(sep,-3,-2);// s == "middlename  surname"

Warning: Using thisQRegExp version is much more expensive than the overloaded string and character versions.

See alsosplit() andsimplified().

QString & QString::setNum(int n,int base = 10)

Sets the string to the printed value ofn in the specifiedbase, and returns a reference to the string.

The base is 10 by default and must be between 2 and 36. For bases other than 10,n is treated as an unsigned integer.

QString str;str.setNum(1234);// str == "1234"

The formatting always usesQLocale::C, i.e., English/UnitedStates. To get a localized string representation of a number, useQLocale::toString() with the appropriate locale.

QString & QString::setNum(uint n,int base = 10)

This is an overloaded function.

QString & QString::setNum(long n,int base = 10)

This is an overloaded function.

QString & QString::setNum(ulong n,int base = 10)

This is an overloaded function.

QString & QString::setNum(qlonglong n,int base = 10)

This is an overloaded function.

QString & QString::setNum(qulonglong n,int base = 10)

This is an overloaded function.

QString & QString::setNum(short n,int base = 10)

This is an overloaded function.

QString & QString::setNum(ushort n,int base = 10)

This is an overloaded function.

QString & QString::setNum(double n,char format = 'g',int precision = 6)

This is an overloaded function.

Sets the string to the printed value ofn, formatted according to the givenformat andprecision, and returns a reference to the string.

Theformat can be 'f', 'F', 'e', 'E', 'g' or 'G' (see thearg() function documentation for an explanation of the formats).

UnlikeQLocale::toString(), this function doesn't honor the user's locale settings.

QString & QString::setNum(float n,char format = 'g',int precision = 6)

This is an overloaded function.

Sets the string to the printed value ofn, formatted according to the givenformat andprecision, and returns a reference to the string.

QString & QString::setRawData(constQChar * unicode,int size)

Resets theQString to use the firstsize Unicode characters in the arrayunicode. The data inunicode isnot copied. The caller must be able to guarantee thatunicode will not be deleted or modified as long as theQString (or an unmodified copy of it) exists.

This function can be used instead offromRawData() to re-use existingsQString objects to save memory re-allocations.

This function was introduced in Qt 4.7.

See alsofromRawData().

QString & QString::setUnicode(constQChar * unicode,int size)

Resizes the string tosize characters and copiesunicode into the string.

Ifunicode is 0, nothing is copied, but the string is still resized tosize.

See alsounicode() andsetUtf16().

QString & QString::setUtf16(constushort * unicode,int size)

Resizes the string tosize characters and copiesunicode into the string.

Ifunicode is 0, nothing is copied, but the string is still resized tosize.

Note that unlikefromUtf16(), this function does not consider BOMs and possibly differing byte ordering.

See alsoutf16() andsetUnicode().

QString QString::simplified() const

Returns a string that has whitespace removed from the start and the end, and that has each sequence of internal whitespace replaced with a single space.

Whitespace means any character for whichQChar::isSpace() returns true. This includes the ASCII characters '\t', '\n', '\v', '\f', '\r', and ' '.

Example:

QString str="  lots\t of\nwhitespace\r\n ";str= str.simplified();// str == "lots of whitespace";

See alsotrimmed().

int QString::size() const

Returns the number of characters in this string.

The last character in the string is at position size() - 1. In addition,QString ensures that the character at position size() is always '\0', so that you can use the return value ofdata() andconstData() as arguments to functions that expect '\0'-terminated strings.

Example:

QString str="World";int n= str.size();// n == 5str.data()[0];// returns 'W'str.data()[4];// returns 'd'str.data()[5];// returns '\0'

See alsoisEmpty() andresize().

QStringList QString::split(constQString & sep,SplitBehavior behavior = KeepEmptyParts,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Splits the string into substrings whereversep occurs, and returns the list of those strings. Ifsep does not match anywhere in the string, split() returns a single-element list containing this string.

cs specifies whethersep should be matched case sensitively or case insensitively.

Ifbehavior isQString::SkipEmptyParts, empty entries don't appear in the result. By default, empty entries are kept.

Example:

QString str="a,,b,c";QStringList list1= str.split(",");// list1: [ "a", "", "b", "c" ]QStringList list2= str.split(",",QString::SkipEmptyParts);// list2: [ "a", "b", "c" ]

See alsoQStringList::join() andsection().

QStringList QString::split(constQChar & sep,SplitBehavior behavior = KeepEmptyParts,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

QStringList QString::split(constQRegExp & rx,SplitBehavior behavior = KeepEmptyParts) const

This is an overloaded function.

Splits the string into substrings wherever the regular expressionrx matches, and returns the list of those strings. Ifrx does not match anywhere in the string,split() returns a single-element list containing this string.

Here's an example where we extract the words in a sentence using one or more whitespace characters as the separator:

QString str;QStringList list;str="Some  text\n\twith  strange whitespace.";list= str.split(QRegExp("\\s+"));// list: [ "Some", "text", "with", "strange", "whitespace." ]

Here's a similar example, but this time we use any sequence of non-word characters as the separator:

str="This time, a normal English sentence.";list= str.split(QRegExp("\\W+"),QString::SkipEmptyParts);// list: [ "This", "time", "a", "normal", "English", "sentence" ]

Here's a third example where we use a zero-length assertion,\b (word boundary), to split the string into an alternating sequence of non-word and word tokens:

str="Now: this sentence fragment.";list= str.split(QRegExp("\\b"));// list: [ "", "Now", ": ", "this", " ", "sentence", " ", "fragment", "." ]

See alsoQStringList::join() andsection().

QString & QString::sprintf(constchar * cformat, ...)

Safely builds a formatted string from the format stringcformat and an arbitrary list of arguments.

The %lc escape sequence expects a unicode character of type ushort (as returned byQChar::unicode()). The %ls escape sequence expects a pointer to a zero-terminated array of unicode characters of type ushort (as returned byQString::utf16()).

Note:This function expects a UTF-8 string for %s and Latin-1 for the format string.

The format string supports most of the conversion specifiers provided by printf() in the standard C++ library. It doesn't honor the length modifiers (e.g.h forshort,ll forlong long). If you need those, use the standard snprintf() function instead:

size_t BufSize;char buf[BufSize];::snprintf(buf, BufSize,"%lld",123456789LL);QString str=QString::fromAscii(buf);

Warning: We do not recommend using QString::sprintf() in new Qt code. Instead, consider usingQTextStream orarg(), both of which support Unicode strings seamlessly and are type-safe. Here's an example that usesQTextStream:

QString result;QTextStream(&result)<<"pi = "<<3.14;// result == "pi = 3.14"

Fortranslations, especially if the strings contains more than one escape sequence, you should consider using thearg() function instead. This allows the order of the replacements to be controlled by the translator.

See alsoarg().

void QString::squeeze()

Releases any memory not required to store the character data.

The sole purpose of this function is to provide a means of fine tuningQString's memory usage. In general, you will rarely ever need to call this function.

See alsoreserve() andcapacity().

bool QString::startsWith(constQString & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns true if the string starts withs; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

QString str="Bananas";str.startsWith("Ban");// returns truestr.startsWith("Car");// returns false

See alsoendsWith().

bool QString::startsWith(constQLatin1String & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsstartsWith().

bool QString::startsWith(constQChar & c,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This function overloadsstartsWith().

Returns true if the string starts withc; otherwise returns false.

bool QString::startsWith(constQStringRef & s,Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

Returns true if the string starts with the string references; otherwise returns false.

Ifcs isQt::CaseSensitive (default), the search is case sensitive; otherwise the search is case insensitive.

This function was introduced in Qt 4.8.

See alsoendsWith().

void QString::swap(QString & other)

Swaps stringother with this string. This operation is very fast and never fails.

This function was introduced in Qt 4.8.

QByteArray QString::toAscii() const

Returns an 8-bit representation of the string as aQByteArray.

If a codec has been set usingQTextCodec::setCodecForCStrings(), it is used to convert Unicode to 8-bit char; otherwise this function does the same astoLatin1().

Note that, despite the name, this function does not necessarily return an US-ASCII (ANSI X3.4-1986) string and its result may not be US-ASCII compatible.

See alsofromAscii(),toLatin1(),toUtf8(),toLocal8Bit(), andQTextCodec.

QString QString::toCaseFolded() const

Returns the case folded equivalent of the string. For most Unicode characters this is the same astoLower().

double QString::toDouble(bool * ok = 0) const

Returns the string converted to adouble value.

Returns 0.0 if the conversion fails.

If a conversion error occurs,*ok is set to false; otherwise*ok is set to true.

QString str="1234.56";double val= str.toDouble();// val == 1234.56

Various string formats for floating point numbers can be converted to double values:

bool ok;double d;d=QString("1234.56e-02" ).toDouble(&ok);// ok == true, d == 12.3456

This function tries to interpret the string according to the current locale. The current locale is determined from the system at application startup and can be changed by callingQLocale::setDefault(). If the string cannot be interpreted according to the current locale, this function falls back on the "C" locale.

QLocale::setDefault(QLocale::C);d=QString("1234,56" ).toDouble(&ok);// ok == falsed=QString("1234.56" ).toDouble(&ok);// ok == true, d == 1234.56QLocale::setDefault(QLocale::German);d=QString("1234,56" ).toDouble(&ok);// ok == true, d == 1234.56d=QString("1234.56" ).toDouble(&ok);// ok == true, d == 1234.56

Due to the ambiguity between the decimal point and thousands group separator in various locales, this function does not handle thousands group separators. If you need to convert such numbers, seeQLocale::toDouble().

QLocale::setDefault(QLocale::C);d=QString("1234,56" ).toDouble(&ok);// ok == false

See alsonumber(),QLocale::setDefault(),QLocale::toDouble(), andtrimmed().

float QString::toFloat(bool * ok = 0) const

Returns the string converted to afloat value.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true. Returns 0.0 if the conversion fails.

Example:

QString str1="1234.56";str1.toFloat();// returns 1234.56bool ok;QString str2="R2D2";str2.toFloat(&ok);// returns 0.0, sets ok to false

See alsonumber(),toDouble(), andtoInt().

int QString::toInt(bool * ok = 0,int base = 10) const

Returns the string converted to anint using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;int hex= str.toInt(&ok,16);// hex == 255, ok == trueint dec= str.toInt(&ok,10);// dec == 0, ok == false

See alsonumber(),toUInt(), andtoDouble().

QByteArray QString::toLatin1() const

Returns a Latin-1 representation of the string as aQByteArray.

The returned byte array is undefined if the string contains non-Latin1 characters. Those characters may be suppressed or replaced with a question mark.

See alsofromLatin1(),toAscii(),toUtf8(),toLocal8Bit(), andQTextCodec.

QByteArray QString::toLocal8Bit() const

Returns the local 8-bit representation of the string as aQByteArray. The returned byte array is undefined if the string contains characters not supported by the local 8-bit encoding.

QTextCodec::codecForLocale() is used to perform the conversion from Unicode. If the locale encoding could not be determined, this function does the same astoLatin1().

If this string contains any characters that cannot be encoded in the locale, the returned byte array is undefined. Those characters may be suppressed or replaced by another.

See alsofromLocal8Bit(),toAscii(),toLatin1(),toUtf8(), andQTextCodec.

long QString::toLong(bool * ok = 0,int base = 10) const

Returns the string converted to along using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;long hex= str.toLong(&ok,16);// hex == 255, ok == truelong dec= str.toLong(&ok,10);// dec == 0, ok == false

See alsonumber(),toULong(), andtoInt().

qlonglong QString::toLongLong(bool * ok = 0,int base = 10) const

Returns the string converted to along long using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;qint64 hex= str.toLongLong(&ok,16);// hex == 255, ok == trueqint64 dec= str.toLongLong(&ok,10);// dec == 0, ok == false

See alsonumber(),toULongLong(), andtoInt().

QString QString::toLower() const

Returns a lowercase copy of the string.

QString str="Qt by NOKIA";str= str.toLower();// str == "qt by nokia"

The case conversion will always happen in the 'C' locale. For locale dependent case folding useQLocale::toLower()

See alsotoUpper() andQLocale::toLower().

short QString::toShort(bool * ok = 0,int base = 10) const

Returns the string converted to ashort using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;short hex= str.toShort(&ok,16);// hex == 255, ok == trueshort dec= str.toShort(&ok,10);// dec == 0, ok == false

See alsonumber(),toUShort(), andtoInt().

std::string QString::toStdString() const

Returns a std::string object with the data contained in thisQString. The Unicode data is converted into 8-bit characters using thetoAscii() function.

This operator is mostly useful to pass aQString to a function that accepts a std::string object.

If theQString contains Unicode characters that theQTextCodec::codecForCStrings() codec cannot handle, using this operator can lead to loss of information.

This operator is only available if Qt is configured with STL compatibility enabled.

See alsotoAscii(),toLatin1(),toUtf8(), andtoLocal8Bit().

std::wstring QString::toStdWString() const

Returns a std::wstring object with the data contained in thisQString. The std::wstring is encoded in utf16 on platforms where wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms where wchar_t is 4 bytes wide (most Unix systems).

This operator is mostly useful to pass aQString to a function that accepts a std::wstring object.

This operator is only available if Qt is configured with STL compatibility enabled.

See alsoutf16(),toAscii(),toLatin1(),toUtf8(), andtoLocal8Bit().

uint QString::toUInt(bool * ok = 0,int base = 10) const

Returns the string converted to anunsigned int using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;uint hex= str.toUInt(&ok,16);// hex == 255, ok == trueuint dec= str.toUInt(&ok,10);// dec == 0, ok == false

See alsonumber() andtoInt().

ulong QString::toULong(bool * ok = 0,int base = 10) const

Returns the string converted to anunsigned long using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;ulong hex= str.toULong(&ok,16);// hex == 255, ok == trueulong dec= str.toULong(&ok,10);// dec == 0, ok == false

See alsonumber().

qulonglong QString::toULongLong(bool * ok = 0,int base = 10) const

Returns the string converted to anunsigned long long using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;quint64 hex= str.toULongLong(&ok,16);// hex == 255, ok == truequint64 dec= str.toULongLong(&ok,10);// dec == 0, ok == false

See alsonumber() andtoLongLong().

ushort QString::toUShort(bool * ok = 0,int base = 10) const

Returns the string converted to anunsigned short using basebase, which is 10 by default and must be between 2 and 36, or 0. Returns 0 if the conversion fails.

If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.

Ifbase is 0, the C language convention is used: If the string begins with "0x", base 16 is used; if the string begins with "0", base 8 is used; otherwise, base 10 is used.

Example:

QString str="FF";bool ok;ushort hex= str.toUShort(&ok,16);// hex == 255, ok == trueushort dec= str.toUShort(&ok,10);// dec == 0, ok == false

See alsonumber() andtoShort().

QVector<uint> QString::toUcs4() const

Returns a UCS-4/UTF-32 representation of the string as aQVector<uint>.

UCS-4 is a Unicode codec and is lossless. All characters from this string can be encoded in UCS-4. The vector is not null terminated.

This function was introduced in Qt 4.2.

See alsofromUtf8(),toAscii(),toLatin1(),toLocal8Bit(),QTextCodec,fromUcs4(), andtoWCharArray().

QString QString::toUpper() const

Returns an uppercase copy of the string.

QString str="TeXt";str= str.toUpper();// str == "TEXT"

The case conversion will always happen in the 'C' locale. For locale dependent case folding useQLocale::toUpper()

See alsotoLower() andQLocale::toLower().

QByteArray QString::toUtf8() const

Returns a UTF-8 representation of the string as aQByteArray.

UTF-8 is a Unicode codec and can represent all characters in a Unicode string likeQString.

However, in the Unicode range, there are certain codepoints that are not considered characters. The Unicode standard reserves the last two codepoints in each Unicode Plane (U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFFE, etc.), as well as 16 codepoints in the range U+FDD0..U+FDDF, inclusive, as non-characters. If any of those appear in the string, they may be discarded and will not appear in the UTF-8 representation, or they may be replaced by one or more replacement characters.

See alsofromUtf8(),toAscii(),toLatin1(),toLocal8Bit(), andQTextCodec.

int QString::toWCharArray(wchar_t * array) const

Fills thearray with the data contained in thisQString object. The array is encoded in utf16 on platforms where wchar_t is 2 bytes wide (e.g. windows) and in ucs4 on platforms where wchar_t is 4 bytes wide (most Unix systems).

array has to be allocated by the caller and contain enough space to hold the complete string (allocating the array with the same length as the string is always sufficient).

returns the actual length of the string inarray.

Note:This function does not append a null character to the array.

This function was introduced in Qt 4.2.

See alsoutf16(),toUcs4(),toAscii(),toLatin1(),toUtf8(),toLocal8Bit(), andtoStdWString().

QString QString::trimmed() const

Returns a string that has whitespace removed from the start and the end.

Whitespace means any character for whichQChar::isSpace() returns true. This includes the ASCII characters '\t', '\n', '\v', '\f', '\r', and ' '.

Example:

QString str="  lots\t of\nwhitespace\r\n ";str= str.trimmed();// str == "lots\t of\nwhitespace"

Unlikesimplified(), trimmed() leaves internal whitespace alone.

See alsosimplified().

void QString::truncate(int position)

Truncates the string at the givenposition index.

If the specifiedposition index is beyond the end of the string, nothing happens.

Example:

QString str="Vladivostok";str.truncate(4);// str == "Vlad"

Ifposition is negative, it is equivalent to passing zero.

See alsochop(),resize(), andleft().

constQChar * QString::unicode() const

Returns a '\0'-terminated Unicode representation of the string. The result remains valid until the string is modified.

See alsosetUnicode() andutf16().

constushort * QString::utf16() const

Returns theQString as a '\0'-terminated array of unsigned shorts. The result remains valid until the string is modified.