|
Class: PositionableStream
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
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)
Signal constants
-
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
-
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
-
initialize
-
changed with stx rel5.1;
instance creation
-
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.
testing
-
isAbstract
-
Compatibility-Dolphin
-
endChunk
-
Compatibility-ST/V
-
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
-
back
-
Go back one element and return it.
-
peekBack
-
Return the element at the previous position, without changing position. Use indirect messages in case self is a StandardFileStream.
accessing
-
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)
-
contents
-
return the entire contents of the stream
-
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; that's the position at which EOF is returned
-
readLimit: aNumber
-
set the read-limit; that's the position at which EOF is returned
-
setCollection: newCollection
-
-
writeLimit: aNumber
-
set the writeLimit; that's the position after which writing is prohibited
non homogenous reading
-
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
-
backStep
-
move backward read position by one
-
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
|
-
position
-
return the read position (0-based)
-
position0Based
-
return the read position 0-based
** This is an obsolete interface - do not use it (it may vanish in future versions) **
-
position0Based: index0Based
-
set the read (or write) position
** This is an obsolete interface - do not use it (it may vanish in future versions) **
-
position1Based
-
return the read position 1-based
** This is an obsolete interface - do not use it (it may vanish in future versions) **
-
position1Based: index1Based
-
set the read (or write) position
** This is an obsolete interface - do not use it (it may vanish in future versions) **
-
position: index0Based
-
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
** This is an obsolete interface - do not use it (it may vanish in future versions) **
-
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.
printing & storing
-
printOn: aStream
-
'' readStream printString
'' writeStream printString
private
-
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)
-
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
usage example(s):
(WriteStream with:#(1 2 3 4 5))
nextPut:6;
contents
|
queries
-
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
-
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.
|
-
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.
-
peek
-
look ahead for and return the next element
-
peek: n
-
look ahead n elements and return them after positioning pack to the
position we had before
-
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.
-
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.
-
upToEnd
-
'abc' readStream upToEnd.
reading-strings
-
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
-
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.
|
-
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
-
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)
|