summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2004-05-10 22:10:33 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2004-05-10 22:10:33 (GMT)
commit0a9f409e6dc9ba06b9d197181daef5ee124852b3 (patch)
tree6bd9b54d04e9261bed1c54166bfec066587a3a89
parent0de8edfaff674e87769171bc165bef7d3fe6ff19 (diff)
downloadtcl-0a9f409e6dc9ba06b9d197181daef5ee124852b3.zip
tcl-0a9f409e6dc9ba06b9d197181daef5ee124852b3.tar.gz
tcl-0a9f409e6dc9ba06b9d197181daef5ee124852b3.tar.bz2
Added examples.
-rw-r--r--ChangeLog4
-rw-r--r--doc/scan.n42
2 files changed, 43 insertions, 3 deletions
diff --git a/ChangeLog b/ChangeLog
index 42359cc..d2e474f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-05-10 Donal K. Fellows <donal.k.fellows@man.ac.uk>
+
+ * doc/scan.n: Added examples.
+
2004-05-10 David Gravereaux <davygrvy@pobox.com>
* win/tclWinPipe.c (BuildCommandLine): Moved non-obvious appending
diff --git a/doc/scan.n b/doc/scan.n
index 81ff539..4298faf 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.10 2004/05/10 22:10:35 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,44 @@ 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 \fIHH:MM\fR time string:
+.CS
+set string "08:08" ;# *Not* octal!
+if {[scan $string "%d:%d" hours minutes] != 2} {
+ error "not a valid time string"
+}
+if {$minutes < 0 || $minutes > 59} {
+ error "invalid number of minutes"
+}
+.CE
+
+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 {[scan $string %s%n word length] == 2} {
+ lappend words $word
+ set string [string range $string $length end]
+}
+.CE
+
+Parse a simple coordinate string, checking that it is complete:
+.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 {
+ [scan $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)