qstring.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

.br
.ti -1c
.BI "bool \fBoperator==\fR (const QString & " "s1" ", const char * " "s2" ")"
.br
.ti -1c
.BI "bool \fBoperator==\fR (const char * " "s1" ", const QString & " "s2" ")"
.br
.ti -1c
.BI "bool \fBoperator>\fR (const QString & " "s1" ", const char * " "s2" ")"
.br
.ti -1c
.BI "bool \fBoperator>=\fR (const QString & " "s1" ", const char * " "s2" ")"
.br
.in -1c
.SH DESCRIPTION
The QString class provides an abstraction of Unicode text and the classic C zero-terminated char array (\fIchar*\fR).
.PP
QString uses implicit sharing, and so it is very efficient and easy to use.
.PP
In all QString methods that take \fIconst char*\fR parameters, the \fIconst char*\fR is interpreted as a classic C-style 0-terminated ASCII string. It is legal for the \fIconst char*\fR parameter to be 0. The results are undefined if the \fIconst char*\fR string is not 0-terminated. Functions that copy classic C strings into a QString will not copy the terminating 0-character. The QChar array of the QString (as returned by unicode()) is not terminated by a null.
.PP
A QString that has not been assigned to anything is \fInull,\fR i.e. both the length and data pointer is 0. A QString that references the empty string ("", a single '\\0' char) is \fIempty.\fR Both null and empty QStrings are legal parameters to the methods. Assigning \fIconst char * 0\fR to QString gives a null QString.
.PP
Note that if you find that you are mixing usage of QCString, QString, and QByteArray, this causes lots of unnecessary copying and might indicate that the true nature of the data you are dealing with is uncertain. If the data is NUL-terminates 8-bit data, use QCString; if it is unterminated (ie. contains NULs) 8-bit daya, use QByteArray; if it is text, use QString.
.PP
See also: Shared classes
.PP
Examples:
.(l
qdir/qdir.cpp showimg/main.cpp tabdialog/tabdialog.cpp grapher/grapher.cpp xform/xform.cpp layout/layout.cpp i18n/main.cpp drawdemo/drawdemo.cpp popup/popup.cpp progress/progress.cpp qmag/qmag.cpp table/main.cpp forever/forever.cpp rot13/rot13.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp picture/picture.cpp hello/main.cpp qbrowser/main.cpp
.)l
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QString::QString ()"
Constructs a null string.
.PP
See also: isNull().
.SH "QString::QString ( QChar ch )"
Constructs a string containing the one character \fIch.\fR
.SH "QString::QString ( const QChar * unicode, uint length )"
Constructs a string that is a deep copy of the first \fIlength\fR QChar in the array \fIunicode.\fR
.PP
See also: QString::make().
.SH "QString::QString ( const QByteArray & ba )"
Constructs a string that is a deep copy of \fIba\fR interpreted as interpreted as a classic C string.
.SH "QString::QString ( const QString & s )"
Constructs an implicitly-shared copy of \fIs.\fR
.SH "QString& QString::append ( char ch )"
Appends \fIch\fR to the string and returns a reference to the result. Equivalent to operator+=().
.SH "QString& QString::append ( const QString & str )"
Appends \fIstr\fR to the string and returns a reference to the result. Equivalent to operator+=().
.SH "QString QString::arg ( QChar a, int fieldwidth=0 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the character \fIa.\fR
.PP
See arg(const QString&,int) for more details.
.SH "QString QString::arg ( char a, int fieldwidth=0 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the character \fIa.\fR
.PP
See arg(const QString&,int) for more details.
.SH "QString QString::arg ( const QString & a, int fieldwidth=0 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the text \fIa.\fR This is particularly useful for translations, as it allows the order of the replacements to be controlled by the translator. For example:
.PP
.nf
.br
    label.setText( tr("I have %1 to your %2").arg(mine).arg(yours) );
.fi
.PP
If there is no \fC%\fIdigit\fR\fR pattern, a warning message (qWarning()) is printed and the text as appended with a space at the end of the string. This is error-recovery and should not be occur in correct code.
.PP
\fIfieldwidth\fR is the minimum amount of space the text will be padded to. A positive value produces right-aligned text, while a negative value produces left aligned text.
.PP
See also: QObject::tr().
.SH "QString QString::arg ( double a, int fieldwidth=0, char fmt='g', int prec=-1 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the value \fIa.\fR
.PP
See arg(const QString&,int) for more details.
.SH "QString QString::arg ( int a, int fieldwidth=0, int base=10 ) const"
See QString::arg(long a, int fieldwidth, int base).
.SH "QString QString::arg ( long a, int fieldwidth=0, int base=10 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the integer value \fIin\fR base \fIbase\fR (defaults to decimal).
.PP
The value is converted to \fIbase\fR notation (default is decimal). The base must be a value from 2 to 36.
.PP
See arg(const QString&,int) for more details.
.SH "QString QString::arg ( short a, int fieldwidth=0, int base=10 ) const"
See QString::arg(long a, int fieldwidth, int base).
.SH "QString QString::arg ( uint a, int fieldwidth=0, int base=10 ) const"
See QString::arg(ulong a, int fieldwidth, int base).
.SH "QString QString::arg ( ulong a, int fieldwidth=0, int base=10 ) const"
Returns a string equal to this one, but with the first occurrence of \fC%\fIdigit\fR\fR replaced by the unsigned integer value \fIin\fR base \fIbase\fR (defaults to decimal).
.PP
The value is converted to \fIbase\fR notation (default is decimal). The base must be a value from 2 to 36.
.PP
See arg(const QString&,int) for more details.
.SH "QString QString::arg ( ushort a, int fieldwidth=0, int base=10 ) const"
See QString::arg(ulong a, int fieldwidth, int base).
.SH "QChar QString::at ( uint ) const"
Returns the character at \fIi,\fR or 0 if \fIi\fR is beyond the length of the string.
.PP
Note: If this QString is not const or const&, the non-const at() will be used instead, which will expand the string if \fIi\fR is beyond the length of the string.
.SH "QCharRef QString::at ( uint i )"
Returns a reference to the character at \fIi,\fR expanding the string with QChar::null if necessary. The resulting reference can then be assigned to, or otherwise used immediately, but becomes invalid once further modifications are made to the string.
.SH "QChar::Direction QString::basicDirection()"
This function returns the basic directionality of the string (QChar::DirR for right to left and QChar::DirL for left to right). Useful to find the right alignment.
.SH "int QString::compare ( const QString & s ) const"
Compares this string to \fIs,\fR returning an integer less than, equal to, or greater than zero if it is, respectively, lexically less than, equal to, or greater than \fIs.\fR
.SH "int QString::compare ( const QString & s1, const QString & s2 ) \fC[static]\fR"
Compare \fIs1\fR to \fIs2\fR returning an integer less than, equal to, or greater than zero if s1 is, respectively, lexically less than, equal to, or greater than s2.
.SH "void QString::compose ()"
Note that this function is not supported in Qt 2.0, and is merely for experimental and illustrative purposes. It is mainly of interest to those experimenting with Arabic and other composition-rich texts.
.PP
Applies possible ligatures to a QString, useful when composition-rich text requires rendering with glyph-poor fonts, but also makes compositions such as QChar(0x0041) ('A') and QChar(0x0308) (Unicode accent diaresis) giving QChar(0x00c4) (German A Umlaut).
.SH "int QString::contains ( QChar 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.
.SH "int QString::contains ( const QRegExp & rx ) const"
Counts the number of overlapping occurrences of \fIrx\fR in the string.
.PP
Example:
.PP
.nf
.br
    QString s = "banana and panama";
.br
    QRegExp r = QRegExp("a[nm]a", TRUE, FALSE);
.br
    s.contains( r );                            // 4 matches
.fi
.PP
See also: find() and findRev().
.SH "int QString::contains ( const QString & str, bool cs=TRUE ) const"
Returns the number of times \fIstr\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
This function counts overlapping substrings, for example, "banana" contains two occurrences of "ana".
.PP
See also: findRev().
.SH "int QString::contains ( char c, bool cs=TRUE ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QString QString::copy () const"
\fBThis function is obsolete.\fR It is provided to keep old programs working. We strongly advise against using it in new code.
.PP
Returns a deep copy of this string.
.PP
Doing this is redundant in Qt 2.x, since QString is implicitly shared, and so will automatically be deeply copied as necessary.
.SH "void QString::fill ( QChar c, int len = -1 )"
Fills the string with \fIlen\fR characters of value \fIc.\fR
.PP
If \fIlen\fR is negative, the current string length is used.
.SH "int QString::find ( QChar c, int index=0, bool cs=TRUE ) const"
Finds the first occurrence of the character \fIc,\fR starting at position \fIindex.\fR
.PP
The search is case sensitive if \fIcs\fR is TRUE, or case insensitive if \fIcs\fR is FALSE.
.PP
Returns the position of \fIc,\fR or -1 if \fIc\fR could not be found.
.SH "int QString::find ( const QRegExp & rx, int index=0 ) const"
Finds the first occurrence of the regular expression \fIrx,\fR starting at position \fIindex.\fR
.PP
Returns the position of the next match, or -1 if \fIrx\fR was not found.
.SH "int QString::find ( const QString & str, int index=0, bool cs=TRUE ) const"
Finds the first occurrence of the string \fIstr,\fR starting at position \fIindex.\fR
.PP
The search is case sensitive if \fIcs\fR is TRUE, or case insensitive if \fIcs\fR is FALSE.
.PP
Returns the position of \fIstr,\fR or -1 if \fIstr\fR could not be found.
.SH "int QString::find ( char c, int index=0, bool cs=TRUE ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "int QString::findRev ( QChar c, int index=-1, bool cs=TRUE ) const"
Finds the first occurrence of the character \fIc,\fR starting at position \fIindex\fR and searching backwards. If \fIindex\fR is negative, the search starts at the end.
.PP
The search is case sensitive if \fIcs\fR is TRUE, or case insensitive if \fIcs\fR is FALSE.
.PP
Returns the position of \fIc,\fR or -1 if \fIc\fR could not be found.
.SH "int QString::findRev ( const QRegExp & rx, int index=-1 ) const"
Finds the first occurrence of the regular expression \fIrx,\fR starting at position \fIindex\fR and searching backwards. If \fIindex\fR is negative, the search starts at the end of this string.
.PP
Returns the position of the next match (backwards), or -1 if \fIrx\fR was not found.
.SH "int QString::findRev ( const QString & str, int index=-1, bool cs=TRUE ) const"
Finds the first occurrence of the string \fIstr,\fR starting at position \fIindex\fR and searching backwards. If \fIindex\fR is negative, the search starts at the end.
.PP
The search is case sensitive if \fIcs\fR is TRUE, or case insensitive if \fIcs\fR is FALSE.
.PP
Returns the position of \fIstr,\fR or -1 if \fIstr\fR could not be found.
.SH "int QString::findRev ( char c, int index=-1, bool cs=TRUE ) const"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QString QString::fromLatin1 ( const char * chars, int len=-1 ) \fC[static]\fR"
Creates a QString from Latin1 text. This is the same as the QString(const char*) constructor, but you can make that constructor invisible if you compile with the define QT_NO_CAST_ASCII, in which case you can explicitly create a QString from Latin-1 text using this function.
.SH "QString QString::fromLocal8Bit ( const char * local8Bit, int len=-1 ) \fC[static]\fR"
Returns the unicode string decoded from the first \fIlen\fR bytes of \fIlocal8Bit.\fR If \fIlen\fR is -1 (the default), the length of \fIlocal8Bit\fR is used. If trailing partial characters are in \fIlocal8Bit,\fR they are ignored.
.PP
\fIlocal8Bit\fR is assumed to be encoded in a locale-specific format.
.PP
See QTextCodec for more diverse coding/decoding of Unicode strings.
.SH "QString QString::fromUtf8 ( const char * utf8, int len=-1 ) \fC[static]\fR"
Returns the unicode string decoded from the first \fIlen\fR bytes of \fIutf8.\fR If \fIlen\fR is -1 (the default), the length of \fIutf8\fR is used. If trailing partial characters are in \fIutf8,\fR they are ignored.
.PP
See QTextCodec for more diverse coding/decoding of Unicode strings.
.SH "QString & QString::insert ( uint index, QChar c )"
Insert \fIc\fR into the string at (before) position \fIindex\fR and returns a reference to the string.
.PP
If \fIindex\fR is beyond the end of the string, the string is extended with spaces (ASCII 32) to length \fIindex\fR and \fIc\fR is then appended.
.PP
Example:
.PP
.nf
.br
    QString s = "Ys";
.br
    s.insert( 1, 'e' );                         // s == "Yes"
.br
    s.insert( 3, '!');                          // s == "Yes!"
.fi
.PP
See also: remove() and replace().
.PP
Examples:
.(l
xform/xform.cpp
.)l
.SH "QString & QString::insert ( uint index, const QChar * s, uint len )"
Insert \fIlen\fR units of QChar data from \fIs\fR into the string before position \fIindex.\fR
.SH "QString & QString::insert ( uint index, const QString & s )"
Insert \fIs\fR into the string before position \fIindex.\fR
.PP
If \fIindex\fR is beyond the end of the string, the string is extended with spaces (ASCII 32) to length \fIindex\fR and \fIs\fR is then appended.
.PP
.nf
.br
    QString s = "I like fish";
.br
    s.insert( 2, "don't ");                     // s == "I don't like fish"
.br
    s = "x";
.br
    s.insert( 3, "yz" );                        // s == "x  yz"
.fi
.SH "QString& QString::insert ( uint index, char c )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "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.
.PP
See example in isNull().
.PP
See also: isNull() and length().
.PP
Examples:
.(l
qmag/qmag.cpp hello/main.cpp
.)l
.SH "bool QString::isNull () const"
Returns TRUE if the string is null. A null string is also an empty string.
.PP
Example:
.PP
.nf
.br
    QString a;          // a.unicode() == 0,  a.length() == 0
.br
    QString b == "";    // b.unicode() == "", b.length() == 0
.br
    a.isNull();         // TRUE, because a.unicode() == 0
.br
    a.isEmpty();        // TRUE, because a.length() == 0
.br
    b.isNull();         // FALSE, because b.unicode() != 0
.br
    b.isEmpty();        // TRUE, because b.length() == 0
.fi
.PP
See also: isEmpty() and length().
.PP
Examples:
.(l
qdir/qdir.cpp
.)l
.SH "const char* QString::latin1 () const"
Returns a Latin-1 representation of the string. Note that the returned value is undefined if the string contains non-Latin-1 characters. If you want to convert strings into formats other than Unicode, see the QTextCodec classes.
.PP
This function is mainly useful for boot-strapping legacy code to use Unicode.
.PP
The result remains valid so long as one unmodified copy of the string exists.
.PP
See also: utf8() and local8Bit().
.SH "QString QString::left ( uint len ) const"
Returns a substring that contains the \fIlen\fR leftmost characters of the string.
.PP
The whole string is returned if \fIlen\fR exceeds the length of the string.
.PP
Example:
.PP
.nf
.br
    QString s = "Pineapple";
.br
    QString t = s.left( 4 );                    // t == "Pine"
.fi
.PP
See also: right(), mid() and isEmpty().
.SH "QString QString::leftJustify ( uint width, QChar fill=' ', bool truncate=FALSE ) const"
Returns a string of length \fIwidth\fR that contains this string and padded by the \fIfill\fR character.
.PP
If the length of the string exceeds \fIwidth\fR and \fItruncate\fR is FALSE, then the returned string is a copy of the string. If the length of the string exceeds \fIwidth\fR and \fItruncate\fR is TRUE, then the returned string is a left(\fIwidth).\fR
.PP
Example:
.PP
.nf
.br
    QString s("apple");
.br
    QString t = s.leftJustify(8, '.');          // t == "apple..."
.fi
.PP
See also: rightJustify().
.SH "uint QString::length () const"
Returns the length of the string.
.PP
Null strings and empty strings have zero length.
.PP
See also: isNull() and isEmpty().
.SH "QCString QString::local8Bit () const"
Returns the string encoded in a locale-specific format. On X11, this is the QTextCodec::codecForLocale(). On Windows, it is a system-defined encoding.
.PP
See QTextCodec for more diverse coding/decoding of Unicode strings.
.PP
See also: QString::fromLocal8Bit(), local8Bit() and utf8().
.SH "QString QString::lower () const"
Returns a new string that is the string converted to lower case.
.PP
Example:
.PP
.nf
.br
    QString s("TeX");
.br
    QString t = s.lower();                      // t == "tex"
.fi
.PP
See also: upper().
.SH "QString QString::mid ( uint index, uint len=0xffffffff ) const"
Returns a substring that contains the \fIlen\fR characters of this string, starting at position \fIindex.\fR
.PP
Returns a null string if the string is empty or \fIindex\fR is out of range. Returns the whole string from \fIindex\fR if \fIindex+len\fR exceeds the length of the string.
.PP
Example:
.PP
.nf
.br
    QString s = "Two pineapples";
.br
    QString t = s.mid( 4, 4 );                  // t == "pine"
.fi
.PP
See also: left() and right().
.PP
Examples:
.(l
qmag/qmag.cpp
.)l
.SH "QString QString::number ( double n, char f='g', int prec=6 ) \fC[static]\fR"
A convenience factory function that returns a string representation of the number \fIn.\fR
.PP
Arguments:
.TP
\fIf\fR is the format specifier: 'f', 'F', 'e', 'E', 'g', 'G' (same as sprintf()).
.TP
\fIprec\fR is the precision.
.PP
See also: setNum().
.SH "QString QString::number ( int n, int base=10 ) \fC[static]\fR"
A convenience factory function that returns a string representation of the number \fIn.\fR
.PP
See also: setNum().
.SH "QString QString::number ( long n, int base=10 ) \fC[static]\fR"
A convenience factory function that returns a string representation of the number \fIn.\fR
.PP
See also: setNum().
.SH "QString QString::number ( uint n, int base=10 ) \fC[static]\fR"
A convenience factory function that returns a string representation of the number \fIn.\fR
.PP
See also: setNum().
.SH "QString QString::number ( ulong n, int base=10 ) \fC[static]\fR"
A convenience factory function that returns a string representation of the number \fIn.\fR
.PP
See also: setNum().
.SH "bool QString::operator! () const"
Returns TRUE if it is a null string, otherwise FALSE. Thus you can write:
.PP
.nf
.br