[_CDCSL_93-16_]<1>Cedar>release>TRope>RopeReader.mesa

RopeReader.mesa

written by Bill Paxton, January 1981

last edit by Paxton, September 13, 1982 9:33 am

last edit by McGregor, June 10, 1982 2:30 pm

last edit by Maxwell, January 5, 1983 8:36 am

last edit by Russ Atkinson, July 22, 1983 9:33 am

last edit by Doug Wyatt, November 4, 1988 3:27:02 pm PST

Plass, September 24, 1991 11:53 am PDT

RopeReader provides fast inline access to characters in ropes

designed for speed in reading a sequence of characters, either forwards or backwards

DIRECTORY

Basics USING [Comparison],

Rope USING [MaxLen, ROPE];

RopeReader: CEDAR DEFINITIONS ~ BEGIN

Overview

create a reader by RopeReader.Create

reader: RopeReader.Ref ← RopeReader.Create[];

position it where you want to read by SetPosition

RopeReader.SetPosition[reader,rope,index];

where rope is to the one to read from, and index is the initial position for the reader

you can reposition a reader at any time

read its position in any of the following ways:

[rope,index] ← RopeReader.Position[reader];

rope ← RopeReader.GetRope[reader];

index ← RopeReader.GetIndex[reader];

to read in ascending order (left to right)

initialize position at index of first character to be read

for example, use 0 to start at beginning of rope

then call Get which reads to the right and increments the position

char ← RopeReader.Get[reader];

to read in descending order (right to left)

initialize position after first character to be read

for example, use size of rope to start at end

then call Backwards which reads to the left and decrements the position

char ← RopeReader.Backwards[reader];

can also get a character without changing the reader position

to look at the next character that Get would return, call Peek

char ← RopeReader.Peek[reader];

to look at what Backwards would return, call PeekBackwards

char ← RopeReader.PeekBackwards[reader];

can intermix reading or peeking to left and right

don't need to reinitialize the reader to change direction

if read off either end of rope, you can choose either to get an error or a client-specified character

there are equality and comparison routines that use readers for efficiency

Equal, EqSubstr, EqSubstrs

Compare, CompareSubstr, CompareSubstrs

operations are also provided to read a block of characters

destination given by either a REF TEXT or a REF chars array

can read either forward or backwards from source

Declarations

ROPE: TYPE ~ Rope.ROPE;

MaxLen: INT ~ Rope.MaxLen;

Ref: TYPE ~ REF Body;

Body: TYPE ~ PRIVATE RECORD [

text: REF TEXT ¬, -- text buffer (must not be NIL)

current: NAT ¬ 0, -- index in text of current character (next to be returned by Get)

rope: ROPE ¬ NIL, -- rope that we are reading

index: INT ¬ 0, -- index in rope of text[0]

charForEndOfRope: BOOLEAN ¬ FALSE,

if true, return endChar; else give ERROR ReadOffEnd

endChar: CHAR ¬ 0C -- char to return when reach end of rope

];

ReadOffEnd: ERROR;

Operations

Create: PROC[size: NAT ¬ 0] RETURNS [Ref];

Creates a rope reader with a text buffer of the given size; if size=0, uses default.

GetRope: PROC [reader: Ref] RETURNS [rope: ROPE]

~ INLINE { RETURN [reader.rope] };

GetIndex: PROC [reader: Ref] RETURNS [index: INT]

~ INLINE { RETURN [reader.index+reader.current] };

Position: PROC [reader: Ref] RETURNS [rope: ROPE, index: INT]

~ INLINE { RETURN [rope: GetRope[reader], index: GetIndex[reader]] };

SetPosition: PROC [reader: Ref, rope: ROPE, index: INT ¬ 0]

~ INLINE {

IF GetRope[reader]=rope AND GetIndex[reader]=index THEN RETURN;

reader.rope ¬ rope; reader.current ¬ 0; reader.text.length ¬ 0; reader.index ¬ index;

};

SetIndex: PROC [reader: Ref, index: INT ¬ 0]

~ INLINE {

IF reader.index+reader.current # index THEN

{reader.current ¬ 0; reader.text.length ¬ 0; reader.index ¬ index}

};

BackupIndex: PROC [reader: Ref, amount: INT]

~ INLINE { SetIndex[reader, GetIndex[reader]-amount] };

BumpIndex: PROC [reader: Ref, amount: INT]

~ INLINE { SetIndex[reader, GetIndex[reader]+amount] };

GetEndChar: PROC [reader: Ref] RETURNS [endChar: CHAR]

~ INLINE { RETURN [reader.endChar] };

Returns the current end char.

This will be returned rather than giving ReadOffEnd error if CharForEndOfRope is true.

CharForEndOfRope: PROC [reader: Ref] RETURNS [BOOLEAN]

~ INLINE { RETURN [reader.charForEndOfRope] };

SetCharForEndOfRope: PROC [reader: Ref, char: CHAR]

~ INLINE { reader.endChar ¬ char; reader.charForEndOfRope ¬ TRUE };

ClearCharForEndOfRope: PROC [reader: Ref]

~ INLINE { reader.charForEndOfRope ¬ FALSE };

Mode: PRIVATE TYPE ~ {get, backwards, peek, peekbackwards};

ReadChar: PRIVATE PROC [reader: Ref, mode: Mode] RETURNS [CHAR];

Get: PROC [reader: Ref] RETURNS [CHAR]

~ INLINE {

get character, then increment reader location

text: REF TEXT ~ reader.text;

i: NAT ~ reader.current;

IF i<text.length THEN { reader.current ¬ i+1; RETURN[text[i]] }

ELSE RETURN[ReadChar[reader, $get]];

};

Backwards: PROC [reader: Ref] RETURNS [CHAR]

~ INLINE {

decrement reader location, then get character

i: NAT ~ reader.current;

IF i>0 THEN RETURN[reader.text[reader.current ¬ i-1]]

ELSE RETURN[ReadChar[reader, $backwards]]

};

Peek: PROC [reader: Ref] RETURNS [CHAR]

~ INLINE {

get character without incrementing reader location

text: REF TEXT ~ reader.text;

i: NAT ~ reader.current;

IF i<text.length THEN RETURN[text[i]]

ELSE RETURN[ReadChar[reader, $peek]]

};

PeekBackwards: PROC [reader: Ref] RETURNS [CHAR]

~ INLINE {

like Backwards, but doesn't change position

i: NAT ~ reader.current;

IF i>0 THEN RETURN[reader.text[i-1]]

ELSE RETURN[ReadChar[reader, $peekbackwards]]

};

Rope comparison operations that make use of readers for efficiency.

Equal: PROC [r1, r2: ROPE, rdr1, rdr2: Ref ¬ NIL] RETURNS [BOOLEAN]

uses readers rdr1 and rdr2 to read ropes r1 and r2 to test for equality

~ INLINE { RETURN [EqSubstrs[r1, r2, 0, 0, MaxLen, rdr1, rdr2]] };

EqSubstrs: PROC [r1, r2: ROPE, start1, start2, len: INT, rdr1, rdr2: Ref ¬ NIL] RETURNS [BOOL];

uses readers rdr1 and rdr2 to read ropes r1 and r2 to test for equality

returns TRUE if r1 starting at start1 is same as

len chars of r2 starting at start2

returns FALSE if not enough chars available in either rope

i.e., if start1+len > size[r1] or start2+len > size[r2]

if rdr1 or rdr2 is NIL, gets own readers from cache

Compare: PROC [r1,r2: ROPE, rdr1,rdr2: Ref ¬ NIL, case: BOOLEAN ¬ TRUE] RETURNS [Basics.Comparison]

uses readers rdr1 and rdr2 to compare ropes r1 and r2

returns less for r1 < r2; equal for r1 = r2; and greater for r1 > r2

if ~case then all characters forced lowercase for comparison

~ INLINE {RETURN [CompareSubstrs[r1,r2,0,MaxLen,0,MaxLen,rdr1,rdr2,case]] };

CompareSubstrs: PROC [r1, r2: ROPE, start1, len1, start2, len2: INT, rdr1, rdr2: Ref ¬ NIL, case: BOOL ¬ TRUE] RETURNS [Basics.Comparison];

uses readers rdr1 and rdr2 to compare substrings of ropes r1 and r2

if rdr1 or rdr2 is NIL, gets own readers from cache

Scratch pool

The next routines provide a small cache of rope readers

to avoid creating a lot of garbage readers

don't use these unless you are certain to free the reader at most once

ok not to free it, but don't free it more than once

GetRopeReader: PROC RETURNS [reader: Ref];

FreeRopeReader: PROC [reader: Ref];

SetDefaultSize: PROC[size: NAT];

Sets the default buffer size used by Create and readers in the cache.

END.

Plass, March 1, 1985 11:47:10 am PST

Cleanup for Cedar 6.0

removed CharsArray stuff, and AppendToString, GetString, BackwardsGetString, AppendToText, GetText, BackwardsGetText (use Rope.AppendChars instead)., Peek, DIRECTORY, ROPE