std/syncio

Этот модуль реализует различные синхронизированные операции ввода-вывода.

Импорты

since, formatfloat, widestrs, exitprocs

Типы

File = ptr CFile

Тип, представляющий дескриптор файла. Источник Изменить

FileHandle = cint

Тип, представляющий дескриптор файла ОС; это полезно для доступа к файлам на низком уровне. Источник Изменить

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.

Режим файла при его открытии. Источник Изменить

FileSeekPos = enum
  fspSet,                   ## Seek to absolute value
  fspCur,                   ## Seek relative to current position
  fspEnd                     ## Seek relative to end

Позиция относительно которой происходит поиск. Источник Изменить

Переменные

stderr {.importc: "stderr", header: "<stdio.h>".}: File

Поток стандартной ошибки. Источник Изменить

stdin {.importc: "stdin", header: "<stdio.h>".}: File

Поток стандартного ввода. Источник Изменить

stdout {.importc: "stdout", header: "<stdio.h>".}: File

Поток стандартного вывода. Источник Изменить

Процедуры

proc close(f: File) {....tags: [], gcsafe, sideEffect, ...raises: [], forbids: [].}

Закрывает файл. Исходный код Редактировать

proc endOfFile(f: File): bool {....tags: [], gcsafe, raises: [], forbids: [].}

Возвращает true, если f находится в конце. Исходный код Редактировать

proc flushFile(f: File) {....tags: [WriteIOEffect], raises: [], forbids: [].}

Очищает буфер f. Исходный код Редактировать

proc getFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}

Возвращает дескриптор файла f. Это полезно только для платформозависимого программирования. Обратите внимание, что в Windows это не возвращает Windows-специфический дескриптор, а дескриптор из C библиотеки, что бы это ни значило. Используйте getOsFileHandle вместо этого. Исходный код Редактировать

proc getFilePos(f: File): int64 {....gcsafe, raises: [IOError], tags: [],
                                  forbids: [].}

Возвращает текущую позицию указателя файла, используемого для чтения из файла f. Первый байт файла имеет индекс ноль. Исходный код Редактировать

proc getFileSize(f: File): int64 {....tags: [ReadIOEffect], gcsafe,
                                   raises: [IOError], forbids: [].}

Возвращает размер файла (в байтах) f. Исходный код Редактировать

proc getOsFileHandle(f: File): FileHandle {....raises: [], tags: [], forbids: [].}

Возвращает дескриптор файла ОС f. Это полезно только для платформозависимого программирования. Исходный код Редактировать

proc open(f: var File; filehandle: FileHandle; mode: FileMode = fmRead): bool {.
    ...tags: [], raises: [], gcsafe, forbids: [].}

Создаёт File из filehandle с заданным mode.

По умолчанию режим — чтение. Возвращает true, если файл был открыт.

Переданный дескриптор файла больше не будет наследуемым.

Исходный код Редактировать

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

Открывает файл с именем filename с заданным mode.

По умолчанию режим — чтение. Возвращает true, если файл был открыт. Не выбрасывает исключение, если файл открыть не удалось.

Дескриптор файла, связанный с полученным File не наследуем.

Исходный код Редактировать

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

Открывает файл с именем filename с заданным mode.

По умолчанию режим — чтение. Выбрасывает исключение IOError если файл открыть не удалось.

Дескриптор файла, связанный с полученным File не наследуем.

Исходный код Редактировать

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

Читает все данные из потока file.

Выбрасывает исключение IO в случае ошибки. Ошибка возникает, если текущая позиция файла не находится в начале файла.

Исходный код Редактировать

proc readBuffer(f: File; buffer: pointer; len: Natural): int {.
    ...tags: [ReadIOEffect], gcsafe, raises: [IOError], forbids: [].}

Читает len байт в буфер, на который указывает buffer. Возвращает фактическое количество прочитанных байт, которое может быть меньше len (если не так много байт осталось), но не больше. Исходный код Редактировать

proc readBytes(f: File; a: var openArray[int8 | uint8]; start, len: Natural): int {.
    ...tags: [ReadIOEffect], gcsafe.}

Читает len байт в буфер a начиная с a[start]. Возвращает фактическое количество прочитанных байт, которое может быть меньше len (если не так много байт осталось), но не больше. Исходный код Редактировать

proc readChar(f: File): char {....tags: [ReadIOEffect],
                               raises: [IOError, EOFError], forbids: [].}

Читает один символ из потока f. Не следует использовать в производительно-чувствительном коде. Исходный код Редактировать

proc readChars(f: File; a: var openArray[char]): int {....tags: [ReadIOEffect],
    gcsafe, raises: [IOError], forbids: [].}

Читает до a.len байт в буфер a. Возвращает фактическое количество прочитанных байт, которое может быть меньше a.len (если не так много байт осталось), но не больше. Исходный код Редактировать

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: [].}

Устаревшее: используйте другую перегрузку `readChars`, возможно: readChars(toOpenArray(buf, start, len-1))

Читает len байт в буфер a начиная с a[start]. Возвращает фактическое количество прочитанных байт, которое может быть меньше len (если не так много байт осталось), но не больше. Исходный код Редактировать

proc readFile(filename: string): string {....tags: [ReadIOEffect], gcsafe,
    raises: [IOError], forbids: [].}

Открывает файл с именем filename для чтения, вызывает readAll и закрывает файл после этого. Возвращает строку. Выбрасывает исключение IO в случае ошибки. Если вам нужно вызвать это внутри макроса времени компиляции, вы можете использовать staticRead. Исходный код Редактировать

proc readLine(f: File): string {....tags: [ReadIOEffect], gcsafe,
                                 raises: [IOError, EOFError], forbids: [].}

Читает строку текста из файла f. Может выбросить исключение IO. Строка текста может быть ограничена LF или CRLF. Символ(ы) новой строки не являются частью возвращаемой строки. Исходный код Редактировать

proc readLine(f: File; line: var string): bool {....tags: [ReadIOEffect], gcsafe,
    raises: [IOError], forbids: [].}

Читает строку текста из файла f в line. Может выбросить исключение IO. Строка текста может быть ограничена LF или CRLF. Символ(ы) новой строки не являются частью возвращаемой строки. Возвращает false если достигнут конец файла, true в противном случае. Если возвращается false, line не содержит новых данных. Исходный код Редактировать

proc readLines(filename: string; n: Natural): seq[string] {.
    ...raises: [IOError, EOFError], tags: [ReadIOEffect], forbids: [].}

Читает n строк из файла с именем filename. Выбрасывает исключение IO в случае ошибки. Выбрасывает EOF, если файл не содержит как минимум n строк. Доступно во время компиляции. Строка текста может быть ограничена LF или CRLF. Символ(ы) новой строки не являются частью возвращаемых строк. Исходный код Редактировать

proc reopen(f: File; filename: string; mode: FileMode = fmRead): bool {.
    ...tags: [], gcsafe, raises: [], forbids: [].}

Переоткрывает файл f с заданным filename и mode. Это часто используется для перенаправления переменных файлов stdin, stdout или stderr.

По умолчанию режим — чтение. Возвращает true, если файл был переоткрыт.

Дескриптор файла, связанный с f не будет наследуемым.

Исходный код Редактировать

proc setFilePos(f: File; pos: int64; relativeTo: FileSeekPos = fspSet) {....gcsafe,
    sideEffect, ...raises: [IOError], tags: [], forbids: [].}

Устанавливает позицию указателя файла, используемого для операций чтения/записи. Первый байт файла имеет индекс ноль. Источник Редактировать

proc setInheritable(f: FileHandle; inheritable: bool): bool {....raises: [],
    tags: [], forbids: [].}

Управляет тем, может ли дескриптор файла унаследоваться дочерними процессами. Возвращает true при успехе. Требуется дескриптор файла ОС, который можно получить с помощью getOsFileHandle.

Эта процедура не гарантируется для всех платформ. Проверьте доступность с помощью declared().

Источник Редактировать

proc setStdIoUnbuffered() {....tags: [], gcsafe, raises: [], forbids: [].}

Настраивает stdin, stdout и stderr для работы без буферизации. Источник Редактировать

proc write(f: File; a: varargs[string, `$`]) {....tags: [WriteIOEffect], gcsafe,
    raises: [IOError], forbids: [].}

Источник Редактировать

proc write(f: File; b: bool) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                               forbids: [].}

Источник Редактировать

proc write(f: File; c: char) {....tags: [WriteIOEffect], gcsafe, raises: [],
                               forbids: [].}

Источник Редактировать

proc write(f: File; c: cstring) {....tags: [WriteIOEffect], gcsafe,
                                  raises: [IOError], forbids: [].}

Записывает значение в файл f. Может выбросить исключение IO. Источник Редактировать

proc write(f: File; i: BiggestInt) {....tags: [WriteIOEffect], gcsafe,
                                     raises: [IOError], forbids: [].}

Источник Редактировать

proc write(f: File; i: int) {....tags: [WriteIOEffect], gcsafe, raises: [IOError],
                              forbids: [].}

Источник Редактировать

proc write(f: File; r: BiggestFloat) {....tags: [WriteIOEffect], gcsafe,
                                       raises: [IOError], forbids: [].}

Источник Редактировать

proc write(f: File; r: float32) {....tags: [WriteIOEffect], gcsafe,
                                  raises: [IOError], forbids: [].}

Источник Редактировать

proc write(f: File; s: string) {....tags: [WriteIOEffect], gcsafe,
                                 raises: [IOError], forbids: [].}

Источник Редактировать

proc writeBuffer(f: File; buffer: pointer; len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}

Записывает байты буфера, на который указывает параметр buffer, в файл f. Возвращает количество фактически записанных байтов, которое может быть меньше len в случае ошибки. Источник Редактировать

proc writeBytes(f: File; a: openArray[int8 | uint8]; start, len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe.}

Записывает байты a[start..start+len-1] в файл f. Возвращает количество фактически записанных байтов, которое может быть меньше len в случае ошибки. Источник Редактировать

proc writeChars(f: File; a: openArray[char]; start, len: Natural): int {.
    ...tags: [WriteIOEffect], gcsafe, raises: [IOError], forbids: [].}

Записывает байты a[start..start+len-1] в файл f. Возвращает количество фактически записанных байтов, которое может быть меньше len в случае ошибки. Источник Редактировать

proc writeFile(filename, content: string) {....tags: [WriteIOEffect], gcsafe,
    raises: [IOError], forbids: [].}

Открывает файл с именем filename для записи. Затем записывает content полностью в файл и закрывает файл после этого. В случае ошибки генерирует исключение IO. Источник Редактировать

proc writeFile(filename: string; content: openArray[byte]) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}

Открывает файл с именем filename для записи. Затем записывает content полностью в файл и закрывает файл после этого. В случае ошибки генерирует исключение IO. Источник Редактировать

proc writeLine[Ty](f: File; x: varargs[Ty, `$`]) {.inline,
    ...tags: [WriteIOEffect], gcsafe.}

Записывает значения x в f и затем записывает "\n". Может выбросить исключение IO. Источник Редактировать

Итераторы

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

Итерирует по любой строке в файле f.

Символ(ы) новой строки в конце итерируемых строк удаляются.

Пример:

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

Источник Редактировать

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

Итерирует по любой строке в файле с именем filename.

Если файл не существует, IOError будет выброшено. Символ(ы) новой строки в конце итерируемых строк удаляются. Пример:

Пример:

import std/strutils

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

Источник Редактировать

Шаблоны

template `&=`(f: File; x: typed)

Псевдоним для write. Источник Редактировать

template readLines(filename: string): seq[string] {.
    ...deprecated: "use readLines with two arguments".}

Устарело: используйте readLines с двумя аргументами

Источник Редактировать

template stdmsg(): File

Шаблон, который расширяется до stdout или stderr в зависимости от useStdoutAsStdmsg переключателя во время компиляции. Источник Редактировать