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.

See also "Stream Handling" in Expecco_API.
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). Notice that a a stream on a collection which contains non-characters will return its elements when reading. Thus, you can also open stream on integers, floats, or whatever the collection contains.

aCollection writeStream
aString writeStream

returns a stream to write to a general collection or especially a string stream. The stream will write initially into the given collection, but will reallocate a bigger collection if required. Usually, the given collection will be empty so the stream will immediately allocate a new container and return that at the end (see "contents" below).

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 operating system-command. For example, on Unix, you can read the output of the "ls" command via "PipeStream readingFrom:'ls'".

PipeStream writingTo: OS-command => PipeStream

returns a stream writing to the input of an operating system-command

Testing

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

returns true if no more elements are to be read

Reading

Text vs. Binary Mode

By default, character streams (in particular: file streams) are in text mode, meaning that the read functions retrieve characters or strings. If the mode is switched to binary mode, bytes (integers) and byteArrays are retrieved.

aStream binary
aStream.binary() [JS]
aStream text
aStream.text() [JS]

switches to binary or text mode

Characters

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

returns the next element (as character object if text stream) or byte if in binary mode or arbitrary object if streaming other collections.

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) or bytes in binary mode

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), independent of the current read mode

aStream nextBytes: count => ByteArray

returns the next count bytes (as a byte array), independent of the read mode

aStream nextBytes: count into: aByteArray startingAt: index1Based => count

reads the next count bytes into the given byteArray starting at index in the byteArray. Returns the number of bytes read (which might be less than count, if the End-Of-File is reached). Will report an error, if the given buffer is too small.

Reading Words, Lines, etc.

aCharacterStream nextAlphaNumericWord => String | nil
aCharacterStream nextLine => String | nil

returns the next word (up to non-letterOrDigit) or line (up to the line end) as a string. The stream must be in text mode.

aStream upTo: element => String | ByteArray

returns characters (in text mode) or bytes (in binary mode) up to element as either a string or byte array. The element itself will be read, but not be part of the returned collection (i.e. it is skipped over). This is useful eg. to read characters up to a semicolon.

aStream upToAny: collectionOfElement => String | ByteArray

similar, but looks for multiple such separators. This is useful eg. to read characters up to a either a semicolon or a comma (as in CSV files).

aStream upToAnyForWhich: aBlock => String | ByteArray

similar, but a test-block (aka lambda function) is given, which checks for the limiting element.

aStream upToSeparator => String

returns all characters (in text mode) up to the next separator (space, tab or newline). The stream is left positioned before the separator (i.e. the next read will return the separator character).
Same as "aStream upToAnyForWhich: #isSeparator".

aStream upToEnd => String | ByteArray

returns all characters (in text mode) or bytes (in binary mode) up to the end of the stream as either a string or byte array.

Numbers

Number readFrom: aStringOrStream => Number

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

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 => collection

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')
(actually an OrderedCollection is returned).

aStream scanf: formatString => collection

same as above, but implemented by the stream

Binary Data Reading

The following functions read sequences of binary bytes - not human readable characters/digits.

aStream nextInt32MSB: msbBoolean => Integer

reads the next 4 bytes from the stream as a 32 bit unsigned integer. The byte order is specified by msbBoolean as most-significant-first if true or least-significant-first if false.

aStream nextSignedInt32MSB: msbBoolean => Integer

reads the next 4 bytes from the stream as a 32 bit signed integer.

aStream nextInt16MSB: msbBoolean => Integer

reads the next 2 bytes from the stream as a 16 bit unsigned integer.

aStream nextSignedInt16MSB: msbBoolean => Integer

reads the next 2 bytes from the stream as a 16 bit signed integer.

aStream nextInt64MSB: msbBoolean => Integer

reads the next 8 bytes from the stream as a 64 bit unsigned integer.

aStream nextSignedInt64MSB: msbBoolean => Integer

reads the next 8 bytes from the stream as a 64 bit signed integer.

aStream nextIEEESingleMSB: msbBoolean => Float32

reads the next 4 bytes from the stream as a 32 bit IEEE single precision float.

aStream nextIEEEDoubleMSB: msbBoolean => Float64

reads the next 8 bytes from the stream as a 64 bit IEEE double precision float.

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; for binary streams, that is the bytes written so far as a byte array; for other streams, that will be an Array containing the written objects.

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). Notice: although this function is named "cr", it actually writes a newline character (LF), which is the standard line-end convention used on Unix systems. The name "cr" is used for history reasons and for compatibility with other Smalltalk systems.

aStream return

Appends (writes) a return character. Use this, if you explicitly want a CR to be written.

aStream crlf

Appends (writes) a cr-lf sequence. This is needed eg. when generating HTTP headers or when talking to other internet socket connections.

aStream tab

Appends (writes) a tabulator 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)

aStream nextPutLine: aString
aStream.nextPutLine( aString ) [JS]

writes aString followed by a line end (which is a newline-character)

Binary Data Writing

These functions write binary data - not human readable strings (digits).

aStream nextPutInt32: anInteger MSB: msbBoolean

writes anInteger as a 32 bit binary integer (4 bytes). The byte order is specified by msbBoolean as most-significant-first if true or least-significant-first if false.

aStream nextPutInt16: anInteger MSB: msbBoolean

writes anInteger as a 16 bit binary integer (2 bytes).

aStream nextPutInt64: anInteger MSB: msbBoolean

writes anInteger as a 64 bit binary integer (8 bytes).

aStream nextPutIEEEDouble: aFloat MSB: msbBoolean

writes aFloat as a 64 bit binary IEEE double precision float (8 bytes).

aStream nextPutIEEESingle: aFloat MSB: msbBoolean

writes aFloat as a 32 bit binary IEEE single precision float (4 bytes).

C-Style Writing

aStream printf: formatString withAll: argsCollection

prints according to format which is a C-printf style format specification
Eg.
Transcript printf:'%d %x foo %s %s' withAll: { 1234 . 1234 . 'hello' . 'world'} will generate "1234 4d2 foo hello world".

aStream printf: formatString with: arg

shortcut for above if only one argument needs to be passed.

aStream printf: formatString with: arg1 with: arg2

shortcut for above if two arguments need to be passed.

---

Copyright © 2014-2024 eXept Software AG