Yet more doc update backporting

1 files changed, 50 insertions, 3 deletions

diff --git a/doc/scan.n b/doc/scan.n
index 81ff539..3e32f4a 100644
--- a/doc/scan.n
+++ b/doc/scan.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: scan.n,v 1.9 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: scan.n,v 1.9.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH scan n 8.4 Tcl "Tcl Built-In Commands"
@@ -33,7 +33,6 @@ inline manner, returning the data that would otherwise be stored in the
 variables as a list.  In the inline case, an empty string is returned when
 the end of the input string is reached before any conversions have been
 performed.
-
 .SH "DETAILS ON SCANNING"
 .PP
 \fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together.
@@ -188,7 +187,6 @@ white-space character is encountered or when the maximum field
 width has been reached, whichever comes first.
 If a \fB*\fR is present in the conversion specifier 
 then no variable is assigned and the next scan argument is not consumed.
-
 .SH "DIFFERENCES FROM ANSI SSCANF"
 .PP
 The behavior of the \fBscan\fR command is the same as the behavior of
@@ -209,6 +207,55 @@ modifiers are ignored when converting real values (i.e. type
 .IP [4]
 If the end of the input string is reached before any conversions have been
 performed and no variables are given, an empty string is returned.
+.SH EXAMPLES
+Parse a simple color specification of the form \fI#RRGGBB\fR using
+hexadecimal conversions with field sizes:
+.CS
+set string "#08D03F"
+\fBscan\fR $string "#%2x%2x%2x" r g b
+.CE
+.PP
+Parse a \fIHH:MM\fR time string, noting that this avoids problems with
+octal numbers by forcing interpretation as decimals (if we did not
+care, we would use the \fB%i\fR conversion instead):
+.CS
+set string "08:08"   ;# *Not* octal!
+if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} {
+   error "not a valid time string"
+}
+# We have to understand numeric ranges ourselves...
+if {$minutes < 0 || $minutes > 59} {
+   error "invalid number of minutes"
+}
+.CE
+.PP
+Break a string up into sequences of non-whitespace characters (note
+the use of the \fB%n\fR conversion so that we get skipping over
+leading whitespace correct):
+.CS
+set string " a string {with braced words} + leading space "
+set words {}
+while {[\fBscan\fR $string %s%n word length] == 2} {
+   lappend words $word
+   set string [string range $string $length end]
+}
+.CE
+.PP
+Parse a simple coordinate string, checking that it is complete by
+looking for the terminating character explicitly:
+.CS
+set string "(5.2,-4e-2)"
+# Note that the spaces before the literal parts of
+# the scan pattern are significant, and that ")" is
+# the Unicode character \\u0029
+if {
+   [\fBscan\fR $string " (%f ,%f %c" x y last] != 3
+   || $last != 0x0029
+} then {
+   error "invalid coordinate string"
+}
+puts "X=$x, Y=$y"
+.CE
 
 .SH "SEE ALSO"
 format(n), sscanf(3)