Class: PositionableStream

• Inheritance
• Description
• Class protocol
  • Signal constants
  • constants
  • initialization
  • instance creation
• Instance protocol
  • Compatibility-Dolphin
  • Compatibility-ST/V
  • accessing
  • positioning
  • printing & storing
  • private
  • reading
  • testing

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--ReadStream
            |
            +--WriteStream

Package:

stx:libbasic

Category:

Streams

Version:

rev: 1.153 date: 2009/01/13 11:58:02

user: stefan

file: PositionableStream.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Instances of PositionableStream allow positioning the read pointer.
The PositionableStream class also adds methods for source-chunk reading
and writing, and for filing-in/out of source code.

This is an abstract class.

Compatibility Notice:
    In previous versions of ST/X, streams started with a 1-position (i.e. as in collections),
    while ST-80 has always been using 0-based postions for streams and 1-based positions for collections.

THIS CERTAINLY IS BAD.

Although this is confusing ST/X has been changed to now also use 0-based stream positioning.

Class protocol:

 invalidPositionErrorSignal

return the signal raised if positioning is attempted to an
invalid position (i.e. before the begin of the stream or after
the end)

 zeroPosition

return the number, which marks the initial position.
Compatibility Notice:
In previous versions of ST/X, streams started with a 1-position (i.e. as in collections),
while ST-80 has always been using 0-based postions for streams and 1-based positions for collections.

Although this is confusing ST/X has been changed to now also use 0-based stream positioning.

 initialize

 on: aCollection

return a new PositionableStream streaming on aCollection

 on: aCollection from: first to: last

return a new PositionableStream streaming on aCollection
from first to last

 with: aCollection

return a new PositionableStream streaming on aCollection,
the stream is positioned to the end of the collection.

Instance protocol:

 endChunk

 skipTo: anElement

ST/V compatibility:
skip for the element given by the argument, anElement;
return nil if not found, self otherwise.
On a successful match, the next read will return the element after anElement.

 collection

 contents

return the entire contents of the stream

 peek

look ahead for and return the next element

 peekForAll: aCollection

return true and advance if the next elements are the same
as aCollection.
otherwise stay and let the position unchanged

 readLimit

return the read-limit; thats the position at which EOF is returned

 readLimit: aNumber

set the read-limit; thats the position at which EOF is returned

 writeLimit: aNumber

set the writeLimit; thats the position after which writing is prohibited

 backStep

move backward read position by one

 position

return the read position

 position0Based

return the read position 0-based

 position0Based: index0Based

set the read (or write) position

 position1Based

return the read position 1-based

 position1Based: index1Based

set the read (or write) position

 position: newPos

set the read (or write) position

 reset

set the read position to the beginning of the collection

 resetPosition

set the read position to the beginning of the collection

 setToEnd

set the read position to the end of the collection.
#next will return EOF, #nextPut: will append to the stream.
(same Behavior as FileStream.

 skip: numberToSkip

skip the next numberToSkip elements

 skipThroughAll: aCollection

skip for and through the sequence given by the argument, aCollection;
return nil if not found, self otherwise.
On a successful match, the next read will return elements after aCollection;
if no match was found, the receiver will be positioned at the end.
This is redefined here, to make use of positioning.

 skipToAll: aCollection

skip for the sequence given by the argument, aCollection;
return nil if not found, self otherwise.
On a successful match, the next read will return elements of aCollection.

 printOn: aStream

 contentsSpecies

return a class of which instances will be returned, when
parts of the collection are asked for.
(see upTo-kind of methods in subclasses)

 on: aCollection

setup for streaming on aCollection

 on: aCollection from: first to: last

setup for streaming on aCollection from first to last

 positionError

report an error when positioning past the end
or before the beginning.

 positionError: badPostition

report an error when positioning past the end
or before the beginning.

 with: aCollection

setup for streaming to the end of aCollection

 nextAvailable: count

 upToAll: aCollection

read until a subcollection consisisting of the elements in aCollection
is encountered.
Return everything read excluding the elements in aCollection.
The position is left before the collection; i.e. the next
read operations will return those elements.
If no such subcollection is encountered, all elements up to the end
are read and returned.
See also #throughAll: which also reads up to some objects
but positions behind it and DOES include it in the returned
collection.
See also #upToAllExcluding:, which returns the same, but leaves the
read pointer after the matched subcollection.

Note: this behavior is inconsistent with the other upTo.. methods,
which position after the found item. We implement the method
this way for the sake of ST80-compatibility.

 atEnd

return true, if the read-position is at the end

 isEmpty

return true, if the contents of the stream is empty

 isInternalByteStream

return true, if the stream is an internal stream reading bytes

 isPositionable

return true, if the stream supports positioning (this one is)