diff options
Diffstat (limited to 'doc/scan.n')
| -rw-r--r-- | doc/scan.n | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/doc/scan.n b/doc/scan.n new file mode 100644 index 0000000..96121f8 --- /dev/null +++ b/doc/scan.n @@ -0,0 +1,134 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) scan.n 1.12 96/08/26 13:00:13 +'\" +.so man.macros +.TH scan n "" Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +scan \- Parse string using conversion specifiers in the style of sscanf +.SH SYNOPSIS +\fBscan \fIstring format varName \fR?\fIvarName ...\fR? +.BE + +.SH INTRODUCTION +.PP +This command parses fields from an input string in the same fashion +as the ANSI C \fBsscanf\fR 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. +\fIString\fR gives the input to be parsed and \fIformat\fR indicates +how to parse it, using \fB%\fR conversion specifiers as in \fBsscanf\fR. +Each \fIvarName\fR gives the name of a variable; when a field is +scanned from \fIstring\fR the result is converted back into a string +and assigned to the corresponding variable. + +.SH "DETAILS ON SCANNING" +.PP +\fBScan\fR operates by scanning \fIstring\fR and \fIformatString\fR together. +If the next character in \fIformatString\fR is a blank or tab then it +matches any number of white space characters in \fIstring\fR (including +zero). +Otherwise, if it isn't a \fB%\fR character then it +must match the next character of \fIstring\fR. +When a \fB%\fR is encountered in \fIformatString\fR, it indicates +the start of a conversion specifier. +A conversion specifier contains three fields after the \fB%\fR: +a \fB*\fR, which indicates that the converted value is to be discarded +instead of assigned to a variable; a number indicating a maximum field +width; and a conversion character. +All of these fields are optional except for the conversion character. +.PP +When \fBscan\fR finds a conversion specifier in \fIformatString\fR, it +first skips any white-space characters in \fIstring\fR. +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 \fBscan\fR. +The following conversion characters are supported: +.TP 10 +\fBd\fR +The input field must be a decimal integer. +It is read in and the value is stored in the variable as a decimal string. +.TP 10 +\fBo\fR +The input field must be an octal integer. It is read in and the +value is stored in the variable as a decimal string. +.TP 10 +\fBx\fR +The input field must be a hexadecimal integer. It is read in +and the value is stored in the variable as a decimal string. +.TP 10 +\fBc\fR +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. +.TP 10 +\fBs\fR +The input field consists of all the characters up to the next +white-space character; the characters are copied to the variable. +.TP 10 +\fBe\fR or \fBf\fR or \fBg\fR +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 \fBe\fR or \fBE\fR 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. +.TP 10 +\fB[\fIchars\fB]\fR +The input field consists of any number of characters in +\fIchars\fR. +The matching string is stored in the variable. +If the first character between the brackets is a \fB]\fR then +it is treated as part of \fIchars\fR rather than the closing +bracket for the set. +.TP 10 +\fB[^\fIchars\fB]\fR +The input field consists of any number of characters not in +\fIchars\fR. +The matching string is stored in the variable. +If the character immediately following the \fB^\fR is a \fB]\fR then it is +treated as part of the set rather than the closing bracket for +the set. +.LP +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 \fB%d\fR, as +many octal digits as possible for \fB%o\fR, 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 \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 +the ANSI C \fBsscanf\fR procedure except for the following differences: +.IP [1] +\fB%p\fR and \fB%n\fR conversion specifiers are not currently +supported. +.IP [2] +For \fB%c\fR conversions a single character value is +converted to a decimal string, which is then assigned to the +corresponding \fIvarName\fR; +no field width may be specified for this conversion. +.IP [3] +The \fBl\fR, \fBh\fR, and \fBL\fR modifiers are ignored; integer +values are always converted as if there were no modifier present +and real values are always converted as if the \fBl\fR modifier +were present (i.e. type \fBdouble\fR is used for the internal +representation). + +.SH KEYWORDS +conversion specifier, parse, scan |