eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'PositionableStream':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: PositionableStream


Inheritance:

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

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.188 date: 2019/03/13 16:01:22
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 uses 0-based stream positioning.

[caveat:]
    Basing capabilities like readability/writability/positionability/peekability on inheritance makes
    the class hierarchy ugly and leads to strange and hard to teach redefinitions (aka. NonPositionableStream
    below PositionableStream or ExternalReadStream under WriteStream)


Class protocol:

Signal constants
o  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)

constants
o  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.

initialization
o  initialize
changed with stx rel5.1;

instance creation
o  on: aCollection
return a new PositionableStream streaming on aCollection

o  on: aCollection from: first to: last
return a new PositionableStream streaming on aCollection
from first to last

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

testing
o  isAbstract


Instance protocol:

Compatibility-Dolphin
o  endChunk

Compatibility-ST/V
o  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.

Compatibility-Squeak
o  back
Go back one element and return it.

o  peekBack
Return the element at the previous position, without changing position. Use indirect messages in case self is a StandardFileStream.

accessing
o  collection
return the underlying collection buffer.
Notice, that this buffer may become invalid after being retrieved,
if more data is written to the stream (because a bigger buffer might be
allocated). Therefore, it should be only used in special situations,
where an already filled buffer needs to be backpatched later
(eg. before being sent out to some external stream or socket)

o  contents
return the entire contents of the stream

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

o  readLimit
return the read-limit; that's the position at which EOF is returned

o  readLimit: aNumber
set the read-limit; that's the position at which EOF is returned

o  setCollection: newCollection

o  writeLimit: aNumber
set the writeLimit; that's the position after which writing is prohibited

non homogenous reading
o  nextBytes: numBytes into: aCollection startingAt: initialIndex
return the next numBytes from the stream. If the end is
reached before, only that many bytes are copied into the
collection.
Returns the number of bytes that have been actually read.
The receiver must support reading of binary bytes.

Notice: this method is provided here for protocol completeness
with externalStreams - it is normally not used with other
streams.

positioning
o  backStep
move backward read position by one

o  match: subCollection
Set the access position of the receiver to be past the next occurrence of the subCollection.
Answer whether subCollection is found.
No wildcards, and case does matter.

usage example(s):

     'abc def ghi' readStream match:'def'; upToEnd

o  position
return the read position (0-based)

o  position0Based
return the read position 0-based

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  position0Based: index0Based
set the read (or write) position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  position1Based
return the read position 1-based

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  position1Based: index1Based
set the read (or write) position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  position: index0Based
set the read (or write) position

o  reset
set the read position to the beginning of the collection

o  resetPosition
set the read position to the beginning of the collection

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  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.

o  skip: numberToSkip
skip the next numberToSkip elements

o  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.

o  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.

printing & storing
o  printOn: aStream
'' readStream printString
'' writeStream printString

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

o  on: aCollection
setup for streaming on aCollection

o  on: aCollection from: first to: last
setup for streaming on aCollection from first to last

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

o  positionError: badPostition
report an error when positioning past the end
or before the beginning.

o  with: aCollection
setup for streaming to the end of aCollection

usage example(s):

      (WriteStream with:#(1 2 3 4 5)) 
            nextPut:6;
            contents

queries
o  endsBeforePositionWith: aSequenceableCollection
answer true, if the elements in aSequenceableCollection
are at the current end of the stream up to position.

usage example(s):

        ('' writeStream nextPutAll:'Hello World') endsBeforePositionWith:'World'
        ('' writeStream nextPutAll:'Hello World') endsBeforePositionWith:'Hello World'
        ('' writeStream nextPutAll:'Hello World') endsBeforePositionWith:'Hello Worldx'
        ('' writeStream nextPutAll:'Hello World') endsBeforePositionWith:'Bla'
        ('' writeStream) endsBeforePositionWith:'Bla'
        ('' writeStream) endsBeforePositionWith:''
        ''  endsWith:''

reading
o  nextAvailable: count
return the next count elements of the stream as aCollection.
If the stream reaches the end before count elements have been read,
return what is available. (i.e. a shorter collection).

usage example(s):

        'abc' readStream nextAvailable:1.
        'abc' readStream nextAvailable:2.
        'abc' readStream nextAvailable:3.
        'abc' readStream nextAvailable:4.

        'abc' readStream nextAvailable:2; nextAvailable:2.
        'abc' readStream nextAvailable:3; nextAvailable:3.

o  nextAvailable: count into: aCollection startingAt: initialIndex
return the next count objects from the stream. If the end is
reached before, only that many objects are copied into the
collection.
Returns the number of objects that have been actually read.

o  peek
look ahead for and return the next element

o  peek: n
look ahead n elements and return them after positioning pack to the
position we had before

o  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.

o  upToAll_positionBefore: 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.

o  upToEnd
'abc' readStream upToEnd.

reading-strings
o  nextLine
return the characters upTo (but excluding) the next cr (carriage return)
character (i.e. read a single line of text).
If the previous-to-last character is a cr, this is also removed,
so it's possible to read alien (i.e. ms-dos) text as well.
Added for protocol compatibility with externalStreams.

usage example(s):

        '12345678' readStream nextLine
        '12345678' allBold readStream nextLine
        '12\34\56\78' withCRs readStream nextLine
        '12\34\56\78' withCRs readStream nextLine; nextLine
        (ReadStream on:('12\34\56\78' withCRs) from:1 to:4) nextLine; nextLine
        ('12\' withCRs, Character return, '34') readStream nextLine; nextLine
        Character cr asString readStream nextLine
        Character return asString readStream nextLine
        (Character return, Character cr) asString readStream nextLine
        Character return asString readStream nextLine; nextLine

stream-to-stream copy
o  copy: numberOfElementsOrNil into: aWriteStream
read from the receiver, and write numberOfElementsOrNil data to another aWriteStream.
If numberOfElementsOrNil is nil, copy until the end of myself.
Return the number of elements which have been transferred.
Redefined here to avoid intermediate buffers/garbage.

usage example(s):

      'hello world' readStream copy:5 into:'/tmp/mist' asFilename writeStream.
      'hello world' readStream 
                        copy:5 into:Transcript;
                        copy:20 into:Transcript.
      'hello world' readStream copy:5 into:'' writeStream inspect.
      #[1 2 3 4 5 6 7] readStream copy:2 into:'/tmp/mist' asFilename writeStream binary.
      #[1 2 3 4 5 6 7] readStream copy:3 into:#[] writeStream.

o  copy: numberOfElementsOrNil into: aWriteStream bufferSize: bufferSize
read from the receiver, and write numberOfElementsOrNil to another aWriteStream.
If numberOfElementsOrNil is nil, copy until the end of myself.
Return the number of elements which have been transferred.
Redefined here to avoid intermediate buffers/garbage
- bufferSize does not matter here.

testing
o  atEnd
return true, if the read-position is at the end

o  isEmpty
return true, if the contents of the stream is empty

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

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



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 05:40:23 GMT