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

Ulm's Oberon Library:
Lines

NAME

Lines - conversion of line positions in stream offsets and vice versa

SYNOPSIS

TYPE Location =
   RECORD
      (Objects.ObjectRec)
      (* location in input stream *)
      line, pos: Streams.Count; (* both starting from 0 *)
      offset: Streams.Count;
   END;



CONST streamNotScannedYet = 0;
CONST lineNumberOutOfRange = 1;
CONST positionOutOfRange = 2;
CONST invalidPos = 3;
CONST errorcodes = 4;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: SHORTINT;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errorcodes OF Events.Message;



PROCEDURE Scan(s: Streams.Stream);
PROCEDURE Scanned(s: Streams.Stream) : BOOLEAN;
PROCEDURE ConvertPos(s: Streams.Stream; pos: Streams.Count;
                     VAR loc: Location);
PROCEDURE ConvertLoc(s: Streams.Stream; loc: Location;
                     VAR pos: Streams.Count);
PROCEDURE SetPos(s: Streams.Stream; loc: Location);
PROCEDURE GetPos(s: Streams.Stream; VAR loc: Location);



PROCEDURE NumberOfLines(s: Streams.Stream) : Streams.Count;

DESCRIPTION

Lines allows to convert ordinary stream positions to line/column tuples and vice versa. For this to work, Scan must be called initially at the position which is to be treated as the beginning of the first line. Scan scans the entire stream from the current position and builds up an internal line table which is attached to the stream. All other operations lead to streamNotScannedYet if Scan has not been called previously for the given stream. Please note that Scan doesn't rewind the stream. Scan should be called again, if the stream contents gets changed, if the stream has been extended, or if the line terminator (see StreamDisciplines) has been changed.

Scanned returns TRUE if the given stream has been scanned yet by Lines.

ConvertPos takes a stream offset and converts it into a line/column tuple. Please note that line numbers (component line) and columns (component pos) are counted from 0. The given stream offset must not point inside a line terminator or beyond the stream length. ConvertLoc takes a location and converts it into an absolute stream position.

Lines offers the operations GetPos and SetPos which are similar to those of Streams but take a location instead of an absolute stream position.

NumberOfLines returns the number of lines which have been found by Scan.

DIAGNOSTICS

Errors lead to events raised by Lines, Streams, or an underlying implementation. Following errors may be raised by Lines:
streamNotScannedYet
One of the operations has been called without a prior invocation of Scan for the given stream.
lineNumberOutOfRange
A line number was given to ConvertPos or SetPos which was outside the range [0..NumberOfLines(s)).
positionOutOfRange
A position inside a line (column) was given which was outside the range [0..line length].
invalidPos
An absolute stream position was given to ConvertPos or Setpos which pointed inside a line terminator or beyond the known stream length.

SEE ALSO

RelatedEvents
error handling
StreamConditions
definition of line terminator
Streams
stream operations and stream positions
Edited by: borchert, last change: 1996/12/02, revision: 1.2, converted to HTML: 1997/04/28

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