READF - formatted character stream input.

Usage:

B:
   status = readf( [unit,] format, arg1, arg2, ... );
   status = readf( -1, string, format, arg1, arg2, ... );
/* C users use "scanf" family */

Where:

unit

is the number of an open input unit. If "unit" is not specified, the default is the current read unit.

format

is a format string as described below.

arg1, arg2, ...

indicate where to put the data which is read.

string

points to a string from which READF is to obtain its data (core-to-core I/O). To indicate that READF is to read from a string, you must specify a "unit" of -1 as shown above.

status

is a positive integer indicating the number of arguments which were correctly used, provided the read operation was successful. If an error appeared in "format" or if an ordinary character in "format" did not match the next input character, READF returns the negative of the character position (plus one) in "format" at which the error occurred.

Examples:

readf("%g*n", astring );
readf(4, "%s%f%f%d", astring, &float1, &float2, &int );
readf(-1, instring, "%#s%4c%3d%#g*n", &char, &int );

Description:

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.

Format

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>

"#" 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 );

"<char>" indicates the type of data object being read in. The available types are

c

Character. If no "nn" is given, one character is read. Use "%-c" to get the next character, even if it is a blank, tab, or new-line. If "nn" is specified, the given number of characters are placed in the word, right-justified. Since all characters after the first are placed in the word by shifting and ORing, an "nn" greater than four will result in the word containing the last four characters read.

d

Decimal integer. A possibly signed integer number is collected from the input stream. Collection stops when a non-digit is encountered. If a non-digit is encountered and there is an "nn" which is not exhausted, an error is returned.

f

Floating point. READF obtains from the input stream a floating point number consisting of a possibly signed mantissa which may or may not contain a decimal point, possibly followed by an 'e' or 'E' and a possibly signed exponent. If the number is properly formed, but is too large or too small to represent on the machine, the largest or smallest positive or negative value will be assigned. If an "nn" is not specified, collection ends when an inappropriate character is read. If an "nn" is given, the next "nn" characters must be in the correct form or else READF makes no assignment and returns immediately.

i

Integer. If the leading digit of the number is a zero, it is interpreted as an octal value; otherwise, it is interpreted as decimal. See "o" and "d" formats for information on reading octal and decimal integers.

o

Octal. READF reads an octal number from the input stream. The rules are the same as for "d" format, except that the digits must be in the range zero through seven.

g

Get string. READF collects all the characters in the input stream up to but not including the next '*n'. It is not intended for use with an "nn", although one may be specified. "g" is useful for forcing the next input to begin on a new line. The "g" format group will read in a null string; "%#g*n" would be used to collect the remainder of a line, if it is possibly null.

s

String. Normally, this format group directs READF to collect characters from the input stream until a blank, tab or new-line is encountered. An "nn" may be specified to force the collection of a string which contains embedded blanks, tabs, or new-lines.

Notes:

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"

2 : 3

Copyright © 2000, Thinkage Ltd.