eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Stream':

Home

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

Class: Stream


Inheritance:

   Object
   |
   +--Stream
      |
      +--BinaryStream
      |
      +--Comanche::BufferStream
      |
      +--Comanche::DummyStream
      |
      +--CompressionStream
      |
      +--ConsStream
      |
      +--HTTPInterface::WebSocketStream
      |
      +--HashStream
      |
      +--InternalPipeStream
      |
      +--LoggingStream
      |
      +--PeekableStream
      |
      +--PrinterStream
      |
      +--RBScanner
      |
      +--Random
      |
      +--SelectingReadStream
      |
      +--SourceCodeStream
      |
      +--SplittingWriteStream

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.324 date: 2019/07/09 18:36:44
user: cg
file: Stream.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


An abstract class defining common behavior for all stream-like objects.
See concrete subclasses for more detail.

The protocol as implemented here is often only provided as a fallBack
for very uncommon cases. Much of it is redefined for performance.
(In streams which know more about their internal representation ...)


Subclasses should (at least) implement:
    #next           (if readable)
    #nextPut:       (if writable)
    #contents
    #atEnd
    #isReadable
    #isWritable

Peekable & Positionable streams should (at least) implement:
    #peek
    #position
    #position:


[instance variables:]
    signalAtEnd             <nil | Boolean> controls behavior when a read
                                            is attempted past the end-of-stream
                                            if true, the endOfStreamSignal is raised.
                                            if false, nil is returned.
                                            if nil (the default), the signal
                                            is raised, but if there is no handler,
                                            nil is returned.

[Class variables / Exceptions:]
    StreamError             <Exception>     parent of all stream errors

    PositionError           <Exception>     position attemted on a stream
                                            which does not support positioning,
                                            or if the position is invalid.

    ReadError               <Exception>     raised on read errors

    WriteError              <Exception>     raised on write errors

    EndOfStreamSignal       <Signal>        raised at end of stream if signalAtEnd
                                            is enabled.

[caveat:]
    The Stream hierarchy has a few little quirks in it, which are a consequence of some early historic
    decisions. The biggest problem is the distinction between readable and writeable streams based on inheritance,
    instead of by either using state (i.e. a flag) or delegation.
    The problem is that there are streams which can be both, and maybe even dynamically change their opinion,
    on whether being readable/writable.
    (For example, a buffer may be write-only while filled, but become readonly, when given to a consumer.)

    The above decision to base this on inheritance lead to the ugly ReadStream - WriteStream - ReadWriteStream
    hierarchy, with some subclasses undoing the blocking of their superclass.

    Classes named 'ReadStream', 'WriteStream', 'ReadWriteStream', 'PeekableStream' and 'PositionableStream' should
    all be eliminated in favour of a few flags in the 'Stream' superclass.

    It is really time for a new stream hierarchy (XStreams, for example).
    (On the other hand: there is so much code around, which depends on the current situation, that such a change
     must really be thought through - most got used to these issues and live with it more or less happily)


Class protocol:

Signal constants
o  endOfStreamSignal
return the signal raised if read past end of stream is attemted

o  incompleteNextCountSignal
return the signal raised if not all requested elements are returned

o  lineTooLongErrorSignal
return the signal raised if a line is read which is too long (>32k)

o  positionErrorSignal
return the signal raised if positioning is requested for
a stream which does not support that kind of operation

o  readErrorSignal
return the signal raised on read errors

o  streamErrorSignal
return the parent of all stream errors;
handling this one also handles all other errors.
Also, this one may be raised for errors not related to read/write
operations, such as failed ioctls in externalStream etc.

o  writeErrorSignal
return the signal raised on write errors

constants
o  chunkSeparator
return the chunk-separation character

initialization
o  initSignals
(comment from inherited method)
called only once - initialize signals

o  initialize
(comment from inherited method)
called only once - initialize signals

instance creation
o  new
report an error - Streams are created using on:-messages

testing
o  isAbstract


Instance protocol:

Compatibility-Dolphin
o  display: someObject
dolphin compatibility

Compatibility-Squeak
o  nextInt32
( an extension from the stx:libcompat package )
Read a 32-bit signed integer from the next 4 bytes, most significant byte first

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

o  nextInt32Put: i32
( an extension from the stx:libcompat package )
Write a signed integer to the next 4 bytes, most significant byte first

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

o  nextLittleEndianNumber: n
( an extension from the stx:libcompat package )
Answer the next n bytes as a positive Integer or LargePositiveInteger,
where the bytes are ordered from least significant to most significant.

usage example(s):

     self assert:( [|s| s := #[1 2 3 4] readStream nextLittleEndianNumber:4] value = 16r04030201)
     self assert:( [|s| s := #[1 2 3 4 5 6 7 8] readStream nextLittleEndianNumber:8] value = 16r0807060504030201) 

o  nextLittleEndianNumber: n put: value
( an extension from the stx:libcompat package )
write a positive Integer or LargePositiveInteger as the next n bytes ordered from least significant to most significant.

o  nextPutSqueakString: s
( an extension from the stx:libcompat package )
Append the string, s, to the receiver.
Only used by DataStream.
Max size of 64*256*256*256.

o  nextSqueakString
( an extension from the stx:libcompat package )
Read a string from the receiver.
The first byte is the length of the string, unless it is greater than 192,
in which case the first four bytes encode the length.
I expect to be in ascii mode when called (caller puts back to binary).
Max size 1G.

o  nextSqueakStringOld
( an extension from the stx:libcompat package )
Read a string from the receiver. The first byte is the length of the
string, unless it is greater than 192, in which case the first *two* bytes
encode the length.
Max size 16K.

o  nextString
( an extension from the stx:libcompat package )
CG: PLEASE do not use this in new code;

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

o  nextStringOld
( an extension from the stx:libcompat package )
CG: PLEASE do not use this in new code;

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

o  nextStringPut: s
( an extension from the stx:libcompat package )
CG: PLEASE do not use this in new code;

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

o  nextWord
( an extension from the stx:libcompat package )
Answer the next two bytes from the receiver as an Integer, most significant byte first.

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

Compatibility-VW
o  commit
alias for flush -- ST80 compatibility

o  nl
append a newline to the stream.
This is only allowed, if the receiver supports writing.

JS syntactic sugar
o  log: something
( an extension from the stx:libjavascript package )
same as showCR:.
Added to allow for Transcript.log(...) to be used in a similar way as
console.log(...).
Not for non-JavaScript usage

o  show: aString _: arg1
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1', arg1)

o  show: aString _: arg1 _: arg2
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1, arg2)

o  show: aString _: arg1 _: arg2 _: arg3
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  show: aString _: arg1 _: arg2 _: arg3 _: arg4
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  show: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  show: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  show: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  show: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7 _: arg8
for JS easy syntax - allows: Transcript.show('format %1 %2', arg1,...)

o  showCR: aString _: arg1
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1', arg1)

o  showCR: aString _: arg1 _: arg2
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1, arg2)

o  showCR: aString _: arg1 _: arg2 _: arg3
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

o  showCR: aString _: arg1 _: arg2 _: arg3 _: arg4
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

o  showCR: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

o  showCR: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6
( an extension from the stx:libjavascript package )
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

o  showCR: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

o  showCR: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7 _: arg8
for JS easy syntax - allows: Transcript.showCR('format %1 %2', arg1,...)

accessing
o  contents
return the entire contents of the stream.
For a readStream, that is the rest (i.e. upToEnd),
for a writeStream, that is the collected data. As we do not know here,
what we are, this is the responsibility of a subclass...

** This method raises an error - it must be redefined in concrete classes **

o  encoder
for compatibility with encoded stream

o  signalAtEnd
return the signalAtEnd flag setting.
If true, reading past the end will always raise an EndOfStream exception.
If false, no exception is raised and nil is returned from all reading messages.
If nil (default), the exception is raised if there is a handler; otherwise, nil is returned.
The default is nil (for ST80 compatibility) i.e. to only raise a signal if there is a handler.

o  signalAtEnd: aBoolean
set the signalAtEnd flag setting.
If true, reading past the end will raise an EndOfStream exception.
If false, no exception is raised and nil is returned from all reading messages.
If nil (default), the exception is raised if there is a handler; otherwise, nil is returned.
The default (nil) is both st80 backward compatible (i.e. returning nil)
AND allows for modern code to provide a handler.

usage example(s):

force raise (useful for debugging):
     |s|

     s := '12' readStream.
     s signalAtEnd:true.
     Transcript showCR:s next.
     Transcript showCR:s next.
     Transcript showCR:s next.
     Transcript showCR:s next.

usage example(s):

force no-raise (useful for compatibility with other systems):
     |s|

     s := '12' readStream.
     s signalAtEnd:false.
     Stream endOfStreamSignal handle:[:ex |
        Transcript showCR:'end reached'.
        ex return
     ] do:[
        Transcript showCR:s next.
        Transcript showCR:s next.
        Transcript showCR:s next.
        Transcript showCR:s next.
     ]

converting
o  asLineNumberReadStream
returns a new stream, which keeps track of the line number.
It can be asked for the current linenumber,
which is useful eg. for error message generation

o  asStream

defaults
o  bufferSizeForBulkCopy
return the size of buffer used when copying big files/bulk data
from one stream to another.

o  bufferSizeForNormalCopy
return the default buffer size used when copying files
from one stream to another, and no bufferSize is given.

emphasis
o  bold
set emphasis to #bold.
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  boldItalic
set emphasis to #boldItalic
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  emphasis
ignored here
- allows Streams to be used interchangable with text streams

o  emphasis: anEmphasis
ignored here
- allows Streams to be used interchangable with text streams

o  italic
set emphasis to #italic.
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  normal
set emphasis to #normal.
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  strikeout
set emphasis to #strikeout.
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  underline
set emphasis to #underline.
Normal streams will ignore this,
which allows arbitrary Streams to be used interchangeable with printStreams

o  withEmphasis: anEmphasis do: aBlock
evaluate aBlock while my emphasis has been changed to anEmphasis.
Emphasis is ignored here, but implemented in some subclasses (PrinterStream, TextCollector etc.).

enumerating
o  do: aBlock
evaluate the argument, aBlock for all remaining elements,
up to the end of the stream

o  linesDo: aBlock
evaluate the argument, aBlock for all lines,
up to the end of the stream

usage example(s):

     Filename readingFile:'/etc/hosts'
     do:[:s |
         s linesDo:[:line | Transcript showCR:line].
     ].

error handling
o  checkNilFileStream
Do nothing if this is a valid FileStream
(i.e. the previous open operation was successful).
Also implemented in UndefinedObject, to raise an Error there.

This is an aid for converting from the old error reporting (returning nil)
to the new error reporting (with real Exceptions).

It will vanish as soon as the conversion has been done

o  errorNotOpen
report an error, that the stream has not been opened or has been closed

o  pastEnd
someone tried to read after the end of the stream.
If signalAtEnd == true, raise a signal. If it's false, return nil.
Otherwise raise the signal, but only if handled; otherwise return nil.

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

o  pastEndRead
someone tried to read after the end of the stream.
If signalAtEnd == true, raise a signal.
If it is false, return nil.
Otherwise raise a notification, which is ignored if not handled;
otherwise return nil.

externalStream compatibility
o  binary
switch to binary mode. In binary mode, reading of text streams
returns byte-valued integers instead of characters; writing expects
byte-valued integers respectively.
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  binary: beBinaryBool
if beBinaryBool is true, switch to binary mode, if false, switch to text mode.
Answer the prevous mode - true for binary mode, false for text mode.
In binary mode, reading of text streams
returns byte-valued integers instead of characters; writing expects
byte-valued integers respectively.
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  blocking: aBoolean
set non-blocking mode.
Ignored, since internal streams never block

o  buffered: aBoolean
ExternalStream compatibility: change buffered mode.
Ignored, since internal streams are never buffered.

o  eolMode
Dummy here, but added to make internalStreams protocol compatible
with externalStreams.

o  eolMode: aSymbol
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  lineEndCRLF
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  lineEndConvention

o  lineEndConvention: aSymbol

o  lineEndLF
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  lineEndTransparent
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

o  stream
for compatibility with encodedStream

o  text
switch to text mode.
Ignored here, but added to make internalStreams protocol compatible
with externalStreams.

non homogenous reading
o  nextAvailableBytes: numBytes into: aCollection startingAt: initialIndex
for compatibility with ExternalStream

o  nextByte
return the next byte of the stream
- we do not know here how to do it, it should be redefined in subclass

o  nextBytes: count
read the next count bytes and return it as a byteArray.
If EOF is encountered while reading, a truncated byteArray is returned.
If EOF is already reached before the first byte can be read,
an error is raised.

o  nextBytes: count into: anObject
read the next count bytes into an object and return the number of
bytes read. On EOF, 0 is returned.
If the receiver is some socket/pipe-like stream, an exception
is raised if the connection is broken.

The object must have non-pointer indexed instvars (i.e. it must be
a ByteArray, String, Float- or DoubleArray).
If anObject is a string or byteArray and reused, this provides the
fastest possible physical I/O (since no new objects are allocated).

Use with care - non object oriented i/o.
Warning: in general, you cannot use this method to pass data from other
architectures since it does not care for byte order or float representation.

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.

o  nextBytes: numBytes into: aCollection startingAt: initialIndex blockSize: blockSize
like nextBytes:into:startingAt:, but read in blocks of the given size.
This leads to better behavior when reading large chunks from a slow device,
such as a cdrom drive (since a single unix-read is not interruptable).

o  nextBytesInto: anObject
read bytes into an object, regardless of binary/text mode.
The number of bytes to read is defined by the object's size.
Return the number of bytes read. On EOF, 0 is returned.
If the receiver is some socket/pipe-like stream, an exception
is raised if the connection is broken.

The object to read into must have non-pointer indexed instvars
(i.e. it must be a ByteArray, String, Float- or DoubleArray).
If anObject is a string or byteArray and reused, this provides the
fastest possible physical I/O (since no new objects are allocated).

Use with care - non object oriented i/o.
Warning: in general, you cannot use this method to pass data from other
architectures since it does not care for byte order or float representation.

usage example(s):

to read 100 bytes from a stream:

    |b aStream|

    aStream := 'smalltalk.rc' asFilename readStream.
    b := ByteArray new:100.
    aStream nextBytesInto:b.
    aStream close.
    b inspect

o  nextIEEEDouble
read an 8-byte IEEE double precision float number in native byte order

o  nextIEEEDoubleMSB: msbFirst
read an 8-byte IEEE double precision float number

o  nextIEEESingle
read a 4-byte IEEE single precision float number in native byte order

o  nextIEEESingleMSB: msbFirst
read a 4-byte IEEE single precision float number

o  nextInt16MSB: msbFlag
return a signed short (2 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextInt24MSB: msbFlag
return a signed 3 byte integer from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

usage example(s):

     ((ReadStream on:#[16r10 16r20 16rFF]) nextInt24MSB:true) hexPrintString
     ((ReadStream on:#[16rFF 16r20 16r30]) nextInt24MSB:false) hexPrintString

     ((ReadStream on:#[16rFF 16r20 16r30]) nextInt24MSB:true) hexPrintString
     ((ReadStream on:#[16r10 16r20 16rFF]) nextInt24MSB:false) hexPrintString

o  nextInt32MSB: msbFlag
return a signed long (4 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextInt64MSB: msbFlag
return a signed longlong (also called hyper) (8 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextSignedByte
return a signed byte (-128..127) from the stream.
The receiver must support reading of binary bytes.

usage example(s):

     #[16rFF 16r80 16r7F 16r01] readStream nextSignedByte

o  nextString: count
read the next count bytes and return it as a string.
If EOF is encountered while reading, a truncated string is returned.
If EOF is already reached before the first byte can be read,
an error is raised.

o  nextUnsigned: numBytes MSB: msbFlag
return a numBytes-sized unsigned (numBytes bytes) from the stream as an Integer.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextUnsignedInt16MSB: msbFlag
return an unsigned short (2 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

usage example(s):

     ((ReadStream on:#[16r10 16r20 16r30]) nextUnsignedInt16MSB:true) hexPrintString
     ((ReadStream on:#[16r10 16r20 16r30]) nextUnsignedInt16MSB:false) hexPrintString

o  nextUnsignedInt24MSB: msbFlag
return an unsigned 3 byte integer from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

usage example(s):

     ((ReadStream on:#[16r10 16r20 16r30]) nextUnsignedInt24MSB:true) hexPrintString
     ((ReadStream on:#[16r10 16r20 16r30]) nextUnsignedInt24MSB:false) hexPrintString

o  nextUnsignedInt32MSB: msbFlag
return an unsigned long (4 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextUnsignedInt64MSB: msbFlag
return an unsigned longlong (also called hyper) (8 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

non homogenous reading - aliases
o  nextInt16LSB
return a signed short (2 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt16MSB
return a signed short (2 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt16Net
return a signed short (2 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

o  nextInt32LSB
return a signed long (4 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt32MSB
return a signed long (4 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt32Net
return a signed long (4 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

o  nextInt64LSB
return a signed longlong (also called hyper) (8 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt64MSB
return a signed longlong (also called hyper) (8 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextInt64Net
return a signed longlong (also called hyper) (8 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

o  nextNumber: numBytes
Return the next n bytes as a positive Integer;
bytes are taken msb-first.

o  nextUnsignedInt16LSB
return an unsigned short (2 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt16MSB
return an unsigned short (2 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt16Net
return an unsigned short (2 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

o  nextUnsignedInt32LSB
return an unsigned long (4 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt32MSB
return an unsigned long (4 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt32Net
return an unsigned long (4 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

o  nextUnsignedInt64LSB
return an unsigned longlong (also called hyper) (8 bytes) in LSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt64MSB
return an unsigned longlong (also called hyper) (8 bytes) in MSB-first order from the stream.
The receiver must support reading of binary bytes.

o  nextUnsignedInt64Net
return an unsigned longlong (also called hyper) (8 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB-first per definition

non homogenous reading - obsolete
o  nextHyperMSB: msbFlag
return a signed hyper (8 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextLong
Read four bytes (msb-first) and return the value as a 32-bit signed Integer.
The returned value may be a LargeInteger.
(msb-first for compatibility with other smalltalks)

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

o  nextLongMSB: msbFlag
return a signed long (4 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextLongNet
return a signed long (4 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.

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

o  nextShortMSB: msbFlag
return a signed short (2 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextShortNet
return a signed short (2 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB per definition

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

o  nextUnsignedHyperMSB: msbFlag
return an unsigned hyper (8 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextUnsignedLongMSB: msbFlag
return an unsigned long (4 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextUnsignedLongNet
return an unsigned long (4 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.

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

o  nextUnsignedShortMSB: msbFlag
return an unsigned short (2 bytes) from the stream.
The receiver must support reading of binary bytes.

The msbFlag argument controls if the integer is to be read with
most-significant-byte-first (true) or least-first (false).
This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextUnsignedShortNet
return an unsigned short (2 bytes) in network byte order from the stream.
The receiver must support reading of binary bytes.
Network byte order is MSB per definition

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

non homogenous writing
o  next: count putByte: aByteValue
write a byte n times

o  nextNumber: n put: v
Append to the receiver the argument, v, which is a positive Integer,
as the next n bytes. Bytes are written msb first.
Possibly pad with leading zeros.
The receiver must support writing of binary bytes.

o  nextNumber: n put: v MSB: msb
Append to the receiver the argument, v, which is a positive Integer,
as the next n bytes.
Bytes are written in the specified byte order.
Possibly pad with leading zeros (trailing zeros, if lsb).
The receiver must support writing of binary bytes.

o  nextPutAllUtf16: aString
write a string as UTF-16BE characters.

o  nextPutAllUtf16Bytes: aString MSB: msb
write a string as UTF-16 bytes - no 0-word is written.
The underlying stream must support writing of bytes

usage example(s):

        (#[] writeStream
            nextPutAllUtf16Bytes:'BÄxxx' MSB:true;
            nextPutUtf16:(Character codePoint:16r10CCCC) MSB:true;
            contents)

o  nextPutAllUtf8: aString
write the UTF-8 representation of aString to myself.

usage example(s):

     String streamContents:[:s|
         s nextPutAllUtf8:'hallo'
     ].

     ByteArray streamContents:[:s|
         s nextPutAllUtf8:'hallo'
     ].

     String streamContents:[:s|
         s nextPutAllUtf8:'abcdeäöüß' asUnicode32String
     ].

     ByteArray streamContents:[:s|
         s nextPutAllUtf8:'abcdeäöüß' asUnicode32String
     ].

     '/tmp/bytes' asFilename writingFileDo:[:s|
         s nextPutAllUtf8:'abcdeäöüß'
     ].

o  nextPutByte: aByteValue
write a byte.
Same as nextPut: here; for protocol compatibility with externalStream.

o  nextPutBytes: anObject
write bytes from an object; the number of bytes is defined by
the object's size.
Return the number of bytes written or nil on error.
The object must have non-pointer indexed instvars
(i.e. be a ByteArray, String, Float- or DoubleArray).
Use with care - non object oriented i/o.
Warning: in general, you cannot use this method to pass non-byte data to other
architectures since it does not care for byte order or float representation.

o  nextPutBytes: count from: anObject
write count bytes from an object.
Return the number of bytes written or nil on error.
The object must have non-pointer indexed instvars
(i.e. be a ByteArray, String, Float- or DoubleArray).
Use with care - non object oriented i/o.
Warning: in general, you cannot use this method to pass non-byte data to other
architectures since it does not care for byte order or float representation.

o  nextPutBytes: count from: anObject startingAt: start
write count bytes from an object starting at index start.
Return the number of bytes written.
The object must have non-pointer indexed instvars
(i.e. be a ByteArray, String, Float- or DoubleArray).
Use with care - non object oriented i/o.
This is provided for compatibility with externalStream;
to support binary storage

o  nextPutBytesFrom: anObject
write bytes from an object; the number of bytes is defined by the object's size.
Return the number of bytes written or nil on error.
The object must have non-pointer indexed instvars
(i.e. be a ByteArray, String, Float- or DoubleArray).
Use with care - non object oriented i/o.
Warning: in general, you cannot use this method to pass non-byte data to other
architectures since it does not care for byte order or float representation.

o  nextPutIEEEDouble: aFloat
write an 8-byte IEEE double precision float number

o  nextPutIEEEDouble: aFloat MSB: msb
write an 8-byte IEEE double precision float number

o  nextPutIEEESingle: aFloat
write a 4-byte IEEE single precision float number

o  nextPutIEEESingle: aFloat MSB: msb
write a 4-byte IEEE single precision float number

o  nextPutInt16: anIntegerOrCharacter MSB: msbFlag
Write the argument, anIntegerOrCharacter as a short (two bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextPutInt16LSB: aNumber
Write the argument, aNumber as a short (two bytes) in LSB-first order.
Returns the receiver on ok, nil on error.
The receiver must support writing of binary bytes.

o  nextPutInt16MSB: aNumber
Write the argument, aNumber as a short (two bytes) in MSB-first order.
Returns the receiver.
The receiver must support writing of binary bytes.

o  nextPutInt16Net: aNumber
Write the argument, aNumber as a short (two bytes) in the network byte order.
Returns the receiver.
The receiver must support writing of binary bytes.
Network byte order is MSB-first per definition

o  nextPutInt32: aNumber MSB: msbFlag
Write the argument, aNumber as a long (four bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextPutInt32LSB: aNumber
Write the argument, aNumber as a long (4 bytes) in LSB-first order.
Returns the receiver.
The receiver must support writing of binary bytes.

o  nextPutInt32MSB: aNumber
Write the argument, aNumber as a long (4 bytes) in MSB-first order.
Returns the receiver.
The receiver must support writing of binary bytes.

o  nextPutInt32Net: aNumber
Write the argument, aNumber as a long (four bytes) in the network byte order.
Returns the receiver.
The receiver must support writing of binary bytes.
Network byte order is MSB-first per definition

o  nextPutInt64: aNumber MSB: msbFlag
Write the argument, aNumber as a longlong (8 bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

o  nextPutInt64LSB: aNumber
Write the argument, aNumber as a longlong (8 bytes) in LSB-first order.
Returns the receiver.
The receiver must support writing of binary bytes.

o  nextPutInt64MSB: aNumber
Write the argument, aNumber as a longlong (8 bytes) in MSB-first order.
Returns the receiver.
The receiver must support writing of binary bytes.

o  nextPutInt64Net: aNumber
Write the argument, aNumber as a longlong (8 bytes) in the network byte order.
Returns the receiver.
The receiver must support writing of binary bytes.
Network byte order is MSB-first per definition

o  nextPutUtf16: aCharacter
append my UTF-16 representation to the argument, aStream.
Notice: this writes characters - not bytes.
The underlying stream must be a stream which can deal with characters,
eg. OrderedCollectionStream, TwoByteCharacterStream, etc.
Also notice, that characters above 16rFFFF are escaped according UTF16 specifications.

o  nextPutUtf16Bytes: aCharacter MSB: msb
append my UTF-16 representation to the argument, aStream.
UTF-16 can encode only characters with code points between 0 to 16r10FFFF.
The underlying stream must support writing of bytes.

o  nextPutUtf8: aCharacter
append my UTF-8 representation to the argument, aStream.
The underlying stream must be a stream which can deal with characters.
Up to 31 bits can be encoded in up to 6 bytes.
However, currently, characters are limited to 31 bits.

non homogenous writing - obsolete
o  nextPutHyper: aNumber MSB: msbFlag
Write the argument, aNumber as a hyper (8 bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextPutLong: aNumber MSB: msbFlag
Write the argument, aNumber as a long (four bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextPutLongNet: aNumber
Write the argument, aNumber as a long (four bytes) in the network byte order.
Returns the receiver.
The receiver must support writing of binary bytes.

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

o  nextPutShort: anIntegerOrCharacter MSB: msbFlag
Write the argument, anIntegerOrCharacter as a short (two bytes).
If msbFlag is true, data is written most-significant byte first;
otherwise least first.
Returns the receiver.
The receiver must support writing of binary bytes.

This interface is provided to allow talking to external programs,
where it's known that the byte order is some definite one.
If you don't care (i.e. talk to other smalltalks) or you can control the
order, please use the corresponding xxxNet methods, which use a standard
network byte order.

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

o  nextPutShortNet: aNumber
Write the argument, aNumber as a short (two bytes) in the network byte order.
Returns the receiver.
The receiver must support writing of binary bytes.
Network byte order is MSB per definition

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

open & close
o  close
close the stream - nothing done here.
Added for compatibility with external streams.

queries
o  canReadWithoutBlocking
return true, if the stream can be read without blocking the program (actually: suspending the thread).
This is redefined in external streams, which read from a communication line
(sockets and devices).
Always true here, because all internal streams never block

o  canWriteWithoutBlocking
return true, if the stream can be written without blocking the program (actually: suspending the thread).
This is redefined in external streams, which write to a communication line
(sockets and devices).
Always true here, because all internal streams never block

o  contentsSpecies
this should return the class of which an instance is
returned by the #contents method. Here, Array is returned,
since the abstract Stream-class has no idea of the underlying
collection class.
It is redefined in some subclasses - for example, to return String.

o  current
for compatibility with Transcript - allow Transcript current,
even if redirected to the standardError

o  inputStream
return the receiver.
for compatibility with filtering streams

o  isBinary
return true, if in binary mode. Always returns false here,
to make internalStreams protocol compatible with externalStreams.

o  isOpen
for compatibility with externalStream:
return true, if this stream is open.

o  isReadable
return true, if reading is supported by the receiver.
This has to be redefined in concrete subclasses.

** This method raises an error - it must be redefined in concrete classes **

o  isWritable
return true, if writing is supported by the receiver.
This has to be redefined in concrete subclasses.

** This method raises an error - it must be redefined in concrete classes **

o  lineLength
return the lineLength which `looks good' when pretty printed
text is sent to this stream.
This has NO meaning whatsoever to regular streams;
however, it may be used as a layout hint for prettyprinting functions
- for compatibility with TextCollectors, which returns its views actual
line length, and allows the prettyprinter to wrap at that position.

o  lineNumber
return the current lineNumber if known
(for compatibility with LineNumberReadStream)

o  numAvailableForRead
answer the number of bytes available for reading

o  numberOfTerminalCols

o  numberOfTerminalLines

o  outputStream
return the receiver.
for compatibility with filtering streams

o  pageFormat
return the pageFormat - nil here.
This has NO meaning whatsoever to regular streams;
however, it has been added for protocol compatibility with printerStreams

o  size
return the number of elements in the streamed collection.

** This method raises an error - it must be redefined in concrete classes **

o  terminalType

reading
o  next
return the next element of the stream
- we do not know here how to do it, it must be redefined in subclass

** This method raises an error - it must be redefined in concrete classes **

o  next: count
return the next count elements of the stream as aCollection,
which depends on the streams type - (see #contentsSpecies).

usage example(s):

     (ReadStream on:#(1 2 3 4 5)) next:3
     (ReadStream on:'hello') next:3

o  next: count into: aWriteStream
put the next count elements of the stream into aWriteStream

o  next: numObjects into: aCollection startingAt: initialIndex
return the next numObjects from the stream.

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).
The type of collection is specified in #contentsSpecies.

usage example(s):

     (ReadStream on:#(1 2 3 4 5)) nextAvailable:3
     (ReadStream on:#(1 2 3 4 5)) nextAvailable:10
     (ReadStream on:'hello') nextAvailable:3
     (ReadStream on:'hello') nextAvailable:10

o  nextAvailable: numObjects into: aCollection startingAt: initialIndex
return the next numObjects from the stream.

o  nextMatchFor: anObject
read an element from the receiver, return true if it was equal to
the argument, anObject; false otherwise.

o  nextOrNil
like #next, this returns the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

o  skip: numberToSkip
skip numberToSkip objects, return the receiver

o  skipFor: anObject
skip all objects up-to and including anObject;
read and return the element after anObject.

o  skipLine
read the next line (characters up to newline) skip only;
return nil if EOF reached, self otherwise.
Not allowed in binary mode.

o  skipThrough: anObject
skip all objects up-to and including anObject.
Return the receiver if skip was successful,
otherwise (i.e. if not found) return nil and leave the stream positioned at the end.
The next read operation will return the element after anObject.

o  skipThroughAll: aCollection
skip for and through the sequence given by the argument, aCollection;
return nil if not found, the receiver 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.

o  through: anObject
read a collection of all objects up-to anObject and return these
elements, including anObject.
The next read operation will return the element after anObject.
If anObject is not encountered, all elements up to the end are read
and returned.
Compare this with #upTo: which also reads up to some object
and also positions behind it, but does not include it in the returned
value.

o  throughAll: aCollection
read & return a collection of all objects up-to and including
a subcollection given by aCollection.
(i.e. read until a ``substring'' is encountered.)
The next read operation will return the element after aCollection.
If aCollection is not encountered, all elements up to the end are read
and returned.

o  throughAny: aCollection
read & return a collection of all objects up-to and including
an element contained in aCollection.
(i.e. read until any from aCollection is encountered.)
If no such character is encountered, all elements up to the end are read
and returned.

o  throughElementForWhich: aBlock
read elements until aBlock returns true for an element.
Return the collected elements including that element.
Leave the stream positioned for the next read to return the element after that one.

o  upTo: anObject
read a collection of all objects up-to anObject and return these
elements, but excluding anObject.
The next read operation will return the element after anObject.
(i.e. anObject is considered a separator, which is skipped)
Similar to #through:, but the matching object is not included in the
returned collection.
If anObject is not encountered, all elements up to the end are read
and returned.
Compare this with #through: which also reads up to some object
and also positions behind it, but DOES include it in the returned
value.

o  upTo: anObject into: aStream
read a collection of all objects up-to anObject and append these
elements to aStream, but excluding anObject.
The next read operation will return the element after anObject.
(i.e. anObject is considered a separator, which is skipped)
Similar to #through:, but the matching object is not included in the returned collection.
If anObject is not encountered, all elements up to the end are read and returned.
Compare this with #through: which also reads up to some object
and also positions behind it, but DOES include it in the returned value.

o  upToAllExcluding: aCollection
read a collection of all objects up-to a element which is contained in
aCollection and return these elements, but excluding the matching one.
The next read operation will return the element after aCollection.
If no such element is encountered, all elements up to the end are read
and returned.
See also #throughAll: which also reads up to some object
and also positions behind it, but DOES include it in the returned
value.
See also #upToAll:, which returns the same, but leaves the
read pointer before the matched subcollection.

o  upToEnd
return a collection of the elements up-to the end.
Return an empty collection, if the stream-end is already at the end.

usage example(s):

     (ReadStream on:'1234567890') upToEnd
     ('123456' readStream) next; next; upToEnd
     ('1 23456' readStream) upTo:Character space; upToEnd
     ('12' readStream) next; next; upToEnd

reading-numbers
o  nextDecimalInteger
read and return the next integer from the receiver stream.
Leaves the stream positioned after the digits

o  nextDecimalInteger: numChars
read and return the next integer of numChars size from the receiver stream.
Does NOT skip separators.
Leaves the stream positioned after the digits.
Raises an error, if the characters cannot be converted to an integer

o  nextDecimalNumber
read and return the next number from the receiver stream.
Leaves the stream positioned after the digits

o  nextDecimalNumber: numChars
read and return the next number of numChars size from the receiver stream.
Does NOT skip separators.
Leaves the stream positioned after the digits.
Raises an error, if the characters cannot be converted to a number

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.

stacked computing streams
o  collecting: aBlock
( an extension from the stx:libbasic2 package )
return a stacked computing stream, which reads elements from the receiver,
applies aBlock to each read element, and provides the results as elements to its reader.

o  selecting: aBlock
( an extension from the stx:libbasic2 package )
return a stacked computing stream, which reads elements from the receiver,
but only provides elements for which aBlock returns true to its reader.

stream-to-stream copy
o  copy: numberOfElementsOrNil into: outStream
read from the receiver, and write numberOfElements elements to outStream, a WriteStream.
Return the number of elements which have been transferred.
If numberOfElementsOrNil is nil, copy until the end of myself.

o  copy: numberOfElementsOrNil into: aWriteStream bufferSize: bufferSizeOrNil
read from the receiver, and write numberOfElementsOrNil elements to outStream, a WriteStream.
Return the number of elements which have been transferred.
If numberOfElementsOrNil is nil, copy until the end of myself.
If bufferSizeOrNil is not nil, data is transferred in chunks of that size,
otherwise a default (bufferSizeForNormalCopy) is used.

o  copyToEndFrom: inStream
read from inStream, and write all elements up to the end to the receiver.
Return the number of elements which have been transferred.
Same functionality as #copyToEndInto:, but reversed arg and receiver
(useful in a cascade message of the writeStream)

o  copyToEndInto: outStream
read from the receiver, and write all elements up to the end to outStream, a WriteStream.
Return the number of elements which have been transferred

usage example(s):

retVal := self copyToEndInto:outStream bufferSize:(64*1024).

o  copyToEndInto: outStream bufferSize: bufferSizeOrNil
read from the receiver, and write all elements up to the end to outStream, aWriteStream.
Return the number of elements which have been transferred.
If bufferSizeOrNil is not nil, data is transferred in chunks of that size,
otherwise a default (bufferSizeForNormalCopy) is used.

usage example(s):

      'hello world' readStream copyToEndInto:'/tmp/mist' asFilename writeStream.
      'hello world' readStream copyToEndInto:'' writeStream.
      ('/tmp/mist' asFilename readStream binary; yourself) copyToEndInto:#[] writeStream
      #[1 2 3 4 5 6 7] readStream copyToEndInto:'/tmp/mist' asFilename writeStream binary; yourself.

      |s|
      s := #() writeStream.
      #(1 2 3 a 'b' 6.4 true) readStream next; copyToEndInto:s. s inspect.

testing
o  atEnd
return true if the end of the stream has been reached;
- we do not know here how to do it, it must be redefined in subclass

** This method raises an error - it must be redefined in concrete classes **

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

** This method raises an error - it must be redefined in concrete classes **

o  isEmptyOrNil
return true, if the contents of the stream is empty
(we already know, that we are not nil)

o  isEncodedStream
true, iff this is an encoder/decoder stream

o  isLineNumberReadStream
true, iff this is a lineNumbering stream

o  isPositionable
return true, if the stream supports positioning (some do not).
Since this is an abstract class, false is returned here - just to make certain.

o  isPrinterStream
return true, if this is a printerStream.
Since this is an abstract class, false is returned here.

o  isStream
return true, if the receiver is some kind of Stream. Always return true here.

o  isTerminalStream
true, iff this is a terminal emulator stream

o  isTextCollector
true, iff this is a text collector emulating a stream

usage example(s):

     Transcript isTextCollector

o  notEmpty
return true, if the contents of the stream is not empty

o  notEmptyOrNil
return true, if the contents of the stream is empty
(we already know, that we are not nil)

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitStream:with: to aVisitor.

waiting for I/O
o  readWait
suspend the current process, until the receiver
becomes ready for reading. If data is already available,
return immediately.
The other threads are not affected by the wait.

o  readWaitTimeoutMs: timeout
ST-80 compatibility

o  readWaitWithTimeout: secondsOrTimeDurationOrNil
suspend the current process, until the receiver
becomes ready for reading or a timeout (in seconds) expired.
If data is already available, return immediate.
With nil seconds, wait forever.
Return true if a timeout occurred (i.e. false, if data is available).
The other threads are not affected by the wait.

o  readWaitWithTimeoutMs: millis
suspend the current process, until the receiver
becomes ready for reading or a timeout (in milliseconds) expired.
If data is already available, return immediate.
With nil millis, wait forever.
Return true if a timeout occurred (i.e. false, if data is available).
The other threads are not affected by the wait.

o  readWriteWait
suspend the current process, until the receiver
becomes ready for writing or reading.
Return immediate if the receiver is already ready.
The other threads are not affected by the wait.

o  readWriteWaitWithTimeoutMs: millis
never have to wait

o  writeWait
suspend the current process, until the receiver
becomes ready for writing.
Return immediate if the receiver is already ready.
The other threads are not affected by the wait.

o  writeWaitTimeoutMs: timeout
ST-80 compatibility

o  writeWaitWithTimeout: secondsOrTimeDurationOrNil
suspend the current process, until the receiver
becomes ready for writing or a timeout (in seconds) expired.
Return true if a timeout occurred (i.e. false, if data is available).
Return immediate if the receiver is already ready.
The other threads are not affected by the wait.

o  writeWaitWithTimeoutMs: millis
never have to wait

writing
o  beginEntry
ignored here - for compatibility with Transcript

o  cr
append a carriage-return to the stream.
This is only allowed, if the receiver supports writing.

o  crTab
append a carriage-return followed by a tab to the stream.
Same as crtab for ST/X backward compatibility.
This is only allowed, if the receiver supports writing.

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

o  crlf
append a CR LF to the stream.
This is only allowed, if the receiver supports writing.

o  crtab
append a carriage-return followed by a tab to the stream.
This is only allowed, if the receiver supports writing.

o  crtab: n
append a carriage-return followed by n tabs to the stream.
This is only allowed, if the receiver supports writing.

o  endEntry
ignored here - for compatibility with Transcript

o  ff
append a form-feed (new-pagee) to the receiver-stream.
This is only allowed, if the receiver supports writing.

o  flush
write out all unbuffered data - ignored here, but added
to make internalStreams protocol compatible with externalStreams

o  format: formatSpec with: args
convenient formatted printing:
%1..%9 - positional parameters from args-collection
%(name) - named parameter from args-dictionary
%% - escape for %
%<cr> - cr (also tab, nl)

usage example(s):

     1 to: 10 do:[:i |
        Transcript
            format:'[%1] Hello %2 World - this is %3%'
            with:{i . 'my' . 'nice'}
     ].

o  lf
append a LF to the stream.
This is only allowed, if the receiver supports writing.

o  next: count put: anObject
put the argument, anObject count times onto the receiver.
This is only allowed, if the receiver supports writing.

o  next: count putAll: aCollection
put all elements from the argument, aCollection count times onto the receiver.
This is only allowed, if the receiver supports writing.

o  next: n putAll: aCollection startingAt: pos1
append n elements starting at pos1 of the argument, aCollection to the stream.

o  nextPut: anObject
put the argument, anObject onto the receiver
- we do not know here how to do it, it must be redefined in subclass

** This method raises an error - it must be redefined in concrete classes **

o  nextPutAll: aCollection
put all elements of the argument, aCollection onto the receiver.
This is only allowed, if the receiver supports writing.

o  nextPutAll: count from: aCollection startingAt: initialIndex
append count elements with index starting at initialIndex
of the argument, aCollection onto the receiver.
This is only allowed, if the receiver supports writing.
Answer the number of elements that were appended.
This is for compatibility with ExternalStream, where less then
count elements may be written. Dolphin defines this as well.

o  nextPutAll: aCollection startingAt: first
append the elements starting with index to the end
of the argument, aCollection onto the receiver.
This is only allowed, if the receiver supports writing.

o  nextPutAll: aCollection startingAt: first to: last
append the elements from first index to last index
of the argument, aCollection onto the receiver.
This is only allowed, if the receiver supports writing.

o  nextPutAllLines: aCollectionOfStrings
put all elements of the argument, aCollection as individual lines
onto the receiver, append a cr (carriage return) after each.
This is only useful with character streams in textMode,
and only allowed, if the receiver supports writing.

o  nextPutAllText: aText
normal streams can not handle text/emphasis, so convert aText to the string

o  nextPutAllUnicode: aString
normal streams can not handle multi-byte characters, so convert them to utf8

o  nextPutAllUntranslated: aCollection
for compatibility with printStreams (putAll - as-is without escapes)

o  nextPutLine: aCollection
put all elements of the argument, aCollection onto the receiver,
and append a cr (carriage return). aCollection should contain characters.
This is only useful with character streams in textMode
and only allowed if the receiver supports writing.

o  nextPutUnicode: aCharacter
normal streams can not handle multi-byte characters, so convert them to utf8

o  print: anObject
append a printed representation of anObject to the receiver.
Same as 'anObject printOn:self'; Added for ST-80 compatibility.

o  printCR: anObject
append a printed representation of anObject to the receiver,
followed by a newline character.

o  printf: format
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'Hello World\n'
     Transcript printf:'Hello World %d\n' with:123

o  printf: format arguments: arguments
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
Same as printf:withAll:, for protocol completeness.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%05x %d %f %o\n' withAll:{ 123. 234*5. 1.234. 8r377 }
     Transcript printf:'%03d %03d %03d\n' withAll:{ 1. 2. 3 }

o  printf: format with: argument
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%05x\n' with:12345

o  printf: format with: argument1 with: argument2
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%05x %3s\n' with:12345 with:'abc'

o  printf: format with: argument1 with: argument2 with: argument3
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%05x %3s %09s\n' with:12345 with:'abc' with:'abc'
     Transcript printf:'%05x %3s %9s\n' with:12345 with:'abc' with:'abc'

o  printf: format with: argument1 with: argument2 with: argument3 with: argument4
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%02x %02x %02x %02x\n' with:1 with:2 with:3 with:4
     Transcript printf:'%2x %2x %2x %2x\n' with:1 with:2 with:3 with:4
     Transcript printf:'%-2x %-2x %-2x %-2x\n' with:1 with:2 with:3 with:4

o  printf: format with: argument1 with: argument2 with: argument3 with: argument4 with: argument5
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%02x %02x %02x %02x\n' with:1 with:2 with:3 with:4
     Transcript printf:'%2x %2x %2x %2x\n' with:1 with:2 with:3 with:4
     Transcript printf:'%-2x %-2x %-2x %-2x\n' with:1 with:2 with:3 with:4

o  printf: format withAll: arguments
( an extension from the stx:libbasic2 package )
C-style printing into a stream.
For smalltalk specific formats,
see documentation in PrintfScanf >> format_printf

usage example(s):

     Transcript printf:'%05x %d %f %o\n' withAll:{ 123. 234*5. 1.234. 8r377 }
     Transcript printf:'%03d %03d %03d\n' withAll:{ 1. 2. 3 }

o  println
for those used to Java/Javascript, a compatibility message.
Most useful inside expecco

o  println: anObject
for those used to Java/Javascript, a compatibility message.
Most useful inside expecco

o  show: something
append a printed representation of the argument to the stream.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something with: arg
append a printed representation of the argument to the stream, expanding
the placeHolder %1 with the printString of arg.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something with: arg1 with: arg2
append a printed representation of the argument to the stream, expanding
the placeHolders %1 and %2 with the printStrings of arg1 and arg2.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something with: arg1 with: arg2 with: arg3
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something with: arg1 with: arg2 with: arg3 with: arg4
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something with: arg1 with: arg2 with: arg3 with: arg4 with: arg5
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  show: something withArguments: args
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of argi.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCR: aString
append a printed representation of the argument to the stream
and append a newline character.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCR: something with: arg
append a printed representation of the argument to the stream, expanding
the placeHolder %1 with the printString of arg.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

usage example(s):

     Transcript showCR:'hello %1' with:'world'

o  showCR: something with: arg1 with: arg2
append a printed representation of the argument to the stream, expanding
the placeHolders %1 and %2 with the printStrings of arg1 and arg2.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCR: something with: arg1 with: arg2 with: arg3
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

usage example(s):

     Transcript showCR:'hello %1 %2 %3' with:'foo' with:10 with:'bla'

o  showCR: something with: arg1 with: arg2 with: arg3 with: arg4
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCR: something with: arg1 with: arg2 with: arg3 with: arg4 with: arg5
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of arg1, arg2 and arg3.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCR: something withArguments: args
append a printed representation of the argument to the stream, expanding
the placeHolders %1,%2 and %3 with the printStrings of argi.
This makes streams somewhat compatible to TextCollectors and
allows you to say:
Smalltalk at:#Transcript put:Stdout
or to use #show:/#showCR: with internal or external streams.

o  showCr: aString
append a printed representation of the argument to the stream
and append a newline character.
This is obsolete ST/X backward compatibility; use #showCR:

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

o  space
append a space character to the receiver.
This is only allowed, if the receiver supports writing.

o  spaces: count
append count space-characters to the receiver.
This is only allowed, if the receiver supports writing.

o  store: anObject
append a printed representation of anObject to the receiver,
from which the receiver can be reconstructed (i.e. its storeString).
Same as 'anObject storeOn:self'; Added for ST-80 compatibility.

o  sync
write out all unbuffered data - ignored here, but added
to make internalStreams protocol compatible with externalStreams

o  syncData
write out all unbuffered data - ignored here, but added
to make internalStreams protocol compatible with externalStreams

o  tab
append a tab-character to the stream.
This is only allowed, if the receiver supports writing.

o  tab: count
append count tab-characters to the receiver.
This is only allowed, if the receiver supports writing.

writing-chunks
o  nextChunkPut: aString
put aString as a chunk onto the receiver;
double all exclamation marks except within primitives and append a
single delimiting exclamation mark at the end.
This modification of the chunk format (not doubling exclas in primitive code)
was done to have primitive code more readable and easier be edited in the fileBrowser
or other editors.
It's no incompatibility, since inline primitives are an ST/X special
and code containing ST/X primitives cannot be loaded into other smalltalks anyway.

o  nextPutAllAsChunk: aString
put aString as a chunk onto the receiver;
double all exclamation marks except within primitives.
This modification of the chunk format (not doubling exclas in primitive code)
was done to have primitive code more readable and easier be edited in the fileBrowser
or other editors.
It's no incompatibility, since inline primitives are an ST/X special
and code containing ST/X primitives cannot be loaded into other smalltalks anyway.

o  nextPutChunkSeparator
append a chunk separator character



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Thu, 28 Mar 2024 23:02:58 GMT