qcstring.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QCString 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QCString \- Abstraction of the classic C zero-terminated char array (char *)
.SH SYNOPSIS
All the functions in this class are reentrant when Qt is built with thread support.</p>
.PP
\fC#include <qcstring.h>\fR
.PP
Inherits QByteArray.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQCString\fR ()"
.br
.ti -1c
.BI "\fBQCString\fR ( int size )"
.br
.ti -1c
.BI "\fBQCString\fR ( const QCString & s )"
.br
.ti -1c
.BI "\fBQCString\fR ( const char * str )"
.br
.ti -1c
.BI "\fBQCString\fR ( const char * str, uint maxsize )"
.br
.ti -1c
.BI "QCString & \fBoperator=\fR ( const QCString & s )"
.br
.ti -1c
.BI "QCString & \fBoperator=\fR ( const char * str )"
.br
.ti -1c
.BI "bool \fBisNull\fR () const"
.br
.ti -1c
.BI "bool \fBisEmpty\fR () const"
.br
.ti -1c
.BI "uint \fBlength\fR () const"
.br
.ti -1c
.BI "bool \fBresize\fR ( uint len )"
.br
.ti -1c
.BI "bool \fBtruncate\fR ( uint pos )"
.br
.ti -1c
.BI "bool \fBfill\fR ( char c, int len = -1 )"
.br
.ti -1c
.BI "QCString \fBcopy\fR () const"
.br
.ti -1c
.BI "QCString & \fBsprintf\fR ( const char * format, ... )"
.br
.ti -1c
.BI "int \fBfind\fR ( char c, int index = 0, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBfind\fR ( const char * str, int index = 0, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBfind\fR ( const QRegExp & rx, int index = 0 ) const"
.br
.ti -1c
.BI "int \fBfindRev\fR ( char c, int index = -1, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBfindRev\fR ( const char * str, int index = -1, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBfindRev\fR ( const QRegExp & rx, int index = -1 ) const"
.br
.ti -1c
.BI "int \fBcontains\fR ( char c, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBcontains\fR ( const char * str, bool cs = TRUE ) const"
.br
.ti -1c
.BI "int \fBcontains\fR ( const QRegExp & rx ) const"
.br
.ti -1c
.BI "QCString \fBleft\fR ( uint len ) const"
.br
.ti -1c
.BI "QCString \fBright\fR ( uint len ) const"
.br
.ti -1c
.BI "QCString \fBmid\fR ( uint index, uint len = 0xffffffff ) const"
.br
.ti -1c
.BI "QCString \fBleftJustify\fR ( uint width, char fill = ' ', bool truncate = FALSE ) const"
.br
.ti -1c
.BI "QCString \fBrightJustify\fR ( uint width, char fill = ' ', bool truncate = FALSE ) const"
.br
.ti -1c
.BI "QCString \fBlower\fR () const"
.br
.ti -1c
.BI "QCString \fBupper\fR () const"
.br
.ti -1c
.BI "QCString \fBstripWhiteSpace\fR () const"
.br
.ti -1c
.BI "QCString \fBsimplifyWhiteSpace\fR () const"
.br
.ti -1c
.BI "QCString & \fBinsert\fR ( uint index, const char * s )"
.br
.ti -1c
.BI "QCString & \fBinsert\fR ( uint index, char c )"
.br
.ti -1c
.BI "QCString & \fBappend\fR ( const char * str )"
.br
.ti -1c
.BI "QCString & \fBprepend\fR ( const char * s )"
.br
.ti -1c
.BI "QCString & \fBremove\fR ( uint index, uint len )"
.br
.ti -1c
.BI "QCString & \fBreplace\fR ( uint index, uint len, const char * str )"
.br
.ti -1c
.BI "QCString & \fBreplace\fR ( const QRegExp & rx, const char * str )"
.br
.ti -1c
.BI "QCString & \fBreplace\fR ( char c, const char * after )"
.br
.ti -1c
.BI "QCString & \fBreplace\fR ( const char * before, const char * after )"
.br
.ti -1c
.BI "QCString & \fBreplace\fR ( char c1, char c2 )"
.br
.ti -1c
.BI "short \fBtoShort\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "ushort \fBtoUShort\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "int \fBtoInt\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "uint \fBtoUInt\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "long \fBtoLong\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "ulong \fBtoULong\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "float \fBtoFloat\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "double \fBtoDouble\fR ( bool * ok = 0 ) const"
.br
.ti -1c
.BI "QCString & \fBsetStr\fR ( const char * str )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( short n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( ushort n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( int n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( uint n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( long n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( ulong n )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( float n, char f = 'g', int prec = 6 )"
.br
.ti -1c
.BI "QCString & \fBsetNum\fR ( double n, char f = 'g', int prec = 6 )"
.br
.ti -1c
.BI "bool \fBsetExpand\fR ( uint index, char c )"
.br
.ti -1c
.BI "\fBoperator const char *\fR () const"
.br
.ti -1c
.BI "QCString & \fBoperator+=\fR ( const char * str )"
.br
.ti -1c
.BI "QCString & \fBoperator+=\fR ( char c )"
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
.in +1c
.ti -1c
.BI "void * \fBqmemmove\fR ( void * dst, const void * src, uint len )"
.br
.ti -1c
.BI "char * \fBqstrdup\fR ( const char * src )"
.br
.ti -1c
.BI "char * \fBqstrcpy\fR ( char * dst, const char * src )"
.br
.ti -1c
.BI "char * \fBqstrncpy\fR ( char * dst, const char * src, uint len )"
.br
.ti -1c
.BI "int \fBqstrcmp\fR ( const char * str1, const char * str2 )"
.br
.ti -1c
.BI "int \fBqstrncmp\fR ( const char * str1, const char * str2, uint len )"
.br
.ti -1c
.BI "int \fBqstricmp\fR ( const char * str1, const char * str2 )"
.br
.ti -1c
.BI "int \fBqstrnicmp\fR ( const char * str1, const char * str2, uint len )"
.br
.ti -1c
.BI "QDataStream & \fBoperator<<\fR ( QDataStream & s, const QCString & str )"
.br
.ti -1c
.BI "QDataStream & \fBoperator>>\fR ( QDataStream & s, QCString & str )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QCString & s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const QCString & s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator<\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator<\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator<=\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator<=\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator>\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator>\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "bool \fBoperator>=\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "bool \fBoperator>=\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "const QCString \fBoperator+\fR ( const QCString & s1, const QCString & s2 )"
.br
.ti -1c
.BI "const QCString \fBoperator+\fR ( const QCString & s1, const char * s2 )"
.br
.ti -1c
.BI "const QCString \fBoperator+\fR ( const char * s1, const QCString & s2 )"
.br
.ti -1c
.BI "const QCString \fBoperator+\fR ( const QCString & s, char c )"
.br
.ti -1c
.BI "const QCString \fBoperator+\fR ( char c, const QCString & s )"
.br
.in -1c
.SH DESCRIPTION
The QCString class provides an abstraction of the classic C zero-terminated char array (char *).
.PP
QCString inherits QByteArray, which is defined as QMemArray<char>. Since QCString is a QMemArray, it uses explicit sharing with a reference count.
.PP
QCString tries to behave like a more convenient \fCconst char *\fR. 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.
.PP
Note that for the QCString methods that take a \fCconst char *\fR parameter the \fCconst char *\fR must either be 0 (null) or not-null and '&#92;0' (NUL byte) terminated; otherwise the results are undefined.
.PP
A QCString that has not been assigned to anything is \fInull\fR, i.e. both the length and the data pointer is 0. A QCString that references the empty string ("", a single '&#92;0' char) is \fIempty\fR. Both null and empty QCStrings are legal parameters to the methods. Assigning \fCconst char *\fR 0 to QCString produces a null QCString.
.PP
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().
.PP
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().
.PP
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.
.PP
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().
.PP
Many operators are overloaded to work with QCStrings. QCString also supports some more obscure functions, e.g. sprintf(), setStr() and setExpand().
.PP
<blockquote><p align="center">\fB Note on Character Comparisons \fR
.PP
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 \fC$LC_CTYPE\fR is set, most Unix systems do "the right thing".) Functions that this affects include contains(), find(), findRev(), operator<(), operator<=(), operator>(), operator>=(), lower() and upper().
.PP
This issue does not apply to QStrings since they represent characters using Unicode. </blockquote>
.PP
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.
.PP
See also Collection Classes, Implicitly and Explicitly Shared Classes, Text Related Classes, and Non-GUI Classes.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QCString::QCString ()"
Constructs a null string.
.PP
See also isNull().
.SH "QCString::QCString ( int size )"
Constructs a string with room for \fIsize\fR characters, including the '&#92;0'-terminator. Makes a null string if \fIsize\fR == 0.
.PP
If \fIsize\fR > 0, then the first and last characters in the string are initialized to '&#92;0'. All other characters are uninitialized.
.PP
See also resize() and isNull().
.SH "QCString::QCString ( const QCString & s )"
Constructs a shallow copy \fIs\fR.
.PP
See also assign().
.SH "QCString::QCString ( const char * str )"
Constructs a string that is a deep copy of \fIstr\fR.
.PP
If \fIstr\fR is 0 a null string is created.
.PP
See also isNull().
.SH "QCString::QCString ( const char * str, uint maxsize )"
Constructs a string that is a deep copy of \fIstr\fR. The copy will be at most \fImaxsize\fR bytes long including the '&#92;0'-terminator.
.PP
Example:
.PP
.nf
.br
    QCString str( "helloworld", 6 ); // assigns "hello" to str
.br
.fi
.PP
If \fIstr\fR contains a 0 byte within the first \fImaxsize\fR bytes, the resulting QCString will be terminated by this 0. If \fIstr\fR is 0 a null string is created.
.PP
See also isNull().
.SH "QCString & QCString::append ( const char * str )"
Appends string \fIstr\fR to the string and returns a reference to the string. Equivalent to operator+=().
.SH "int QCString::contains ( char c, bool cs = TRUE ) const"
Returns the number of times the character \fIc\fR occurs in the string.
.PP
The match is case sensitive if \fIcs\fR is TRUE, or case insensitive if \fIcs\fR if FALSE.
.PP
See also Note on character comparisons.
.SH "int QCString::contains ( const char * str, bool cs = TRUE ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP