Minor improvement to documentation for [string last], and reformatting to

remove long-obsolete changebars.


FossilOrigin-Name: 085d171f6f6708311b515ae38ae888d47249b227

1 files changed, 117 insertions, 151 deletions

diff --git a/doc/string.n b/doc/string.n
index 9435274..07241af 100644
--- a/doc/string.n
+++ b/doc/string.n
@@ -5,7 +5,7 @@
 '\" 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.15 2002/04/17 23:42:46 hobbs Exp $
+'\" RCS: @(#) $Id: string.n,v 1.16 2002/06/28 08:44:46 dkf Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -21,7 +21,6 @@ string \- Manipulate strings
 .PP
 Performs one of several string operations, depending on \fIoption\fR.
 The legal \fIoption\fRs (which may be abbreviated) are:
-.VS 8.1
 .TP
 \fBstring bytelength \fIstring\fR
 Returns a decimal string giving the number of bytes used to represent
@@ -30,40 +29,34 @@ 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 length\fR operation (including determining the length of a
-Tcl ByteArray object).  Refer to the \fBTcl_NumUtfChars\fR
-manual entry for more details on the UTF\-8 representation.
+Tcl ByteArray object).  Refer to the \fBTcl_NumUtfChars\fR manual
+entry for more details on the UTF\-8 representation.
 .TP
 \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
-.VE 8.1
-Perform a character-by-character comparison of strings \fIstring1\fR and
-\fIstring2\fR.  Returns
-\-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically
-less than, equal to, or greater than \fIstring2\fR.
-.VS 8.1
-If \fB\-length\fR is specified, then only the first \fIlength\fR characters
-are used in the comparison.  If \fB\-length\fR is negative, it is
-ignored.  If \fB\-nocase\fR is specified, then the strings are
-compared in a case-insensitive manner.
+Perform a character-by-character comparison of strings \fIstring1\fR
+and \fIstring2\fR.  Returns \-1, 0, or 1, depending on whether
+\fIstring1\fR is lexicographically less than, equal to, or greater
+than \fIstring2\fR.  If \fB\-length\fR is specified, then only the
+first \fIlength\fR characters are used in the comparison.  If
+\fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
+specified, then the strings are compared in a case-insensitive manner.
 .TP
 \fBstring equal\fR ?\fB\-nocase\fR? ?\fB-length int\fR? \fIstring1 string2\fR
-Perform a character-by-character comparison of strings
-\fIstring1\fR and \fIstring2\fR.  Returns 1 if \fIstring1\fR and
-\fIstring2\fR are identical, or 0 when not.  If \fB\-length\fR is
-specified, then only the first \fIlength\fR characters are used in the
-comparison.  If \fB\-length\fR is negative, it is ignored.  If
-\fB\-nocase\fR is specified, then the strings are compared in a
-case-insensitive manner.
+Perform a character-by-character comparison of strings \fIstring1\fR
+and \fIstring2\fR.  Returns 1 if \fIstring1\fR and \fIstring2\fR are
+identical, or 0 when not.  If \fB\-length\fR is specified, then only
+the first \fIlength\fR characters are used in the comparison.  If
+\fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
+specified, then the strings are compared in a case-insensitive manner.
 .TP
 \fBstring first \fIstring1 string2\fR ?\fIstartIndex\fR?
-.VE 8.1
 Search \fIstring2\fR for a sequence of characters that exactly match
 the characters in \fIstring1\fR.  If found, return the index of the
 first character in the first such match within \fIstring2\fR.  If not
-found, return \-1.
-.VS 8.1
-If \fIstartIndex\fR is specified (in any of the forms accepted by the
-\fBindex\fR method), then the search is constrained to start with the
-character in \fIstring2\fR specified by the index.  For example,
+found, return \-1.  If \fIstartIndex\fR is specified (in any of the
+forms accepted by the \fBindex\fR method), then the search is
+constrained to start with the character in \fIstring2\fR specified by
+the index.  For example,
 .RS
 .CS
 \fBstring first a 0a23456789abcdef 5\fR
@@ -74,29 +67,22 @@ will return \fB10\fR, but
 .CE
 will return \fB\-1\fR.
 .RE
-.VE 8.1
 .TP
 \fBstring index \fIstring charIndex\fR
-Returns the \fIcharIndex\fR'th character of the \fIstring\fR
-argument.  A \fIcharIndex\fR of 0 corresponds to the first
-character of the string.  
-.VS 8.1
-\fIcharIndex\fR may be specified as
-follows:
+Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument.
+A \fIcharIndex\fR of 0 corresponds to the first character of the
+string.  \fIcharIndex\fR may be specified as follows:
 .RS
 .IP \fIinteger\fR 10
-The char specified at this integral index
+The char specified at this integral index.
 .IP \fBend\fR 10
 The last char of the string.
 .IP \fBend\-\fIinteger\fR 10
-The last char of the string minus the specified integer
-offset (e.g. \fBend\-1\fR would refer to the "c" in "abcd").
+The last char of the string minus the specified integer offset
+(e.g. \fBend\-1\fR would refer to the "c" in "abcd").
 .PP
-.VE 8.1
-If \fIcharIndex\fR is less than 0 or greater than
-or equal to the length of the string then an empty string is
-returned.
-.VS 8.1
+If \fIcharIndex\fR 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 \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR
@@ -106,16 +92,16 @@ empty string returns 0, otherwise and empty string will return 1 on
 any class.  If \fB\-failindex\fR 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 \fIvarname\fR.  The \fIvarname\fR
-will not be set if the function returns 1.  The following character classes
-are recognized (the class name can be abbreviated):
+will not be set if the function returns 1.  The following character
+classes are recognized (the class name can be abbreviated):
 .RS
 .IP \fBalnum\fR 10
 Any Unicode alphabet or digit character.
 .IP \fBalpha\fR 10
 Any Unicode alphabet character.
 .IP \fBascii\fR 10
-Any character with a value less than \\u0080 (those that
-are in the 7\-bit ascii range).
+Any character with a value less than \\u0080 (those that are in the
+7\-bit ascii range).
 .IP \fBboolean\fR 10
 Any of the forms allowed to \fBTcl_GetBoolean\fR.
 .IP \fBcontrol\fR 10
@@ -125,16 +111,17 @@ Any Unicode digit character.  Note that this includes characters
 outside of the [0\-9] range.
 .IP \fBdouble\fR 10
 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 \fIvarname\fR will contain \-1.
+whitespace.  In case of under/overflow in the value, 0 is returned and
+the \fIvarname\fR will contain \-1.
 .IP \fBfalse\fR 10
-Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is false.
+Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
+false.
 .IP \fBgraph\fR 10
 Any Unicode printing character, except space.
 .IP \fBinteger\fR 10
-Any of the valid forms for an integer in Tcl, with optional surrounding
-whitespace.  In case of under/overflow in the value, 0 is returned
-and the \fIvarname\fR will contain \-1.
+Any of the valid forms for an integer in Tcl, with optional
+surrounding whitespace.  In case of under/overflow in the value, 0 is
+returned and the \fIvarname\fR will contain \-1.
 .IP \fBlower\fR 10
 Any Unicode lower case alphabet character.
 .IP \fBprint\fR 10
@@ -144,30 +131,29 @@ Any Unicode punctuation character.
 .IP \fBspace\fR 10
 Any Unicode space character.
 .IP \fBtrue\fR 10
-Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is true.
+Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
+true.
 .IP \fBupper\fR 10
 Any upper case alphabet character in the Unicode character set.
 .IP \fBwordchar\fR 10
-Any Unicode word character.  That is any alphanumeric character,
-and any Unicode connector punctuation characters (e.g. underscore).
+Any Unicode word character.  That is any alphanumeric character, and
+any Unicode connector punctuation characters (e.g. underscore).
 .IP \fBxdigit\fR 10
 Any hexadecimal digit character ([0\-9A\-Fa\-f]).
 .PP
 In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the
-function will return 0, then the \fIvarname\fR will always be set to 0,
-due to the varied nature of a valid boolean value.
+function will return 0, then the \fIvarname\fR will always be set to
+0, due to the varied nature of a valid boolean value.
 .RE
 .TP
-\fBstring last \fIstring1 string2\fR ?\fIstartIndex\fR?
-.VE 8.1
+\fBstring last \fIstring1 string2\fR ?\fIlastIndex\fR?
 Search \fIstring2\fR for a sequence of characters that exactly match
 the characters in \fIstring1\fR.  If found, return the index of the
 first character in the last such match within \fIstring2\fR.  If there
-is no match, then return \-1.
-.VS 8.1
-If \fIstartIndex\fR is specified (in any of the forms accepted by the
-\fBindex\fR method), then only the characters in \fIstring2\fR at or before the
-specified \fIstartIndex\fR will be considered by the search.  For example,
+is no match, then return \-1.  If \fIlastIndex\fR is specified (in any
+of the forms accepted by the \fBindex\fR method), then only the
+characters in \fIstring2\fR at or before the specified \fIlastIndex\fR
+will be considered by the search.  For example,
 .RS
 .CS
 \fBstring last a 0a23456789abcdef 15\fR
@@ -178,28 +164,25 @@ will return \fB10\fR, but
 .CE
 will return \fB1\fR.
 .RE
-.VE 8.1
 .TP
 \fBstring length \fIstring\fR
 Returns a decimal string giving the number of characters in
 \fIstring\fR.  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.
-.VS 8.1
+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 map\fR ?\fB\-nocase\fR? \fIcharMap string\fR
 Replaces characters in \fIstring\fR based on the key-value pairs in
-\fIcharMap\fR.  \fIcharMap\fR is a list of \fIkey value key value\fR ...
-as in the form returned by \fBarray get\fR.  Each instance of a
+\fIcharMap\fR.  \fIcharMap\fR is a list of \fIkey value key value\fR
+...  as in the form returned by \fBarray get\fR.  Each instance of a
 key in the string will be replaced with its corresponding value.  If
 \fB\-nocase\fR is specified, then matching is done without regard to
 case differences. Both \fIkey\fR and \fIvalue\fR 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.  \fIstring\fR is
-only iterated over once, so earlier key replacements will have no
-affect for later key matches.  For example,
+characters.  Replacement is done in an ordered manner, so the key
+appearing first in the list will be checked first, and so on.
+\fIstring\fR 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} 1abcaababcabababc\fR
@@ -208,53 +191,42 @@ will return the string \fB01321221\fR.
 .RE
 .TP
 \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR
-.VE 8.1
-See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0
-if it doesn't.  
-.VS 8.1
-If \fB\-nocase\fR is specified, then the pattern attempts to match
-against the string in a case insensitive manner.
-.VE 8.1
-For the two strings to match, their contents
-must be identical except that the following special sequences
-may appear in \fIpattern\fR:
+See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if
+it doesn't.  If \fB\-nocase\fR 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 \fIpattern\fR:
 .RS
 .IP \fB*\fR 10
-Matches any sequence of characters in \fIstring\fR,
-including a null string.
+Matches any sequence of characters in \fIstring\fR, including a null
+string.
 .IP \fB?\fR 10
 Matches any single character in \fIstring\fR.
 .IP \fB[\fIchars\fB]\fR 10
 Matches any character in the set given by \fIchars\fR.  If a sequence
-of the form
-\fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
-between \fIx\fR and \fIy\fR, inclusive, will match.
-.VS 8.1
-When used with \fB\-nocase\fR, 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\-nocase\fR
-this is considered like {[A\-Za\-z]} (and probably what was meant in the
-first place).
-.VE 8.1
+of the form \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any
+character between \fIx\fR and \fIy\fR, inclusive, will match.  When
+used with \fB\-nocase\fR, 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\-nocase\fR this is considered like {[A\-Za\-z]} (and probably what
+was meant in the first place).
 .IP \fB\e\fIx\fR 10
-Matches the single character \fIx\fR.  This provides a way of
-avoiding the special interpretation of the characters
-\fB*?[]\e\fR in \fIpattern\fR.
+Matches the single character \fIx\fR.  This provides a way of avoiding
+the special interpretation of the characters \fB*?[]\e\fR in
+\fIpattern\fR.
 .RE
 .TP
 \fBstring range \fIstring first last\fR
 Returns a range of consecutive characters from \fIstring\fR, starting
 with the character whose index is \fIfirst\fR and ending with the
-character whose index is \fIlast\fR. An index of 0 refers to the
-.VS 8.1
-first character of the string.  \fIfirst\fR and \fIlast\fR may be
-specified as for the \fBindex\fR method.
-.VE 8.1
-If \fIfirst\fR is less than zero then it is treated as if it were zero, and
-if \fIlast\fR is greater than or equal to the length of the string then
-it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater than
-\fIlast\fR then an empty string is returned.
-.VS 8.1
+character whose index is \fIlast\fR. An index of 0 refers to the first
+character of the string.  \fIfirst\fR and \fIlast\fR may be specified
+as for the \fBindex\fR method.  If \fIfirst\fR is less than zero then
+it is treated as if it were zero, and if \fIlast\fR is greater than or
+equal to the length of the string then it is treated as if it were
+\fBend\fR.  If \fIfirst\fR is greater than \fIlast\fR then an empty
+string is returned.
 .TP
 \fBstring repeat \fIstring count\fR
 Returns \fIstring\fR repeated \fIcount\fR number of times.
@@ -265,61 +237,56 @@ with the character whose index is \fIfirst\fR and ending with the
 character whose index is \fIlast\fR.  An index of 0 refers to the
 first character of the string.  \fIFirst\fR and \fIlast\fR may be
 specified as for the \fBindex\fR method.  If \fInewstring\fR is
-specified, then it is placed in the removed character range.
-If \fIfirst\fR is less than zero then it is treated as if it were zero, and
-if \fIlast\fR is greater than or equal to the length of the string then
-it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater than
-\fIlast\fR or the length of the initial string, or \fIlast\fR is less
-than 0, then the initial string is returned untouched.
+specified, then it is placed in the removed character range.  If
+\fIfirst\fR is less than zero then it is treated as if it were zero,
+and if \fIlast\fR is greater than or equal to the length of the string
+then it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater
+than \fIlast\fR or the length of the initial string, or \fIlast\fR is
+less than 0, then the initial string is returned untouched.
 .TP
 \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
-Returns a value equal to \fIstring\fR except that all upper (or title) case
-letters have been converted to lower case.  If \fIfirst\fR is specified, it
-refers to the first char index in the string to start modifying.  If
-\fIlast\fR is specified, it refers to the char index in the string to stop
-at (inclusive).  \fIfirst\fR and \fIlast\fR may be
+Returns a value equal to \fIstring\fR except that all upper (or title)
+case letters have been converted to lower case.  If \fIfirst\fR is
+specified, it refers to the first char index in the string to start
+modifying.  If \fIlast\fR is specified, it refers to the char index in
+the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
 specified as for the \fBindex\fR method.
 .TP
 \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
 Returns a value equal to \fIstring\fR except that the first character
-in \fIstring\fR 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 \fIfirst\fR is specified, it
+in \fIstring\fR 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 \fIfirst\fR is specified, it
 refers to the first char index in the string to start modifying.  If
-\fIlast\fR is specified, it refers to the char index in the string to stop
-at (inclusive).  \fIfirst\fR and \fIlast\fR may be
-specified as for the \fBindex\fR method.
+\fIlast\fR is specified, it refers to the char index in the string to
+stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified as
+for the \fBindex\fR method.
 .TP
 \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
-Returns a value equal to \fIstring\fR except that all lower (or title) case
-letters have been converted to upper case.  If \fIfirst\fR is specified, it
-refers to the first char index in the string to start modifying.  If
-\fIlast\fR is specified, it refers to the char index in the string to stop
-at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified as for the
-\fBindex\fR method.
-.VE 8.1
+Returns a value equal to \fIstring\fR except that all lower (or title)
+case letters have been converted to upper case.  If \fIfirst\fR is
+specified, it refers to the first char index in the string to start
+modifying.  If \fIlast\fR is specified, it refers to the char index in
+the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
+specified as for the \fBindex\fR method.
 .TP
 \fBstring trim \fIstring\fR ?\fIchars\fR?
-Returns a value equal to \fIstring\fR except that any leading
-or trailing characters from the set given by \fIchars\fR are
-removed.
-If \fIchars\fR is not specified then white space is removed
-(spaces, tabs, newlines, and carriage returns).
+Returns a value equal to \fIstring\fR except that any leading or
+trailing characters from the set given by \fIchars\fR are removed.  If
+\fIchars\fR is not specified then white space is removed (spaces,
+tabs, newlines, and carriage returns).
 .TP
 \fBstring trimleft \fIstring\fR ?\fIchars\fR?
-Returns a value equal to \fIstring\fR except that any
-leading characters from the set given by \fIchars\fR are
-removed.
-If \fIchars\fR is not specified then white space is removed
-(spaces, tabs, newlines, and carriage returns).
+Returns a value equal to \fIstring\fR except that any leading
+characters from the set given by \fIchars\fR are removed.  If
+\fIchars\fR is not specified then white space is removed (spaces,
+tabs, newlines, and carriage returns).
 .TP
 \fBstring trimright \fIstring\fR ?\fIchars\fR?
-Returns a value equal to \fIstring\fR except that any
-trailing characters from the set given by \fIchars\fR are
-removed.
-If \fIchars\fR is not specified then white space is removed
-(spaces, tabs, newlines, and carriage returns).
-.VS 8.1
+Returns a value equal to \fIstring\fR except that any trailing
+characters from the set given by \fIchars\fR are removed.  If
+\fIchars\fR is not specified then white space is removed (spaces,
+tabs, newlines, and carriage returns).
 .TP
 \fBstring wordend \fIstring charIndex\fR
 Returns the index of the character just after the last one in the word
@@ -336,7 +303,6 @@ specified as for the \fBindex\fR 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.
-.VE 8.1
 
 .SH "SEE ALSO"
 expr(n), list(n)