198 lines
10 KiB
HTML
198 lines
10 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - scan manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="scan.htm#M2" NAME="L1049">NAME</A>
|
|
<DL><DD>scan - Parse string using conversion specifiers in the style of sscanf</DL>
|
|
<DD><A HREF="scan.htm#M3" NAME="L1050">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>scan </B><I>string format </I>?<I>varName varName ...</I>?
|
|
</DL>
|
|
<DD><A HREF="scan.htm#M4" NAME="L1051">INTRODUCTION</A>
|
|
<DD><A HREF="scan.htm#M5" NAME="L1052">DETAILS ON SCANNING</A>
|
|
<DL>
|
|
<DD><A HREF="scan.htm#M6" NAME="L1053"><B>d</B></A>
|
|
<DD><A HREF="scan.htm#M7" NAME="L1054"><B>o</B></A>
|
|
<DD><A HREF="scan.htm#M8" NAME="L1055"><B>x</B></A>
|
|
<DD><A HREF="scan.htm#M9" NAME="L1056"><B>u</B></A>
|
|
<DD><A HREF="scan.htm#M10" NAME="L1057"><B>i</B></A>
|
|
<DD><A HREF="scan.htm#M11" NAME="L1058"><B>c</B></A>
|
|
<DD><A HREF="scan.htm#M12" NAME="L1059"><B>s</B></A>
|
|
<DD><A HREF="scan.htm#M13" NAME="L1060"><B>e</B> or <B>f</B> or <B>g</B></A>
|
|
<DD><A HREF="scan.htm#M14" NAME="L1061"><B>[</B><I>chars</I><B>]</B></A>
|
|
<DD><A HREF="scan.htm#M15" NAME="L1062"><B>[^</B><I>chars</I><B>]</B></A>
|
|
<DD><A HREF="scan.htm#M16" NAME="L1063"><B>n</B></A>
|
|
</DL>
|
|
<DD><A HREF="scan.htm#M17" NAME="L1064">DIFFERENCES FROM ANSI SSCANF</A>
|
|
<DL>
|
|
</DL>
|
|
<DD><A HREF="scan.htm#M18" NAME="L1065">SEE ALSO</A>
|
|
<DD><A HREF="scan.htm#M19" NAME="L1066">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
scan - Parse string using conversion specifiers in the style of sscanf
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>scan </B><I>string format </I>?<I>varName varName ...</I>?<BR>
|
|
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
|
This command parses fields from an input string in the same fashion as the
|
|
ANSI C <B>sscanf</B> procedure and returns a count of the number of
|
|
conversions performed, or -1 if the end of the input string is reached
|
|
before any conversions have been performed. <I>String</I> gives the input
|
|
to be parsed and <I>format</I> indicates how to parse it, using <B>%</B>
|
|
conversion specifiers as in <B>sscanf</B>. Each <I>varName</I> gives the
|
|
name of a variable; when a field is scanned from <I>string</I> the result is
|
|
converted back into a string and assigned to the corresponding variable.
|
|
If no <I>varName</I> variables are specified, then <B>scan</B> works in an
|
|
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.
|
|
|
|
<H3><A NAME="M5">DETAILS ON SCANNING</A></H3>
|
|
<B>Scan</B> operates by scanning <I>string</I> and <I>format</I> together.
|
|
If the next character in <I>format</I> is a blank or tab then it
|
|
matches any number of white space characters in <I>string</I> (including
|
|
zero).
|
|
Otherwise, if it isn't a <B>%</B> character then it
|
|
must match the next character of <I>string</I>.
|
|
When a <B>%</B> is encountered in <I>format</I>, it indicates
|
|
the start of a conversion specifier.
|
|
A conversion specifier contains up to four fields after the <B>%</B>:
|
|
a <B>*</B>, which indicates that the converted value is to be discarded
|
|
instead of assigned to a variable; a XPG3 position specifier; a number
|
|
indicating a maximum field width; and a conversion character.
|
|
All of these fields are optional except for the conversion character.
|
|
The fields that are present must appear in the order given above.
|
|
<P>
|
|
When <B>scan</B> finds a conversion specifier in <I>format</I>, it
|
|
first skips any white-space characters in <I>string</I> (unless the
|
|
specifier is <B>[</B> or <B>c</B>).
|
|
Then it converts the next input characters according to the
|
|
conversion specifier and stores the result in the variable given
|
|
by the next argument to <B>scan</B>.
|
|
<P>
|
|
If the <B>%</B> is followed by a decimal number and a <B>$</B>, as in
|
|
``<B>%2$d</B>'', then the variable to use is not taken from the next
|
|
sequential argument. Instead, it is taken from the argument indicated
|
|
by the number, where 1 corresponds to the first <I>varName</I>. If
|
|
there are any positional specifiers in <I>format</I> then all of the
|
|
specifiers must be positional. Every <I>varName</I> on the argument
|
|
list must correspond to exactly one conversion specifier or an error
|
|
is generated, or in the inline case, any position can be specified
|
|
at most once and the empty positions will be filled in with empty strings.
|
|
<P>
|
|
The following conversion characters are supported:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>d</B></A><DD>
|
|
The input field must be a decimal integer.
|
|
It is read in and the value is stored in the variable as a decimal string.
|
|
<P><DT><A NAME="M7"><B>o</B></A><DD>
|
|
The input field must be an octal integer. It is read in and the
|
|
value is stored in the variable as a decimal string.
|
|
If the value exceeds MAX_INT (017777777777 on platforms using 32-bit
|
|
integers), it will be truncated to a signed integer. Hence, 037777777777
|
|
will appear as -1 on a 32-bit machine.
|
|
<P><DT><A NAME="M8"><B>x</B></A><DD>
|
|
The input field must be a hexadecimal integer. It is read in
|
|
and the value is stored in the variable as a decimal string.
|
|
If the value exceeds MAX_INT (0x7FFFFFFF on platforms using 32-bit
|
|
integers), it will be truncated to a signed integer. Hence, 0xFFFFFFFF
|
|
will appear as -1 on a 32-bit machine.
|
|
<P><DT><A NAME="M9"><B>u</B></A><DD>
|
|
The input field must be a decimal integer. The value is stored in the
|
|
variable as an unsigned decimal integer string.
|
|
<P><DT><A NAME="M10"><B>i</B></A><DD>
|
|
The input field must be an integer. The base (i.e. decimal, octal, or
|
|
hexadecimal) is determined in the same fashion as described in
|
|
<B><A HREF="../TkCmd/expr.htm">expr</A></B>. The value is stored in the variable as a decimal string.
|
|
<P><DT><A NAME="M11"><B>c</B></A><DD>
|
|
A single character is read in and its binary value is stored in
|
|
the variable as a decimal string.
|
|
Initial white space is not skipped in this case, so the input
|
|
field may be a white-space character.
|
|
This conversion is different from the ANSI standard in that the
|
|
input field always consists of a single character and no field
|
|
width may be specified.
|
|
<P><DT><A NAME="M12"><B>s</B></A><DD>
|
|
The input field consists of all the characters up to the next
|
|
white-space character; the characters are copied to the variable.
|
|
<P><DT><A NAME="M13"><B>e</B> or <B>f</B> or <B>g</B></A><DD>
|
|
The input field must be a floating-point number consisting
|
|
of an optional sign, a string of decimal digits possibly
|
|
containing a decimal point, and an optional exponent consisting
|
|
of an <B>e</B> or <B>E</B> followed by an optional sign and a string of
|
|
decimal digits.
|
|
It is read in and stored in the variable as a floating-point string.
|
|
<P><DT><A NAME="M14"><B>[</B><I>chars</I><B>]</B></A><DD>
|
|
The input field consists of any number of characters in
|
|
<I>chars</I>.
|
|
The matching string is stored in the variable.
|
|
If the first character between the brackets is a <B>]</B> then
|
|
it is treated as part of <I>chars</I> rather than the closing
|
|
bracket for the set.
|
|
If <I>chars</I>
|
|
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
|
|
character between <I>a</I> and <I>b</I> (inclusive) will match.
|
|
If the first or last character between the brackets is a <B>-</B>, then
|
|
it is treated as part of <I>chars</I> rather than indicating a range.
|
|
<P><DT><A NAME="M15"><B>[^</B><I>chars</I><B>]</B></A><DD>
|
|
The input field consists of any number of characters not in
|
|
<I>chars</I>.
|
|
The matching string is stored in the variable.
|
|
If the character immediately following the <B>^</B> is a <B>]</B> then it is
|
|
treated as part of the set rather than the closing bracket for
|
|
the set.
|
|
If <I>chars</I>
|
|
contains a sequence of the form <I>a</I><B>-</B><I>b</I> then any
|
|
character between <I>a</I> and <I>b</I> (inclusive) will be excluded
|
|
from the set.
|
|
If the first or last character between the brackets is a <B>-</B>, then
|
|
it is treated as part of <I>chars</I> rather than indicating a range.
|
|
<P><DT><A NAME="M16"><B>n</B></A><DD>
|
|
No input is consumed from the input string. Instead, the total number
|
|
of chacters scanned from the input string so far is stored in the variable.
|
|
<P></DL>
|
|
<P>
|
|
The number of characters read from the input for a conversion is the
|
|
largest number that makes sense for that particular conversion (e.g.
|
|
as many decimal digits as possible for <B>%d</B>, as
|
|
many octal digits as possible for <B>%o</B>, and so on).
|
|
The input field for a given conversion terminates either when a
|
|
white-space character is encountered or when the maximum field
|
|
width has been reached, whichever comes first.
|
|
If a <B>*</B> is present in the conversion specifier
|
|
then no variable is assigned and the next scan argument is not consumed.
|
|
|
|
<H3><A NAME="M17">DIFFERENCES FROM ANSI SSCANF</A></H3>
|
|
The behavior of the <B>scan</B> command is the same as the behavior of
|
|
the ANSI C <B>sscanf</B> procedure except for the following differences:
|
|
<P>
|
|
<DL>
|
|
<P><DT>[1]<DD>
|
|
<B>%p</B> conversion specifier is not currently supported.
|
|
<P><DT>[2]<DD>
|
|
For <B>%c</B> conversions a single character value is
|
|
converted to a decimal string, which is then assigned to the
|
|
corresponding <I>varName</I>;
|
|
no field width may be specified for this conversion.
|
|
<P><DT>[3]<DD>
|
|
The <B>l</B>, <B>h</B>, and <B>L</B> modifiers are ignored; integer
|
|
values are always converted as if there were no modifier present
|
|
and real values are always converted as if the <B>l</B> modifier
|
|
were present (i.e. type <B>double</B> is used for the internal
|
|
representation).
|
|
<P><DT>[4]<DD>
|
|
If the end of the input string is reached before any conversions have been
|
|
performed and no variables are given, and empty string is returned.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M18">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/format.htm">format</A></B>, <B>sscanf</B>
|
|
<H3><A NAME="M19">KEYWORDS</A></H3>
|
|
<A href="../Keywords/C.htm#conversion specifier">conversion specifier</A>, <A href="../Keywords/P.htm#parse">parse</A>, <A href="../Keywords/S.htm#scan">scan</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 2000 Scriptics Corporation.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|