The QString class provides an abstraction of Unicode text and the classic C null-terminated char array (char*). More...

#include <qstring.h>

Inheritance diagram for QString:

Classes
struct	Null

Public Member Functions
	QString ()

	QString (QChar)

	QString (const QString &)

	QString (const QByteArray &)

	QString (const QCString &)

	QString (const QChar *unicode, uint length)

	QString (const char *str)

	~QString ()

QString &	operator= (const QString &)

QString &	operator= (const char *)

QString &	operator= (const QCString &)

QString &	operator= (QChar c)

QString &	operator= (char c)

	QString (const Null &)

QString &	operator= (const Null &)

bool	isNull () const

bool	isEmpty () const

uint	length () const

void	truncate (uint pos)

void	fill (QChar c, int len=-1)

QString	copy () const

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

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

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

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

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

QString	arg (ushort a, int fieldwidth=0, int base=10) const

QString	arg (char a, int fieldwidth=0) const

QString	arg (QChar a, int fieldwidth=0) const

QString	arg (const QString &a, int fieldwidth=0) const

QString	arg (double a, int fieldwidth=0, char fmt='g', int prec=-1) const

QString &	sprintf (const char *format,...)

int	find (QChar c, int index=0, bool cs=TRUE) const

int	find (char c, int index=0, bool cs=TRUE) const

int	find (const QString &str, int index=0, bool cs=TRUE) const

int	find (const QRegExp &, int index=0) const

int	find (const char *str, int index=0) const

int	findRev (QChar c, int index=-1, bool cs=TRUE) const

int	findRev (char c, int index=-1, bool cs=TRUE) const

int	findRev (const QString &str, int index=-1, bool cs=TRUE) const

int	findRev (const QRegExp &, int index=-1) const

int	findRev (const char *str, int index=-1) const

int	contains (QChar c, bool cs=TRUE) const

int	contains (char c, bool cs=TRUE) const

int	contains (const char *str, bool cs=TRUE) const

int	contains (const QString &str, bool cs=TRUE) const

int	contains (const QRegExp &) const

QString	left (uint len) const

QString	right (uint len) const

QString	mid (uint index, uint len=0xffffffff) const

QString	leftJustify (uint width, QChar fill=' ', bool trunc=FALSE) const

QString	rightJustify (uint width, QChar fill=' ', bool trunc=FALSE) const

QString	lower () const

QString	upper () const

QString	stripWhiteSpace () const

QString	simplifyWhiteSpace () const

QString &	insert (uint index, const QString &)

QString &	insert (uint index, const QChar *, uint len)

QString &	insert (uint index, QChar)

QString &	insert (uint index, char c)

QString &	append (char)

QString &	append (QChar)

QString &	append (const QString &)

QString &	prepend (char)

QString &	prepend (QChar)

QString &	prepend (const QString &)

QString &	remove (uint index, uint len)

QString &	replace (uint index, uint len, const QString &)

QString &	replace (uint index, uint len, const QChar *, uint clen)

QString &	replace (const QRegExp &, const QString &)

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

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

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

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

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

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

uint64	toUInt64 (bool *ok=0, int base=10) const

float	toFloat (bool *ok=0) const

double	toDouble (bool *ok=0) const

QString &	setNum (short, int base=10)

QString &	setNum (ushort, int base=10)

QString &	setNum (int, int base=10)

QString &	setNum (uint, int base=10)

QString &	setNum (long, int base=10)

QString &	setNum (ulong, int base=10)

QString &	setNum (float, char f='g', int prec=6)

QString &	setNum (double, char f='g', int prec=6)

void	setExpand (uint index, QChar c)

QString &	operator+= (const QString &str)

QString &	operator+= (QChar c)

QString &	operator+= (char c)

QChar	at (uint i) const

QChar	operator[] (int i) const

QCharRef	at (uint i)

QCharRef	operator[] (int i)

QChar	constref (uint i) const

QChar &	ref (uint i)

const QChar *	unicode () const

const char *	ascii () const

const char *	latin1 () const

const unsigned short *	ucs2 () const

QCString	utf8 () const

QCString	local8Bit () const

bool	operator! () const

QString &	setUnicode (const QChar *unicode, uint len)

QString &	setUnicodeCodes (const ushort *unicode_as_ushorts, uint len)

QString &	setLatin1 (const char *, int len=-1)

int	compare (const QString &s) const

void	compose ()

QChar::Direction	basicDirection ()

QString	visual (int index=0, int len=-1)

const char *	data () const

bool	startsWith (const QString &) const

Static Public Member Functions
static QString	number (long, int base=10)

static QString	number (ulong, int base=10)

static QString	number (int, int base=10)

static QString	number (uint, int base=10)

static QString	number (double, char f='g', int prec=6)

static QString	fromLatin1 (const char *, int len=-1)

static QString	fromUcs2 (const unsigned short *ucs2)

static QString	fromUtf8 (const char *, int len=-1)

static QString	fromLocal8Bit (const char *, int len=-1)

static int	compare (const QString &s1, const QString &s2)

Static Public Attributes
static const Null	null = { }

Friends
class	QConstString

Q_EXPORT QDataStream &	operator>> (QDataStream &, QString &)

Related Functions
(Note that these are not member functions.)
bool	operator== (const QString &s1, const QString &s2)

bool	operator== (const QString &s1, const char *s2)

bool	operator== (const char *s1, const QString &s2)

bool	operator!= (const QString &s1, const QString &s2)

bool	operator!= (const QString &s1, const char *s2)

bool	operator!= (const char *s1, const QString &s2)

bool	operator< (const QString &s1, const char *s2)

bool	operator< (const char *s1, const QString &s2)

bool	operator<= (const QString &s1, const char *s2)

bool	operator<= (const char *s1, const QString &s2)

bool	operator> (const QString &s1, const char *s2)

bool	operator> (const char *s1, const QString &s2)

bool	operator>= (const QString &s1, const char *s2)

bool	operator>= (const char *s1, const QString &s2)

QString	operator+ (const QString &s1, const QString &s2)

QString	operator+ (const QString &s1, const char *s2)

QString	operator+ (const char *s1, const QString &s2)

QString	operator+ (const QString &s, char c)

QString	operator+ (char c, const QString &s)

QDataStream &	operator<< (QDataStream &s, const QString &str)

Detailed Description

The QString class provides an abstraction of Unicode text and the classic C null-terminated char array (char*).

QString uses implicit sharing, and so it is very efficient and easy to use.

In all QString methods that take const char* parameters, the const char* is interpreted as a classic C-style 0-terminated ASCII string. It is legal for the const char* parameter to be 0. The results are undefined if the const char* string is not 0-terminated. Functions that copy classic C strings into a QString will not copy the terminating 0-character. The QChar array of the QString (as returned by unicode()) is not terminated by a null.

A QString that has not been assigned to anything is null, i.e. both the length and data pointer is 0. A QString that references the empty string ("", a single '\0' char) is empty. Both null and empty QStrings are legal parameters to the methods. Assigning const char 0 to QString gives a null QString.

Note that if you find that you are mixing usage of QCString, QString, and QByteArray, this causes lots of unnecessary copying and might indicate that the true nature of the data you are dealing with is uncertain. If the data is NUL-terminated 8-bit data, use QCString; if it is unterminated (ie. contains NULs) 8-bit data, use QByteArray; if it is text, use QString.

See also: QChar Shared classes

Constructor & Destructor Documentation

§ QString() [1/6]

QString::QString ( )

inline

Constructs a null string.

See also: isNull()

§ QString() [2/6]

QString::QString ( QChar ch )

Constructs a string containing the one character ch.

§ QString() [3/6]

QString::QString ( const QString & s )

Constructs an implicitly-shared copy of s.

§ QString() [4/6]

QString::QString ( const QByteArray & ba )

Constructs a string that is a deep copy of ba interpreted as a classic C string.

§ QString() [5/6]

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

Constructs a string that is a deep copy of the first length QChar in the array unicode.

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

If only unicode is 0, the string is empty, but has length characters of space preallocated - QString expands automatically anyway, but this may speed some cases up a little.

See also: isNull()

§ QString() [6/6]

QString::QString ( const char * str )

Constructs a string that is a deep copy of str, interpreted as a classic C string.

If str is 0 a null string is created.

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

See also: isNull()

§ ~QString()

QString::~QString ( )

inline

Destroys the string and frees the "real" string, if this was the last copy of that string.

Member Function Documentation

§ append() [1/3]

QString & QString::append ( char ch )

inline

Appends ch to the string and returns a reference to the result. Equivalent to operator+=().

§ append() [2/3]

QString & QString::append ( QChar ch )

inline

Appends ch to the string and returns a reference to the result. Equivalent to operator+=().

§ append() [3/3]

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

inline

Appends str to the string and returns a reference to the result. Equivalent to operator+=().

§ arg() [1/10]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [2/10]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [3/10]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [4/10]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [5/10]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [6/10]

QString QString::arg	(	ushort	a,
		int	fieldwidth = `0`,
		int	base = `10`
	)		const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is expressed in to base notation, which is decimal by default and must be in the range 2-36 inclusive.

§ arg() [7/10]

QString QString::arg	(	char	a,
		int	fieldwidth = `0`
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

a is assumed to be in the Latin1 character set.

§ arg() [8/10]

QString QString::arg	(	QChar	a,
		int	fieldwidth = `0`
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ arg() [9/10]

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

Returns a string equal to this one, but with the lowest-numbered occurrence of i (for a positive integer i) replaced by a.

label.setText( tr("Rename %1 to %2?").arg(oldName).arg(newName) );

fieldwidth is the minimum amount of space a is padded to. A positive value produces right-aligned text, while a negative value produces left aligned text.

Warning: Using arg() for constructing "real" sentences programmatically is likely to lead to translation problems. Inserting objects like numbers or file names is fairly safe.; Relying on spaces to create alignment is prone to lead to translation problems.

If there is no i pattern, a warning message (qWarning()) is printed and the text as appended at the end of the string. This is error recovery and should not occur in correct code.

See also: QObject::tr()

§ arg() [10/10]

QString QString::arg	(	double	a,
		int	fieldwidth = `0`,
		char	fmt = `'g'`,
		int	prec = `-1`
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

is formatted according to the fmt format specified, which is 'g' by default and can be any of 'f', 'F', 'e', 'E', 'g' or 'G', all of which have the same meaning as for sprintf(). prec determines the precision, just as for number() and sprintf().

§ ascii()

const char * QString::ascii ( ) const

This functions simply calls latin1() and returns the result.

§ at() [1/2]

QChar QString::at ( uint i ) const

inline

Returns the character at i, or 0 if i is beyond the length of the string.

Note: If this QString is not const or const&, the non-const at() will be used instead, which will expand the string if i is beyond the length of the string.

§ at() [2/2]

QCharRef QString::at ( uint i )

inline

Returns a reference to the character at i, expanding the string with QChar::null if necessary. The resulting reference can then be assigned to, or otherwise used immediately, but becomes invalid once further modifications are made to the string.

§ basicDirection()

QChar::Direction QString::basicDirection ( )

This function returns the basic directionality of the string (QChar::DirR for right to left and QChar::DirL for left to right). Useful to find the right alignment.

§ compare() [1/2]

int QString::compare ( const QString & s ) const

Compares this string to s, returning an integer less than, equal to, or greater than zero if it is, respectively, lexically less than, equal to, or greater than s.

§ compare() [2/2]

int QString::compare	(	const QString &	s1,
		const QString &	s2
	)

inlinestatic

Compare s1 to s2 returning an integer less than, equal to, or greater than zero if s1 is, respectively, lexically less than, equal to, or greater than s2.

§ compose()

void QString::compose ( )

Note that this function is not supported in Qt 2.0, and is merely for experimental and illustrative purposes. It is mainly of interest to those experimenting with Arabic and other composition-rich texts.

Applies possible ligatures to a QString, useful when composition-rich text requires rendering with glyph-poor fonts, but also makes compositions such as QChar(0x0041) ('A') and QChar(0x0308) (Unicode accent diaresis) giving QChar(0x00c4) (German A Umlaut).

§ constref()

QChar QString::constref ( uint i ) const

inline

Equivalent to at(i), this returns the QChar at i by value.

See also: ref()

§ contains() [1/5]

int QString::contains	(	QChar	c,
		bool	cs = `TRUE`
	)		const

Returns the number of times the character c occurs in the string.

The match is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

§ contains() [2/5]

int QString::contains	(	char	c,
		bool	cs = `TRUE`
	)		const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ contains() [3/5]

int QString::contains	(	const char *	str,
		bool	cs = `TRUE`
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ contains() [4/5]

int QString::contains	(	const QString &	str,
		bool	cs = `TRUE`
	)		const

Returns the number of times str occurs in the string.

The match is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

This function counts overlapping substrings, for example, "banana" contains two occurrences of "ana".

See also: findRev()

§ contains() [5/5]

int QString::contains ( const QRegExp & rx ) const

Counts the number of overlapping occurrences of rx in the string.

Example:

QString s = "banana and panama";
QRegExp r = QRegExp("a[nm]a", TRUE, FALSE);
s.contains( r );              // 4 matches

See also: find() findRev()

§ copy()

QString QString::copy ( ) const

inline

Returns a deep copy of this string.

Doing this is redundant in Qt 2.x, since QString is implicitly shared, and so will automatically be deeply copied as necessary.

§ data()

const char * QString::data ( ) const

inline

Returns a pointer to a 0-terminated classic C string.

In Qt 1.x, this returned a char* allowing direct manipulation of the string as a sequence of bytes. In Qt 2.x where QString is a Unicode string, char* conversion constructs a temporary string, and hence direct character operations are meaningless.

§ fill()

void QString::fill	(	QChar	c,
		int	len = `-1`
	)

Fills the string with len characters of value c.

If len is negative, the current string length is used.

§ find() [1/5]

int QString::find	(	QChar	c,
		int	index = `0`,
		bool	cs = `TRUE`
	)		const

Finds the first occurrence of the character c, starting at position index. If index is -1, the search starts at the last character; if -2, at the next to last character; etc.

The search is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

Returns the position of c, or -1 if c could not be found.

§ find() [2/5]

int QString::find	(	char	c,
		int	index = `0`,
		bool	cs = `TRUE`
	)		const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ find() [3/5]

int QString::find	(	const QString &	str,
		int	index = `0`,
		bool	cs = `TRUE`
	)		const

Finds the first occurrence of the string str, starting at position index. If index is -1, the search starts at the last character; if -2, at the next to last character; etc.

The search is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

Returns the position of str, or -1 if str could not be found.

§ find() [4/5]

int QString::find	(	const QRegExp &	rx,
		int	index = `0`
	)		const

Finds the first occurrence of the regular expression rx, starting at position index. If index is -1, the search starts at the last character; if -2, at the next to last character; etc.

Returns the position of the next match, or -1 if rx was not found.

See also: findRev() replace() contains()

§ find() [5/5]

int QString::find	(	const char *	str,
		int	index = `0`
	)		const

inline

Equivalent to find(QString(str), index).

§ findRev() [1/5]

int QString::findRev	(	QChar	c,
		int	index = `-1`,
		bool	cs = `TRUE`
	)		const

Finds the first occurrence of the character c, starting at position index and searching backwards. If index is -1, the search starts at the last character; if -2, at the next to last character; etc.

The search is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

Returns the position of c, or -1 if c could not be found.

§ findRev() [2/5]

int QString::findRev	(	char	c,
		int	index = `-1`,
		bool	cs = `TRUE`
	)		const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ findRev() [3/5]

int QString::findRev	(	const QString &	str,
		int	index = `-1`,
		bool	cs = `TRUE`
	)		const

Finds the first occurrence of the string str, starting at position index and searching backwards. If index is -1, the search starts at the last character; -2, at the next to last character; etc.

The search is case sensitive if cs is TRUE, or case insensitive if cs is FALSE.

Returns the position of str, or -1 if str could not be found.

§ findRev() [4/5]

int QString::findRev	(	const QRegExp &	rx,
		int	index = `-1`
	)		const

Finds the first occurrence of the regular expression rx, starting at position index and searching backwards. If index is -1, the search starts at the last character; if -2, at the next to last character; etc.

Returns the position of the next match (backwards), or -1 if rx was not found.

See also: find()

§ findRev() [5/5]

int QString::findRev	(	const char *	str,
		int	index = `-1`
	)		const

inline

Equivalent to findRev(QString(str), index).

§ fromLatin1()

QString QString::fromLatin1	(	const char *	chars,
		int	len = `-1`
	)

static

Creates a QString from Latin1 text. This is the same as the QString(const char*) constructor, but you can make that constructor invisible if you compile with the define QT_NO_CAST_ASCII, in which case you can explicitly create a QString from Latin-1 text using this function.

§ fromLocal8Bit()

QString QString::fromLocal8Bit	(	const char *	local8Bit,
		int	len = `-1`
	)

static

Returns the unicode string decoded from the first len bytes of local8Bit. If len is -1 (the default), the length of local8Bit is used. If trailing partial characters are in local8Bit, they are ignored.

local8Bit is assumed to be encoded in a locale-specific format.

See QTextCodec for more diverse coding/decoding of Unicode strings.

§ fromUcs2()

QString QString::fromUcs2 ( const unsigned short * str )

static

Constructs a string that is a deep copy of str, interpreted as a UCS2 encoded, zero terminated, Unicode string.

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

See also: isNull()

§ fromUtf8()

QString QString::fromUtf8	(	const char *	utf8,
		int	len = `-1`
	)

static

Returns the unicode string decoded from the first len bytes of utf8. If len is -1 (the default), the length of utf8 is used. If trailing partial characters are in utf8, they are ignored.

See QTextCodec for more diverse coding/decoding of Unicode strings.

§ insert() [1/4]

QString & QString::insert	(	uint	index,
		const QString &	s
	)

Insert s into the string before position index.

If index is beyond the end of the string, the string is extended with spaces (ASCII 32) to length index and s is then appended.

QString s = "I like fish";
s.insert( 2, "don't ");   // s == "I don't like fish"
s = "x";
s.insert( 3, "yz" );  // s == "x  yz"

§ insert() [2/4]

QString & QString::insert	(	uint	index,
		const QChar *	s,
		uint	len
	)

Insert len units of QChar data from s into the string before position index.

§ insert() [3/4]

QString & QString::insert	(	uint	index,
		QChar	c
	)

Insert c into the string at (before) position index and returns a reference to the string.

If index is beyond the end of the string, the string is extended with spaces (ASCII 32) to length index and c is then appended.

Example:

QString s = "Ys";
s.insert( 1, 'e' );       // s == "Yes"
s.insert( 3, '!');        // s == "Yes!"

See also: remove(), replace()

§ insert() [4/4]

QString & QString::insert	(	uint	index,
		char	c
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ isEmpty()

bool QString::isEmpty ( ) const

inline

Returns TRUE if the string is empty, i.e. if length() == 0. An empty string is not always a null string.

See example in isNull().

See also: isNull(), length()

§ isNull()

bool QString::isNull ( ) const

inline

Returns TRUE if the string is null. A null string is also an empty string.

Example:

QString a;        // a.unicode() == 0,  a.length() == 0
QString b = "";   // b.unicode() == "", b.length() == 0
a.isNull();       // TRUE, because a.unicode() == 0
a.isEmpty();  // TRUE, because a.length() == 0
b.isNull();       // FALSE, because b.unicode() != 0
b.isEmpty();  // TRUE, because b.length() == 0

See also: isEmpty(), length()

§ latin1()

const char * QString::latin1 ( ) const

Returns a Latin-1 representation of the string. Note that the returned value is undefined if the string contains non-Latin-1 characters. If you want to convert strings into formats other than Unicode, see the QTextCodec classes.

This function is mainly useful for boot-strapping legacy code to use Unicode.

The result remains valid so long as one unmodified copy of the source string exists.

See also: utf8(), local8Bit()

§ left()

QString QString::left ( uint len ) const

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

The whole string is returned if len exceeds the length of the string.

Example:

QString s = "Pineapple";

QString t = s.left( 4 ); // t == "Pine"

See also: right(), mid(), isEmpty()

§ leftJustify()

QString QString::leftJustify	(	uint	width,
		QChar	fill = `' '`,
		bool	truncate = `FALSE`
	)		const

Returns a string of length width that contains this string and padded by the fill character.

If the length of the string exceeds width and truncate is FALSE, then the returned string is a copy of the string. If the length of the string exceeds width and truncate is TRUE, then the returned string is a left(width).

Example:

QString s("apple");

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

See also: rightJustify()

§ length()

uint QString::length ( ) const

inline

Returns the length of the string.

Null strings and empty strings have zero length.

See also: isNull(), isEmpty()

§ local8Bit()

QCString QString::local8Bit ( ) const

Returns the string encoded in a locale-specific format. On X11, this is the QTextCodec::codecForLocale(). On Windows, it is a system-defined encoding.

See QTextCodec for more diverse coding/decoding of Unicode strings.

See also: QString::fromLocal8Bit(), latin1(), utf8()

§ lower()

QString QString::lower ( ) const

Returns a new string that is the string converted to lower case.

Example:

QString s("TeX");

QString t = s.lower(); // t == "tex"

See also: upper()

§ mid()

QString QString::mid	(	uint	index,
		uint	len = `0xffffffff`
	)		const

Returns a substring that contains the len characters of this string, starting at position index.

Returns a null string if the string is empty or index is out of range. Returns the whole string from index if index+len exceeds the length of the string.

Example:

QString s = "Five pineapples";

QString t = s.mid( 5, 4 ); // t == "pine"

See also: left(), right()

§ number() [1/5]

QString QString::number	(	long	n,
		int	base = `10`
	)

static

A convenience factory function that returns a string representation of the number n.

See also: setNum()

§ number() [2/5]

QString QString::number	(	ulong	n,
		int	base = `10`
	)

static

A convenience factory function that returns a string representation of the number n.

See also: setNum()

§ number() [3/5]

QString QString::number	(	int	n,
		int	base = `10`
	)

static

A convenience factory function that returns a string representation of the number n.

See also: setNum()

§ number() [4/5]

QString QString::number	(	uint	n,
		int	base = `10`
	)

static

A convenience factory function that returns a string representation of the number n.

See also: setNum()

§ number() [5/5]

QString QString::number	(	double	n,
		char	f = `'g'`,
		int	prec = `6`
	)

static

This static function returns the printed value of n, formatted in the f format with prec precision.

f can be 'f', 'F', 'e', 'E', 'g' or 'G', all of which have the same meaning as for sprintf().

See also: setNum()

§ operator!()

bool QString::operator! ( ) const

inline

Returns TRUE if it is a null string, otherwise FALSE. Thus you can write:

QString name = getName();
if ( !name )
  name = "Rodney";

Note that if you say:

QString name = getName();
if ( name )
  doSomethingWith(name);

Then this will call operator const char*(), which will do what you want, but rather inefficiently - you may wish to define the macro QT_NO_ASCII_CAST when writing code which you wish to strictly remain Unicode-clean.

When you want the above semantics, use !isNull() or even !!:

QString name = getName();
if ( !!name )
  doSomethingWith(name);

§ operator+=() [1/3]

QString & QString::operator+= ( const QString & str )

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

§ operator+=() [2/3]

QString & QString::operator+= ( QChar c )

Appends c to the string and returns a reference to the string.

§ operator+=() [3/3]

QString & QString::operator+= ( char c )

Appends c to the string and returns a reference to the string.

§ operator=() [1/5]

QString & QString::operator= ( const QString & s )

Assigns a shallow copy of s to this string and returns a reference to this string.

§ operator=() [2/5]

QString & QString::operator= ( const char * str )

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

If str is 0 a null string is created.

See also: isNull()

§ operator=() [3/5]

QString & QString::operator= ( const QCString & cs )

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

§ operator=() [4/5]

QString & QString::operator= ( QChar c )

inline

Sets the string to contain just the single character c.

§ operator=() [5/5]

QString & QString::operator= ( char c )

inline

Sets the string to contain just the single character c.

§ operator[]() [1/2]

QChar QString::operator[] ( int i ) const

inline

Returns the character at i, or QChar::null if i is beyond the length of the string.

Note: If this QString is not const or const&, the non-const operator[] will be used instead, which will expand the string if i is beyond the length of the string.

§ operator[]() [2/2]

QCharRef QString::operator[] ( int i )

inline

Returns an object that references the character at i. This reference can then be assigned to, or otherwise used immediately, but becomes invalid once further modifications are made to the string. The QCharRef internal class can be used much like a constant QChar, but if you assign to it, you change the original string (which enlarges and detaches itself). You will get compilation errors if you try to use the result as anything but a QChar.

§ prepend() [1/3]

QString & QString::prepend ( char ch )

inline

Prepends ch to the string and returns a reference to the result.

See also: insert()

§ prepend() [2/3]

QString & QString::prepend ( QChar ch )

inline

Prepends ch to the string and returns a reference to the result.

See also: insert()

§ prepend() [3/3]

QString & QString::prepend ( const QString & s )

inline

Prepend s to the string. Equivalent to insert(0,s).

See also: insert()

§ ref()

QChar & QString::ref ( uint i )

inline

Returns the QChar at i by reference.

See also: constref()

§ remove()

QString & QString::remove	(	uint	index,
		uint	len
	)

Removes len characters starting at position index from the string and returns a reference to the string.

If index is too big, nothing happens. If index is valid, but len is too large, the rest of the string is removed.

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

See also: insert(), replace()

§ replace() [1/3]

QString & QString::replace	(	uint	index,
		uint	len,
		const QString &	s
	)

Replaces len characters starting at position index from the string with s, and returns a reference to the string.

If index is too big, nothing is deleted and s is inserted at the end of the string. If index is valid, but len is too large, str replaces the rest of the string.

QString s = "Say yes!";

s.replace( 4, 3, "NO" ); // s == "Say NO!"

See also: insert(), remove()

§ replace() [2/3]

QString & QString::replace	(	uint	index,
		uint	len,
		const QChar *	s,
		uint	slen
	)

Replaces len characters starting at position index by slen units ot QChar data from s, and returns a reference to the string.

See also: insert(), remove()

§ replace() [3/3]

QString & QString::replace	(	const QRegExp &	rx,
		const QString &	str
	)

Replaces every occurrence of rx in the string with str. Returns a reference to the string.

Examples:

QString s = "banana";
s.replace( QRegExp("a.*a"), "" );     // becomes "b"
QString s = "banana";
s.replace( QRegExp("^[bn]a"), " " );  // becomes " nana"
QString s = "banana";
s.replace( QRegExp("^[bn]a"), "" );       // NOTE! becomes ""

See also: find() findRev()

§ right()

QString QString::right ( uint len ) const

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

The whole string is returned if len exceeds the length of the string.

Example:

QString s = "Pineapple";

QString t = s.right( 5 ); // t == "apple"

See also: left(), mid(), isEmpty()

§ rightJustify()

QString QString::rightJustify	(	uint	width,
		QChar	fill = `' '`,
		bool	truncate = `FALSE`
	)		const

Returns a string of length width that contains pad characters followed by the string.

If the length of the string exceeds width and truncate is FALSE, then the returned string is a copy of the string. If the length of the string exceeds width and truncate is TRUE, then the returned string is a left(width).

Example:

QString s("pie");

QString t = s.rightJustify(8, '.'); // t == ".....pie"

See also: leftJustify()

§ setExpand()

void QString::setExpand	(	uint	index,
		QChar	c
	)

Sets the character at position index to c and expands the string if necessary, filling with spaces.

This method is redundant in Qt 2.x, because operator[] will expand the string as necessary.

§ setLatin1()

QString & QString::setLatin1	(	const char *	str,
		int	len = `-1`
	)

Sets this string to str, interpreted as a classic Latin 1 C string. If the len argument is negative (default), it is set to strlen(str).

If str is 0 a null string is created. If str is "" an empty string is created.

See also: isNull(), isEmpty()

§ setNum() [1/8]

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

inline

Sets the string to the printed value of n and returns a reference to the string.

§ setNum() [2/8]

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

inline

Sets the string to the printed unsigned value of n and returns a reference to the string.

§ setNum() [3/8]

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

inline

Sets the string to the printed value of n and returns a reference to the string.

§ setNum() [4/8]

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

inline

Sets the string to the printed unsigned value of n and returns a reference to the string.

§ setNum() [5/8]

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

Sets the string to the printed value of n and returns a reference to the string.

The value is converted to base notation (default is decimal). The base must be a value from 2 to 36.

§ setNum() [6/8]

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

Sets the string to the printed unsigned value of n and returns a reference to the string.

The value is converted to base notation (default is decimal). The base must be a value from 2 to 36.

§ setNum() [7/8]

QString & QString::setNum	(	float	n,
		char	f = `'g'`,
		int	prec = `6`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

§ setNum() [8/8]

QString & QString::setNum	(	double	n,
		char	f = `'g'`,
		int	prec = `6`
	)

Sets the string to the printed value of n, formatted in the f format with prec precision, and returns a reference to the string.

f can be 'f', 'F', 'e', 'E', 'g' or 'G', all of which have the same meaning as for sprintf().

§ setUnicode()

QString & QString::setUnicode	(	const QChar *	unicode,
		uint	len
	)

Resizes the string to len unicode characters and copies unicode into the string. If unicode is null, nothing is copied, but the string is resized to len anyway. If len is zero, the string becomes a null string.

See also: setLatin1(), isNull()

§ setUnicodeCodes()

QString & QString::setUnicodeCodes	(	const ushort *	unicode_as_ushorts,
		uint	len
	)

Resizes the string to len unicode characters and copies unicode_as_ushorts into the string (on some X11 client platforms this will involve a byte-swapping pass).

If unicode is null, nothing is copied, but the string is resized to len anyway. If len is zero, the string becomes a null string.

See also: setLatin1(), isNull()

§ simplifyWhiteSpace()

QString QString::simplifyWhiteSpace ( ) const

Returns a new string that has white space removed from the start and the end, plus any sequence of internal white space replaced with a single space (ASCII 32).

White space means any character for which QChar::isSpace() returns TRUE. This includes ASCII characters 9 (TAB), 10 (LF), 11 (VT), 12 (FF), 13 (CR), and 32 (Space).

QString s = " lots\t of\nwhite space ";

QString t = s.simplifyWhiteSpace(); // t == "lots of white space"

See also: stripWhiteSpace()

§ sprintf()

QString & QString::sprintf	(	const char *	cformat,
			...
	)

Safely builds a formatted string from a format string and an arbitrary list of arguments. The format string supports all the escape sequences of printf() in the standard C library.

The s escape sequence expects a utf8() encoded string. The format string cformat is expected to be in latin1. If you need a unicode format string, use QString::arg() instead. For typesafe string building, with full Unicode support, you can use QTextOStream like this:

QString str;
QString s = ...;
int x = ...;
QTextOStream(&str) << s << " : " << x;

For translations, especially if the strings contains more than one escape sequence, you should consider using the arg() function instead. This allows the order of the replacements to be controlled by the translator, and has Unicode support.

See also: arg()

§ startsWith()

bool QString::startsWith ( const QString & s ) const

Returns whether the strings starts with s, or not.

§ stripWhiteSpace()

QString QString::stripWhiteSpace ( ) const

Returns a new string that has white space removed from the start and the end.

White space means any character for which QChar::isSpace() returns TRUE. This includes ASCII characters 9 (TAB), 10 (LF), 11 (VT), 12 (FF), 13 (CR), and 32 (Space).

Example:

QString s = " space ";

QString t = s.stripWhiteSpace(); // t == "space"

See also: simplifyWhiteSpace()

§ toDouble()

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

Returns the string converted to a double value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toFloat()

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

Returns the string converted to a float value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toInt()

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

Returns the string converted to a int value.

QString str("FF");
bool ok;
int hex = str.toInt( &ok, 16 ); // will return 255, and ok set to TRUE
int dec = str.toInt( &ok, 10 ); // will return 0, and ok set to FALSE

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toLong()

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

Returns the string converted to a long value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toShort()

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

Returns the string converted to a short value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toUInt()

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

Returns the string converted to an unsigned int value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toUInt64()

uint64 QString::toUInt64	(	bool *	ok = `0`,
		int	base = `10`
	)		const

Returns the string converted to an unsigned long value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toULong()

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

Returns the string converted to an unsigned long value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ toUShort()

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

Returns the string converted to an unsigned short value.

If ok is non-null, *ok is set to TRUE if there are no conceivable errors, and FALSE if the string is not a number at all, or if it has trailing garbage.

§ truncate()

void QString::truncate ( uint newLen )

Truncates the string at position newLen if newLen is less than the current length . Otherwise, nothing happens.

Example:

QString s = "truncate this string";

s.truncate( 5 ); // s == "trunc"

In Qt 1.x, it was possible to "truncate" a string to a longer length. This is no longer possible.

§ ucs2()

const unsigned short * QString::ucs2 ( ) const

Returns the QString as a zero terminated array of unsigned shorts if the string is not null; otherwise returns zero.

The result remains valid so long as one unmodified copy of the source string exists.

§ unicode()

const QChar * QString::unicode ( ) const

inline

Returns the Unicode representation of the string. The result remains valid until the string is modified.

§ upper()

QString QString::upper ( ) const

Returns a new string that is the string converted to upper case.

Example:

QString s("TeX");

QString t = s.upper(); // t == "TEX"

See also: lower()

§ utf8()

QCString QString::utf8 ( ) const

Returns the string encoded in UTF8 format.

See QTextCodec for more diverse coding/decoding of Unicode strings.

See also: QString::fromUtf8(), local8Bit(), latin1()

§ visual()

QString QString::visual	(	int	index = `0`,
		int	len = `-1`
	)

This function returns the QString ordered visually. Useful for painting the string or when transforming to a visually ordered encoding.

Friends And Related Function Documentation

§ operator!=() [1/3]

bool operator!=	(	const QString &	s1,
		const QString &	s2
	)

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

§ operator!=() [2/3]

bool operator!=	(	const QString &	s1,
		const char *	s2
	)

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

§ operator!=() [3/3]

bool operator!=	(	const char *	s1,
		const QString &	s2
	)

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

§ operator+() [1/5]

QString operator+	(	const QString &	s1,
		const QString &	s2
	)

§ operator+() [2/5]

QString operator+	(	const QString &	s1,
		const char *	s2
	)

§ operator+() [3/5]

QString operator+	(	const char *	s1,
		const QString &	s2
	)

§ operator+() [4/5]

QString operator+	(	const QString &	s,
		char	c
	)

§ operator+() [5/5]

QString operator+	(	char	c,
		const QString &	s
	)

§ operator<() [1/2]

bool operator<	(	const QString &	s1,
		const char *	s2
	)

Equivalent to qstrcmp(s1,s2) < 0.

§ operator<() [2/2]

bool operator<	(	const char *	s1,
		const QString &	s2
	)

Equivalent to qstrcmp(s1,s2) < 0.

§ operator<<()

QDataStream & operator<<	(	QDataStream &	s,
		const QString &	str
	)

See also: Format of the QDataStream operators

§ operator<=() [1/2]

bool operator<=	(	const QString &	s1,
		const char *	s2
	)

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

§ operator<=() [2/2]

bool operator<=	(	const char *	s1,
		const QString &	s2
	)

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

§ operator==() [1/3]

bool operator==	(	const QString &	s1,
		const QString &	s2
	)

Equivalent to qstrcmp(s1,s2) == 0.

§ operator==() [2/3]

bool operator==	(	const QString &	s1,
		const char *	s2
	)

Equivalent to qstrcmp(s1,s2) == 0.

§ operator==() [3/3]

bool operator==	(	const char *	s1,
		const QString &	s2
	)

Equivalent to qstrcmp(s1,s2) == 0.

§ operator>() [1/2]

bool operator>	(	const QString &	s1,
		const char *	s2
	)

Equivalent to qstrcmp(s1,s2) > 0.

§ operator>() [2/2]

bool operator>	(	const char *	s1,
		const QString &	s2
	)

Equivalent to qstrcmp(s1,s2) > 0.

§ operator>=() [1/2]

bool operator>=	(	const QString &	s1,
		const char *	s2
	)

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

§ operator>=() [2/2]

bool operator>=	(	const char *	s1,
		const QString &	s2
	)

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

§ operator>>

QDataStream & operator>>	(	QDataStream &	s,
		QString &	str
	)

friend

Reads a string from the stream.

See also: Format of the QDataStream operators

The documentation for this class was generated from the following files:

qtools/qstring.h
qtools/qstring.cpp

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Related Functions

Detailed Description

Constructor & Destructor Documentation

§ QString() [1/6]

§ QString() [2/6]

§ QString() [3/6]

§ QString() [4/6]

§ QString() [5/6]

§ QString() [6/6]

§ ~QString()

Member Function Documentation

§ append() [1/3]

§ append() [2/3]

§ append() [3/3]

§ arg() [1/10]

§ arg() [2/10]

§ arg() [3/10]

§ arg() [4/10]

§ arg() [5/10]

§ arg() [6/10]

§ arg() [7/10]

§ arg() [8/10]

§ arg() [9/10]

§ arg() [10/10]

§ ascii()

§ at() [1/2]

§ at() [2/2]

§ basicDirection()

§ compare() [1/2]

§ compare() [2/2]

§ compose()

§ constref()

§ contains() [1/5]

§ contains() [2/5]

§ contains() [3/5]

§ contains() [4/5]

§ contains() [5/5]

§ copy()

§ data()

§ fill()

§ find() [1/5]

§ find() [2/5]

§ find() [3/5]

§ find() [4/5]

§ find() [5/5]

§ findRev() [1/5]

§ findRev() [2/5]

§ findRev() [3/5]

§ findRev() [4/5]

§ findRev() [5/5]

§ fromLatin1()

§ fromLocal8Bit()

§ fromUcs2()

§ fromUtf8()

§ insert() [1/4]

§ insert() [2/4]

§ insert() [3/4]

§ insert() [4/4]

§ isEmpty()

§ isNull()

§ latin1()

§ left()

§ leftJustify()

§ length()

§ local8Bit()

§ lower()

§ mid()

§ number() [1/5]

§ number() [2/5]

§ number() [3/5]

§ number() [4/5]

§ number() [5/5]

§ operator!()

§ operator+=() [1/3]

§ operator+=() [2/3]