Moved the descriptions of the index formats to their own section, and

added a warning to the 'bytelength' subcommand about future compatibility.

1 files changed, 75 insertions, 61 deletions

diff --git a/doc/string.n b/doc/string.n
index 6e4a8a4..50fdeeb 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.45 2008/10/17 10:22:25 dkf Exp $
+.\" RCS: @(#) $Id: string.n,v 1.46 2009/11/08 20:01:18 dkf Exp $
 .\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -31,6 +31,13 @@ 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.
+.RS
+.PP
+\fICompatibility note:\fR it is likely that this subcommand will be
+withdrawn in a future version of Tcl. It is better to use the
+\fBencoding convertto\fR command to convert a string to a known
+encoding and then apply \fBstring length\fR to that.
+.RE
 .TP
 \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
 .
@@ -57,7 +64,7 @@ Search \fIhaystackString\fR for a sequence of characters that exactly match
 the characters in \fIneedleString\fR.  If found, return the index of the
 first character in the first such match within \fIhaystackString\fR.  If not
 found, return \-1.  If \fIstartIndex\fR is specified (in any of the
-forms accepted by the \fBindex\fR method), then the search is
+forms described in \fBSTRING INDICES\fR), then the search is
 constrained to start with the character in \fIhaystackString\fR specified by
 the index.  For example,
 .RS
@@ -79,51 +86,9 @@ will return \fB\-1\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.  \fIcharIndex\fR may be specified as follows:
+string.  \fIcharIndex\fR may be specified as described in the
+\fBSTRING INDICES\fR section.
 .RS
-.IP \fIinteger\fR 10
-For any index value that passes \fBstring is integer -strict\fR,
-the char specified at this integral index
-(e.g. \fB2\fR would refer to the
-.QW c
-in
-.QW abcd ).
-.IP \fBend\fR 10
-The last char of the string
-(e.g. \fBend\fR would refer to the
-.QW d
-in
-.QW abcd ).
-.IP \fBend\fR\-\fIN\fR 10
-The last char of the string minus the specified integer offset \fIN\fR
-(e.g. \fBend\fR\-1 would refer to the
-.QW c
-in
-.QW abcd ).
-.IP \fBend\fR+\fIN\fR 10
-The last char of the string plus the specified integer offset \fIN\fR
-(e.g. \fBend\fR+\-1 would refer to the
-.QW c
-in
-.QW abcd ).
-.IP \fIM\fR+\fIN\fR 10
-The char specified at the integral index that is the sum of 
-integer values \fIM\fR and \fIN\fR
-(e.g. \fB1+1\fR would refer to the
-.QW c
-in
-.QW abcd ).
-.IP \fIM\fR\-\fIN\fR 10
-The char specified at the integral index that is the difference of 
-integer values \fIM\fR and \fIN\fR
-(e.g. \fB2\-1\fR would refer to the
-.QW b
-in
-.QW abcd ).
-.PP
-In the specifications above, the integer value \fIM\fR contains no
-trailing whitespace and the integer value \fIN\fR contains no
-leading whitespace.
 .PP
 If \fIcharIndex\fR is less than 0 or greater than or equal to the
 length of the string then this command returns an empty string.
@@ -137,7 +102,7 @@ empty string returns 0, otherwise an 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
+will not be set if \fBstring is\fR returns 1.  The following character
 classes are recognized (the class name can be abbreviated):
 .RS
 .IP \fBalnum\fR 12
@@ -207,7 +172,7 @@ Search \fIhaystackString\fR for a sequence of characters that exactly match
 the characters in \fIneedleString\fR.  If found, return the index of the
 first character in the last such match within \fIhaystackString\fR.  If there
 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
+of the forms described in \fBSTRING INDICES\fR), then only the
 characters in \fIhaystackString\fR at or before the specified \fIlastIndex\fR
 will be considered by the search.  For example,
 .RS
@@ -340,7 +305,7 @@ 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.
+specified using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
 .
@@ -350,8 +315,8 @@ 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.
+stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified
+using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
 .
@@ -360,7 +325,7 @@ 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.
+specified using the forms described in \fBSTRING INDICES\fR.
 .TP
 \fBstring trim \fIstring\fR ?\fIchars\fR?
 .
@@ -387,19 +352,68 @@ tabs, newlines, and carriage returns).
 .
 Returns the index of the character just after the last one in the word
 containing character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR
-may be specified as for the \fBindex\fR method.  A word is
+may be specified using the forms in \fBSTRING INDICES\fR.  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 charIndex\fR
 .
-Returns the index of the first character in the word containing
-character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be
-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.
+Returns the index of the first character in the word containing character
+\fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be specified using the
+forms in \fBSTRING INDICES\fR.  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 "STRING INDICES"
+.PP
+When referring to indices into a string (e.g., for \fBstring index\fR
+or \fBstring range\fR) the following formats are supported:
+.IP \fIinteger\fR 10
+For any index value that passes \fBstring is integer \-strict\fR,
+the char specified at this integral index (e.g., \fB2\fR would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fBend\fR 10
+The last char of the string (e.g., \fBend\fR would refer to the
+.QW d
+in
+.QW abcd ).
+.IP \fBend\-\fIN\fR 10
+The last char of the string minus the specified integer offset \fIN\fR (e.g.,
+.QW \fBend\-1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fBend+\fIN\fR 10
+The last char of the string plus the specified integer offset \fIN\fR (e.g.,
+.QW \fBend+\-1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fIM\fB+\fIN\fR 10
+The char specified at the integral index that is the sum of 
+integer values \fIM\fR and \fIN\fR (e.g.,
+.QW \fB1+1\fR
+would refer to the
+.QW c
+in
+.QW abcd ).
+.IP \fIM\fB\-\fIN\fR 10
+The char specified at the integral index that is the difference of 
+integer values \fIM\fR and \fIN\fR (e.g.,
+.QW \fB2\-1\fR
+would refer to the
+.QW b
+in
+.QW abcd ).
+.PP
+In the specifications above, the integer value \fIM\fR contains no
+trailing whitespace and the integer value \fIN\fR contains no
+leading whitespace.
 .SH EXAMPLE
 .PP
 Test if the string in the variable \fIstring\fR is a proper non-empty
@@ -408,9 +422,9 @@ prefix of the string \fBfoobar\fR.
 .CS
 set length [\fBstring length\fR $string]
 if {$length == 0} {
-   set isPrefix 0
+    set isPrefix 0
 } else {
-   set isPrefix [\fBstring equal\fR -length $length $string "foobar"]
+    set isPrefix [\fBstring equal\fR \-length $length $string "foobar"]
 }
 .CE
 .SH "SEE ALSO"