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

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.

StringStream = ref StringStreamObj

a stream that encapsulates a string

StringStreamObj = object of StreamObj
  data*: string
  pos: int

FileStream = ref FileStreamObj

a stream that encapsulates a File

FileStreamObj = object of Stream
  f: File

Procs

proc flush(s: Stream) {...}{.raises: [Exception], tags: [WriteIOEffect].}

flushes the buffers that the stream s might use.

proc close(s: Stream) {...}{.raises: [Exception], tags: [].}

closes the stream s.

proc close(s, unused: Stream) {...}{.deprecated, raises: [Exception], tags: [].}

closes the stream s.

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.

proc setPosition(s: Stream; pos: int) {...}{.raises: [Exception], tags: [].}

sets the position pos of the stream s.

proc getPosition(s: Stream): int {...}{.raises: [Exception], tags: [].}

retrieves the current position in the stream s.

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.

proc readAll(s: Stream): string {...}{.raises: [Exception], tags: [ReadIOEffect].}

Reads all available data.

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

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.

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.

proc write[T](s: Stream; x: T)

generic write procedure. Writes x to the stream s. Implementation:

s.writeData(s, addr(x), sizeof(x))

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.

proc write(s: Stream; args: varargs[string, `$`]) {...}{.raises: [Exception],
    tags: [WriteIOEffect].}

writes one or more strings to the the stream. No length fields or terminating zeros are written.

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.

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.

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.

proc readBool(s: Stream): bool {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads a bool from the stream s. Raises EIO if an error occurred.

proc peekBool(s: Stream): bool {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks a bool from the stream s. Raises EIO if an error occurred.

proc readInt8(s: Stream): int8 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an int8 from the stream s. Raises EIO if an error occurred.

proc peekInt8(s: Stream): int8 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an int8 from the stream s. Raises EIO if an error occurred.

proc readInt16(s: Stream): int16 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an int16 from the stream s. Raises EIO if an error occurred.

proc peekInt16(s: Stream): int16 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an int16 from the stream s. Raises EIO if an error occurred.

proc readInt32(s: Stream): int32 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an int32 from the stream s. Raises EIO if an error occurred.

proc peekInt32(s: Stream): int32 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an int32 from the stream s. Raises EIO if an error occurred.

proc readInt64(s: Stream): int64 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an int64 from the stream s. Raises EIO if an error occurred.

proc peekInt64(s: Stream): int64 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an int64 from the stream s. Raises EIO if an error occurred.

proc readUint8(s: Stream): uint8 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an uint8 from the stream s. Raises EIO if an error occurred.

proc peekUint8(s: Stream): uint8 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an uint8 from the stream s. Raises EIO if an error occurred.

proc readUint16(s: Stream): uint16 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an uint16 from the stream s. Raises EIO if an error occurred.

proc peekUint16(s: Stream): uint16 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an uint16 from the stream s. Raises EIO if an error occurred.

proc readUint32(s: Stream): uint32 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an uint32 from the stream s. Raises EIO if an error occurred.

proc peekUint32(s: Stream): uint32 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an uint32 from the stream s. Raises EIO if an error occurred.

proc readUint64(s: Stream): uint64 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

reads an uint64 from the stream s. Raises EIO if an error occurred.

proc peekUint64(s: Stream): uint64 {...}{.raises: [Exception, IOError], tags: [ReadIOEffect].}

peeks an uint64 from the stream s. Raises EIO if an error occurred.

proc readFloat32(s: Stream): float32 {...}{.raises: [Exception, IOError],
                                   tags: [ReadIOEffect].}

reads a float32 from the stream s. Raises EIO if an error occurred.

proc peekFloat32(s: Stream): float32 {...}{.raises: [Exception, IOError],
                                   tags: [ReadIOEffect].}

peeks a float32 from the stream s. Raises EIO if an error occurred.

proc readFloat64(s: Stream): float64 {...}{.raises: [Exception, IOError],
                                   tags: [ReadIOEffect].}

reads a float64 from the stream s. Raises EIO if an error occurred.

proc peekFloat64(s: Stream): float64 {...}{.raises: [Exception, IOError],
                                   tags: [ReadIOEffect].}

peeks a float64 from the stream s. Raises EIO if an error occurred.

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.

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.

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

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.

proc readLine(s: Stream): TaintedString {...}{.raises: [Exception, IOError],
                                      tags: [ReadIOEffect].}

Reads a line from a stream s. Note: This is not very efficient. Raises EIO if an error occurred.

proc peekLine(s: Stream): TaintedString {...}{.raises: [Exception, Exception, IOError],
                                      tags: [ReadIOEffect].}

Peeks a line from a stream s. Note: This is not very efficient. Raises EIO if an error occurred.

proc newStringStream(s: string = ""): StringStream {...}{.raises: [], tags: [].}

creates a new stream from the string s.

proc newFileStream(f: File): FileStream {...}{.raises: [], tags: [].}

creates a new stream from the file f.

proc newFileStream(filename: string; mode: FileMode = fmRead; bufSize: int = -1): 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. This function returns nil in case of failure. To prevent unexpected behavior and ensure proper error handling, use openFileStream instead.

proc openFileStream(filename: string; mode: FileMode = fmRead; bufSize: int = -1): FileStream {...}{.
    raises: [IOError], tags: [].}

creates a new stream from the file named filename with the mode mode. If the file cannot be opened, an IO exception is raised.

Iterators

iterator lines(s: Stream): TaintedString {...}{.raises: [Exception], tags: [ReadIOEffect].}

Iterates over every line in the stream. The iteration is based on readLine.