summaryrefslogtreecommitdiffstats
path: root/doc/scan.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/scan.n')
-rw-r--r--doc/scan.n53
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)