Class: WriteStream

• Inheritance
• Description
• Instance protocol
  • Compatibility-Squeak
  • accessing
  • positioning
  • private
  • private-accessing
  • queries
  • reading-disabled
  • testing
  • writing
• Examples

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:

 resetContents

Squeak compatibility

 clear

for compatibility with Transcript

 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

Usage example(s):

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

 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.

 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.

 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.

 reset

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

 position: index0Based

redefined to allow positioning past the readLimit

 skip: count

redefined to allow positioning back over already written characters

 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

 growCollection

grow the streamed collection to at least 10 elements

 growCollection: minNewSize

grow the streamed collection to at least minNewSize

 with: aCollection

setup for streaming to the end of aCollection

Usage example(s):

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

 on: aCollection

(comment from inherited method)
setup for streaming 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.

 collectionSize

common stream protocol: return the size of the stream

 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'

 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

 isReadable

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

 isWritable

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

 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:$*

 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

 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.

 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'

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

 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

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)