B: status = readf( [unit,] format, arg1, arg2, ... ); status = readf( -1, string, format, arg1, arg2, ... ); /* C users use "scanf" family */
readf("%g*n", astring ); readf(4, "%s%f%f%d", astring, &float1, &float2, &int ); readf(-1, instring, "%#s%4c%3d%#g*n", &char, &int );
READF reads the input stream, interprets it according to a format, makes any conversions necessary, and performs any required assignments to the arguments. Except for the "unit" number, ALL ARGUMENTS PASSED TO READF MUST BE POINTERS, with the exception of arguments corresponding to "wild cards" in the format string (see "Format" below).
READF may obtain its input from a "unit" which is open for reading, or from a "string". Reading always stops when a '*e' marking end-of-file or end-of-string is obtained.
The "format" string is composed of format groups or ordinary characters. If an ordinary character is encountered, it is expected to match the next character in the input stream; if not, a format error is returned. A format group is of the following form (braces surround optional fields).
%{#}{-}{nn|?|*}<char>The "%" character indicates the start of a format group. Use a format of "%%" to match a "%" character in the input stream.
"#" indicates that this format group does not have a corresponding argument. Characters matching the group are to be collected, but READF does not assign the result to any argument.
"-" indicates that the characters matching the format group are to be collected starting immediately with the next character in the input stream. Normally, READF skips over preceding tabs, new-lines, or blanks before processing a format group.
"nn" is integer which is taken as a field width for the data being read in. Normally input is "free format", with format items separated by one or more blanks, tabs, or new-lines. In place of an integer, you may specify a "?" or "*" character; in this case, the corresponding argument in the argument list must be an integer giving the field width. For example, in
readf( unit, "%*s", i, cp );the variable "i" gives an integer value that is used as the field width. A string of this width is read into the area indicated by the pointer "cp". (If the above read operation was successful, "readf" would return a value of 2, indicating that it successfully used both "i" and "cp".)
"<char>" indicates the type of data object being read in. The available types are
If there are more arguments than data objects read in, the unmatched arguments will have undefined values. If there are fewer arguments specified than what READF needs, READF aborts.
READF always uses UNGETC to return to the input stream the character which caused the scan to stop. In free format mode, this is usually a blank, tab, or new-line.
The construct "%#0s" is useful if you want to skip white space characters (blanks or tabs) followed by a known character. For example, the format
"%d%#0s:%d"could be used to read inputs like
2 : 3where there is an arbitrary number of white space characters before the colon. (The "#" character indicates that the "%s" construct does not have a corresponding argument in the argument list.)
Copyright © 2000, Thinkage Ltd.