Modula-2 || Compiler & Tools || Library || Search Engine

Ulm's Modula-2 Library:
LongStrings

NAME

LongStrings - dynamic strings handling

SYNOPSIS

TYPE Long;



CONST LastChar = -1; NotFound = -2;



(* handling of longs *)
PROCEDURE Alloc (VAR long : Long);
PROCEDURE Dispose (VAR long : Long);
PROCEDURE Free (VAR long : Long);
PROCEDURE StrAdr(long : Long) : ADDRESS;
PROCEDURE StrSize(long : Long) : CARDINAL;
PROCEDURE CutLong(long : Long; newsize : CARDINAL);
PROCEDURE ClearLong (long : Long);



(* diagnostic *)
PROCEDURE ValidLong(long : Long) : BOOLEAN;



(* appending text *)
PROCEDURE AddString(long : Long; text : ARRAY OF CHAR);
PROCEDURE AddChar(long : Long; char : CHAR);
PROCEDURE AddBytes(long : Long; add : ADDRESS; n : CARDINAL);



(* searching  *)
PROCEDURE GetChar (long : Long; index : INTEGER) : CHAR;
PROCEDURE CountChar (long : Long; char : CHAR) : CARDINAL;
PROCEDURE FindChar(long : Long; char : CHAR;
                   offset, count : INTEGER) : INTEGER;



(* output *)
PROCEDURE Lwrite(long : Long; file : FILE) : BOOLEAN;
PROCEDURE LwritePart(long : Long; from, to : INTEGER;
                     file : FILE) : BOOLEAN;
PROCEDURE Echo(origin, echo : FILE) : BOOLEAN;
PROCEDURE NoEcho(origin, echo : FILE) : BOOLEAN;

DESCRIPTION

This module handles with objects called Long, which live in the dynamic memory area of a process and may grow up to any size the relevant system parameters admit. Reallocation is performed implicitly when the contents of a Long is extended.

Alloc creates long and allocates some memory for it. Dispose disposes long and deallocates the memory occupied. Free should be used instead of Dispose if many longs are used very temporary (f.i. in the scope of a procedure). This may improve performance and prevents from a partition of the dynamic memory into many small pieces.

The contents long (i.e. the information stored) is extented by AddChar, AddString, and AddBytes. AddChar adds a single character char, AddString appends a string text (up to terminating null byte respectively HIGH(text) and AddBytes copies n bytes found at the address given by adr into the contents of long. By means of AddBytes and AddChar even null bytes can be added.

StrSize yields the effective size of long, i.e. the number of bytes currently stored. A new size newsize can be defined by CutLong. ClearLong(long) is equivalent CutLong(long, 0).

The contents of long is always a coherent memory area beginning at the address returned by by StrAdr. LongStrings guarantees a null byte to be found at StrAdr(long) + StrSize(long).

Important note: StrAdr(long) is not a constant throughout the lifetime of long.

GetChar CountChar and FindChar access the contents of long. GetChar returns the character found at position index (ranging from 0 to size--1). index LastChar to obtain the last character of a long. CountChar counts the appearances of char in the contents of long. FindChar looks for a certain character. Searching is begun at position offset (LastChar means end of contents) and executed backward if count is negative . If char is found ABS(count) times, FindChar returns the corresponding index into contents, otherwise the result will be NotFound.

Lwrite writes the whole contents of long to the given file, LwritePart outputs a subrage specified by [from,to].

Echo defines an echo file echo for file source Each further output by Lwrite and LwritePart to file source will be written to all its echo files as well. NoEcho with the same arguments as a prior call of Echo deletes an echo definition.

Note that any output of the modules P, F, E and OutLines may be echoed.

DIAGNOSTIC

ValidLong returns TRUE if long is regarded as a valid long. A long becomes invalid if disposed or freed or if allocation or reallocation fails because the process runs out of memory. By default, LongStrings will not recover from the latter situation since Storage would terminate the program before.

Output routines return FALSE in any case of error, StrSize and StrAdr return 0 respectively NIL if long is not a valid argument.

AUTHOR

Werner Stanglow

Edited by: borchert, last change: 1997/02/25, revision: 1.2, converted to HTML: 1997/04/28