QString(3qt)QString(3qt)NAMEQString - Abstraction of Unicode text and the classic C
null-terminated char array (
#include <qstring.h>
Inherited by QConstString.
Public Members
QString ()
QString ( QChar )
QString ( const QString & )
QString ( const QByteArray & )
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 )
bool isNull () const
bool isEmpty () const
uint length () const
void truncate ( uint pos )
void fill ( QChar c, int len = -1 )
QString copy () const (obsolete)
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
Trolltech AS 13 June 2001 1
QString(3qt)QString(3qt)
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
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 ) (obsolete)
QString& operator+= ( const QString & str )
QString& operator+= ( QChar c )
QString& operator+= ( char c )
Trolltech AS 13 June 2001 2
QString(3qt)QString(3qt)
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 (obsolete)
const char* latin1 () const
QCString utf8 () const
QCString local8Bit () const
bool operator! () const
operator const char* ()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 )
bool startsWith ( const QString & ) const
Static Public Members
QString number ( long, int base=10 )
QString number ( ulong, int base=10 )
QString number ( int, int base=10 )
QString number ( uint, int base=10 )
QString number ( double, char f='g', int prec=6 )
QString fromLatin1 ( const char *, int len=-1 )
QString fromUtf8 ( const char *, int len=-1 )
QString fromLocal8Bit ( const char *, int len=-1 )
int compare ( const QString & s1, const QString & s2 )
RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
QDataStream & operator>> (QDataStream & s, QString & str)
QString operator+ (const char * s1, const QString & s2)
bool operator<= (const char * s1, const QString & s2)
QString operator+ (const QString & s1, const char * s2)
QString operator+ (const QString & s1, const QString & s2)
QDataStream & operator<< (QDataStream & s, const QString &
str)
bool operator== (const QString & 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 char * s1, const QString & s2)
QString operator+ (char c, const QString & s)
bool operator<= (const QString & s1, const char * s2)
QString operator+ (const QString & s, char c)
bool operator> (const char * s1, const QString & s2)
bool operator< (const QString & s1, const char * s2)
bool operator!= (const char * s1, const QString & s2)
Trolltech AS 13 June 2001 3
QString(3qt)QString(3qt)
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 QString & s1, const char * s2)
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 and Shared classes
Examples: showimg/main.cpp grapher/grapher.cpp
xform/xform.cpp layout/layout.cpp helpviewer/main.cpp
life/main.cpp i18n/main.cpp drawdemo/drawdemo.cpp
popup/popup.cpp menu/menu.cpp progress/progress.cpp
qmag/qmag.cpp forever/forever.cpp rot13/rot13.cpp
desktop/desktop.cpp scrollview/scrollview.cpp
movies/main.cpp picture/picture.cpp hello/main.cpp
MEMBER FUNCTION DOCUMENTATIONQString::QString ()
Constructs a null string.
See also isNull().
QString::QString ( QChar ch )
Constructs a string containing the one character ch.
Trolltech AS 13 June 2001 4
QString(3qt)QString(3qt)QString::QString ( const QByteArray & ba )
Constructs a string that is a deep copy of ba interpreted
as a classic C string.
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::QString ( const QString & s )
Constructs an implicitly-shared copy of s.
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 ()
Destroys the string and frees the "real" string, if this
was the last copy of that string.
QString::operator const char * () const
Returns latin1(). Be sure to see the warnings documented
there. Note that for new code which you wish to be
strictly Unicode-clean, you can define the macro
QT_NO_ASCII_CAST when compiling your code to hide this
function so that automatic casts are not done. This has
the added advantage that you catch the programming error
described under operator!().
QString& QString::append ( QChar ch )
Appends ch to the string and returns a reference to the
result. Equivalent to operator+=().
Trolltech AS 13 June 2001 5
QString(3qt)QString(3qt)QString& QString::append ( char ch )
Appends ch to the string and returns a reference to the
result. Equivalent to operator+=().
QString& QString::append ( const QString & str )
Appends str to the string and returns a reference to the
result. Equivalent to operator+=().
QString QString::arg ( const QString & a, int fieldwidth=0 )
const
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.
Warning: 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().
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.
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.
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
Trolltech AS 13 June 2001 6
QString(3qt)QString(3qt)
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().
QString QString::arg ( int 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.
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.
QString QString::arg ( short 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.
QString QString::arg ( uint 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.
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.
QString QString::arg ( ushort 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
Trolltech AS 13 June 2001 7
QString(3qt)QString(3qt)
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.
const char* QString::ascii () const
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
This functions simply calls latin1() and returns the
result.
QChar QString::at ( uint ) const
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.
QCharRef QString::at ( uint i )
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.
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.
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.
int QString::compare ( const QString & s1, const QString & s2 )
[static]
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.
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)Trolltech AS 13 June 2001 8
QString(3qt)QString(3qt)
('A') and QChar(0x0308) (Unicode accent diaresis) giving
QChar(0x00c4) (German A Umlaut).
QChar QString::constref ( uint i ) const
Equivalent to at(i), this returns the QChar at i by value.
See also ref().
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.
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() and findRev().
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().
int QString::contains ( char c, 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.
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.
QString QString::copy () const
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
Trolltech AS 13 June 2001 9
QString(3qt)QString(3qt)
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.
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.
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.
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() and contains().
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.
int QString::find ( const char * str, int index=0 ) const
Equivalent to find(QString(str), index).
int QString::find ( char c, int index=0, 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.
int QString::findRev ( QChar c, int index=-1, bool cs=TRUE )
const
Trolltech AS 13 June 2001 10
QString(3qt)QString(3qt)
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.
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().
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.
int QString::findRev ( const char * str, int index=-1 ) const
Equivalent to findRev(QString(str), index).
int QString::findRev ( char c, int index=-1, 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.
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.
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
Trolltech AS 13 June 2001 11
QString(3qt)QString(3qt)
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.
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.
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() and replace().
Examples: xform/xform.cpp
QString & QString::insert ( uint index, const QChar * s, uint len
)
Insert len units of QChar data from s into the string
before position index.
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"
Trolltech AS 13 June 2001 12
QString(3qt)QString(3qt)QString& QString::insert ( uint index, char c )
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
bool QString::isEmpty () const
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() and length().
Examples: qmag/qmag.cpp hello/main.cpp
bool QString::isNull () const
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() and length().
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() and local8Bit().
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:
Trolltech AS 13 June 2001 13
QString(3qt)QString(3qt)QString s = "Pineapple";
QString t = s.left( 4 ); // t == "Pine"
See also right(), mid() and isEmpty().
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().
uint QString::length () const
Returns the length of the string.
Null strings and empty strings have zero length.
See also isNull() and isEmpty().
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() and utf8().
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().
QString QString::mid ( uint index, uint len=0xffffffff ) const
Returns a substring that contains the len characters of
this string, starting at position index.
Trolltech AS 13 June 2001 14
QString(3qt)QString(3qt)
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() and right().
Examples: qmag/qmag.cpp
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().
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().
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().
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().
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().
bool QString::operator! () const
Returns TRUE if it is a null string, otherwise FALSE. Thus
you can write:
QString name = getName();
if ( !name )
name = "Rodney";
Trolltech AS 13 June 2001 15
QString(3qt)QString(3qt)
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);
QString & QString::operator+= ( QChar c )
Appends c to the string and returns a reference to the
string.
QString & QString::operator+= ( char c )
Appends c to the string and returns a reference to the
string.
QString& QString::operator+= ( const QString & str )
Appends str to the string and returns a reference to the
string.
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.
QString & QString::operator= ( const QString & s )
Assigns a shallow copy of s to this string and returns a
reference to this string.
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().
QString& QString::operator= ( QChar c )
Sets the string to contain just the single character c.
QString& QString::operator= ( char c )
Sets the string to contain just the single character c.
Trolltech AS 13 June 2001 16
QString(3qt)QString(3qt)QChar QString::operator[] ( int ) const
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.
QCharRef QString::operator[] ( int )
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.
QString & QString::prepend ( const QString & s )
Prepend s to the string. Equivalent to insert(0,s).
See also insert().
QString& QString::prepend ( QChar ch )
Prepends ch to the string and returns a reference to the
result.
See also insert().
QString& QString::prepend ( char ch )
Prepends ch to the string and returns a reference to the
result.
See also insert().
QChar& QString::ref ( uint i )
Returns the QChar at i by reference.
See also constref().
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() and replace().
Trolltech AS 13 June 2001 17
QString(3qt)QString(3qt)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() and findRev().
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() and remove().
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() and remove().
Examples: qmag/qmag.cpp
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() and isEmpty().
Trolltech AS 13 June 2001 18
QString(3qt)QString(3qt)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().
void QString::setExpand ( uint index, QChar c )
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
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.
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() and isEmpty().
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().
QString & QString::setNum ( int n, int base=10 )
Sets the string to the printed value of n and returns a
reference to the string.
QString & QString::setNum ( long n, int base=10 )
Sets the string to the printed value of n and returns a
reference to the string.
Trolltech AS 13 June 2001 19
QString(3qt)QString(3qt)
The value is converted to base notation (default is
decimal). The base must be a value from 2 to 36.
QString & QString::setNum ( short n, int base=10 )
Sets the string to the printed value of n and returns a
reference to the string.
QString & QString::setNum ( uint n, int base=10 )
Sets the string to the printed unsigned value of n and
returns a reference to the string.
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.
QString & QString::setNum ( ushort n, int base=10 )
Sets the string to the printed unsigned value of n and
returns a reference to the string.
QString & QString::setNum ( float n, char f='g', int prec=6 )
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
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() and isNull().
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() and isNull().
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
Trolltech AS 13 June 2001 20
QString(3qt)QString(3qt)
(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().
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().
Examples: xform/xform.cpp layout/layout.cpp
drawdemo/drawdemo.cpp popup/popup.cpp
progress/progress.cpp qmag/qmag.cpp forever/forever.cpp
scrollview/scrollview.cpp movies/main.cpp
picture/picture.cpp
bool QString::startsWith ( const QString & s ) const
Returns whether the strings starts with s, or not.
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"
Trolltech AS 13 June 2001 21
QString(3qt)QString(3qt)
See also simplifyWhiteSpace().
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.
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.
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.
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.
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.
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.
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
Trolltech AS 13 June 2001 22
QString(3qt)QString(3qt)
number at all, or if it has trailing garbage.
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.
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.
const QChar* QString::unicode () const
Returns the Unicode representation of the string. The
result remains valid until the string is modified.
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().
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() and latin1().
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.
RELATED FUNCTION DOCUMENTATIONQDataStream & operator>> (QDataStream & s, QString & str)
Reads a string from the stream.
See also Format of the QDataStream operators
Trolltech AS 13 June 2001 23
QString(3qt)QString(3qt)QString operator+ (const char * s1, const QString & s2)
Returns the concatenated string of s1 and s2.
bool operator<;= (const char * s1, const QString & s2)
Returns TRUE if s1 is alphabetically less than or equal to
s2, otherwise FALSE.
Equivalent to qstrcmp(s1,s2) <= 0
QString operator+ (const QString & s1, const char * s2)
Returns the concatenated string of s1 and s2.
QString operator+ (const QString & s1, const QString & s2)
Returns the concatenated string of s1 and s2.
QDataStream & operator<;< (QDataStream & s, const QString & str)
Writes a string to the stream.
See also Format of the QDataStream operators
bool operator== (const QString & s1, const QString & s2)
Returns TRUE if the two strings are equal, or FALSE if
they are different. A null string is different from an
empty, non-null string.
Equivalent to qstrcmp(s1,s2) == 0
bool operator!= (const QString & s1, const QString & s2)
Returns TRUE if the two strings are different, or FALSE if
they are equal.
Equivalent to qstrcmp(s1,s2) != 0
bool operator!= (const QString & s1, const char * s2)
Returns TRUE if the two strings are different, or FALSE if
they are equal.
Equivalent to qstrcmp(s1,s2) != 0
bool operator<; (const char * s1, const QString & s2)
Returns TRUE if s1 is alphabetically less than s2,
otherwise FALSE.
Equivalent to qstrcmp(s1,s2) < 0
bool operator>= (const char * s1, const QString & s2)
Returns TRUE if s1 is alphabetically greater than or equal
to s2, otherwise FALSE.
Equivalent to qstrcmp(s1,s2) >= 0
QString operator+ (char c, const QString & s)
Returns the concatenated string of c and s.
Trolltech AS 13 June 2001 24
QString(3qt)QString(3qt)bool operator<;= (const QString & s1, const char * s2)
Returns TRUE if s1 is alphabetically less than or equal to
s2, otherwise FALSE.
Equivalent to qstrcmp(s1,s2) <= 0
QString operator+ (const QString & s, char c)
Returns the concatenated string of s and c.
bool operator> (const char * s1, const QString & s2)
Returns TRUE if s1 is alphabetically greater than s2,
otherwise FALSE.
Equivalent to qstrcmp(s1,s2) > 0
bool operator<; (const QString & s1, const char * s2)
Returns TRUE if s1 is alphabetically less than s2,
otherwise FALSE.
Equivalent to qstrcmp(s1,s2) < 0
bool operator!= (const char * s1, const QString & s2)
Returns TRUE if the two strings are different, or FALSE if
they are equal.
Equivalent to qstrcmp(s1,s2) != 0
bool operator== (const QString & s1, const char * s2)
Returns TRUE if the two strings are equal, or FALSE if
they are different.
Equivalent to qstrcmp(s1,s2) == 0
bool operator== (const char * s1, const QString & s2)
Returns TRUE if the two strings are equal, or FALSE if
they are different.
Equivalent to qstrcmp(s1,s2) == 0
bool operator> (const QString & s1, const char * s2)
Returns TRUE if s1 is alphabetically greater than s2,
otherwise FALSE.
Equivalent to qstrcmp(s1,s2) > 0
bool operator>= (const QString & s1, const char * s2)
Returns TRUE if s1 is alphabetically greater than or equal
to s2, otherwise FALSE.
Equivalent to qstrcmp(s1,s2) >= 0
SEE ALSO
http://doc.trolltech.com/qstring.html
http://www.trolltech.com/faq/tech.html
Trolltech AS 13 June 2001 25
QString(3qt)QString(3qt)COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qstring.3qt)
and the Qt version (2.3.1).
Trolltech AS 13 June 2001 26
