Module streams

This module provides a stream interface and two implementations thereof: the FileStream and the StringStream which implement the stream interface for Nim file objects (File) and strings. Other modules may provide other implementations for this standard stream interface.

Examples:

import streams
var
  ss = newStringStream("""The first line
the second line
the third line""")
  line = ""
while ss.readLine(line):
  echo line
ss.close()

var fs = newFileStream("somefile.txt", fmRead)
if not isNil(fs):
  while fs.readLine(line):
    echo line
  fs.close()

Types

Stream = ref StreamObj
  Source Edit
StreamObj = object of RootObj
  closeImpl*: proc (s: Stream) {.
nimcall, tags: [], gcsafe
.} atEndImpl*: proc (s: Stream): bool {.
nimcall, tags: [], gcsafe
.} setPositionImpl*: proc (s: Stream; pos: int) {.
nimcall, tags: [], gcsafe
.} getPositionImpl*: proc (s: Stream): int {.
nimcall, tags: [], gcsafe
.} readDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int): int {.
nimcall, tags: [ReadIOEffect], gcsafe
.} peekDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int): int {.
nimcall, tags: [ReadIOEffect], gcsafe
.} writeDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int) {.
nimcall, tags: [WriteIOEffect], gcsafe
.} flushImpl*: proc (s: Stream) {.
nimcall, tags: [WriteIOEffect], gcsafe
.}
Stream interface that supports writing or reading. Note that these fields here shouldn't be used directly. They are accessible so that a stream implementation can override them.   Source Edit
StringStream = ref StringStreamObj
a stream that encapsulates a string   Source Edit
StringStreamObj = object of StreamObj
  data*: string
  pos: int
  Source Edit
FileStream = ref FileStreamObj
a stream that encapsulates a File   Source Edit
FileStreamObj = object of Stream
  f: File
  Source Edit

Procs

proc flush(s: Stream) {.
raises: [Exception], tags: [WriteIOEffect]
.}
flushes the buffers that the stream s might use.   Source Edit
proc close(s: Stream) {.
raises: [Exception], tags: []
.}
closes the stream s.   Source Edit
proc close(s, unused: Stream) {.
deprecated, raises: [Exception], tags: []
.}
closes the stream s.   Source Edit
proc atEnd(s: Stream): bool {.
raises: [Exception], tags: []
.}
checks if more data can be read from f. Returns true if all data has been read.   Source Edit
proc atEnd(s, unused: Stream): bool {.
deprecated, raises: [Exception], tags: []
.}
checks if more data can be read from f. Returns true if all data has been read.   Source Edit
proc setPosition(s: Stream; pos: int) {.
raises: [Exception], tags: []
.}
sets the position pos of the stream s.   Source Edit
proc setPosition(s, unused: Stream; pos: int) {.
deprecated, raises: [Exception], tags: []
.}
sets the position pos of the stream s.   Source Edit
proc getPosition(s: Stream): int {.
raises: [Exception], tags: []
.}
retrieves the current position in the stream s.   Source Edit
proc getPosition(s, unused: Stream): int {.
deprecated, raises: [Exception], tags: []
.}
retrieves the current position in the stream s.   Source Edit
proc readData(s: Stream; buffer: pointer; bufLen: int): int {.
raises: [Exception], tags: [ReadIOEffect]
.}
low level proc that reads data into an untyped buffer of bufLen size.   Source Edit
proc readAll(s: Stream): string {.
raises: [Exception], tags: [ReadIOEffect]
.}
Reads all available data.   Source Edit
proc readData(s, unused: Stream; buffer: pointer; bufLen: int): int {.
deprecated, raises: [Exception], tags: [ReadIOEffect]
.}
low level proc that reads data into an untyped buffer of bufLen size.   Source Edit
proc peekData(s: Stream; buffer: pointer; bufLen: int): int {.
raises: [Exception], tags: [ReadIOEffect]
.}
low level proc that reads data into an untyped buffer of bufLen size without moving stream position   Source Edit
proc writeData(s: Stream; buffer: pointer; bufLen: int) {.
raises: [Exception], tags: [WriteIOEffect]
.}
low level proc that writes an untyped buffer of bufLen size to the stream s.   Source Edit
proc writeData(s, unused: Stream; buffer: pointer; bufLen: int) {.
deprecated, raises: [Exception], tags: [WriteIOEffect]
.}
low level proc that writes an untyped buffer of bufLen size to the stream s.   Source Edit
proc write[T](s: Stream; x: T)
generic write procedure. Writes x to the stream s. Implementation:
s.writeData(s, addr(x), sizeof(x))
  Source Edit
proc write(s: Stream; x: string) {.
raises: [Exception], tags: [WriteIOEffect]
.}
writes the string x to the the stream s. No length field or terminating zero is written.   Source Edit
proc writeLn(s: Stream; args: varargs[string, `$`]) {.
deprecated, raises: [Exception], tags: [WriteIOEffect]
.}
Deprecated since version 0.11.4: Use writeLine instead.   Source Edit
proc writeLine(s: Stream; args: varargs[string, `$`]) {.
raises: [Exception], tags: [WriteIOEffect]
.}
writes one or more strings to the the stream s followed by a new line. No length field or terminating zero is written.   Source Edit
proc readChar(s: Stream): char {.
raises: [Exception], tags: [ReadIOEffect]
.}
reads a char from the stream s. Raises EIO if an error occurred. Returns '0' as an EOF marker.   Source Edit
proc peekChar(s: Stream): char {.
raises: [Exception], tags: [ReadIOEffect]
.}
peeks a char from the stream s. Raises EIO if an error occurred. Returns '0' as an EOF marker.   Source Edit
proc readBool(s: Stream): bool {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads a bool from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekBool(s: Stream): bool {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks a bool from the stream s. Raises EIO if an error occurred.   Source Edit
proc readInt8(s: Stream): int8 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads an int8 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekInt8(s: Stream): int8 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks an int8 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readInt16(s: Stream): int16 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads an int16 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekInt16(s: Stream): int16 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks an int16 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readInt32(s: Stream): int32 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads an int32 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekInt32(s: Stream): int32 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks an int32 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readInt64(s: Stream): int64 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads an int64 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekInt64(s: Stream): int64 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks an int64 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readFloat32(s: Stream): float32 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads a float32 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekFloat32(s: Stream): float32 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks a float32 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readFloat64(s: Stream): float64 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
reads a float64 from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekFloat64(s: Stream): float64 {.
raises: [Exception, IOError], tags: [ReadIOEffect]
.}
peeks a float64 from the stream s. Raises EIO if an error occurred.   Source Edit
proc readStr(s: Stream; length: int): TaintedString {.
raises: [Exception], tags: [ReadIOEffect]
.}
reads a string of length length from the stream s. Raises EIO if an error occurred.   Source Edit
proc peekStr(s: Stream; length: int): TaintedString {.
raises: [Exception], tags: [ReadIOEffect]
.}
peeks a string of length length from the stream s. Raises EIO if an error occurred.   Source Edit
proc readLine(s: Stream; line: var TaintedString): bool {.
raises: [Exception], tags: [ReadIOEffect]
.}
reads a line of text from the stream s into line. line must not be nil! May throw an IO exception. A line of text may be delimited by CR, LF or CRLF. The newline character(s) are not part of the returned string. Returns false if the end of the file has been reached, true otherwise. If false is returned line contains no new data.   Source Edit
proc peekLine(s: Stream; line: var TaintedString): bool {.
raises: [Exception, Exception], tags: [ReadIOEffect]
.}
peeks a line of text from the stream s into line. line must not be nil! May throw an IO exception. A line of text may be delimited by CR, LF or CRLF. The newline character(s) are not part of the returned string. Returns false if the end of the file has been reached, true otherwise. If false is returned line contains no new data.   Source Edit
proc readLine(s: Stream): TaintedString {.
raises: [Exception], tags: [ReadIOEffect]
.}
Reads a line from a stream s. Note: This is not very efficient. Raises EIO if an error occurred.   Source Edit
proc peekLine(s: Stream): TaintedString {.
raises: [Exception, Exception], tags: [ReadIOEffect]
.}
Peeks a line from a stream s. Note: This is not very efficient. Raises EIO if an error occurred.   Source Edit
proc newStringStream(s: string = ""): StringStream {.
raises: [], tags: []
.}
creates a new stream from the string s.   Source Edit
proc newFileStream(f: File): FileStream {.
raises: [], tags: []
.}
creates a new stream from the file f.   Source Edit
proc newFileStream(filename: string; mode: FileMode = fmRead): FileStream {.
raises: [], tags: []
.}
creates a new stream from the file named filename with the mode mode. If the file cannot be opened, nil is returned. See the system module for a list of available FileMode enums.   Source Edit