Stream API Functions

This document lists most useful (and most often needed) functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

Reference: Stream and ExternalStream and Socket

Back to Useful API Functions

Creation

Internal Streams

aCollection readStream => Stream
aString readStream => Stream

returns a stream to read from a general collection or especially from a string (which is a collection of characters)

aCollection writeStream
aString writeStream

returns a stream to write to a general collection or especially a string stream.

External Streams

pathString asFilename readStream => Stream
pathString asFilename writeStream => Stream
pathString asFilename appendingWriteStream => Stream

returns a stream to read / write the file named aFilenameString

Socket newTCPclientToHost:hostNameOrAddress port:aPortOrServiceName => SocketStream

returns a connected socket for reading and writing

PipeStream readingFrom:OS-command => PipeStream

returns a stream reading the output from an OS-command

PipeStream writingTo:OS-command => PipeStream

returns a stream writing to the input of an OS-command

Testing

aStream atEnd => Boolean
aStream.atEnd() [JS]

returns true if no more elements are to be read

Reading

Characters

aStream next => Character | nil
aStream.next() [JS]

returns the next character (as character object)

Example:

 s := 'data.txt' asFilename readStream.
 s next.
 => character

aStream next:count => String
aStream.next(count) [JS]

returns the next count characters (as a string)

Example:

 s := 'data.txt' asFilename readStream.
 s next:5.
 => string-of-5-chars

Binary Bytes

aStream nextByte => Integer | nil

returns the next byte (as an integer)

aStream nextBytes:count => ByteArray

returns the next count bytes (as a byte array)

Words and Lines

aStream nextAlphaNumericWord => String | nil

returns the next word (up to non-letterOrDigit) as a string

aStream nextLine => String | nil

returns the next line (up to newLine) as a string

Numbers

Number readFrom: aStringOrStream => Number

reads the string representation of a number.
Eg. Number readFrom:'123.456' => 123.456 (a float)

Integer readFrom: aStringOrStream => Number

reads the string representation of an integer.
Eg. Number readFrom:'123.456' => 123 (an integer)

C-Style Reading

formatString scanf:aStringOrStream

reads according to format; returns a collection of matches. The argument can be string or stream.
Eg. '%d %x %s %s' scanf: '1234 ffee hello world' => #(1234 65518 'hello' 'world').

Positioning

aStream position:pos => Stream

positions the stream; pos is 0-based (i.e. 0 is the very beginning). Some streams are not positionable (eg. PipeStream, Socket)

aStream position => Integer

returns the position of the stream; pos is 0-based (i.e. 0 is the very beginning). Not all streams have a concept of a position (eg. PipeStream, Socket do not)

aStream skip:count => Stream

positions the stream count elements further (i.e. reads over count elements)

Finish Writing

When done with writing, external streams should be closed with:

aStream close => void

closes the stream; for file streams, any buffered output is now written. For sockets and pipes, the connection is shut down.

When done with writing to an internal stream, its contents can be retrieved with:

aStream contents => Collection

retrieves the elements written so far. For a string stream, that is the characters written so far as a string.

Writing

aStream nextPut:someElement
aStream.nextPut(someElement) [JS]

Appends (writes) an element to the stream. For the special but most common case of a string- or file stream, the written element should be a character object.

aStream nextPutByte:anInteger

Appends (writes) a single byte. This is only allowed for string streams.

aStream cr

Appends (writes) a newline character (line-end character)

aStream nextPutAll:aCollectionOfElements
aStream.nextPutAll(aCollectionOfElements) [JS]

writes all elements from the argument to the stream. The collection's elements must be compatible with the streams element types. For string streams, this will usually be a string.

Example (writes a file):

 s := 'data.txt' asFilename writeStream.
 s nextPut: $a.
 s nextPut: $b.
 s nextPutByte: 0x0A.
 s nextPutAll: '123'. 
 s close.
 => file now contains 'ab<nl>123'

Example (writes a string):

 s :=  writeStream.
 s nextPut: $a.
 s nextPut: $b.
 s cr.
 s nextPutAll: '123'. 
 s contents.
 => 'ab<nl>123'

Example (writes an array):

 s := #() writeStream.   
 s nextPut: 1.
 s nextPut: 'two'.
 s nextPut: 3.14159.
 s nextPutAll: #(11 22 true false). 
 s contents
 => #( 1 'two' 3.14159 11 22 true false)

---

Copyright © 2014-2024 eXept Software AG