# Module streams

This module provides a stream interface and two implementations thereof: the PFileStream and the PStringStream which implement the stream interface for Nimrod file objects (TFile) and strings. Other modules may provide other implementations for this standard stream interface.

# Types

    PStream = ref TStream

    TStream = object of TObject
      closeImpl*: proc (s: PStream) {.nimcall, tags: [].}
      atEndImpl*: proc (s: PStream): bool {.nimcall, tags: [].}
      setPositionImpl*: proc (s: PStream; pos: int) {.nimcall, tags: [].}
      getPositionImpl*: proc (s: PStream): int {.nimcall, tags: [].}
      readDataImpl*: proc (s: PStream; buffer: pointer; bufLen: int): int {.nimcall,
          tags: [FReadIO].}
      writeDataImpl*: proc (s: PStream; buffer: pointer; bufLen: int) {.nimcall,
          tags: [FWriteIO].}
      flushImpl*: proc (s: PStream) {.nimcall, tags: [FWriteIO].}

  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.

    PStringStream = ref TStringStream

  a stream that encapsulates a string

    TStringStream = object of TStream
      data*: string
      pos: int

    PFileStream = ref TFileStream

  a stream that encapsulates a TFile

    TFileStream = object of TStream
      f: TFile

# Procs

    proc flush(s: PStream) {.raises: [E_Base], tags: [FWriteIO].}

  flushes the buffers that the stream s might use.

    proc close(s: PStream) {.raises: [E_Base], tags: [].}

  closes the stream s.

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

  closes the stream s.

    proc atEnd(s: PStream): bool {.raises: [E_Base], tags: [].}

  checks if more data can be read from f. Returns true if all data has been read.

    proc atEnd(s, unused: PStream): bool {.deprecated, raises: [E_Base], tags: [].}

  checks if more data can be read from f. Returns true if all data has been read.

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

  sets the position pos of the stream s.

    proc setPosition(s, unused: PStream; pos: int) {.deprecated, raises: [E_Base],
        tags: [].}

  sets the position pos of the stream s.

    proc getPosition(s: PStream): int {.raises: [E_Base], tags: [].}

  retrieves the current position in the stream s.

    proc getPosition(s, unused: PStream): int {.deprecated, raises: [E_Base],
        tags: [].}

  retrieves the current position in the stream s.

    proc readData(s: PStream; buffer: pointer; bufLen: int): int {.raises: [E_Base],
        tags: [FReadIO].}

  low level proc that reads data into an untyped buffer of bufLen size.

    proc readData(s, unused: PStream; buffer: pointer; bufLen: int): int {.
        deprecated, raises: [E_Base], tags: [FReadIO].}

  low level proc that reads data into an untyped buffer of bufLen size.

    proc writeData(s: PStream; buffer: pointer; bufLen: int) {.raises: [E_Base],
        tags: [FWriteIO].}

  low level proc that writes an untyped buffer of bufLen size to the stream s.

    proc writeData(s, unused: PStream; buffer: pointer; bufLen: int) {.deprecated,
        raises: [E_Base], tags: [FWriteIO].}

  low level proc that writes an untyped buffer of bufLen size to the stream s.

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

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

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

    proc write(s: PStream; x: string) {.raises: [E_Base], tags: [FWriteIO].}

  writes the string x to the the stream s. No length field or terminating zero is written.

    proc writeln(s: PStream; args: varargs[string, `$`]) {.raises: [E_Base],
        tags: [FWriteIO].}

  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: PStream): char {.raises: [E_Base], tags: [FReadIO].}

  reads a char from the stream s. Raises EIO if an error occured. Returns '0' as an EOF marker.

    proc readBool(s: PStream): bool {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readInt8(s: PStream): int8 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readInt16(s: PStream): int16 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readInt32(s: PStream): int32 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readInt64(s: PStream): int64 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readFloat32(s: PStream): float32 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readFloat64(s: PStream): float64 {.raises: [E_Base, EIO], tags: [FReadIO].}

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

    proc readStr(s: PStream; length: int): TaintedString {.raises: [E_Base],
        tags: [FReadIO].}

  reads a string of length length from the stream s. Raises EIO if an error occured.

    proc readLine(s: PStream; line: var TaintedString): bool {.raises: [E_Base],
        tags: [FReadIO].}

  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.

    proc readLine(s: PStream): TaintedString {.raises: [E_Base], tags: [FReadIO].}

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

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

  creates a new stream from the string s.

    proc newFileStream(f: TFile): PFileStream {.raises: [], tags: [].}

  creates a new stream from the file f.

    proc newFileStream(filename: string; mode: TFileMode): PFileStream {.
        raises: [EOutOfMemory], 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 TFileMode enums.

Generated: 2013-05-21 09:55:11 UTC