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
               |
               +--IndentStream
               |
               +--ReadWriteStream

Package:
stx:libbasic
Category:
Streams
Version:
rev: 1.132 date: 2024/02/12 15:02:23
user: cg
file: WriteStream.st directory: libbasic
module: stx stc-classLibrary: libbasic

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)

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.

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

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPut:$a.
     s last.
     s nextPut:$b.
     s last.
     s nextPut:$c.
     s last.

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

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPut:$a.
     s last:1.
     s nextPut:$b.
     s last:1.
     s last:2.
     s nextPut:$c.
     s last:1.
     s last:2.
     s last:3.

o  lastOrNil
return the last element - answer nil if the stream is empty

Usage example(s):

     |s|

     s := '' writeStream.
     s lastOrNil.
     s nextPut:$b.
     s lastOrNil.

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.

Usage example(s):

     |w r|

     w := WriteStream on:(String new).
     w nextPutAll:'12345'.
     r := w readStream.
     w nextPutAll:'abc'.
     w nextPutAll:(r upToEnd).
     w nextPutAll:'def'.
     w contents.

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.

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPutAll:'123456'.
     s truncateTo:4.
     s nextPutAll:'abc'.
     s contents

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPutAll:'1234'.
     s truncateTo:4.
     s nextPutAll:'abc'.
     s contents

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPutAll:'123'.
     s truncateTo:4.
     s nextPutAll:'abc'.
     s contents

Usage example(s):

     |s|

     s := 'testFile' asFilename writeStream.
     s nextPutAll:'123456'.
     s truncateTo:4.
     s nextPutAll:'abc'.
     s close.
     'testFile' asFilename contents

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

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

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

Usage example(s):

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

private-accessing
o  on: aCollection
(comment from inherited method)
setup for streaming 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  collectionSize
common stream protocol: return the size of the stream

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'

o  size
return the current size

reading-disabled
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.
Answer the argument.
Specially tuned for appending to String, ByteArray and Array streams.

Usage example(s):

        (WriteStream on:'') nextPut:30; nextPut:$a; nextPut:20; nextPut:$Z; contents

o  nextPutAll: aCollection
append all elements of the argument, aCollection to the stream.
Answer the receiver.
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.

Usage example(s):

     |s|

     s := '' writeStream.
     s nextPutAll:'hello '.
     s nextPutAll:'1234world012345' startingAt:5 to:9.
     s contents   
     => 'hello world'

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

Usage example(s):

        (WriteStream on:Unicode16String new)
            nextPutAllUnicode:'HÄlllo'.

        (WriteStream on:ByteArray new)
            nextPutAllUnicode:'HÄlllo'.

        (WriteStream on:Array new)
            nextPutAllUnicode:'HÄlllo'.
Todo:
        (WriteStream on:WordArray new)
            nextPutAllUnicode:'HÄlllo'.

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

Usage example(s):

        (WriteStream on:Unicode16String new)
            nextPutUnicode:$Ä.

        (WriteStream on:ByteArray new)
            nextPutUnicode:$Ä

        (WriteStream on:Array new)
            nextPutUnicode:$Ä
Todo:
        (WriteStream on:WordArray new)
            nextPutUnicode:$Ä


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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Tue, 10 Dec 2024 08:52:14 GMT