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.