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

Ulm's Oberon Library:
SubStreams

NAME

SubStreams - streams representing an interval of another stream

SYNOPSIS

CONST noSeek = 0; noLength = 1; errors = 2;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorCode = SHORTINT;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



TYPE OpenProc = PROCEDURE (VAR s: Streams.Stream;
                           base: Streams.Stream;
                           from, length: Streams.Count;
                           errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE Register(type: Services.Type; open: OpenProc);



PROCEDURE Open(VAR s: Streams.Stream;
               base: Streams.Stream;
               from, length: Streams.Count;
               errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE Supported(s: Streams.Stream) : BOOLEAN;
PROCEDURE DirectlySupported(s: Streams.Stream) : BOOLEAN;



PROCEDURE Join(VAR s: Streams.Stream; s1, s2: Streams.Stream;
               errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

SubStreams allows to create streams which represent a selected interval of another stream. The substream implementation may be offered by the stream implementation of the base stream itself, by a separate service provider (see Services), or defaults to that of Maps. Specific substream implementations are expected to operate faster than the default implementation by avoiding at least one level of intermediate calls.

Open creates a stream which represents the subrange [from..from+length) of base which will be mapped to [0..length) on s. Note that s works in general as filter object of base, i.e. all other operations may be forwarded as well (if supported by Forwarders).

Supported allows to check whether a stream may be passed as base stream to Open. DirectlySupported returns TRUE if substreams are directly supported by the implementation of s, i.e. SubStreams needs not to create a stream on base of Maps for s as base stream.

Join returns a stream which accesses s1 and s2 in a concatenated way. If s1 and s2 are neighbouring substreams of the the same base stream, Join will create a new substream directly from the common base stream -- otherwise s1 and s2 will be tied together by Maps.

Register registers a specific implementation for the given type (which must be an extension of Streams.Stream) and all extensions thereof if not overridden by more specific calls). Note that the opening procedure needs not to call Forwarders.Forward -- this will be done by SubStreams.

DIAGNOSTICS

Following errors may be generated by SubStreams:
noSeek
This error is returned by Open if the base stream (in the default case) does not support seek and tell operations of Streams.
noLength
Join was unable to determine the length of s1 or s2.
All other error events are generated by the specific implementations or Streams.

Register checks its parameter for validity in form of assertions.

SEE ALSO

Forwarders
general support of filter objects
Maps
more general stream mapping support
MemStreams
stream implementation which is suitable as substream implementation if the stream contents resides in a contiguous buffer
Services
type system (as first class objects)
Streams
stream operations
Edited by: borchert, last change: 1996/12/09, revision: 1.4, converted to HTML: 1997/04/28

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