Class: WriteStream

• Inheritance
• Description
• Related information
• Instance protocol
  • Compatibility-Dolphin
  • accessing
  • positioning
  • private
  • private-accessing
  • queries
  • reading
  • testing
  • writing
• Examples

Inheritance:

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

Package:

stx:libbasic

Category:

Streams

Version:

rev: 1.71 date: 2009/10/05 09:19:55

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 if 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.

Related information:

    CharacterWriteStream
    (if
    streaming
    for
    a
    unicode
    string)

Instance protocol:

 display: someObject

 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.

 last

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

 last: n

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

 reset

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

 position0Based: index0Based

redefined to allow positioning past the readLimit

 growCollection

grow the streamed collection to at least 10 elements

 growCollection: minNewSize

grow the streamed collection to at least minNewSize

 setCollection: newCollection

 on: aCollection

 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.

 isReadable

return true if the receiver supports reading - thats not true

 isWritable

return true, if writing is supported by the recevier.
Always return true here

 size

return the current size

 next

catch read access to write stream - report an error

 peek

catch read access to write stream - report an error

 isEmpty

return true, if the contents of the stream is empty

 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.

 next: n putAll: aCollection startingAt: pos1

append some elements of the argument, aCollection to the stream.

 nextPut: anObject

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

 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.

 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.

 nextPutAllUnicode: aString

normal streams can not handle multi-byte characters, so convert them to utf8

 nextPutByte: anObject

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

 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

 nextPutUnicode: aCharacter

normal streams can not handle multi-byte characters, so convert them to utf8

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)