Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions

QCString Class Reference

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

#include <QCString>

This class is part of the Qt 3 compatibility library. It is provided to keep old source code working. We strongly advise against using it in new code.

Inherits QByteArray.

Note: All the functions in this class are reentrant.

Public Functions

Static Public Members

Related Non-Members


Detailed Description

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

QCString tries to behave like a more convenient const char *. The price of doing this is that some algorithms will perform badly. For example, append() is O(length()) since it scans for a null terminator. Although you might use QCString for text that is never exposed to the user, for most purposes, and especially for user-visible text, you should use QString. QString provides implicit sharing, Unicode and other internationalization support, and is well optimized.

Note that for the QCString methods that take a const char * parameter the const char * must either be 0 (null) or not-null and '\0' (NUL byte) terminated; otherwise the results are undefined.

A QCString that has not been assigned to anything is null, i.e. both the length and the 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 produces a null QCString.

The length() function returns the length of the string; resize() resizes the string and truncate() truncates the string. A string can be filled with a character using fill(). Strings can be left or right padded with characters using leftJustify() and rightJustify(). Characters, strings and regular expressions can be searched for using find() and findRev(), and counted using contains().

Strings and characters can be inserted with insert() and appended with append(). A string can be prepended with prepend(). Characters can be removed from the string with remove() and replaced with replace().

Portions of a string can be extracted using left(), right() and mid(). Whitespace can be removed using stripWhiteSpace() and simplifyWhiteSpace(). Strings can be converted to uppercase or lowercase with upper() and lower() respectively.

Strings that contain numbers can be converted to numbers with toShort(), toInt(), toLong(), toULong(), toFloat() and toDouble(). Numbers can be converted to strings with setNum().

Many operators are overloaded to work with QCStrings. QCString also supports some more obscure functions, e.g. sprintf(), setStr() and setExpand().

Note on Character Comparisons

In QCString the notion of uppercase and lowercase and of which character is greater than or less than another character is locale dependent. This affects functions which support a case insensitive option or which compare or lowercase or uppercase their arguments. Case insensitive operations and comparisons will be accurate if both strings contain only ASCII characters. (If $LC_CTYPE is set, most Unix systems do "the right thing".) Functions that this affects include contains(), find(), findRev(), operator<(), operator<=(), operator>(), operator>=(), lower() and upper().

This issue does not apply to QStrings since they represent characters using Unicode.

Performance note: The QCString methods for QRegExp searching are implemented by converting the QCString to a QString and performing the search on that. This implies a deep copy of the QCString data. If you are going to perform many QRegExp searches on a large QCString, you will get better performance by converting the QCString to a QString yourself, and then searching in the QString.


Member Function Documentation

QCString::QCString ()

Constructs a null string.

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

Constructs a shallow copy s.

See also assign().

QCString::QCString ( const QByteArray & ba )

Constructs a copy of ba.

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 maxsize )

Constructs a string that is a deep copy of str. The copy will be at most maxsize bytes long including the '\0'-terminator.

Example:

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

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

See also isNull().

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

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

QCString QCString::copy () const

Returns a deep copy of this string.

See also detach().

QCString QCString::leftJustify ( uint width, char fill = ' ', bool truncate = false ) const

Returns a string of length width (plus one for the terminating '\0') that contains this string padded with the fill character.

If the length of the string exceeds width and truncate is false (the default), 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().

QCString QCString::lower () const

Use QByteArray::toLower() instead.

QCString QCString::rightJustify ( uint width, char fill = ' ', bool truncate = false ) const

Returns a string of length width (plus one for the terminating '\0') that contains zero or more of the fill character followed by this string.

If the length of the string exceeds width and truncate is false (the default), 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, padding with spaces.

Returns false if index was out of range and the string could not be expanded; otherwise returns true.

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

Sets the string to the string representation of the number n and returns a reference to the string.

The format of the string representation is specified by the format character f, and the precision (number of digits after the decimal point) is specified with prec.

The valid formats for f are 'e', 'E', 'f', 'g' and 'G'. The formats are the same as for sprintf(); they are explained in QString::arg().

QCString & QCString::setNum ( long n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

QCString & QCString::setNum ( ulong n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

QCString & QCString::setNum ( int n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

QCString & QCString::setNum ( uint n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

QCString & QCString::setNum ( short n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

QCString & QCString::setNum ( ushort n )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the string to the string representation of the number n and returns a reference to the string.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

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

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

QCString QCString::simplifyWhiteSpace () const

Use QByteArray::simplified() instead.

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

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

If the 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 actual 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 risky: Sooner or later someone will paste a huge line into your application.

QCString QCString::stripWhiteSpace () const

Use QByteArray::trimmed() instead.

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

Returns the string converted to a double value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

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

Returns the string converted to a float value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

int QCString::toInt ( bool * ok = 0 ) const

Returns the string converted to a int value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

long QCString::toLong ( bool * ok = 0 ) const

Returns the string converted to a long value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

short QCString::toShort ( bool * ok = 0 ) const

Returns the string converted to a short value.

If ok is not 0: *ok is set to false if the string is not a number, is out of range, or if it has trailing garbage; otherwise *ok is set to true.

uint QCString::toUInt ( bool * ok = 0 ) const

Returns the string converted to an unsigned int value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

ulong QCString::toULong ( bool * ok = 0 ) const

Returns the string converted to an unsigned long value.

If ok is not 0: *ok is set to false if the string is not a number, or if it has trailing garbage; otherwise *ok is set to true.

ushort QCString::toUShort ( bool * ok = 0 ) const

Returns the string converted to an unsigned short value.

If ok is not 0: *ok is set to false if the string is not a number, is out of range, or if it has trailing garbage; otherwise *ok is set to true.

QCString QCString::upper () const

Use QByteArray::toUpper() instead.

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 QByteArray & ba )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Assigns byte array ba to this QCString.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

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().


Related Non-Members

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

Returns true if s1 and s2 are different; otherwise returns false.

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

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 and s2 are different; otherwise returns false.

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

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 and s2 are different; otherwise returns false.

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

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

Returns a string which consists of the concatenation of s1 and s2.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a string which consists of the concatenation of s1 and s2.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a string which consists of the concatenation of s1 and s2.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a string which consists of the concatenation of s and c.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a string which consists of the concatenation of c and s.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is less than s2; otherwise returns false.

Equivalent to qstrcmp(s1, s2) < 0.

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is less than s2; otherwise returns false.

Equivalent to qstrcmp(s1, s2) < 0.

See also Note on character comparisons.

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

Writes string str to the stream s.

See also Format of the QDataStream operators.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is less than or equal to s2; otherwise returns false.

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

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is less than or equal to s2; otherwise returns false.

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

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 and s2 are equal; otherwise returns false.

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

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 and s2 are equal; otherwise returns false.

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

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 and s2 are equal; otherwise returns false.

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

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is greater than s2; otherwise returns false.

Equivalent to qstrcmp(s1, s2) > 0.

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is greater than s2; otherwise returns false.

Equivalent to qstrcmp(s1, s2) > 0.

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is greater than or equal to s2; otherwise returns false.

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

See also Note on character comparisons.

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

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns true if s1 is greater than or equal to s2; otherwise returns false.

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

See also Note on character comparisons.

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

Reads a string into str from the stream s.

See also Format of the QDataStream operators.


Copyright © 2004 Trolltech. Trademarks
Qt 4.0.0-tp2