Q3CString Class Reference
[Qt3Support module]

Detailed Description

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

Q3CString 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 Q3CString 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 Q3CString 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 default constructed Q3CString is null, i.e. both the length and the data pointer are 0 and isNull() returns true.

Note: However, if you ask for the data pointer of a null Q3CString by calling data(), then because the internal representation of the null Q3CString is shared, it will be detached and replaced with a non-shared, empty representation, a non-null data pointer will be returned, and subsequent calls to isNull() will return false. But if you ask for the data pointer of a null Q3CString by calling constData(), the shared internal representation is not detached, a null data pointer is returned, and subsequent calls to isNull() will continue to return true.

A Q3CString that references the empty string ("", a single '\0' char) is empty, i.e. isEmpty() returns true. Both null and empty Q3CStrings are legal parameters to the methods. Assigning const char * 0 to Q3CString produces a null Q3CString.

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 Q3CStrings. Q3CString also supports some more obscure functions, e.g. sprintf(), setStr() and setExpand().

Note on Character Comparisons

In Q3CString 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 Q3CString methods for QRegExp searching are implemented by converting the Q3CString to a QString and performing the search on that. This implies a deep copy of the Q3CString data. If you are going to perform many QRegExp searches on a large Q3CString, you will get better performance by converting the Q3CString to a QString yourself, and then searching in the QString.

Member Function Documentation

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

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

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

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

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