Qt logo

QCString Class Reference


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

#include <qcstring.h>

Inherits QByteArray.

List of all member functions.

Public Members

Related Functions

(Note that these are not member functions.)

Detailed Description

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

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

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

You might use QCString for text that is never exposed to the user, but for text the user sees, you should use QString (which provides implicit sharing, Unicode and other internationalization support).

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

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

See also: Shared classes

Member Function Documentation

QCString::QCString ()

Constructs a null string.

See also: isNull().

QCString::QCString ( const QCString & s )

Constructs a shallow copy s.

See also: assign().

QCString::QCString ( const char * str )

Constructs a string that is a deep copy of str.

If str is 0 a null string is created.

See also: isNull().

QCString::QCString ( const char * str, uint maxlen )

Constructs a string that is a deep copy of str, that is no more than maxlen bytes long including the '\0'-terminator.

Example: 

    QCString str("helloworld",6); // Assigns "hello" to str.

If str contains a 0 byte within the first maxlen bytes, the resulting QCString will be terminated by the 0. If str is 0 a null string is created.

See also: isNull().

QCString::QCString ( 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.

See also: resize() and isNull().

QCString::operator const char * () const

Returns the string data.

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

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

int QCString::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 QCString::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 QCString::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".

See also: findRev().

QCString QCString::copy () const

Returns a deep copy of this string.

See also: detach().

bool QCString::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 QCString::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 QCString::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 QCString::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 QCString::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 QCString::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 QCString::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.

QCString & QCString::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: 

    QCString s = "Yes";
    s.insert( 3, '!');                          // s == "Yes!"

See also: remove() and replace().

QCString & QCString::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. 

    QCString 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 QCString::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 QCString::isNull () const

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

Example: 

    QCString a;         // a.data() == 0,  a.size() == 0, a.length() == 0
    QCString 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().

QCString QCString::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: 

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

See also: right() and mid().

QCString QCString::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: 

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

See also: rightJustify().

uint QCString::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().

QCString QCString::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: 

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

See also: upper().

QCString QCString::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: 

    QCString s = "Two pineapples";
    QCString t = s.mid( 4, 4 );                 // t == "pine"

See also: left() and right().

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

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

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

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

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

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

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

Assigns a deep copy of str to this string and returns a reference to this string.

If str is 0 a null string is created.

See also: isNull().

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

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

See also: insert().

QCString & QCString::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. 

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

See also: insert() and replace().

QCString & QCString::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 s = "banana";
    s.replace( QRegExp("^[bn]a"), " " );        // becomes " nana"

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

QCString & QCString::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. 

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

See also: insert() and remove().

bool QCString::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: 

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

See also: truncate().

QCString QCString::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: 

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

See also: left() and mid().

QCString QCString::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.

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: 

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

See also: leftJustify().

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

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

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

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

Sets the string to the printed value of n.

Arguments:

Returns a reference to the string.

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

Sets the string to the printed value of n.

Arguments:

Returns a reference to the string.

QCString & QCString::setNum ( int n )

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

QCString & QCString::setNum ( long n )

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

QCString & QCString::setNum ( short n )

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

QCString & QCString::setNum ( uint n )

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

QCString & QCString::setNum ( ulong n )

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

QCString & QCString::setNum ( ushort n )

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

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

Makes a deep copy of str. Returns a reference to the string.

QCString QCString::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 ASCII code 9, 10, 11, 12, 13 or 32. 

    QCString s = "  lots\t of\nwhite    space ";
    QCString t = s.simplifyWhiteSpace();                // t == "lots of white space"

See also: stripWhiteSpace().

QCString & QCString::sprintf ( const char * format, ... )

Implemented as a call to the native vsprintf() (see your C-library manual).

If your string is shorter than 256 characters, this sprintf() calls resize(256) to decrease the chance of memory corruption. The string is resized back to its natural length before sprintf() returns.

Example: 

    QCString s;
    s.sprintf( "%d - %s", 1, "first" );         // result < 256 chars

    QCString big( 25000 );                      // very long string
    big.sprintf( "%d - %s", 2, longString );    // result < 25000 chars

Warning: All vsprintf() implementations will write past the end of the target string (*this) if the format specification and arguments happen to be longer than the target string, and some will also fail if the target string is longer than some arbitrary implementation limit.

Giving user-supplied arguments to sprintf() is begging for trouble. Sooner or later someone will paste a 3000-character line into your application.

QCString QCString::stripWhiteSpace () const

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

White space means any ASCII code 9, 10, 11, 12, 13 or 32.

Example: 

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

See also: simplifyWhiteSpace().

double QCString::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 QCString::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 QCString::toInt ( bool * ok=0 ) const

Returns the string converted to a 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.

long QCString::toLong ( bool * ok=0 ) 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 QCString::toShort ( bool * ok=0 ) 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 QCString::toUInt ( bool * ok=0 ) 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 QCString::toULong ( bool * ok=0 ) 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.

ushort QCString::toUShort ( bool * ok=0 ) 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.

bool QCString::truncate ( uint pos )

Truncates the string at position pos.

Equivalent to calling resize(pos+1).

Example: 

    QCString s = "truncate this string";
    s.truncate( 5 );                            // s == "trunc"

See also: resize().

QCString QCString::upper () const

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

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

Example: 

    QCString s("TeX");
    QCString t = s.upper();                     // t == "TEX"

See also: lower().

Related Functions

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

Returns TRUE if the two strings are different, or FALSE if they are equal.

Equivalent to strcmp(s1,s2) != 0

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

Returns TRUE if the two strings are different, or FALSE if they are equal.

Equivalent to strcmp(s1,s2) != 0

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

Returns TRUE if the two strings are equal, or FALSE if they are different.

Equivalent to strcmp(s1,s2) == 0

char * qstrncpy (char * dst, const char * src, uint len)

A safe strncpy() function.

Copies all characters up to len bytes from str into dst and returns a pointer to dst. Guarantees that dst is \0-terminated. If src is null, it immediately returns 0.

See also: strcpy().

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

Writes a string to the stream.

Output format: [length (Q_UINT32) data...].

int strncmp (const char * str1, const char * str2, uint len)

A safe strncmp() function that overrides the one defined by the C library. The original strncmp() function has been renamed cstrncmp().

Compares str1 and str2 up to len bytes.

Returns a negative value if str1 is less than str2, 0 if str1 is equal to str2 or a positive value if str1 is greater than str2.

Special case I: Returns 0 if str1 and str2 are both null.

Special case II: Returns a random nonzero value if str1 is null or str2 is null (but not both).

See also: strcmp(), stricmp() and strnicmp().

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

Returns TRUE if s1 is alphabetically less than s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) < 0

void * memmove (void * dst, const void * src, uint len)

This function is normally part of the C library. Qt implements memmove() for platforms that do not have it.

memmove() copies len bytes from src into dst. The data is copied correctly even if src and dst overlap.

int strcmp (const char * str1, const char * str2)

A safe strcmp() function that overrides the one defined by the C library. The original strcmp() function has been renamed cstrcmp().

Compares str1 and str2. Returns a negative value if str1 is less than str2, 0 if str1 is equal to str2 or a positive value if str1 is greater than str2.

Special case I: Returns 0 if str1 and str2 are both null.

Special case II: Returns a random nonzero value if str1 is null or str2 is null (but not both).

See also: strncmp(), stricmp() and strnicmp().

Examples: desktop/desktop.cpp

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

Returns TRUE if s1 is alphabetically greater than s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) > 0

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

Reads a string from the stream.

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

Returns TRUE if s1 is alphabetically less than or equal to s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) <= 0

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

Returns TRUE if the two strings are different, or FALSE if they are equal.

Equivalent to strcmp(s1,s2) != 0

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

Returns TRUE if s1 is alphabetically less than or equal to s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) <= 0

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

Returns TRUE if s1 is alphabetically greater than or equal to s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) >= 0

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

Returns the concatenated string of s and c.

int stricmp (const char * str1, const char * str2)

A safe stricmp() function that overrides the one defined by the C library, if the C library has one.

Compares str1 and str2 ignoring the case.

Returns a negative value if str1 is less than str2, 0 if str1 is equal to str2 or a positive value if str1 is greater than str2.

Special case I: Returns 0 if str1 and str2 are both null.

Special case II: Returns a random nonzero value if str1 is null or str2 is null (but not both).

See also: strcmp(), strncmp() and strnicmp().

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

Returns the concatenated string of s1 and s2.

int strnicmp (const char * str1, const char * str2, uint len)

A safe strnicmp() function that overrides the one defined by the C library, if the C library has one.

Compares str1 and str2 up to len bytes ignoring the case.

Returns a negative value if str1 is less than str2, 0 if str1 is equal to str2 or a positive value if str1 is greater than str2.

Special case I: Returns 0 if str1 and str2 are both null.

Special case II: Returns a random nonzero value if str1 is null or str2 is null (but not both).

See also: strcmp(), strncmp() and stricmp().

char * qstrdup (const char * str)

Returns a duplicate string.

Allocates space for a copy of str (using new), copies it, and returns a pointer to the copy. If src is null, it immediately returns 0.

char * strcpy (char * dst, const char * str)

A safe strcpy() function that overrides the one defined by the C library. The original strcpy() function has been renamed cstrcpy().

Copies all characters (including \0) from str into dst and returns a pointer to dst. If src is null, it immediately returns 0.

See also: qstrncpy().

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

Returns the concatenated string of c and s.

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

Returns TRUE if s1 is alphabetically greater than or equal to s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) >= 0

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

Returns TRUE if the two strings are equal, or FALSE if they are different.

Equivalent to strcmp(s1,s2) == 0

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

Returns TRUE if s1 is alphabetically greater than s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) > 0

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

Returns the concatenated string of s1 and s2.

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

Returns TRUE if s1 is alphabetically less than s2, otherwise FALSE.

Equivalent to strcmp(s1,s2) < 0

uint strlen (const char * str)

A safe strlen() function that overrides the one defined by the C library. The original strlen() function has been renamed cstrlen().

Returns the number of characters in str, or 0 if str is null.

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

Returns the concatenated string of s1 and s2.

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

Returns TRUE if the two strings are equal, or FALSE if they are different.

Equivalent to strcmp(s1,s2) == 0

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

Copyright © 1999 Troll TechTrademarks
Qt version 2.0.2