| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1993 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: scan.n,v 1.1.1.1 2002-01-16 10:25:25 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH scan n "" Tcl "Tcl Built-In Commands"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
| 14 |
|
|
.SH NAME
|
| 15 |
|
|
scan \- Parse string using conversion specifiers in the style of sscanf
|
| 16 |
|
|
.SH SYNOPSIS
|
| 17 |
|
|
\fBscan \fIstring format varName \fR?\fIvarName ...\fR?
|
| 18 |
|
|
.BE
|
| 19 |
|
|
|
| 20 |
|
|
.SH INTRODUCTION
|
| 21 |
|
|
.PP
|
| 22 |
|
|
This command parses fields from an input string in the same fashion
|
| 23 |
|
|
as the ANSI C \fBsscanf\fR procedure and returns a count of the number
|
| 24 |
|
|
of conversions performed, or -1 if the end of the input string is
|
| 25 |
|
|
reached before any conversions have been performed.
|
| 26 |
|
|
\fIString\fR gives the input to be parsed and \fIformat\fR indicates
|
| 27 |
|
|
how to parse it, using \fB%\fR conversion specifiers as in \fBsscanf\fR.
|
| 28 |
|
|
Each \fIvarName\fR gives the name of a variable; when a field is
|
| 29 |
|
|
scanned from \fIstring\fR the result is converted back into a string
|
| 30 |
|
|
and assigned to the corresponding variable.
|
| 31 |
|
|
|
| 32 |
|
|
.SH "DETAILS ON SCANNING"
|
| 33 |
|
|
.PP
|
| 34 |
|
|
\fBScan\fR operates by scanning \fIstring\fR and \fIformatString\fR together.
|
| 35 |
|
|
If the next character in \fIformatString\fR is a blank or tab then it
|
| 36 |
|
|
matches any number of white space characters in \fIstring\fR (including
|
| 37 |
|
|
zero).
|
| 38 |
|
|
Otherwise, if it isn't a \fB%\fR character then it
|
| 39 |
|
|
must match the next character of \fIstring\fR.
|
| 40 |
|
|
When a \fB%\fR is encountered in \fIformatString\fR, it indicates
|
| 41 |
|
|
the start of a conversion specifier.
|
| 42 |
|
|
A conversion specifier contains three fields after the \fB%\fR:
|
| 43 |
|
|
a \fB*\fR, which indicates that the converted value is to be discarded
|
| 44 |
|
|
instead of assigned to a variable; a number indicating a maximum field
|
| 45 |
|
|
width; and a conversion character.
|
| 46 |
|
|
All of these fields are optional except for the conversion character.
|
| 47 |
|
|
.PP
|
| 48 |
|
|
When \fBscan\fR finds a conversion specifier in \fIformatString\fR, it
|
| 49 |
|
|
first skips any white-space characters in \fIstring\fR.
|
| 50 |
|
|
Then it converts the next input characters according to the
|
| 51 |
|
|
conversion specifier and stores the result in the variable given
|
| 52 |
|
|
by the next argument to \fBscan\fR.
|
| 53 |
|
|
The following conversion characters are supported:
|
| 54 |
|
|
.TP 10
|
| 55 |
|
|
\fBd\fR
|
| 56 |
|
|
The input field must be a decimal integer.
|
| 57 |
|
|
It is read in and the value is stored in the variable as a decimal string.
|
| 58 |
|
|
.TP 10
|
| 59 |
|
|
\fBo\fR
|
| 60 |
|
|
The input field must be an octal integer. It is read in and the
|
| 61 |
|
|
value is stored in the variable as a decimal string.
|
| 62 |
|
|
.TP 10
|
| 63 |
|
|
\fBx\fR
|
| 64 |
|
|
The input field must be a hexadecimal integer. It is read in
|
| 65 |
|
|
and the value is stored in the variable as a decimal string.
|
| 66 |
|
|
.TP 10
|
| 67 |
|
|
\fBc\fR
|
| 68 |
|
|
A single character is read in and its binary value is stored in
|
| 69 |
|
|
the variable as a decimal string.
|
| 70 |
|
|
Initial white space is not skipped in this case, so the input
|
| 71 |
|
|
field may be a white-space character.
|
| 72 |
|
|
This conversion is different from the ANSI standard in that the
|
| 73 |
|
|
input field always consists of a single character and no field
|
| 74 |
|
|
width may be specified.
|
| 75 |
|
|
.TP 10
|
| 76 |
|
|
\fBs\fR
|
| 77 |
|
|
The input field consists of all the characters up to the next
|
| 78 |
|
|
white-space character; the characters are copied to the variable.
|
| 79 |
|
|
.TP 10
|
| 80 |
|
|
\fBe\fR or \fBf\fR or \fBg\fR
|
| 81 |
|
|
The input field must be a floating-point number consisting
|
| 82 |
|
|
of an optional sign, a string of decimal digits possibly
|
| 83 |
|
|
containing a decimal point, and an optional exponent consisting
|
| 84 |
|
|
of an \fBe\fR or \fBE\fR followed by an optional sign and a string of
|
| 85 |
|
|
decimal digits.
|
| 86 |
|
|
It is read in and stored in the variable as a floating-point string.
|
| 87 |
|
|
.TP 10
|
| 88 |
|
|
\fB[\fIchars\fB]\fR
|
| 89 |
|
|
The input field consists of any number of characters in
|
| 90 |
|
|
\fIchars\fR.
|
| 91 |
|
|
The matching string is stored in the variable.
|
| 92 |
|
|
If the first character between the brackets is a \fB]\fR then
|
| 93 |
|
|
it is treated as part of \fIchars\fR rather than the closing
|
| 94 |
|
|
bracket for the set.
|
| 95 |
|
|
.TP 10
|
| 96 |
|
|
\fB[^\fIchars\fB]\fR
|
| 97 |
|
|
The input field consists of any number of characters not in
|
| 98 |
|
|
\fIchars\fR.
|
| 99 |
|
|
The matching string is stored in the variable.
|
| 100 |
|
|
If the character immediately following the \fB^\fR is a \fB]\fR then it is
|
| 101 |
|
|
treated as part of the set rather than the closing bracket for
|
| 102 |
|
|
the set.
|
| 103 |
|
|
.LP
|
| 104 |
|
|
The number of characters read from the input for a conversion is the
|
| 105 |
|
|
largest number that makes sense for that particular conversion (e.g.
|
| 106 |
|
|
as many decimal digits as possible for \fB%d\fR, as
|
| 107 |
|
|
many octal digits as possible for \fB%o\fR, and so on).
|
| 108 |
|
|
The input field for a given conversion terminates either when a
|
| 109 |
|
|
white-space character is encountered or when the maximum field
|
| 110 |
|
|
width has been reached, whichever comes first.
|
| 111 |
|
|
If a \fB*\fR is present in the conversion specifier
|
| 112 |
|
|
then no variable is assigned and the next scan argument is not consumed.
|
| 113 |
|
|
|
| 114 |
|
|
.SH "DIFFERENCES FROM ANSI SSCANF"
|
| 115 |
|
|
.PP
|
| 116 |
|
|
The behavior of the \fBscan\fR command is the same as the behavior of
|
| 117 |
|
|
the ANSI C \fBsscanf\fR procedure except for the following differences:
|
| 118 |
|
|
.IP [1]
|
| 119 |
|
|
\fB%p\fR and \fB%n\fR conversion specifiers are not currently
|
| 120 |
|
|
supported.
|
| 121 |
|
|
.IP [2]
|
| 122 |
|
|
For \fB%c\fR conversions a single character value is
|
| 123 |
|
|
converted to a decimal string, which is then assigned to the
|
| 124 |
|
|
corresponding \fIvarName\fR;
|
| 125 |
|
|
no field width may be specified for this conversion.
|
| 126 |
|
|
.IP [3]
|
| 127 |
|
|
The \fBl\fR, \fBh\fR, and \fBL\fR modifiers are ignored; integer
|
| 128 |
|
|
values are always converted as if there were no modifier present
|
| 129 |
|
|
and real values are always converted as if the \fBl\fR modifier
|
| 130 |
|
|
were present (i.e. type \fBdouble\fR is used for the internal
|
| 131 |
|
|
representation).
|
| 132 |
|
|
|
| 133 |
|
|
.SH KEYWORDS
|
| 134 |
|
|
conversion specifier, parse, scan
|
