Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
Scan

NAME

Scan - formatted input from streams

SYNOPSIS

PROCEDURE F(fmt: ARRAY OF CHAR);
PROCEDURE F1(fmt: ARRAY OF CHAR; VAR p1: ARRAY OF BYTE);
PROCEDURE F2(fmt: ARRAY OF CHAR; VAR p1, p2: ARRAY OF BYTE);
PROCEDURE F3(fmt: ARRAY OF CHAR; VAR p1, p2, p3: ARRAY OF BYTE);
PROCEDURE F4(fmt: ARRAY OF CHAR; VAR p1, p2, p3, p4: ARRAY OF BYTE);
PROCEDURE F5(fmt: ARRAY OF CHAR; VAR p1, p2, p3, p4, p5: ARRAY OF BYTE);
PROCEDURE F6(fmt: ARRAY OF CHAR; VAR p1, p2, p3, p4, p5, p6: ARRAY OF BYTE);
PROCEDURE F7(fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7: ARRAY OF BYTE);
PROCEDURE F8(fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7, p8: ARRAY OF BYTE);
PROCEDURE F9(fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7, p8, p9: ARRAY OF BYTE);



PROCEDURE S(in: Streams.Stream; fmt: ARRAY OF CHAR);
PROCEDURE S1(in: Streams.Stream; fmt: ARRAY OF CHAR; VAR p1: ARRAY OF BYTE);
PROCEDURE S2(in: Streams.Stream; fmt: ARRAY OF CHAR; VAR p1, p2: ARRAY OF BYTE);
PROCEDURE S3(in: Streams.Stream; fmt: ARRAY OF CHAR;
	     VAR p1, p2, p3: ARRAY OF BYTE);
PROCEDURE S4(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4: ARRAY OF BYTE);
PROCEDURE S5(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5: ARRAY OF BYTE);
PROCEDURE S6(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6: ARRAY OF BYTE);
PROCEDURE S7(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7: ARRAY OF BYTE);
PROCEDURE S8(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7, p8: ARRAY OF BYTE);
PROCEDURE S9(in: Streams.Stream; fmt: ARRAY OF CHAR;
             VAR p1, p2, p3, p4, p5, p6, p7, p8, p9: ARRAY OF BYTE);

DESCRIPTION

Scan offers formatted reading in scanf(3) style from Streams.stdin (F through F9) or from in (S through S9). The procedures scan input in dependence of the format string fmt and put read items into parameters p1 through p9. The number of parameters determine the procedure name.

The format string fmt is interpreted as follows: Any character not belonging to an escape sequence introduced by \ or a format element introduced by % must match the next input character. Scan skips the next input character on success and aborts processing otherwise. A blank character in the format string matches a possibly empty sequence of white space characters in Streams.stdin resp. in. White space is given by StreamDisciplines.

Escape sequences encode one character which must match the next input character. Following escape sequences are understood:

\[0-9A-F]+
character in hex representation.
\b
backspace character (08X).
\e
escape character (1BX).
\f
form feed (0CX).
\n
new line (as defined by StreamDisciplines).
\q
single quote ("'").
\Q
quote character (ASCII.quote).
\r
carriage return (0DX).
\t
horizontal tab (09X).
\&
audible bell (07X).

It is important to note that in despite to scanf(3) "\n" and "\t" does not lead to white space skipping. Instead, they match a new line resp. a tab character.

Format elements must conform to following syntax: 

FormatElement = "%" [Flags] [Width] Conversion .
Flags = "*" .
Width = { DecDigits } .
DecDigits = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" .
Conversion = "c" | "d" | "e" | "f" | "g" | "o" | "s" | "x" | ScanSet .
ScanSet = "[" CharSet "]" .
CharSet = Complement | Set .
Complement = "^" Set .
Set = [ "]" ] { Range | AnyChar } .
Range = AnyChar "-" AnyChar .
Conversions of integer and real numbers accept leading white space. A positive width (default: 0) limits the number of characters read (after skipping white space).

All format elements assigns the read item to the next parameter (p1 through p9). Assignment can be suppressed by use of the "*" flag.

Following conversions are supported:

c
read next character.
d
read integer in decimal notation.
e,f,g
read real number in Oberon syntax. "e" and "d" instead of "E" and "D" are accepted.
o
read integer in octal notation.
s
read string. Leading white space is skipped. String scanning is stopped on the first white space character or if the given parameter is filled. 0X-termination is guaranteed.
x
read integer in hexadecimal notation.
[...]
read sequence of characters according to given character set. String scanning is stopped on the first character which is not member of the given character set, or if the given parameter is filled. 0X-termination is guaranteed.

Termination characters are put back to the input stream if possible.

DIAGNOSTICS

If the input does not match the given format string Scan stops scanning and returns immediately. Scan returns the number of stored items in Streams.stdin.count resp. in.count.

SEE ALSO

Read   		       alternative routines for	formatted input
StreamDisciplines      definition of white space and line terminator
Streams   	       stream operations

BUGS

The current version does not raise events for some common errors, e.g. if the number of parameters and format elements does not match.

Streams does not support Streams.Back for unbuffered streams. Thus termination characters are lost by reading from streams with buffering mode Streams.nobuf.

Edited by: borchert, last change: 91/11/18, revision: 1.3, converted to HTML: 1997/04/28

Oberon || Library || Module Index || Search Engine || Definition || Module