Backport many doc fixes

1 files changed, 42 insertions, 23 deletions

diff --git a/doc/string.n b/doc/string.n
index 30c5adb..49ef611 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.17.2.1 2003/04/11 20:49:53 dgp Exp $
+'\" RCS: @(#) $Id: string.n,v 1.17.2.2 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -95,50 +95,50 @@ 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):
 .RS
-.IP \fBalnum\fR 10
+.IP \fBalnum\fR 12
 Any Unicode alphabet or digit character.
-.IP \fBalpha\fR 10
+.IP \fBalpha\fR 12
 Any Unicode alphabet character.
-.IP \fBascii\fR 10
+.IP \fBascii\fR 12
 Any character with a value less than \\u0080 (those that are in the
 7\-bit ascii range).
-.IP \fBboolean\fR 10
+.IP \fBboolean\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR.
-.IP \fBcontrol\fR 10
+.IP \fBcontrol\fR 12
 Any Unicode control character.
-.IP \fBdigit\fR 10
+.IP \fBdigit\fR 12
 Any Unicode digit character.  Note that this includes characters
 outside of the [0\-9] range.
-.IP \fBdouble\fR 10
+.IP \fBdouble\fR 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 \fIvarname\fR will contain \-1.
-.IP \fBfalse\fR 10
+.IP \fBfalse\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 false.
-.IP \fBgraph\fR 10
+.IP \fBgraph\fR 12
 Any Unicode printing character, except space.
-.IP \fBinteger\fR 10
-Any of the valid forms for a 32-bit integer in Tcl, with optional
+.IP \fBinteger\fR 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 \fIvarname\fR will contain \-1.
-.IP \fBlower\fR 10
+.IP \fBlower\fR 12
 Any Unicode lower case alphabet character.
-.IP \fBprint\fR 10
+.IP \fBprint\fR 12
 Any Unicode printing character, including space.
-.IP \fBpunct\fR 10
+.IP \fBpunct\fR 12
 Any Unicode punctuation character.
-.IP \fBspace\fR 10
+.IP \fBspace\fR 12
 Any Unicode space character.
-.IP \fBtrue\fR 10
+.IP \fBtrue\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 true.
-.IP \fBupper\fR 10
+.IP \fBupper\fR 12
 Any upper case alphabet character in the Unicode character set.
-.IP \fBwordchar\fR 10
+.IP \fBwordchar\fR 12
 Any Unicode word character.  That is any alphanumeric character, and
 any Unicode connector punctuation characters (e.g. underscore).
-.IP \fBxdigit\fR 10
+.IP \fBxdigit\fR 12
 Any hexadecimal digit character ([0\-9A\-Fa\-f]).
 .PP
 In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the
@@ -172,9 +172,9 @@ 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 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
+\fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR
+Replaces substrings in \fIstring\fR based on the key-value pairs in
+\fImapping\fR.  \fImapping\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
@@ -188,6 +188,14 @@ will have no affect for later key matches.  For example,
 \fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc\fR
 .CE
 will return the string \fB01321221\fR.
+.PP
+Note that if an earlier \fIkey\fR 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} 1abcaababcabababc\fR
+.CE
+it will return the string \fB02c322c222c\fR.
 .RE
 .TP
 \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR
@@ -303,6 +311,17 @@ 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.
+.SH EXAMPLE
+Test if the string in the variable \fIstring\fR is a proper non-empty
+prefix of the string \fBfoobar\fR.
+.CS
+set length [\fBstring\fR length $string]
+if {$length == 0} {
+    set isPrefix 0
+} else {
+    set isPrefix [\fBstring\fR equal -length $string $string "foobar"]
+}
+.CE
 
 .SH "SEE ALSO"
 expr(n), list(n)