QString Class Reference

The QString class provides an abstraction of the classic C zero-terminated char array (char*). More...

#include <qstring.h>

Inherits QByteArray.

List of all member functions.

Public Members

QString ()
QString (int size)
QString (const QString& s)
QString (const char* str)
QString& operator= (const QString& s)
QString& operator= (const char* str)
bool isNull () const
bool isEmpty () const
uint length () const
bool resize (uint newlen)
bool truncate (uint pos)
bool fill (char c, int len = -1)
QString copy () const
QString& sprintf (const char* format, ...)
int find (char c, int index=0, bool cs=TRUE) const
int find (const char* str, int index=0, bool cs=TRUE) const
int find (const QRegExp&, int index=0) const
int findRev (char c, int index=-1, bool cs=TRUE) const
int findRev (const char* str, int index=-1, bool cs=TRUE) const
int findRev (const QRegExp&, int index=-1) const
int contains (char c, bool cs=TRUE) const
int contains (const char* 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) const
QString leftJustify (uint width, char fill=' ', bool trunc=FALSE) const
QString rightJustify (uint width, char fill=' ', bool trunc=FALSE) const
QString lower () const
QString upper () const
QString stripWhiteSpace () const
QString simplifyWhiteSpace () const
QString& insert (uint index, const char*)
QString& insert (uint index, char)
QString& prepend (const char*)
QString& remove (uint index, uint len)
QString& replace (uint index, uint len, const char*)
QString& replace (const QRegExp&, const char*)
short toShort (bool* ok=0) const
ushort toUShort (bool* ok=0) const
int toInt (bool* ok=0) const
uint toUInt (bool* ok=0) const
long toLong (bool* ok=0) const
ulong toULong (bool* ok=0) const
float toFloat (bool* ok=0) const
double toDouble (bool* ok=0) const
QString& setStr (const char* s)
QString& setNum (short)
QString& setNum (ushort)
QString& setNum (int)
QString& setNum (uint)
QString& setNum (long)
QString& setNum (ulong)
QString& setNum (float, char f='g', int prec=6)
QString& setNum (double, char f='g', int prec=6)
bool setExpand (uint index, char c)
operator const char* ()const
QString& operator+= (const char* str)
QString& operator+= (char c)

Related Functions

(Note that these are not member functions.)

void * memmove ( void *dst, const void *src, uint len)
char * qstrdup ( const char *str)
uint strlen ( const char *str)
char * strcpy ( char *dst, const char *str)
char * qstrncpy ( char *dst, const char *src, uint len)
int strcmp ( const char *str1, const char *str2)
int strncmp ( const char *str1, const char *str2, uint len)
int stricmp ( const char *str1, const char *str2)
int strnicmp ( const char *str1, const char *str2, uint len)
QDataStream & operator<< ( QDataStream &s, const QString &str)
QDataStream & operator>> ( QDataStream &s, QString &str)
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)

Detailed Description

The QString class provides an abstraction of the classic C zero-terminated char array (char*).

QString inherits QByteArray, which is defined as QArray<char>.

Since QString is a QArray, it uses explicit sharing with a reference count.

Note that for the QString methods that take a const char * parameter the results are undefined if the QString is not zero-terminated. It is legal for the const char * parameter to be 0.

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.

Member Function Documentation

QString::QString ( const QString &s)

Constructs a shallow copy s.

QString::QString ( const char *str)

Constructs a string that is a deep copy of str.

QString::QString ( int size)

Constructs a string with room for size characters, including the '\0'-terminator. Makes a null string if size == 0.

If size > 0, then the first and last characters in the string are initialized to '\0'. All other characters are uninitialized.

QString::QString ()

Constructs a null string.

QString::operator const char * () const

Returns the string data.

int QString::contains ( char 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 if 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

int QString::contains ( const char *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 if FALSE.

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

QString QString::copy () const

Returns a deep copy of this string.

bool QString::fill ( char c, int len = -1)

Fills the string with len bytes of value c, followed by a '\0'-terminator.

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

Returns FALSE is len is nonnegative and there is no memory to resize the string, otherwise TRUE is returned.

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

Finds the first occurrence of the character c, starting at position index.

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.

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

int QString::find ( const char *str, int index=0, bool cs=TRUE) const

Finds the first occurrence of the string str, starting at position index.

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 ( char c, int index=-1, bool cs=TRUE) const

Finds the first occurrence of the character c, starting at position index and searching backwards.

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.

The search will start from the end of the string if index is negative.

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

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

Finds the first occurrence of the string str, starting at position index and searching backwards.

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.

QString & QString::insert ( uint index, char 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 = "Yes";
    s.insert( 3, '!');                          // s == "Yes!"

QString & QString::insert ( uint index, const char *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"

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(), length() and size().

bool QString::isNull () const

Returns TRUE if the string is null, i.e. if data() == 0. A null string is also an empty string.

Example:

    QString a;          // a.data() == 0,  a.size() == 0, a.length() == 0
    QString b == "";    // b.data() == "", b.size() == 1, b.length() == 0
    a.isNull();         // TRUE, because a.data() == 0
    a.isEmpty();        // TRUE, because a.length() == 0
    b.isNull();         // FALSE, because b.data() == ""
    b.isEmpty();        // TRUE, because b.length() == 0

See also: isEmpty(), length() and size().

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"

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

Returns a string of length width (plus '\0') 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..."

uint QString::length () const

Returns the length of the string, excluding the '\0'-terminator. Equivalent to calling strlen(data()).

Null strings and empty strings have zero length.

See also: size(), isNull() and isEmpty().

QString QString::lower () const

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

Presently it only handles 7-bit ASCII, or whatever tolower() handles (if $LC_CTYPE is set, most UNIX systems do the Right Thing).

Example:

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

QString QString::mid ( uint index, uint len) 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 = "Two pineapples";
    QString t = s.mid( 4, 4 );                  // t == "pine"

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

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

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

Appends str to the string and returns a reference to the 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 to this string and returns a reference to this string.

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

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

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 = "neutrino";
    s.remove( 1, 6 );                           // s == "no"

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

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

Example:

    QString s = "banana";
    s.replace( QRegExp("a.*a"), "" );           // becomes "b"

QString & QString::replace ( uint index, uint len, const char *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!"

bool QString::resize ( uint len)

Extends or shrinks the string to len bytes, including the '\0'-terminator.

A \0-terminator is set at position len - 1 unless len == 0.

Example:

    QString s = "resize this string";
    s.resize( 7 );                              // s == "resize"

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"

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

Returns a string of length width (plus '\0') that contains pad characters followed by the string.

Example:

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

bool QString::setExpand ( uint index, char c)

Sets the character at position index to c and expands the string if necessary.

Returns FALSE if this index was out of range and the string could not be expanded, otherwise TRUE.

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

Sets the string to the printed value of n.

Arguments:

f is the format specifier: 'f', 'F', 'e', 'E', 'g', 'G' (same as sprintf()).
prec is the precision.

Returns a reference to the string.

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

Sets the string to the printed value of n.

Arguments:

f is the format specifier: 'f', 'F', 'e', 'E', 'g', 'G' (same as sprintf()).
prec is the precision.

Returns a reference to the string.

QString & QString::setNum ( int n)

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

QString & QString::setNum ( long n)

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

QString & QString::setNum ( short n)

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

QString & QString::setNum ( uint n)

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

QString & QString::setNum ( ulong n)

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

QString & QString::setNum ( ushort n)

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

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

Makes a deep copy of str NO" ( const char *str)

Makes a deep copy of str NO" (