std/syncio

Search:
Source   Edit  

This module implements various synchronized I/O operations.

Types

File = ptr CFile
The type representing a file handle. Source   Edit  
FileHandle = cint
type that represents an OS file handle; this is useful for low-level file access Source   Edit  
FileMode = enum
  fmRead,                   ## Open the file for read access only.
                             ## If the file does not exist, it will not
                             ## be created.
  fmWrite,                  ## Open the file for write access only.
                             ## If the file does not exist, it will be
                             ## created. Existing files will be cleared!
  fmReadWrite,              ## Open the file for read and write access.
                             ## If the file does not exist, it will be
                             ## created. Existing files will be cleared!
  fmReadWriteExisting,      ## Open the file for read and write access.
                             ## If the file does not exist, it will not be
                             ## created. The existing file will not be cleared.
  fmAppend                   ## Open the file for writing only; append data
                             ## at the end. If the file does not exist, it
                             ## will be created.
The file mode when opening a file. Source   Edit  
FileSeekPos = enum
  fspSet,                   ## Seek to absolute value
  fspCur,                   ## Seek relative to current position
  fspEnd                     ## Seek relative to end
Position relative to which seek should happen. Source   Edit  

Vars

stderr {.importc: "stderr", header: "<stdio.h>".}: File
The standard error stream. Source   Edit  
stdin {.importc: "stdin", header: "<stdio.h>".}: File
The standard input stream. Source   Edit  
stdout {.importc: "stdout", header: "<stdio.h>".}: File
The standard output stream. Source   Edit  

Procs

proc close(f: File) {....tags: [], gcsafe, raises: [], forbids: [].}
Closes the file. Source   Edit  
proc endOfFile(f: File): bool {....tags: [], gcsafe, raises: [], forbids: [].}
Returns true if f is at the end. Source   Edit  
proc flushFile(f: File) {....tags: [WriteIOEffect], raises: [], forbids: [].}
Flushes f's buffer. Source   Edit  
proc getFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}
Returns the file handle of the file f. This is only useful for platform specific programming. Note that on Windows this doesn't return the Windows-specific handle, but the C library's notion of a handle, whatever that means. Use getOsFileHandle instead. Source   Edit  
proc getFilePos(f: File): int64 {....gcsafe, raises: [IOError], tags: [],
                                  forbids: [].}
Retrieves the current position of the file pointer that is used to read from the file f. The file's first byte has the index zero. Source   Edit  
proc getFileSize(f: File): int64 {....tags: [ReadIOEffect], gcsafe,
                                   raises: [IOError], forbids: [].}
Retrieves the file size (in bytes) of f. Source   Edit  
proc getOsFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}
Returns the OS file handle of the file f. This is only useful for platform specific programming. Source   Edit  
proc open(f: var File; filehandle: FileHandle; mode: FileMode = fmRead): bool {.
    ...tags: [], raises: [], gcsafe, forbids: [].}

Creates a File from a filehandle with given mode.

Default mode is readonly. Returns true if the file could be opened.

The passed file handle will no longer be inheritable.

Source   Edit  
proc open(f: var File; filename: string; mode: FileMode = fmRead;
          bufSize: int = -1): bool {....tags: [], raises: [], gcsafe, forbids: [].}

Opens a file named filename with given mode.

Default mode is readonly. Returns true if the file could be opened. This throws no exception if the file could not be opened.

The file handle associated with the resulting File is not inheritable.

Source   Edit  
proc open(filename: string; mode: FileMode = fmRead; bufSize: int = -1): File {.
    ...raises: [IOError], tags: [], forbids: [].}

Opens a file named filename with given mode.

Default mode is readonly. Raises an IOError if the file could not be opened.

The file handle associated with the resulting File is not inheritable.

Source   Edit  
proc readAll(file: File): string {....tags: [ReadIOEffect], gcsafe,
                                   raises: [IOError], forbids: [].}

Reads all data from the stream file.

Raises an IO exception in case of an error. It is an error if the current file position is not at the beginning of the file.

Source   Edit  
proc readBuffer(f: File; buffer: pointer; len: Natural): int {.
    ...tags: [ReadIOEffect], gcsafe, raises: [IOError], forbids: [].}
Reads len bytes into the buffer pointed to by buffer. Returns the actual number of bytes that have been read which may be less than len (if not as many bytes are remaining), but not greater. Source   Edit  
proc readBytes(f: File; a: var openArray[int8 | uint8]; start, len: Natural): int {.
    ...tags: [ReadIOEffect], gcsafe.}
Reads len bytes into the buffer a starting at a[start]. Returns the actual number of bytes that have been read which may be less than len (if not as many bytes are remaining), but not greater. Source   Edit  
proc readChar(f: File): char {....tags: [ReadIOEffect],
                               raises: [IOError, EOFError], forbids: [].}
Reads a single character from the stream f. Should not be used in performance sensitive code. Source   Edit  
proc readChars(f: File; a: var openArray[char]): int {....tags: [ReadIOEffect],
    gcsafe, raises: [IOError], forbids: [].}
Reads up to a.len bytes into the buffer a. Returns the actual number of bytes that have been read which may be less than a.len (if not as many bytes are remaining), but not greater. Source   Edit  
proc readChars(f: File; a: var openArray[char]; start, len: Natural): int {.
    ...tags: [ReadIOEffect], gcsafe, deprecated: "use other `readChars` overload, possibly via: readChars(toOpenArray(buf, start, len-1))",
    raises: [IOError], forbids: [].}
Deprecated: use other `readChars` overload, possibly via: readChars(toOpenArray(buf, start, len-1))
Reads len bytes into the buffer a starting at a[start]. Returns the actual number of bytes that have been read which may be less than len (if not as many bytes are remaining), but not greater. Source   Edit  
proc readFile(filename: string): string {....tags: [ReadIOEffect], gcsafe,
    raises: [IOError], forbids: [].}
Opens a file named filename for reading, calls readAll and closes the file afterwards. Returns the string. Raises an IO exception in case of an error. If you need to call this inside a compile time macro you can use staticRead. Source   Edit  
proc readLine(f: File): string {....tags: [ReadIOEffect], gcsafe,
                                 raises: [IOError, EOFError], forbids: [].}
Reads a line of text from the file f. 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. Source   Edit  
proc readLine(f: File; line: var string): bool {....tags: [ReadIOEffect], gcsafe,
    raises: [IOError], forbids: [].}
Reads a line of text from the file f into line. 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. Source   Edit  
proc readLines(filename: string; n: Natural): seq[string] {.
    ...raises: [IOError, EOFError], tags: [ReadIOEffect], forbids: [].}
Reads n lines from the file named filename. Raises an IO exception in case of an error. Raises EOF if file does not contain at least n lines. Available at compile time. A line of text may be delimited by LF or CRLF. The newline character(s) are not part of the returned strings. Source   Edit  
proc reopen(f: File; filename: string; mode: FileMode = fmRead): bool {.
    ...tags: [], gcsafe, raises: [], forbids: [].}

Reopens the file f with given filename and mode. This is often used to redirect the stdin, stdout or stderr file variables.

Default mode is readonly. Returns true if the file could be reopened.

The file handle associated with f won't be inheritable.

Source   Edit  
proc setFilePos(f: File; pos: int64; relativeTo: FileSeekPos = fspSet) {....gcsafe,
    raises: [IOError], tags: [], forbids: [].}
Sets the position of the file pointer that is used for read/write operations. The file's first byte has the index zero. Source   Edit  
proc setInheritable(f: FileHandle; inheritable: bool): bool {....raises: [],
    tags: [], forbids: [].}

control whether a file handle can be inherited by child processes. Returns true on success. This requires the OS file handle, which can be retrieved via getOsFileHandle.

This procedure is not guaranteed to be available for all platforms. Test for availability with declared() <system.html#declared,untyped>.

Source   Edit  
proc setStdIoUnbuffered() {....tags: [], gcsafe, raises: [], forbids: [].}
Configures stdin, stdout and stderr to be unbuffered. Source   Edit  
proc write(f: File; a: varargs[string, `$`]) {....tags: [WriteIOEffect], gcsafe,
    raises: [IOError], forbids: [].}
Source   Edit  
proc write(f: File; b: bool) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                               forbids: [].}
Source   Edit  
proc write(f: File; c: char) {....tags: [WriteIOEffect], gcsafe, raises: [],
                               forbids: [].}
Source   Edit  
proc write(f: File; c: cstring) {....tags: [WriteIOEffect], gcsafe,
                                  raises: [IOError], forbids: [].}
Writes a value to the file f. May throw an IO exception. Source   Edit  
proc write(f: File; i: BiggestInt) {....tags: [WriteIOEffect], gcsafe,
                                     raises: [IOError], forbids: [].}
Source   Edit  
proc write(f: File; i: int) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                              forbids: [].}
Source   Edit  
proc write(f: File; r: BiggestFloat) {....tags: [WriteIOEffect], gcsafe,
                                       raises: [IOError], forbids: [].}
Source   Edit  
proc write(f: File; r: float32) {....tags: [WriteIOEffect], gcsafe,
                                  raises: [IOError], forbids: [].}
Source   Edit  
proc write(f: File; s: string) {....tags: [WriteIOEffect], gcsafe,
                                 raises: [IOError], forbids: [].}
Source   Edit  
proc writeBuffer(f: File; buffer: pointer; len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}
Writes the bytes of buffer pointed to by the parameter buffer to the file f. Returns the number of actual written bytes, which may be less than len in case of an error. Source   Edit  
proc writeBytes(f: File; a: openArray[int8 | uint8]; start, len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe.}
Writes the bytes of a[start..start+len-1] to the file f. Returns the number of actual written bytes, which may be less than len in case of an error. Source   Edit  
proc writeChars(f: File; a: openArray[char]; start, len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}
Writes the bytes of a[start..start+len-1] to the file f. Returns the number of actual written bytes, which may be less than len in case of an error. Source   Edit  
proc writeFile(filename, content: string) {....tags: [WriteIOEffect], gcsafe,
    raises: [IOError], forbids: [].}
Opens a file named filename for writing. Then writes the content completely to the file and closes the file afterwards. Raises an IO exception in case of an error. Source   Edit  
proc writeFile(filename: string; content: openArray[byte]) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}
Opens a file named filename for writing. Then writes the content completely to the file and closes the file afterwards. Raises an IO exception in case of an error. Source   Edit  
proc writeLine[Ty](f: File; x: varargs[Ty, `$`]) {.inline,
    ...tags: [WriteIOEffect], gcsafe.}
Writes the values x to f and then writes "\n". May throw an IO exception. Source   Edit  

Iterators

iterator lines(f: File): string {....tags: [ReadIOEffect], raises: [IOError],
                                  forbids: [].}

Iterates over any line in the file f.

The trailing newline character(s) are removed from the iterated lines.

Example:

proc countZeros(filename: File): tuple[lines, zeros: int] =
  for line in filename.lines:
    for letter in line:
      if letter == '0':
        result.zeros += 1
    result.lines += 1
Source   Edit  
iterator lines(filename: string): string {....tags: [ReadIOEffect],
    raises: [IOError, IOError], forbids: [].}

Iterates over any line in the file named filename.

If the file does not exist IOError is raised. The trailing newline character(s) are removed from the iterated lines. Example:

Example:

import std/strutils

proc transformLetters(filename: string) =
  var buffer = ""
  for line in filename.lines:
    buffer.add(line.replace("a", "0") & '\n')
  writeFile(filename, buffer)
Source   Edit  

Templates

template `&=`(f: File; x: typed)
An alias for write. Source   Edit  
template readLines(filename: string): seq[string] {.
    ...deprecated: "use readLines with two arguments".}
Deprecated: use readLines with two arguments
Source   Edit  
template stdmsg(): File
Template which expands to either stdout or stderr depending on useStdoutAsStdmsg compile-time switch. Source   Edit