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
Inhaltsverzeichnis
Creation[Bearbeiten]
Internal Streams[Bearbeiten]
- aCollection readStream => Stream
- aString readStream => Stream
- ReadStream on: aCollection => 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 => Stream
- aString writeStream => Stream
- WriteStream on: aCollection => Stream
- 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[Bearbeiten]
- 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
Wellknown Streams[Bearbeiten]
- Transcript
- the Smalltalk console window also supports the stream protocol
- Stdin
- the standard input (notice: if started as "exe" on Windows, there will be no stdin; if started via desktop double click on unix, it will report End-of-File).
If started as "com" on Windows and/or in a command window, stdin is reading your command window input.
- the standard input (notice: if started as "exe" on Windows, there will be no stdin; if started via desktop double click on unix, it will report End-of-File).
- Stdout
- the standard output (notice: if started as "exe" on Windows, there will be no stdout; if started via desktop double click on unix, it will typically be redirected to either a log file or to /dev/null).
If started as "com" on Windows and/or in a command window, stdout is shown in the command window.
- the standard output (notice: if started as "exe" on Windows, there will be no stdout; if started via desktop double click on unix, it will typically be redirected to either a log file or to /dev/null).
- Stderr
- the standard error (notice: if started as "exe" on Windows, there will be no stderr; if started via desktop double click on unix, it will typically be redirected to either a log file or to /dev/null)
If started as "com" on Windows and/or in a command window, stdout is shown in the command window.
- the standard error (notice: if started as "exe" on Windows, there will be no stderr; if started via desktop double click on unix, it will typically be redirected to either a log file or to /dev/null)
Testing[Bearbeiten]
- aStream atEnd => Boolean
- aStream.atEnd() [JS]
- returns true if no more elements are to be read
- aStream isPositionable => Boolean
- returns true if the stream supports positioning. Not all streams support this (e.g. Sockets, PipeStreams, StdOut etc. do not).
- aStream size => Integer
- returns the number of bytes written to a writeStream or the overall size of a readStream's contents. Not all streams know their size and will report an error (e.g. Sockets, PipeStreams, StdOut etc. do not).
Mode Settings[Bearbeiten]
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
- aStream buffered: aBoolean
- for external write streams: turns buffering on/off.
By default, terminal stream are line buffered, while file streams use a larger buffer. When writing, buffers are filled first and then bigger chunks are written en-bloc. Notice that buffering may lead to characters written to a file a unseen by other programs until the buffer is flushed or the file stream is closed (see flush below).
- for external write streams: turns buffering on/off.
Reading[Bearbeiten]
Characters[Bearbeiten]
- 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[Bearbeiten]
- 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.[Bearbeiten]
- 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 e.g. to read characters up to a semicolon.
- aStream upToAny: collectionOfElement => String | ByteArray
- similar, but looks for multiple such separators. This is useful e.g. 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".
- 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).
- 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[Bearbeiten]
- Number readFrom: aStringOrStream => Number
- reads the string representation of a number.
E.g.Number readFrom:'123.456'
=> 123.456 (a float)
and:Number readFrom:'123456'
=> 123456 (an integer)
- reads the string representation of a number.
- Integer readFrom: aStringOrStream => Number
- reads the string representation of an integer.
E.g.Number readFrom:'123.456'
=> 123 (an integer)
- reads the string representation of an integer.
C-Style Reading[Bearbeiten]
- formatString scanf: aStringOrStream => collection
- reads according to format; returns a collection of matches. The argument can be string or stream.
E.g.'%d %x %s %s' scanf: '1234 ffee hello world'
=> #(1234 65518 'hello' 'world')
(actually an OrderedCollection is returned).
- reads according to format; returns a collection of matches. The argument can be string or stream.
- aStream scanf: formatString => collection
- same as above, but implemented by the stream
Binary Data Reading[Bearbeiten]
The following functions read sequences of binary bytes - not human readable characters/digits.
- aStream nextByte => Integer
- aStream nextSignedByte => Integer
- reads the next byte from the stream as an 8 bit unsigned / signed integer.
- aStream nextInt16MSB: msbBoolean => Integer
- aStream nextSignedInt16MSB: msbBoolean => Integer
- reads the next 2 bytes from the stream as a 16 bit unsigned / signed integer.
- aStream nextInt32MSB: msbBoolean => Integer
- aStream nextSignedInt32MSB: msbBoolean => Integer
- reads the next 4 bytes from the stream as a 32 bit unsigned or signed integer. The byte order is specified by msbBoolean as most-significant-first if true or least-significant-first if false.
- aStream nextInt64MSB: msbBoolean => Integer
- aStream nextSignedInt64MSB: msbBoolean => Integer
- reads the next 8 bytes from the stream as a 64 bit unsigned / signed integer.
- aStream nextIEEESingleMSB: msbBoolean => Float32
- aStream nextIEEEDoubleMSB: msbBoolean => Float64
- reads the next 4 bytes (8 bytes) from the stream as a 32 bit IEEE single (64 bit double) precision float.
Positioning[Bearbeiten]
- aStream position: pos => Stream
- positions the stream; pos is 0-based (i.e. 0 is the very beginning). Some streams are not positionable and will report an error (e.g. PipeStream, Socket). If the stream is a byte- or character stream, the position is measured in bytes, If the stream is an internal (object-) stream, it is measured in number of objects.
- 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 (e.g. PipeStream, Socket do not)
- aStream setToEnd => void
- position the stream to the end. Usually used when appending to an existing file.
- aStream reset => void
- position the stream to the beginning.
- aStream skip: count => Stream
- positions the stream count elements further (i.e. reads but ignores count elements)
Writing[Bearbeiten]
- 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 e.g. 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. // or: WriteStream on:String new. 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[Bearbeiten]
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 nextPutIEEESingle: aFloat MSB: msbBoolean
- aStream nextPutIEEEDouble: aFloat MSB: msbBoolean
- writes aFloat as a 32 bit (64 bit) binary IEEE single (double) precision float (4/8 bytes).
C-Style Writing[Bearbeiten]
- aStream printf: formatString withAll: argsCollection
- prints according to format which is a C-printf style format specification
E.g.Transcript
printf: '%d %x foo %s %s'
withAll: { 1234 . 1234 . 'hello' . 'world'}
will generate "1234 4d2 foo hello world".
- prints according to format which is a C-printf style format specification
- 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.
Finish Writing[Bearbeiten]
When done with writing, external streams should be closed with:
- aStream flush => void
- for write streams: flushes any buffered data. The stream remains open and more data can be written, but everything written before is given to the operating system to write it to disk or send it to a receiver. Notice: it is not guaranteed that the data is really on the disk/transmitted after a flush: if a machine crashes (looses power) immediately after the flush, the data may still be in another (operating system) buffer and not physically written. On some operating systems, you can ensure that by sending syncFileSystem to the stream after the flush.
- aStream close => void
- closes the stream; for file streams, any buffered output is now written. For sockets and pipes, the connection is shut down. If you forget to close an external stream, the data might be held in a buffer for an arbitrary time. If the garbage collector detects that an open stream is no longer references, it will close the stream (finalization). However, this may not happen for a long time, if enough memory is available or the system is otherwise idle.
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.