eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'WriteStream':

Home

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

Class: WriteStream


Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--CharacterWriteStream
               |
               +--ReadWriteStream

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.112 date: 2018/05/24 19:08:42
user: cg
file: WriteStream.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


Streams for writing into.
WriteStreams are especially useful, if big strings are to be constructed
from pieces - create a writeStream, add the pieces (with #nextPut: or
#nextPutAll:) and finally fetch the concatenated string via #contents.
This is much better than constructing the big string by concatenating via
the comma (,) operator, since less intermediate garbage objects are created.

This implementation currently DOES change the
identity of the streamed-upon collection IF it cannot grow easily.
Collections which cannot grow easily are for example: Array, ByteArray and String.
Thus it is slightly incompatible to ST-80 since 'aStream contents' does
not always return the original collection. This may change.

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


Related information:

    CharacterWriteStream
    (if
    streaming
    for
    a
    unicode
    string)

Instance protocol:

Compatibility-Squeak
o  resetContents
Squeak compatibility

accessing
o  clear
for compatibility with Transcript

o  contents
return the current contents (a collection) of the stream.
Currently, this returns the actual collection if possible
(and reset is implemented to create a new one) in contrast to
ST80, where contents returns a copy and reset only sets the writePointer.
The ST/X behavior creates less temporary garbage in the normal case
(where things are written for the contents only) but may be incompatible
with some applications. Time will show, if this is to be changed.

o  last
return the last element - report an error if the stream is empty

o  last: n
return the last n elements as species of the underlying collection;
Report an error if the stream is empty

o  readStream
return a readstream on the current contents;
that is: if more is written to the stream in the meantime,
the readStream will NOT show it.
To avoid copying the contents, a readStream with a readLimit
is created. In the hope, that noone repositions and rewrites the
underlying writeStream.
If that leads to problems, you should use contents readStream.

o  reset
reset the stream; write anew.
See the comment in WriteStream>>contents

positioning
o  position: index0Based
redefined to allow positioning past the readLimit

o  skip: count
redefined to allow positioning back over already written characters

o  truncateTo: givenMax
if the streamed contents is larger than maxSize,
reset the write position back to this size.
Otherwise do nothing.

private
o  growCollection
grow the streamed collection to at least 10 elements

o  growCollection: minNewSize
grow the streamed collection to at least minNewSize

private-accessing
o  on: aCollection

o  on: aCollection from: start to: last
create and return a new stream for writing onto aCollection, where
writing is limited to the elements in the range start to last.

queries
o  endsWith: aCollection
Answer true, if the contents of the stream ends with aCollection.
Speedup for upToAll:, throughAll etc.
usage example(s):
        (WriteStream with:'abcdef') endsWith:'def'
        (WriteStream with:'def') endsWith:'def'
        (WriteStream with:'abc') endsWith:'def'
        (WriteStream with:'ef') endsWith:'def'
false    

o  size
return the current size

reading
o  next
catch read access to write stream - report an error

o  peek
catch read access to write stream - report an error

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

o  isReadable
return true if the receiver supports reading - that's not true

o  isWritable
return true, if writing is supported by the receiver.
Always return true here

writing
o  next: count put: anObject
append anObject count times to the receiver.
Redefined to avoid count grows of the underlying collection -
instead a single grow on the final size is performed.
usage example(s):
     '' writeStream next:10 put:$*

o  nextPut: anObject
append the argument, anObject to the stream.
Specially tuned for appending to String, ByteArray and Array streams.

o  nextPutAll: aCollection
append all elements of the argument, aCollection to the stream.
Redefined to avoid count grows of the underlying collection -
instead a single grow on the final size is performed.

o  nextPutAll: aCollection startingAt: pos1 to: pos2
append some elements of the argument, aCollection to the stream.
Redefined to avoid count grows of the underlying collection -
instead a single grow on the final size is performed.

o  nextPutAllUnicode: aString
normal streams can not handle multi-byte characters, so convert them to utf8
usage example(s):
this code is not perfect if you use both #nextPutAll: and #nextPutAllUnicode:
     with the same stream, since 8-bit characters (with the highest bits set)
     are not stored as UTF, so we get some inconsistent string

o  nextPutByte: anObject
append the argument, anObject to the stream.
Specially tuned for appending to String and ByteArray streams.

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  nextPutUnicode: aCharacter
normal streams can not handle multi-byte characters, so convert them to utf8
usage example(s):
this code is not perfect if you use both #nextPut: and #nextPutUnicode:
     with the same stream, since 8-bit characters (with the highest bits set)
     are not stored as UTF, so we get some inconsistent string


Examples:


     |s|

     s := WriteStream on:''.
     s nextPutAll:'hello';
       space;
       nextPutAll:'world'.

     s contents inspect
     |s|

     s := WriteStream on:''.
     s nextPutAll:'hello';
       space;
       nextPutAll:'world'.

     Transcript nextPutLine:(s contents)
     |s|

     s := '' writeStream.
     s nextPutAll:'hello';
       space;
       nextPutAll:'world'.

     Transcript nextPutLine:(s contents)


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Wed, 19 Sep 2018 13:02:33 GMT