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

Ulm's Oberon Library:
ConstStrings

NAME

ConstStrings - WORM-device for strings

SYNOPSIS

TYPE String = POINTER TO StringRec;
TYPE StringRec =
   RECORD
      (Disciplines.ObjectRec)
      (* read-only *)
      len: Streams.Count;
      hashval: LONGINT;
   END;
TYPE Domain = POINTER TO DomainRec;
TYPE DomainRec = RECORD (Disciplines.ObjectRec) END;
VAR std: Domain; (* default domain *)



PROCEDURE CreateDomain(VAR domain: Domain);
PROCEDURE Init(VAR s: Streams.Stream);
PROCEDURE Close(s: Streams.Stream; VAR string: String);
PROCEDURE CloseD(s: Streams.Stream; domain: Domain; VAR string: String);
PROCEDURE Create(VAR string: String; s: ARRAY OF CHAR);
PROCEDURE CreateD(VAR string: String; domain: Domain; s: ARRAY OF CHAR);
PROCEDURE Open(VAR s: Streams.Stream; string: String);
PROCEDURE Compare(string1, string2: String) : INTEGER;
PROCEDURE Write(s: Streams.Stream; string: String);
PROCEDURE Extract(VAR s: ARRAY OF CHAR; string: String);

DESCRIPTION

Strings of type ConstStrings.String are written once and can be read multiply afterwards (WORM). A string is opened for writing with Init. If writing is completed Close or CloseD are to be called in order to get a reference to the string. Close and CloseD check if the string has already been entered into the table of the given domain (std in case of Close) and, if so, return the same string reference. Thus strings of the same domain are equal iff their references are equal. Close and CloseD store the length of the string and its hashvalue into the public components. Afterwards the string can be read after opening with Open. Note that Close and CloseD are used only for closing the initial stream. Streams opened by Open are to be closed by Streams.Close or Streams.Release. Create and CreateD handle the standard case of converting character arrays to constant strings. Note, however, that strings passed to Create or CreateD must be 0X-terminated. (Otherwise an assertion will fail.)

Compare returns an integer less than zero, equal to zero, or greater than zero if string1 is less than, equal, or greater than string2. Both strings may be of different domains.

Write copies string to s and returns the number of bytes written in s.count. Extract copies string to the character array s. The resulting string is guaranteed to be 0X-terminated.

EXAMPLE

The following example converts a given string into a string reference of ConstStrings:

PROCEDURE PutString(VAR string: ConstStrings.String;
                    buf: ARRAY OF CHAR);
   VAR
      s: Streams.Stream;
BEGIN
   ConstStrings.Init(s);
   Write.StringS(s, buf);
   ConstStrings.Close(s, string);
END PutString;

GetString copies the value of string into buf:

PROCEDURE GetString(string: ConstStrings.String;
                    VAR buf: ARRAY OF CHAR);
BEGIN
   ConstStrings.Open(s, string);
   Strings.Read(buf, s);
   Streams.Release(s);
END GetString;

BUGS

Seeking on the initial stream is permitted but the current position of the stream must be left at the end of the written string which is not necessarily the end of the stream. This is required because the current implementation of Close and CloseD reuses initial streams.

Edited by: borchert, last change: 2004/06/25, revision: 1.7, converted to HTML: 2007/02/27