通讯编程

开发平台：
Visual C++

string.n：源码内容
							'"
'" Copyright (c) 1993 The Regents of the University of California.
'" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: string.n,v 1.17.2.4 2006/12/14 14:24:22 dkf Exp $
'" 
.so man.macros
.TH string n 8.1 Tcl "Tcl Built-In Commands"
.BS
'" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
string - Manipulate strings
.SH SYNOPSIS
fBstring fIoption arg fR?fIarg ...?fR
.BE
.SH DESCRIPTION
.PP
Performs one of several string operations, depending on fIoptionfR.
The legal fIoptionfRs (which may be abbreviated) are:
.TP
fBstring bytelength fIstringfR
Returns a decimal string giving the number of bytes used to represent
fIstringfR in memory.  Because UTF-8 uses one to three bytes to
represent Unicode characters, the byte length will not be the same as
the character length in general.  The cases where a script cares about
the byte length are rare.  In almost all cases, you should use the
fBstring lengthfR operation (including determining the length of a
Tcl ByteArray object).  Refer to the fBTcl_NumUtfCharsfR manual
entry for more details on the UTF-8 representation.
.TP
fBstring comparefR ?fB-nocasefR? ?fB-length intfR? fIstring1 string2fR
Perform a character-by-character comparison of strings fIstring1fR
and fIstring2fR.  Returns -1, 0, or 1, depending on whether
fIstring1fR is lexicographically less than, equal to, or greater
than fIstring2fR.  If fB-lengthfR is specified, then only the
first fIlengthfR characters are used in the comparison.  If
fB-lengthfR is negative, it is ignored.  If fB-nocasefR is
specified, then the strings are compared in a case-insensitive manner.
.TP
fBstring equalfR ?fB-nocasefR? ?fB-length intfR? fIstring1 string2fR
Perform a character-by-character comparison of strings fIstring1fR
and fIstring2fR.  Returns 1 if fIstring1fR and fIstring2fR are
identical, or 0 when not.  If fB-lengthfR is specified, then only
the first fIlengthfR characters are used in the comparison.  If
fB-lengthfR is negative, it is ignored.  If fB-nocasefR is
specified, then the strings are compared in a case-insensitive manner.
.TP
fBstring first fIstring1 string2fR ?fIstartIndexfR?
Search fIstring2fR for a sequence of characters that exactly match
the characters in fIstring1fR.  If found, return the index of the
first character in the first such match within fIstring2fR.  If not
found, return -1.  If fIstartIndexfR is specified (in any of the
forms accepted by the fBindexfR method), then the search is
constrained to start with the character in fIstring2fR specified by
the index.  For example,
.RS
.CS
fBstring first a 0a23456789abcdef 5fR
.CE
will return fB10fR, but
.CS
fBstring first a 0123456789abcdef 11fR
.CE
will return fB-1fR.
.RE
.TP
fBstring index fIstring charIndexfR
Returns the fIcharIndexfR'th character of the fIstringfR argument.
A fIcharIndexfR of 0 corresponds to the first character of the
string.  fIcharIndexfR may be specified as follows:
.RS
.IP fIintegerfR 10
The char specified at this integral index.
.IP fBendfR 10
The last char of the string.
.IP fBend-fIintegerfR 10
The last char of the string minus the specified integer offset
(e.g. fBend-1fR would refer to the "c" in "abcd").
.PP
If fIcharIndexfR is less than 0 or greater than or equal to the
length of the string then an empty string is returned.
.RE
.TP
fBstring is fIclassfR ?fB-strictfR? ?fB-failindex fIvarnamefR? fIstringfR
Returns 1 if fIstringfR is a valid member of the specified character
class, otherwise returns 0.  If fB-strictfR is specified, then an
empty string returns 0, otherwise and empty string will return 1 on
any class.  If fB-failindexfR is specified, then if the function
returns 0, the index in the string where the class was no longer valid
will be stored in the variable named fIvarnamefR.  The fIvarnamefR
will not be set if the function returns 1.  The following character
classes are recognized (the class name can be abbreviated):
.RS
.IP fBalnumfR 12
Any Unicode alphabet or digit character.
.IP fBalphafR 12
Any Unicode alphabet character.
.IP fBasciifR 12
Any character with a value less than \u0080 (those that are in the
7-bit ascii range).
.IP fBbooleanfR 12
Any of the forms allowed to fBTcl_GetBooleanfR.
.IP fBcontrolfR 12
Any Unicode control character.
.IP fBdigitfR 12
Any Unicode digit character.  Note that this includes characters
outside of the [0-9] range.
.IP fBdoublefR 12
Any of the valid forms for a double in Tcl, with optional surrounding
whitespace.  In case of under/overflow in the value, 0 is returned and
the fIvarnamefR will contain -1.
.IP fBfalsefR 12
Any of the forms allowed to fBTcl_GetBooleanfR where the value is
false.
.IP fBgraphfR 12
Any Unicode printing character, except space.
.IP fBintegerfR 12
Any of the valid forms for an ordinary integer in Tcl, with optional
surrounding whitespace.  In case of under/overflow in the value, 0 is
returned and the fIvarnamefR will contain -1.
.IP fBlowerfR 12
Any Unicode lower case alphabet character.
.IP fBprintfR 12
Any Unicode printing character, including space.
.IP fBpunctfR 12
Any Unicode punctuation character.
.IP fBspacefR 12
Any Unicode space character.
.IP fBtruefR 12
Any of the forms allowed to fBTcl_GetBooleanfR where the value is
true.
.IP fBupperfR 12
Any upper case alphabet character in the Unicode character set.
.IP fBwordcharfR 12
Any Unicode word character.  That is any alphanumeric character, and
any Unicode connector punctuation characters (e.g. underscore).
.IP fBxdigitfR 12
Any hexadecimal digit character ([0-9A-Fa-f]).
.PP
In the case of fBbooleanfR, fBtruefR and fBfalsefR, if the
function will return 0, then the fIvarnamefR will always be set to
0, due to the varied nature of a valid boolean value.
.RE
.TP
fBstring last fIstring1 string2fR ?fIlastIndexfR?
Search fIstring2fR for a sequence of characters that exactly match
the characters in fIstring1fR.  If found, return the index of the
first character in the last such match within fIstring2fR.  If there
is no match, then return -1.  If fIlastIndexfR is specified (in any
of the forms accepted by the fBindexfR method), then only the
characters in fIstring2fR at or before the specified fIlastIndexfR
will be considered by the search.  For example,
.RS
.CS
fBstring last a 0a23456789abcdef 15fR
.CE
will return fB10fR, but
.CS
fBstring last a 0a23456789abcdef 9fR
.CE
will return fB1fR.
.RE
.TP
fBstring length fIstringfR
Returns a decimal string giving the number of characters in
fIstringfR.  Note that this is not necessarily the same as the
number of bytes used to store the string.  If the object is a
ByteArray object (such as those returned from reading a binary encoded
channel), then this will return the actual byte length of the object.
.TP
fBstring mapfR ?fB-nocasefR? fImapping stringfR
Replaces substrings in fIstringfR based on the key-value pairs in
fImappingfR.  fImappingfR is a list of fIkey value key value ...fR
as in the form returned by fBarray getfR.  Each instance of a
key in the string will be replaced with its corresponding value.  If
fB-nocasefR is specified, then matching is done without regard to
case differences. Both fIkeyfR and fIvaluefR may be multiple
characters.  Replacement is done in an ordered manner, so the key
appearing first in the list will be checked first, and so on.
fIstringfR is only iterated over once, so earlier key replacements
will have no affect for later key matches.  For example,
.RS
.CS
fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababcfR
.CE
will return the string fB01321221fR.
.PP
Note that if an earlier fIkeyfR is a prefix of a later one, it will
completely mask the later one.  So if the previous example is
reordered like this,
.CS
fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababcfR
.CE
it will return the string fB02c322c222cfR.
.RE
.TP
fBstring matchfR ?fB-nocasefR? fIpatternfR fIstringfR
See if fIpatternfR matches fIstringfR; return 1 if it does, 0 if
it doesn't.  If fB-nocasefR is specified, then the pattern attempts
to match against the string in a case insensitive manner.  For the two
strings to match, their contents must be identical except that the
following special sequences may appear in fIpatternfR:
.RS
.IP fB*fR 10
Matches any sequence of characters in fIstringfR, including a null
string.
.IP fB?fR 10
Matches any single character in fIstringfR.
.IP fB[fIcharsfB]fR 10
Matches any character in the set given by fIcharsfR.  If a sequence
of the form fIxfB-fIyfR appears in fIcharsfR, then any
character between fIxfR and fIyfR, inclusive, will match.  When
used with fB-nocasefR, the end points of the range are converted to
lower case first.  Whereas {[A-z]} matches '_' when matching
case-sensitively ('_' falls between the 'Z' and 'a'), with
fB-nocasefR this is considered like {[A-Za-z]} (and probably what
was meant in the first place).
.IP fBefIxfR 10
Matches the single character fIxfR.  This provides a way of avoiding
the special interpretation of the characters fB*?[]efR in
fIpatternfR.
.RE
.TP
fBstring range fIstring first lastfR
Returns a range of consecutive characters from fIstringfR, starting
with the character whose index is fIfirstfR and ending with the
character whose index is fIlastfR. An index of 0 refers to the first
character of the string.  fIfirstfR and fIlastfR may be specified
as for the fBindexfR method.  If fIfirstfR is less than zero then
it is treated as if it were zero, and if fIlastfR is greater than or
equal to the length of the string then it is treated as if it were
fBendfR.  If fIfirstfR is greater than fIlastfR then an empty
string is returned.
.TP
fBstring repeat fIstring countfR
Returns fIstringfR repeated fIcountfR number of times.
.TP
fBstring replace fIstring first lastfR ?fInewstringfR?
Removes a range of consecutive characters from fIstringfR, starting
with the character whose index is fIfirstfR and ending with the
character whose index is fIlastfR.  An index of 0 refers to the
first character of the string.  fIFirstfR and fIlastfR may be
specified as for the fBindexfR method.  If fInewstringfR is
specified, then it is placed in the removed character range.  If
fIfirstfR is less than zero then it is treated as if it were zero,
and if fIlastfR is greater than or equal to the length of the string
then it is treated as if it were fBendfR.  If fIfirstfR is greater
than fIlastfR or the length of the initial string, or fIlastfR is
less than 0, then the initial string is returned untouched.
.TP
fBstring tolower fIstringfR ?fIfirstfR? ?fIlastfR?
Returns a value equal to fIstringfR except that all upper (or title)
case letters have been converted to lower case.  If fIfirstfR is
specified, it refers to the first char index in the string to start
modifying.  If fIlastfR is specified, it refers to the char index in
the string to stop at (inclusive).  fIfirstfR and fIlastfR may be
specified as for the fBindexfR method.
.TP
fBstring totitle fIstringfR ?fIfirstfR? ?fIlastfR?
Returns a value equal to fIstringfR except that the first character
in fIstringfR is converted to its Unicode title case variant (or
upper case if there is no title case variant) and the rest of the
string is converted to lower case.  If fIfirstfR is specified, it
refers to the first char index in the string to start modifying.  If
fIlastfR is specified, it refers to the char index in the string to
stop at (inclusive).  fIfirstfR and fIlastfR may be specified as
for the fBindexfR method.
.TP
fBstring toupper fIstringfR ?fIfirstfR? ?fIlastfR?
Returns a value equal to fIstringfR except that all lower (or title)
case letters have been converted to upper case.  If fIfirstfR is
specified, it refers to the first char index in the string to start
modifying.  If fIlastfR is specified, it refers to the char index in
the string to stop at (inclusive).  fIfirstfR and fIlastfR may be
specified as for the fBindexfR method.
.TP
fBstring trim fIstringfR ?fIcharsfR?
Returns a value equal to fIstringfR except that any leading or
trailing characters from the set given by fIcharsfR are removed.  If
fIcharsfR is not specified then white space is removed (spaces,
tabs, newlines, and carriage returns).
.TP
fBstring trimleft fIstringfR ?fIcharsfR?
Returns a value equal to fIstringfR except that any leading
characters from the set given by fIcharsfR are removed.  If
fIcharsfR is not specified then white space is removed (spaces,
tabs, newlines, and carriage returns).
.TP
fBstring trimright fIstringfR ?fIcharsfR?
Returns a value equal to fIstringfR except that any trailing
characters from the set given by fIcharsfR are removed.  If
fIcharsfR is not specified then white space is removed (spaces,
tabs, newlines, and carriage returns).
.TP
fBstring wordend fIstring charIndexfR
Returns the index of the character just after the last one in the word
containing character fIcharIndexfR of fIstringfR.  fIcharIndexfR
may be specified as for the fBindexfR method.  A word is
considered to be any contiguous range of alphanumeric (Unicode letters
or decimal digits) or underscore (Unicode connector punctuation)
characters, or any single character other than these.
.TP
fBstring wordstart fIstring charIndexfR
Returns the index of the first character in the word containing
character fIcharIndexfR of fIstringfR.  fIcharIndexfR may be
specified as for the fBindexfR method.  A word is considered to be any
contiguous range of alphanumeric (Unicode letters or decimal digits)
or underscore (Unicode connector punctuation) characters, or any
single character other than these.
.SH EXAMPLE
Test if the string in the variable fIstringfR is a proper non-empty
prefix of the string fBfoobarfR.
.CS
set length [fBstring lengthfR $string]
if {$length == 0} {
   set isPrefix 0
} else {
   set isPrefix [fBstring equalfR -length $length $string "foobar"]
}
.CE
.SH "SEE ALSO"
expr(n), list(n)
.SH KEYWORDS
case conversion, compare, index, match, pattern, string, word, equal, ctype

						