vbtkit/src/mtext/MTextRd.i3


 Copyright (C) 1992, Digital Equipment Corporation                         
 All rights reserved.                                                      
 See the file COPYRIGHT for a full description.                            
                                                                           
 Last modified on Fri Nov 20 20:59:20 PST 1992 by meehan     
      modified on Tue Jun 16 13:16:23 PDT 1992 by muller     
      modified on Wed May  3 11:10:09 PDT 1989 by mbrown     
      modified on Tue Oct 11 19:06:48 1988 by chan           

INTERFACE MTextRd;

IMPORT Rd, MText, Thread;

TYPE
  T <: Public;
  Public = Rd.T OBJECT
           METHODS
             init (m         : MText.T  := NIL;
                   start     : CARDINAL := 0;
                   rangeStart: CARDINAL := 0;
                   rangeEnd  : CARDINAL := LAST (CARDINAL);
                   reverse   : BOOLEAN  := FALSE            ): T
                   RAISES {Rd.Failure, Thread.Alerted}
           END;
rd.init(m, ...) initializes a seekable, non-intermittent reader for the MText m.

It is intended that this method be called more than once, to re-initialize a reader (and avoid re-allocating storage for rd.buff); in this case, it is permitted for m to be NIL, and the default value is the MText that was previously used by the reader.

The reader's source may be a proper subsequence of the underlying MText, and the reader can be initialized to read in reverse order.

src(rd) comprises the characters of m that are contained in the interval

       [first(rd) .. last(rd)]
   
where
       first(rd)) = rangeStart
   
and
       last(rd) = MIN (rangeEnd, MText.Length(m)) - 1]
       len(rd) = MAX (last(rd) - first(rd) + 1, 0)
In a forward reader (reverse = FALSE), Rd.GetChar delivers characters from start to last(rd). Rd.Index returns the index relative to first(rd). Hence just after a forward reader rd is initialized,
       cur(rd) = start - first(rd)
In a reverse reader, Rd.GetChar delivers characters from start-1 (not start) to first(rd). Rd.Index returns the index relative to last(rd)+1. Hence just after a reverse reader rd is initialized,
       cur(rd) = last(rd) + 1 - start
Thus the value returned by Rd.Index increases by 1 with each call to Rd.GetChar, regardless of the reader's direction.

The coordinate system used by Rd.Seek is consistent with Rd.Index.

If the underlying MText is modified, the reader is invalid and should be re-initialized.

rd.init calls Rd.Seek(rd, rd.cur), which can raise Rd.Failure or Thread.Alerted.

Synchronization: it is not possible to have several readers reading the mtext concurrently. The reason is that a read to a file node causes the mtext data structure to change. If you don't use file nodes, then it's safe. (JRM doesn't believe this.)

PROCEDURE New (m         : MText.T;
               start     : CARDINAL  := 0;
               rangeStart: CARDINAL  := 0;
               rangeEnd  : CARDINAL  := LAST (CARDINAL);
               reverse   : BOOLEAN   := FALSE            ): T
  RAISES {Rd.Failure, Thread.Alerted};
This is equivalent to
      NEW (T).init (m, start, rangeStart, rangeEnd, reverse, alertable)

END MTextRd.