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
      |
      +--BitStream
      |
      +--Comanche::BufferStream
      |
      +--Comanche::DummyStream
      |
      +--CompressionStream
      |
      +--ConsStream
      |
      +--HashStream
      |
      +--InternalPipeStream
      |
      +--LoggingStream
      |
      +--PeekableStream
      |
      +--PrinterStream
      |
      +--RBScanner
      |
      +--Random
      |
      +--SelectingReadStream
      |
      +--SourceCodeStream
      |
      +--SplittingWriteStream
      |
      +--WebSocketStream

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.399 date: 2024/03/05 12:10:55
user: cg
file: Stream.st directory: libbasic
module: stx stc-classLibrary: libbasic

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)

copyright

COPYRIGHT (c) 1989 by Claus Gittinger All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

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 notification 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

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

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

constants
o  chunkSeparator
return the chunk-separation character

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

testing
o  isAbstract
Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

utilities
o  streamContents: blockWithArg
create a write-stream instance of the receiver-class,
evaluate blockWithArg, passing that stream,
extract and return the stream's contents.
Similar to collection>>streamContents:, but usable if
you don't know the type of collection in advance
(eg: especially for CharacterWriteStream)

Usage example(s):

     CharacterWriteStream streamContents:[:s |
        s nextPutLine:'hello'.
        s nextPutLine:'world'
     ]     


Instance protocol:

Compatibility-Dolphin
o  display: someObject
dolphin compatibility,
and also sent by displayOn:

Compatibility-ST/V
o  skipThroughEndOfLine
skip over until a line end (\n) is encountered.
The next read will return the element after the newline.

Usage example(s):

     |s|
     s := ReadStream on: c'123456789\n01234567890'.
     s next:3.  
     s skipThroughEndOfLine.
     s upToEnd      

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  nextLongPut: anInteger
( an extension from the stx:libcompat package )

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) **

o  nextWordPut: anInteger
( an extension from the stx:libcompat package )

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  _convertPrintArgs: args
( an extension from the stx:libjavascript package )
common code to either slice args into a format arg1,
or to concatenate them

o  log: aString
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3 _: arg4
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
Not for non-JavaScript usage

o  log: aString _: arg1 _: arg2 _: arg3 _: arg4 _: arg5 _: arg6 _: arg7 _: arg8
( 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(...).
(and, by the way, JS-actions in expecco see a binding for console -> Transcript.
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)
or:
Transcript.show('format ', 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
( 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 _: arg8
( an extension from the stx:libjavascript package )
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
( 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 _: arg8
( an extension from the stx:libjavascript package )
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 must be redefined in concrete classes (subclassResponsibility) **

o  encoder
for compatibility with encoded stream

o  encoding
for compatibility with encoded stream

Usage example(s):

unknown encoding

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

o  asUTF8EncodedStream
returns a new stream, which automatically encodes/decodes characters

Usage example(s):

     |s encoded decoded|
     s := '' writeStream asUTF8EncodedStream.
     s nextPutAll:'abcäëödef'.
     encoded := s contents. 

     s := encoded readStream asUTF8EncodedStream.
     decoded := s contents.     

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

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8 9).
     s next.
     s next.
     s do:[:element | Transcript showCR:element]

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

Usage example(s):

     |s|
     s := '/etc/hosts' asFilename readStream.
     s linesDo:[:line | Transcript showCR:line].
     s close

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  lineEndCR
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 if signalAtEnd is set, or nil is returned if not.

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.

Usage example(s):

     |s n buffer|

     buffer := ByteArray new:10.

     s := ReadStream on:#[1 2 3 4 5 6 7 8 9].
     s next:3.
     n := s nextBytes:9 into:buffer startingAt:1.
     Transcript showCR:('n = %1; buffer = <%2>' bindWith:n with:buffer)

Usage example(s):

     |s n buffer|

     buffer := String new:10.

     s := ReadStream on:'Hello World'.
     s next:6.
     n := s nextBytes:5 into:buffer startingAt:1.
     Transcript showCR:('n = %1; buffer = <%2>' bindWith:n with:buffer)

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

Usage example(s):

     |s aStream|
     aStream := 'smalltalk.rc' asFilename readStream.
     s := String new:100.
     aStream nextBytesInto:s.
     aStream close.
     s inspect

o  nextIEEEAppleExtended80MSB: msbFirst
read a 10-byte IEEE extended precision (80bit) float number

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.

Usage example(s):

     |bytes s|

     bytes := #[16rFF 16rFF 16rFF 16rFF].
     s := bytes readStream.
     Transcript showCR:(s nextInt32MSB:true).
     s reset.
     Transcript showCR:(s nextInt32MSB:false).

     bytes := #[16r12 16r34 16r56 16r78].
     s := bytes readStream.
     Transcript showCR:(s nextInt32MSB:true).
     s reset.
     Transcript showCR:(s nextInt32MSB:false).

     bytes := #[16r89 16rab 16rcd 16ref].
     s := bytes readStream.
     Transcript showCR:(s nextInt32MSB:true).
     s reset.
     Transcript showCR:(s nextInt32MSB:false).

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.

Usage example(s):

     |bytes s|

     bytes := #[16rFF 16rFF 16rFF 16rFF 16rFF 16rFF 16rFF 16rFF].
     s := bytes readStream.
     Transcript showCR:(s nextInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextInt64MSB:false) hexPrintString.

     bytes := #[16r10 16r00 16r00 16r00 16r00 16r00 16r00 16r00].
     s := bytes readStream.
     Transcript showCR:(s nextInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextInt64MSB:false) hexPrintString.

     bytes := #[16r12 16r34 16r56 16r78 16r9a 16rbc 16rde 16rf0].
     s := bytes readStream.
     Transcript showCR:(s nextInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextInt64MSB:false) hexPrintString.

     bytes := #[16rFe 16rdc 16rba 16r98 16r76 16r54 16r32 16r10].
     s := bytes readStream.
     Transcript showCR:(s nextInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextInt64MSB:false) hexPrintString.

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 if signalAtEnd is set, or nil is returned if not.

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.

Usage example(s):

     |s|

     s := #[ 16r01 16r02 16r03 16r04 16r05 ] readStream.
     (s nextUnsigned:3 MSB:true) hexPrintString.
     s := #[ 16r01 16r02 16r03 16r04 16r05 16r06 16r07 16r08 16r09 ] readStream.
     (s nextUnsigned:9 MSB:true) hexPrintString.

     s := #[ 16r01 16r02 16r03 16r04 16r05 ] readStream.
     (s nextUnsigned:3 MSB:false) hexPrintString.
     s := #[ 16r01 16r02 16r03 16r04 16r05 16r06 16r07 16r08 16r09 ] readStream.
     (s nextUnsigned:9 MSB:false) hexPrintString.

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.
Raises an error, if there are no 3 bytes left in the stream.

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   => '102030'
     ((ReadStream on:#[16r10 16r20 16r30]) nextUnsignedInt24MSB:false) hexPrintString  => '302010'

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.

Usage example(s):

     |bytes s|

     bytes := #[16rFF 16rFF 16rFF 16rFF 16rFF 16rFF 16rFF 16rFF].
     s := bytes readStream.
     Transcript showCR:(s nextUnsignedInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextUnsignedInt64MSB:false) hexPrintString.

     bytes := #[16r10 16r00 16r00 16r00 16r00 16r00 16r00 16r00].
     s := bytes readStream.
     Transcript showCR:(s nextUnsignedInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextUnsignedInt64MSB:false) hexPrintString.

     bytes := #[16r12 16r34 16r56 16r78 16r9a 16rbc 16rde 16rf0].
     s := bytes readStream.
     Transcript showCR:(s nextUnsignedInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextUnsignedInt64MSB:false) hexPrintString.

     bytes := #[16rFe 16rdc 16rba 16r98 16r76 16r54 16r32 16r10].
     s := bytes readStream.
     Transcript showCR:(s nextUnsignedInt64MSB:true) hexPrintString.
     s reset.
     Transcript showCR:(s nextUnsignedInt64MSB:false) hexPrintString.

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

Usage example(s):

     |s|
     s := ByteArray new writeStream.
     s nextPutByte:1.
     s next:10 putByte:99.
     s nextPutByte:2.
     s contents

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;
            nextPutUtf16Bytes:(Character codePoint:16r10CCCC) MSB:true;
            contents.

         (WriteStream on:Unicode16String new) 
            nextPutAllUtf16:'BÄxxx';
            nextPutUtf16:(Character codePoint:16r10CCCC);
            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  nextPutIEEEAppleExtended80: aFloat MSB: msbFirst
write a 10-byte IEEE extended precision (80bit) float number

Usage example(s):

     |bytes f|
     bytes := ByteArray streamContents:[:s |
                s nextPutIEEEAppleExtended80:44100.0 MSB:true
              ].
     bytes inspect.
     f := bytes readStream nextIEEEAppleExtended80MSB:true.
     self assert:(f = 44100.0).

Usage example(s):

     |bytes f|
     bytes := ByteArray streamContents:[:s |
                s nextPutIEEEAppleExtended80:44100.0 MSB:false
              ].
     bytes inspect.
     f := bytes readStream nextIEEEAppleExtended80MSB:false.
     self assert:(f = 44100.0).

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.

Usage example(s):

     |s|

     s := #[] writeStream.
     s nextPutInt16:16r1234 MSB:false.
     s contents.

Usage example(s):

     |s|

     s := #[] writeStream.
     s nextPutInt16:16r1234 MSB:true.
     s contents.

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  nextPutInt24: anIntegerOrCharacter MSB: msbFlag
Write the argument, anIntegerOrCharacter as a three byte integer.
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.

Usage example(s):

     |s|

     s := #[] writeStream.
     s nextPutInt24:16r123456 MSB:false.
     s contents.

Usage example(s):

     |s|

     s := #[] writeStream.
     s nextPutInt24:16r123456 MSB:true.
     s contents.

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.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt32:16r12345678 MSB:false.
     bytes := s contents.
     s := bytes readStream.
     (s nextInt32MSB:false) hexPrintString.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt32:16r12345678 MSB:true.
     bytes := s contents.
     s := bytes readStream.
     (s nextInt32MSB:true) hexPrintString.
.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt32:16r-80000000 MSB:true.
     bytes := s contents.
     s := bytes readStream.
     (s nextInt32MSB:true) hexPrintString.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt32:16r-80000000 MSB:false.
     bytes := s contents.
     s := bytes readStream.
     (s nextInt32MSB:false) hexPrintString.

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.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt64:16r123456789abcdef0 MSB:false.
     bytes := s contents.
     s := bytes readStream.
     (s nextUInt64MSB:false) hexPrintString.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt64:16r123456789abcdef0 MSB:true.
     bytes := s contents.
     s := bytes readStream.
     (s nextUInt64MSB:true) hexPrintString.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt64:16r-8000000000000000 MSB:true.
     bytes := s contents.
     s := bytes readStream.
     (s nextUInt64MSB:true) hexPrintString.

Usage example(s):

     |s bytes|

     s := #[] writeStream.
     s nextPutInt64:16r-8000000000000000 MSB:false.
     bytes := s contents.
     s := bytes readStream.
     (s nextUInt64MSB:false) hexPrintString.

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 UTF-16
specifications.

Usage example(s):

        ((WriteStream on:Unicode16String new)
            nextPutUtf16:$B;
            nextPutUtf16:$Ä; 
            nextPutUtf16:(Character codePoint:16r10CCCC)
            yourself) contents

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.
CodePoints > 0xFFFF are encoded as surrogate chars.
The underlying stream must support writing of bytes.

Usage example(s):

        (#[] writeStream
            nextPutUtf16Bytes:$B MSB:true;
            nextPutUtf16Bytes:$Ä MSB:true;
            nextPutUtf16Bytes:(Character codePoint:16r10CCCC) MSB:true;
            contents)

        ('' writeStream
            nextPutUtf16Bytes:$B MSB:true;
            nextPutUtf16Bytes:$Ä MSB:true;
            nextPutUtf16Bytes:(Character codePoint:16r10CCCC) MSB:true;
            contents)

        (FileStream newTemporary
            nextPutUtf16Bytes:$B MSB:false;
            nextPutUtf16Bytes:$Ä MSB:false;
            nextPutUtf16Bytes:(Character codePoint:16r10CCCC) MSB:false;
            reset;
            binary;
            contents)

        (FileStream newTemporary
            nextPutUtf16Bytes:$B MSB:false;
            nextPutUtf16Bytes:$Ä MSB:false;
            nextPutUtf16Bytes:(Character codePoint:16rDC30) MSB:false;
            reset;
            binary;
            contents)

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.

Usage example(s):

      (String streamContents:[:s|
            s nextPutUtf8:$a.
            s nextPutUtf8:$Ä.
            s nextPutUtf8: (Character value:16r1fff).
            s nextPutUtf8: (Character value:16rffff).
            s nextPutUtf8: (Character value:16r1ffffff).
            s nextPutUtf8: (Character value:16r800).
      ])
            asByteArray

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  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 must be redefined in concrete classes (subclassResponsibility) **

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.
Defined here to make internalStreams protocol compatible with externalStreams.

o  isContentsEqualTo: aStringOrByteArray
answer true, if the contents of myself from the current position
to the end is equal to aStringOrByteArray.

Avoid allocating of lots of memory when comparing large files.

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 must be redefined in concrete classes (subclassResponsibility) **

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

** This method must be redefined in concrete classes (subclassResponsibility) **

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 must be redefined in concrete classes (subclassResponsibility) **

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 must be redefined in concrete classes (subclassResponsibility) **

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

Usage example(s):

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

o  next: count into: aCollection
marked as obsolete by Stefan Vogel at 19-Jun-2023

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

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

Usage example(s):

     |s n buffer|

     buffer := Array new:10.

     s := ReadStream on:#(1 2 3 4 5 6 7 8 9).
     s next:3.
     n := s next:9 into:buffer startingAt:2.
     Transcript showCR:('n = %1; buffer = %2' bindWith:n with:buffer)

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  nextAvailableInto: aBuffer
read up to buffer-size elements of the stream into aBuffer.
Return the number of elements read
(i.e. either the buffer's size or the number of elements actually read into it)

Usage example(s):

     |buffer s count|
     buffer := Array new:5.
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     Transcript show:(count := s nextAvailableInto:buffer); space; showCR:(buffer copyTo:count).
     Transcript show:(count := s nextAvailableInto:buffer); space; showCR:(buffer copyTo:count).

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

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     s nextMatchFor:2

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     s nextMatchFor:2.
     s nextMatchFor:2

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

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     s skip:4.
     s next

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

Usage example(s):

     |s next rest|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     next := s skipFor:4.
     rest := s upToEnd.     
     self assert:(next == 5).
     self assert:(rest = #(6 7 8)).

Usage example(s):

     |s next rest|
     s := ReadStream on:'12345678'.
     next := s skipFor:$4.  
     rest := s upToEnd.
     self assert:(next == $5).
     self assert:(rest = '678').

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.

Usage example(s):

     |s|
     s := ReadStream on:#(1 nil 2 3 4 5 6 7 8).
     s skipThrough:4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     s skipThrough:4.
     s skipThrough:4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipThrough:$4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipThrough:$4.
     s skipThrough:$4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipThrough:$4.
     s skipThrough:$4.
     s atEnd

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.

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAll:'901'.
     s upToEnd

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAll:'1234'.
     s upToEnd

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAll:'999'.
     s atEnd

o  skipThroughAny: aCollection
skip for and through one of the characters contained in the argument, aCollection;
return nil if not found, the receiver otherwise.
On a successful match, the next read will return elements after one of the characters;
if no match was found, the receiver will be positioned at the end.

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAny:'93'.
     s upToEnd

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAny:'03'.
     s upToEnd

Usage example(s):

     |s|
     s := ReadStream on:'12345678901234567890'.
     s skipThroughAny:'x'.
     s atEnd

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

Usage example(s):

     |s|
     s := ReadStream on:#(1 nil 2 3 4 5 6 7 8).
     s skipToBefore:4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     s skipThrough:4.
     s skipToBefore:4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipToBefore:$4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipThrough:$4.
     s skipToBefore:$4.
     s next

Usage example(s):

     |s|
     s := ReadStream on:'12345678'.
     s skipThrough:$4.
     s skipToBefore:$4.
     s atEnd

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.

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     Transcript showCR:(s through:4).
     Transcript showCR:s next

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     Transcript showCR:(s through:9).
     Transcript showCR:s next

     |s|
     s := ReadStream on:'hello world'.
     Transcript showCR:(s through:Character space).
     Transcript showCR:(s upToEnd)

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.

Usage example(s):

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     Transcript showCR:(s throughAll:#(4 4 4)).
     Transcript showCR:s next

     |s|
     s := ReadStream on:#(1 2 3 4 5 6 7 8).
     Transcript showCR:(s throughAll:#(4 5 6)).
     Transcript showCR:s next

     |s|
     s := ReadStream on:'hello world, this is some text'.
     Transcript showCR:(s throughAll:'world').
     Transcript showCR:(s throughAll:'some').
     Transcript showCR:s upToEnd.

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.

Usage example(s):

     |s|
     s := ReadStream on:#(1 nil 2 3 4 5 6 7 8).
     Transcript showCR:(s throughAny:#(3 4 5)).
     Transcript showCR:s next

     |s|
     s := ReadStream on:'hello world, this is some text'.
     Transcript showCR:(s throughAny:'wt').
     Transcript showCR:(s throughAny:'wt').
     Transcript showCR:s upToEnd.

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.

Usage example(s):

     #(1 2 3 4 5 6 7 8 9 10) readStream
        throughElementForWhich:[:el | el > 5].

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.

Usage example(s):

     |s|
     s := '12345678901234567890' asArray readStream.
     s readLimit:5.
     s upTo:$3. 
     self assert:(s position = 3).
     s upTo:$x.    
     self assert:(s position = 5).     
     self assert:(s atEnd).     

Usage example(s):

     |s|
     s := '12345678901234567890' readStream.
     s upTo:$x.    
     self assert:(s position = 20).     
     self assert:(s atEnd).     

o  upTo: separatingObject into: aStream
read a collection of all objects up-to separatingObject and append these
elements to aStream, but excluding anObject.
The next read operation will return the element after separatingObject.
(i.e. separatingObject 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.

Usage example(s):

     |s w|
     w := #() writeStream.
     s := ReadStream on:#(1 2 3 4 5 'bla' 6 nil 7 8 9 theEnd).
     s upTo:2 into:w.
     w contents.
     w reset. s reset.

     s upTo:'bla' into:w.
     w contents.
     w reset. s reset.

     s upTo:nil into:w.
     w contents.
     w reset. s reset.

     s upTo:#nothing into:w.
     w contents.
     w reset. s reset.

o  upTo: anObject maxCount: max
read a collection of all objects up-to anObject or upTo max elements
and return these elements, but excluding anObject.
The next read operation will return the element after anObject (or after max elements).
Same as upTo:, but with a size limit

Usage example(s):

     |s t|
     s := '12345678901234567890' readStream.
     t := s upTo:$7 maxCount:5. 
     self assert:(s position = 5).
     self assert:(t = '12345').

Usage example(s):

     |s t|
     s := '12345678901234567890' asArray readStream.
     t := s upTo:$7 maxCount:5. 
     self assert:(s position = 5).
     self assert:(t = #($1 $2 $3 $4 $5)).

Usage example(s):

     |s t|
     s := '12345678901234567890' readStream.
     t := s upTo:$x maxCount:20. 
     self assert:(s atEnd).
     self assert:(t = '12345678901234567890').

o  upTo: separatingObject maxCount: max into: aStream
read a collection of all objects up-to anObject or upTo max elements
and write them into aStream.
The next read operation will return the element after anObject (or after max elements).
Same as upTo:into:, but with a size limit

Usage example(s):

     |s w|
     w := #() writeStream.
     s := ReadStream on:#(1 2 3 4 5 'bla' 6 nil 7 8 9 theEnd).
     s upTo:5 maxCount:3 into:w.
     w contents.
     self assert:(w contents = #(1 2 3)).
     self assert:(s next = 4).

o  upToAllExcluding: aCollection
read a collection of all objects up-to a sequence of elements given in aCollection,
and return these elements, but excluding the matching ones.
The next read operation will return the element after aCollection.
If no such sequence 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.

Usage example(s):

     |s|
     s := ReadStream on:'hello world world'.
     Transcript show:'<'; show:(s upToAllExcluding:'wo'); showCR:'>'.
     Transcript show:'<'; show:(s upToAllExcluding:'wo'); showCR:'>'.
     Transcript show:'<'; show:(s upToEnd); showCR:'>'.

Usage example(s):

     |s|
     s := ReadStream on:'hello world world'.
     Transcript show:'<'; show:(s upToAllExcluding:'xx'); showCR:'>'.
     Transcript show:'<'; show:(s upToEnd); showCR:'>'.

o  upToEnd
return a collection of the elements up-to the end.
Return an empty collection, if the stream 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

Usage example(s):

     |s|
     s := '1234a' readStream.
     Transcript showCR:(s nextDecimalInteger).
     s peek                                -> $a

Usage example(s):

     |s|
     s := '1234.0a' readStream.
     Transcript showCR:(s nextDecimalInteger).
     s peek                                -> $.

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

Usage example(s):

     |s|
     s := '1234a' readStream.
     Transcript showCR:(s nextDecimalInteger:2).
     Transcript showCR:(s nextDecimalInteger).
     s peek                                -> $a

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

Usage example(s):

     |s|
     s := '1234.0a' readStream.
     Transcript showCR:(s nextDecimalNumber).
     s peek                                -> $a

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

Usage example(s):

     |s|
     s := '12.34a' readStream.
     Transcript showCR:(s nextDecimalNumber:4).
     Transcript showCR:(s nextDecimalInteger).
     s peek                                -> $a

reading-strings
o  firstLine
almost the same as nextLine here:
BUT: The next read operation will return the element after the cr.

o  linesUpToEndWithLineDelimiter: lineDelimiter sizeLimit: sizeLimitOrNil encoding: fileEncodingArg onDecodingError: aBlock
read lines from receiver, answer its contents as StringCollection.
The lines are delimited by lineDelimiter (typically a linefeed).
If encoding is nonNil, the text is assumed to be coded according to
that symbol, and #decodeString: should be able to convert it into unicode.
Always returns a unicode string.
In case of a decoding error, the block is called with the
exception, the bad line and lineNr as arguments.
It may choose to proceed from the eception or return.
This is used at multiple places in the system, so its worth a utility function here

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.

Usage example(s):

     |s s2|

     s := 'hello world' readStream.
     s2 := s collecting:[:ch | ch asUppercase].
     s2 upToEnd.   

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.

Usage example(s):

     |s s2|

     s := 'hello world' readStream.
     s2 := s selecting:[:ch | ch isVowel].
     s2 upToEnd.

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.

Usage example(s):

        |s|
        s := WriteStream on:(String new:100).
        '/etc/passwd' asFilename readStream
            copy:nil into:s bufferSize:10.
        s contents

        |s|
        s := WriteStream on:(String new:100).
        '/etc/passwd' asFilename readStream
            copy:100 into:s bufferSize:10.
        s contents

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  isBuffered
return true, if writes to stream do not cause a system call for each operation.
Internal streams never do systsem calls, so this is true

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

** This method must be redefined in concrete classes (subclassResponsibility) **

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)

utilities
o  streamContents: blockWithArg
evaluate blockWithArg, passing myself,
extract and return the stream's contents.
Similar to collection>>streamContents:, but usable if
you have a stream at hand

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: timeoutMS
marked as obsolete by Stefan Vogel at 14-07-2021

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

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  readWriteWaitWithTimeout: secondsOrTimeDurationOrNil
suspend the current process, until the receiver
becomes ready for reading or writing or a timeout (in seconds) expired.
Return true if a timeout occurred (i.e. false, if data is available or can be written).
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
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 buffered 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.

Usage example(s):

     |s|

     s := WriteStream on:#().
     s nextPut:1.
     s next:5 put:2.
     s nextPut:3.
     s contents

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.

Usage example(s):

     |s|

     s := WriteStream on:(String new).
     s next:5 putAll:'Hello'.
     s contents

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

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPutAll:'hello '.
     s next:5 putAll:'1234world012345' startingAt:5.
     s contents

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 must be redefined in concrete classes (subclassResponsibility) **

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

Usage example(s):

     |s|

     s := WriteStream on:#().
     s nextPutAll:(1 to:5).
     s nextPutAll:#('one' 'two' 'three').
     s nextPutAll:#('a' 'b' 'c') asSet.
     s nextPutAll:nil.
     s contents

Usage example(s):

     |s|

     s := WriteStream on:(String new).
     s nextPutAll:($a to:$f).
     s nextPutAll:'one ';
       nextPutAll:'two ';
       nextPutAll:'three'.
     s contents

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.

Usage example(s):

     |s|

     s := WriteStream on:#().
     s nextPutAll:4 from:#('one' 'two' 'three' 'four' 'five') startingAt:2.
     s contents

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.

Usage example(s):

     |s|

     s := WriteStream on:#().
     s nextPutAll:#('one' 'two' 'three' 'four' 'five') startingAt:2.
     s contents

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.

Usage example(s):

     |s|

     s := WriteStream on:#().
     s nextPutAll:#('one' 'two' 'three' 'four' 'five') startingAt:2 to:4.
     s contents

o  nextPutAll: formatString with: arg
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  nextPutAll: formatString with: arg1 with: arg2
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  nextPutAll: formatString with: arg1 with: arg2 with: arg3
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  nextPutAll: formatString with: arg1 with: arg2 with: arg3 with: arg4
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  nextPutAll: formatString with: arg1 with: arg2 with: arg3 with: arg4 with: arg5
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  nextPutAll: formatString with: arg1 with: arg2 with: arg3 with: arg4 with: arg5 with: arg6
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  nextPutAll: formatString withArguments: args
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  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  nextPutLine: formatString with: arg
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  nextPutLine: formatString with: arg1 with: arg2
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  nextPutLine: formatString with: arg1 with: arg2 with: arg3
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  nextPutLine: formatString with: arg1 with: arg2 with: arg3 with: arg4
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  nextPutLine: formatString with: arg1 with: arg2 with: arg3 with: arg4 with: arg5
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  nextPutLine: formatString with: arg1 with: arg2 with: arg3 with: arg4 with: arg5 with: arg6
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  nextPutLine: formatString withArguments: args
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.

Usage example(s):

     |s|

     s := WriteStream on:''.
     s nextPutAll:'one ';
       print:1;
       nextPutAll:' two ';
       print:2.

     s contents

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

o  printf: formatString
( 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: formatString 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: formatString 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: formatString 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: formatString 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: formatString 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: formatString 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: formatString 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: anObject
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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: something
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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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: aStringWithPlaceHolders 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
make sure, that the OS writes cached data to the disk
- ignored here, but added to make internalStreams protocol compatible with externalStreams

o  syncData
tell the OS to ensure that data is synced to disk - 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.

Usage example(s):

     |stream|

     stream := '' writeStream.
     stream nextPutAllAsChunk:'Hello
     ''Hello world!''.
%{   
 Some c code!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
%}.
 ''We are done!''
'.
     stream contents.

o  nextPutChunkSeparator
append a chunk separator character



ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Tue, 10 Dec 2024 08:13:10 GMT