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


Ulm's Oberon Library:
Strings


NAME

Strings - string operations

SYNOPSIS

(* error codes for streams *)
CONST endOfStringReached = 0;   (* write failure: end of string reached *)
CONST outOfRange = 1;           (* seek failure: position out of range *)
CONST badParameter = 2;         (* illegal parameter value (eg whence) *)
CONST posOutside = 3;           (* trunc failure: position beyond trunc pos *)
CONST errorcodes = 4;
TYPE ErrorCode = SHORTINT;
TYPE Event = POINTER TO EventRec;
TYPE EventRec =
   RECORD
      (Events.EventRec)
      stream: Streams.Stream;
      errorcode: ErrorCode;
   END;
VAR errormsg: ARRAY errorcodes OF Events.Message;
VAR error: Events.EventType;


TYPE Stream = POINTER TO StreamRec; TYPE StreamRec = RECORD (Streams.StreamRec) END;

PROCEDURE Write(stream: Streams.Stream; string: ARRAY OF CHAR); PROCEDURE WritePart(stream: Streams.Stream; string: ARRAY OF CHAR; sourceIndex: LONGINT); PROCEDURE Read(VAR string: ARRAY OF CHAR; stream: Streams.Stream); PROCEDURE ReadPart(VAR string: ARRAY OF CHAR; destIndex: LONGINT; stream: Streams.Stream); PROCEDURE Copy(VAR destination: ARRAY OF CHAR; source: ARRAY OF CHAR); PROCEDURE PartCopy(VAR destination: ARRAY OF CHAR; destIndex: LONGINT; source: ARRAY OF CHAR; sourceIndex: LONGINT); PROCEDURE Len(string: ARRAY OF CHAR) : LONGINT; PROCEDURE Concatenate(VAR destination: ARRAY OF CHAR; source: ARRAY OF CHAR); PROCEDURE Open(VAR stream: Streams.Stream; VAR string: ARRAY OF CHAR);

DESCRIPTION

The procedures of Strings follow these conventions:

Write seeks to position 0 of stream, truncates it to zero length and copies string to stream. WritePart works like Write but sourceIndex defines the starting offset of string.

Read copies the contents of stream from position 0 until end of stream to string. ReadPart takes destIndex as starting index of string.

Copy copies source to destination. PartCopy copies source[sourceIndex..] to destination[destIndex..]. Len returns the number of characters of string (without terminating 0X). Concatenate appends source to destination and is thus equivalent to PartCopy(destination, Len(destination), source, 0);

Open opens an array of characters as stream for unbuffered reading and writing. Seek, Tell, and Trunc are permitted. The string argument is expected to be initialized and 0X-terminated. The lowest index with string[index] = 0X determines the length of the stream. The stream may be extended by positioning to the end of the stream and writing to it. The maximal length of the stream is given by LEN(string) - 1. String streams may be shortened by use of Trunc. Because no buffering takes place results of write operations are immediately seen in the underlying string. The terminating 0X is not seen on the stream side and must not be written to the stream. Modifications of the underlying string must be followed by Streams.Touch to see the changes on the stream side.

EXAMPLE

Formatted I/O to strings:
PROCEDURE TimeString(hour, minute, second: INTEGER;
                     VAR time: ARRAY OF CHAR);
   VAR stream: Streams.Stream;
BEGIN
   Strings.Open(stream, time);
   Write.IntS(stream, hour, 2); Write.CharS(stream, ":");
   Write.IntS(stream, minute, 2); Write.CharS(stream, ":");
   Write.IntS(stream, second, 2);
   Streams.Release(stream);
END TimeString;

DIAGNOSTICS

Errors during the access of streams of type Stream are converted into events of RelatedEvents. By default, these events are being queued.

Error events which are generated by Strings are of type error and contain one of the error codes following:

endOfStringReached
A write operation failed because the end of the underlying character array was reached.
outOfRange
Seek was requested to position outside the currently valid range (0 to the string length).
badParameter
A illegal parameter value was given, e.g. an undefined value for whence.
posOutside
A trunc operation failed because the current position would be invalidated by the trunc position.

By default, events of type error are ignored.

SEE ALSO

Streams
stream operations
Texts
in-memory streams

Edited by: borchert, last change: 2003/07/10, revision: 1.9, converted to HTML: 2003/07/10

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