# streams

- Manual
- Standard library
- Index

Search:
Group by:

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.

# Basic usage

The basic flow of using this module is:

1. Open input stream
2. Read or write stream
3. Close stream

## StringStream example

    import streams

    var strm = newStringStream("""The first line
    the second line
    the third line""")

    var line = ""

    while strm.readLine(line):
      echo line

    # Output:
    # The first line
    # the second line
    # the third line

    strm.close()

## FileStream example

Write file stream example:

    import streams

    var strm = newFileStream("somefile.txt", fmWrite)
    var line = ""

    if not isNil(strm):
      strm.writeLine("The first line")
      strm.writeLine("the second line")
      strm.writeLine("the third line")
      strm.close()

    # Output (somefile.txt):
    # The first line
    # the second line
    # the third line

Read file stream example:

    import streams

    var strm = newFileStream("somefile.txt", fmRead)
    var line = ""

    if not isNil(strm):
      while strm.readLine(line):
        echo line
      strm.close()

    # Output:
    # The first line
    # the second line
    # the third line

# See also

- asyncstreams module
- io module for FileMode enum

# Types

    Stream = ref StreamObj

  All procedures of this module use this type. Procedures don't directly use StreamObj. Source Edit

    StreamObj = object of RootObj
      closeImpl*: proc (s: Stream) {...}{.nimcall, raises: [Exception, IOError, OSError],
                                 tags: [WriteIOEffect], gcsafe.}
      atEndImpl*: proc (s: Stream): bool {...}{.nimcall, raises: [Defect, IOError, OSError],
                                      tags: [], gcsafe.}
      setPositionImpl*: proc (s: Stream; pos: int) {...}{.nimcall,
          raises: [Defect, IOError, OSError], tags: [], gcsafe.}
      getPositionImpl*: proc (s: Stream): int {...}{.nimcall,
                                           raises: [Defect, IOError, OSError], tags: [],
                                           gcsafe.}
      readDataStrImpl*: proc (s: Stream; buffer: var string; slice: Slice[int]): int {...}{.
          nimcall, raises: [Defect, IOError, OSError], tags: [ReadIOEffect], gcsafe.}
      readLineImpl*: proc (s: Stream; line: var TaintedString): bool {...}{.nimcall,
          raises: [Defect, IOError, OSError], tags: [ReadIOEffect], gcsafe.}
      readDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int): int {...}{.nimcall,
          raises: [Defect, IOError, OSError], tags: [ReadIOEffect], gcsafe.}
      peekDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int): int {...}{.nimcall,
          raises: [Defect, IOError, OSError], tags: [ReadIOEffect], gcsafe.}
      writeDataImpl*: proc (s: Stream; buffer: pointer; bufLen: int) {...}{.nimcall,
          raises: [Defect, IOError, OSError], tags: [WriteIOEffect], gcsafe.}
      flushImpl*: proc (s: Stream) {...}{.nimcall, raises: [Defect, IOError, OSError],
                                 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.

  Note: Not available for JS backend.

  Source Edit

    StringStreamObj = object of StreamObj
      data*: string                ## A string data.
                  ## This is updated when called `writeLine` etc.
      pos: int

  A string stream object.

  Note: Not available for JS backend.

  Source Edit

    FileStream = ref FileStreamObj

  A stream that encapsulates a `File`.

  Note: Not available for JS backend.

  Source Edit

    FileStreamObj = object of Stream
      f: File

  A file stream object.

  Note: Not available for JS backend.

  Source Edit

# Procs

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

  Flushes the buffers that the stream `s` might use.

  This procedure causes any unwritten data for that stream to be delivered to the host environment to be written to the file.

  See also:

  - close proc

  Examples:

      from os import removeFile

      var strm = newFileStream("somefile.txt", fmWrite)
      doAssert "Before write:" & readFile("somefile.txt") == "Before write:"
      strm.write("hello")
      doAssert "After  write:" & readFile("somefile.txt") == "After  write:"
      strm.flush()
      doAssert "After  flush:" & readFile("somefile.txt") == "After  flush:hello"
      strm.write("HELLO")
      strm.flush()
      doAssert "After  flush:" & readFile("somefile.txt") == "After  flush:helloHELLO"
      strm.close()
      doAssert "After  close:" & readFile("somefile.txt") == "After  close:helloHELLO"
      removeFile("somefile.txt")

  Source Edit

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

  Closes the stream `s`.

  See also:

  - flush proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      ## do something...
      strm.close()

  Source Edit

    proc atEnd(s: Stream): bool {...}{.raises: [Defect, IOError, OSError], tags: [].}

  Checks if more data can be read from `s`. Returns `true` if all data has been read.

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      var line = ""
      doAssert strm.atEnd() == false
      while strm.readLine(line):
        discard
      doAssert strm.atEnd() == true
      strm.close()

  Source Edit

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

  Sets the position `pos` of the stream `s`.

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      strm.setPosition(4)
      doAssert strm.readLine() == "first line"
      strm.setPosition(0)
      doAssert strm.readLine() == "The first line"
      strm.close()

  Source Edit

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

  Retrieves the current position in the stream `s`.

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      doAssert strm.getPosition() == 0
      discard strm.readLine()
      doAssert strm.getPosition() == 15
      strm.close()

  Source Edit

    proc readData(s: Stream; buffer: pointer; bufLen: int): int {...}{.
        raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}

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

  Examples:

      var strm = newStringStream("abcde")
      var buffer: array[6, char]
      doAssert strm.readData(addr(buffer), 1024) == 5
      doAssert buffer == ['a', 'b', 'c', 'd', 'e', '\x00']
      doAssert strm.atEnd() == true
      strm.close()

  Source Edit

    proc readDataStr(s: Stream; buffer: var string; slice: Slice[int]): int {...}{.
        raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}

  Low level proc that reads data into a string `buffer` at `slice`.

  Examples:

      var strm = newStringStream("abcde")
      var buffer = "12345"
      doAssert strm.readDataStr(buffer, 0 .. 3) == 4
      doAssert buffer == "abcd5"
      strm.close()

  Source Edit

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

  Reads all available data.

  Note: Not available for JS backend.

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      doAssert strm.readAll() == "The first line\nthe second line\nthe third line"
      doAssert strm.atEnd() == true
      strm.close()

  Source Edit

    proc peekData(s: Stream; buffer: pointer; bufLen: int): int {...}{.
        raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}

  Low level proc that reads data into an untyped `buffer` of `bufLen` size without moving stream position.

  Examples:

      var strm = newStringStream("abcde")
      var buffer: array[6, char]
      doAssert strm.peekData(addr(buffer), 1024) == 5
      doAssert buffer == ['a', 'b', 'c', 'd', 'e', '\x00']
      doAssert strm.atEnd() == false
      strm.close()

  Source Edit

    proc writeData(s: Stream; buffer: pointer; bufLen: int) {...}{.
        raises: [Defect, IOError, OSError], tags: [WriteIOEffect].}

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

  Examples:

      ## writeData
      var strm = newStringStream("")
      var buffer = ['a', 'b', 'c', 'd', 'e']
      strm.writeData(addr(buffer), sizeof(buffer))
      doAssert strm.atEnd() == true
      ## readData
      strm.setPosition(0)
      var buffer2: array[6, char]
      doAssert strm.readData(addr(buffer2), sizeof(buffer2)) == 5
      doAssert buffer2 == ['a', 'b', 'c', 'd', 'e', '\x00']
      strm.close()

  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))

  Examples:

      var strm = newStringStream("")
      strm.write("abcde")
      strm.setPosition(0)
      doAssert strm.readAll() == "abcde"
      strm.close()

  Source Edit

    proc write(s: Stream; x: string) {...}{.raises: [Defect, IOError, OSError],
                                  tags: [WriteIOEffect].}

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

  Examples:

      var strm = newStringStream("")
      strm.write("THE FIRST LINE")
      strm.setPosition(0)
      doAssert strm.readLine() == "THE FIRST LINE"
      strm.close()

  Source Edit

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

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

  Examples:

      var strm = newStringStream("")
      strm.write(1, 2, 3, 4)
      strm.setPosition(0)
      doAssert strm.readLine() == "1234"
      strm.close()

  Source Edit

    proc writeLine(s: Stream; args: varargs[string, `$`]) {...}{.
        raises: [Defect, IOError, OSError], 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.

  Examples:

      var strm = newStringStream("")
      strm.writeLine(1, 2)
      strm.writeLine(3, 4)
      strm.setPosition(0)
      doAssert strm.readAll() == "12\n34\n"
      strm.close()

  Source Edit

    proc read[T](s: Stream; result: var T)

  Generic read procedure. Reads `result` from the stream `s`.

  Examples:

      var strm = newStringStream("012")
      ## readInt
      var i: int8
      strm.read(i)
      doAssert i == 48
      ## readData
      var buffer: array[2, char]
      strm.read(buffer)
      doAssert buffer == ['1', '2']
      strm.close()

  Source Edit

    proc peek[T](s: Stream; result: var T)

  Generic peek procedure. Peeks `result` from the stream `s`.

  Examples:

      var strm = newStringStream("012")
      ## peekInt
      var i: int8
      strm.peek(i)
      doAssert i == 48
      ## peekData
      var buffer: array[2, char]
      strm.peek(buffer)
      doAssert buffer == ['0', '1']
      strm.close()

  Source Edit

    proc readChar(s: Stream): char {...}{.raises: [Defect, IOError, OSError],
                                 tags: [ReadIOEffect].}

  Reads a char from the stream `s`.

  Raises `IOError` if an error occurred. Returns '\0' as an EOF marker.

  Examples:

      var strm = newStringStream("12\n3")
      doAssert strm.readChar() == '1'
      doAssert strm.readChar() == '2'
      doAssert strm.readChar() == '\n'
      doAssert strm.readChar() == '3'
      doAssert strm.readChar() == '\x00'
      strm.close()

  Source Edit

    proc peekChar(s: Stream): char {...}{.raises: [Defect, IOError, OSError],
                                 tags: [ReadIOEffect].}

  Peeks a char from the stream `s`. Raises `IOError` if an error occurred. Returns '\0' as an EOF marker.

  Examples:

      var strm = newStringStream("12\n3")
      doAssert strm.peekChar() == '1'
      doAssert strm.peekChar() == '1'
      discard strm.readAll()
      doAssert strm.peekChar() == '\x00'
      strm.close()

  Source Edit

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

  Reads a bool from the stream `s`.

  A bool is one byte long and it is `true` for every non-zero (`0000_0000`) value. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(true)
      strm.write(false)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readBool() == true
      doAssert strm.readBool() == false
      doAssertRaises(IOError):
        discard strm.readBool()
      strm.close()

  Source Edit

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

  Peeks a bool from the stream `s`.

  A bool is one byte long and it is `true` for every non-zero (`0000_0000`) value. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(true)
      strm.write(false)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekBool() == true
      ## not false
      doAssert strm.peekBool() == true
      doAssert strm.readBool() == true
      doAssert strm.peekBool() == false
      strm.close()

  Source Edit

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

  Reads an int8 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i8)
      strm.write(2'i8)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readInt8() == 1'i8
      doAssert strm.readInt8() == 2'i8
      doAssertRaises(IOError):
        discard strm.readInt8()
      strm.close()

  Source Edit

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

  Peeks an int8 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i8)
      strm.write(2'i8)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekInt8() == 1'i8
      ## not 2'i8
      doAssert strm.peekInt8() == 1'i8
      doAssert strm.readInt8() == 1'i8
      doAssert strm.peekInt8() == 2'i8
      strm.close()

  Source Edit

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

  Reads an int16 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i16)
      strm.write(2'i16)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readInt16() == 1'i16
      doAssert strm.readInt16() == 2'i16
      doAssertRaises(IOError):
        discard strm.readInt16()
      strm.close()

  Source Edit

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

  Peeks an int16 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i16)
      strm.write(2'i16)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekInt16() == 1'i16
      ## not 2'i16
      doAssert strm.peekInt16() == 1'i16
      doAssert strm.readInt16() == 1'i16
      doAssert strm.peekInt16() == 2'i16
      strm.close()

  Source Edit

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

  Reads an int32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i32)
      strm.write(2'i32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readInt32() == 1'i32
      doAssert strm.readInt32() == 2'i32
      doAssertRaises(IOError):
        discard strm.readInt32()
      strm.close()

  Source Edit

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

  Peeks an int32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i32)
      strm.write(2'i32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekInt32() == 1'i32
      ## not 2'i32
      doAssert strm.peekInt32() == 1'i32
      doAssert strm.readInt32() == 1'i32
      doAssert strm.peekInt32() == 2'i32
      strm.close()

  Source Edit

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

  Reads an int64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i64)
      strm.write(2'i64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readInt64() == 1'i64
      doAssert strm.readInt64() == 2'i64
      doAssertRaises(IOError):
        discard strm.readInt64()
      strm.close()

  Source Edit

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

  Peeks an int64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'i64)
      strm.write(2'i64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekInt64() == 1'i64
      ## not 2'i64
      doAssert strm.peekInt64() == 1'i64
      doAssert strm.readInt64() == 1'i64
      doAssert strm.peekInt64() == 2'i64
      strm.close()

  Source Edit

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

  Reads an uint8 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u8)
      strm.write(2'u8)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readUint8() == 1'u8
      doAssert strm.readUint8() == 2'u8
      doAssertRaises(IOError):
        discard strm.readUint8()
      strm.close()

  Source Edit

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

  Peeks an uint8 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u8)
      strm.write(2'u8)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekUint8() == 1'u8
      ## not 2'u8
      doAssert strm.peekUint8() == 1'u8
      doAssert strm.readUint8() == 1'u8
      doAssert strm.peekUint8() == 2'u8
      strm.close()

  Source Edit

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

  Reads an uint16 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u16)
      strm.write(2'u16)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readUint16() == 1'u16
      doAssert strm.readUint16() == 2'u16
      doAssertRaises(IOError):
        discard strm.readUint16()
      strm.close()

  Source Edit

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

  Peeks an uint16 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u16)
      strm.write(2'u16)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekUint16() == 1'u16
      ## not 2'u16
      doAssert strm.peekUint16() == 1'u16
      doAssert strm.readUint16() == 1'u16
      doAssert strm.peekUint16() == 2'u16
      strm.close()

  Source Edit

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

  Reads an uint32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u32)
      strm.write(2'u32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readUint32() == 1'u32
      doAssert strm.readUint32() == 2'u32
      doAssertRaises(IOError):
        discard strm.readUint32()
      strm.close()

  Source Edit

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

  Peeks an uint32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u32)
      strm.write(2'u32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekUint32() == 1'u32
      ## not 2'u32
      doAssert strm.peekUint32() == 1'u32
      doAssert strm.readUint32() == 1'u32
      doAssert strm.peekUint32() == 2'u32
      strm.close()

  Source Edit

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

  Reads an uint64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u64)
      strm.write(2'u64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readUint64() == 1'u64
      doAssert strm.readUint64() == 2'u64
      doAssertRaises(IOError):
        discard strm.readUint64()
      strm.close()

  Source Edit

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

  Peeks an uint64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1'u64)
      strm.write(2'u64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekUint64() == 1'u64
      ## not 2'u64
      doAssert strm.peekUint64() == 1'u64
      doAssert strm.readUint64() == 1'u64
      doAssert strm.peekUint64() == 2'u64
      strm.close()

  Source Edit

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

  Reads a float32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1.0'f32)
      strm.write(2.0'f32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readFloat32() == 1.0'f32
      doAssert strm.readFloat32() == 2.0'f32
      doAssertRaises(IOError):
        discard strm.readFloat32()
      strm.close()

  Source Edit

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

  Peeks a float32 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1.0'f32)
      strm.write(2.0'f32)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekFloat32() == 1.0'f32
      ## not 2'f32
      doAssert strm.peekFloat32() == 1.0'f32
      doAssert strm.readFloat32() == 1.0'f32
      doAssert strm.peekFloat32() == 2.0'f32
      strm.close()

  Source Edit

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

  Reads a float64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1.0'f64)
      strm.write(2.0'f64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.readFloat64() == 1.0'f64
      doAssert strm.readFloat64() == 2.0'f64
      doAssertRaises(IOError):
        discard strm.readFloat64()
      strm.close()

  Source Edit

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

  Peeks a float64 from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream()
      ## setup for reading data
      strm.write(1.0'f64)
      strm.write(2.0'f64)
      strm.flush()
      strm.setPosition(0)
      ## get data
      doAssert strm.peekFloat64() == 1.0'f64
      ## not 2'f64
      doAssert strm.peekFloat64() == 1.0'f64
      doAssert strm.readFloat64() == 1.0'f64
      doAssert strm.peekFloat64() == 2.0'f64
      strm.close()

  Source Edit

    proc readStr(s: Stream; length: int): TaintedString {...}{.
        raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}

  Reads a string of length `length` from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream("abcde")
      doAssert strm.readStr(2) == "ab"
      doAssert strm.readStr(2) == "cd"
      doAssert strm.readStr(2) == "e"
      doAssert strm.readStr(2) == ""
      strm.close()

  Source Edit

    proc peekStr(s: Stream; length: int): TaintedString {...}{.
        raises: [Defect, IOError, OSError], tags: [ReadIOEffect].}

  Peeks a string of length `length` from the stream `s`. Raises `IOError` if an error occurred.

  Examples:

      var strm = newStringStream("abcde")
      doAssert strm.peekStr(2) == "ab"
      ## not "cd
      doAssert strm.peekStr(2) == "ab"
      doAssert strm.readStr(2) == "ab"
      doAssert strm.peekStr(2) == "cd"
      strm.close()

  Source Edit

    proc readLine(s: Stream; line: var TaintedString): bool {...}{.
        raises: [Defect, IOError, OSError], 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.

  See also:

  - readLine(Stream) proc
  - peekLine(Stream) proc
  - peekLine(Stream, TaintedString) proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      var line = ""
      doAssert strm.readLine(line) == true
      doAssert line == "The first line"
      doAssert strm.readLine(line) == true
      doAssert line == "the second line"
      doAssert strm.readLine(line) == true
      doAssert line == "the third line"
      doAssert strm.readLine(line) == false
      doAssert line == ""
      strm.close()

  Source Edit

    proc peekLine(s: Stream; line: var TaintedString): bool {...}{.
        raises: [Defect, IOError, OSError], 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.

  See also:

  - readLine(Stream) proc
  - readLine(Stream, TaintedString) proc
  - peekLine(Stream) proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      var line = ""
      doAssert strm.peekLine(line) == true
      doAssert line == "The first line"
      doAssert strm.peekLine(line) == true
      ## not "the second line"
      doAssert line == "The first line"
      doAssert strm.readLine(line) == true
      doAssert line == "The first line"
      doAssert strm.peekLine(line) == true
      doAssert line == "the second line"
      strm.close()

  Source Edit

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

  Reads a line from a stream `s`. Raises `IOError` if an error occurred.

  Note: This is not very efficient.

  See also:

  - readLine(Stream, TaintedString) proc
  - peekLine(Stream) proc
  - peekLine(Stream, TaintedString) proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      doAssert strm.readLine() == "The first line"
      doAssert strm.readLine() == "the second line"
      doAssert strm.readLine() == "the third line"
      doAssertRaises(IOError):
        discard strm.readLine()
      strm.close()

  Source Edit

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

  Peeks a line from a stream `s`. Raises `IOError` if an error occurred.

  Note: This is not very efficient.

  See also:

  - readLine(Stream) proc
  - readLine(Stream, TaintedString) proc
  - peekLine(Stream, TaintedString) proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      doAssert strm.peekLine() == "The first line"
      ## not "the second line"
      doAssert strm.peekLine() == "The first line"
      doAssert strm.readLine() == "The first line"
      doAssert strm.peekLine() == "the second line"
      strm.close()

  Source Edit

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

  Creates a new stream from the string `s`.

  Note: Not available for JS backend.

  See also:

  - newFileStream proc creates a file stream from opened File.
  - newFileStream proc creates a file stream from the file name and the mode.
  - openFileStream proc creates a file stream from the file name and the mode.

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      doAssert strm.readLine() == "The first line"
      doAssert strm.readLine() == "the second line"
      doAssert strm.readLine() == "the third line"
      strm.close()

  Source Edit

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

  Creates a new stream from the file `f`.

  Note: Not available for JS backend.

  See also:

  - newStringStream proc creates a new stream from string.
  - newFileStream proc is the same as using open proc on Examples.
  - openFileStream proc creates a file stream from the file name and the mode.

  Examples:

      ## Input (somefile.txt):
      ## The first line
      ## the second line
      ## the third line
      var f: File
      if open(f, "somefile.txt", fmRead, -1):
        var strm = newFileStream(f)
        var line = ""
        while strm.readLine(line):
          echo line
        ## Output:
        ## The first line
        ## the second line
        ## the third line
        strm.close()

  Source Edit

    proc newFileStream(filename: string; mode: FileMode = fmRead; bufSize: int = -1): owned
        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 io module for a list of available FileMode enums.

  Note:

  - This function returns nil in case of failure. To prevent unexpected behavior and ensure proper error handling, use openFileStream proc instead.
  - Not available for JS backend.

  See also:

  - newStringStream proc creates a new stream from string.
  - newFileStream proc creates a file stream from opened File.
  - openFileStream proc creates a file stream from the file name and the mode.

  Examples:

      from os import removeFile

      var strm = newFileStream("somefile.txt", fmWrite)
      if not isNil(strm):
        strm.writeLine("The first line")
        strm.writeLine("the second line")
        strm.writeLine("the third line")
        strm.close()
        ## Output (somefile.txt)
        ## The first line
        ## the second line
        ## the third line
        removeFile("somefile.txt")

  Source Edit

    proc openFileStream(filename: string; mode: FileMode = fmRead; bufSize: int = -1): owned
        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.

  Note: Not available for JS backend.

  See also:

  - newStringStream proc creates a new stream from string.
  - newFileStream proc creates a file stream from opened File.
  - newFileStream proc creates a file stream from the file name and the mode.

  Examples:

      try:
        ## Input (somefile.txt):
        ## The first line
        ## the second line
        ## the third line
        var strm = openFileStream("somefile.txt")
        echo strm.readLine()
        ## Output:
        ## The first line
        strm.close()
      except:
        stderr.write getCurrentExceptionMsg()

  Source Edit

# Iterators

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

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

  See also:

  - readLine(Stream) proc
  - readLine(Stream, TaintedString) proc

  Examples:

      var strm = newStringStream("The first line\nthe second line\nthe third line")
      var lines: seq[string]
      for line in strm.lines():
        lines.add line
      doAssert lines == @["The first line", "the second line", "the third line"]
      strm.close()

  Source Edit