std.io

Имя	Модуль
File.close →	std.io →
File.read →	std.io →
File.write →	std.io →
std.io.open →	std.io →
std.io.readStdin →	std.io →
std.io.writeLine →	std.io →

Module

Process streams carry input and output. File resources share a cursor and closed state across aliases. Use std.fs for operations on complete file contents.

Why

Ссылка

Stream operations expose consumption and lifetime. Whole file replacement already has its own meaning in std.fs.

Availability

Ссылка

Import std.io in language mode 5.21. The current compiler selects std/io.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

Public API

Pending contracts

Ссылка

Read standard input through its end

Ссылка

Правилоtopaz.stdlib.contract.stdin-consumption.rule

Read standard input through its end

readStdin reads the remaining standard input bytes through EOF. UTF-8 validity and text preservation follow UTF-8 decoding. It does not append or remove a newline.

No remaining bytes produces an empty string. A later call reads from the stream position left by the earlier call and therefore returns an empty string at EOF. A terminal follows the same EOF rule as redirected input.

The call may wait for input or EOF. Reading consumes input even when the result is later discarded. A host read failure or invalid UTF-8 produces a structured runtime fault at the readStdin call because the function returns a string rather than a Result.

The Topaz 6.0 host input fault is TPZ4008. Its primary location is the readStdin call.

Причина

Standard input is a stream shared with the host. Consuming it once gives EOF one meaning and lets terminal and redirected input obey the same rule. Strict UTF-8 prevents malformed bytes from silently becoming different text.

Примеры Preserve redirected text and its line endings →Return empty text at an empty input stream →Observe EOF after standard input has been consumed →

Preserve redirected text and its line endings

Ссылка

run · running · Проверка · Не выполнялось

main.tpzPreserve redirected text and its line endingsОткрыть песочницу →

import std.io
let text = io.readStdin()
io.writeLine(text)

Ожидаемый выводКод завершения 0

  alpha
한글

$ topaz run main.tpz · Целевой продукт 5.21.3

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

alpha
한글

Этот пример ещё не выполнялся.

Return empty text at an empty input stream

Ссылка

run · running · Проверка · Не выполнялось

main.tpzReturn empty text at an empty input streamОткрыть песочницу →

import std.io
let text = io.readStdin()
let empty = text == ""
io.writeLine("{empty}")

Ожидаемый выводКод завершения 0

true

$ topaz run main.tpz · Целевой продукт 5.21.3

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

true

Этот пример ещё не выполнялся.

Observe EOF after standard input has been consumed

Ссылка

run · running · Проверка · Не выполнялось

main.tpzObserve EOF after standard input has been consumedОткрыть песочницу →

import std.io
let first = io.readStdin()
let second = io.readStdin()
let atEnd = second == ""
io.writeLine(first)
io.writeLine("{atEnd}")

Ожидаемый выводКод завершения 0

alpha
true

$ topaz run main.tpz · Целевой продукт 5.21.3

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

alpha
true

Этот пример ещё не выполнялся.

Use a file handle with a shared cursor

Ссылка

Правилоtopaz.stdlib.contract.file-resources.rule

Use a file handle with a shared cursor

open evaluates its path once and opens an existing regular file for reading and writing. It does not create or truncate a file. A successful result is Ok containing a File with the cursor at the first byte.

String paths use the host path syntax. Relative paths resolve against the working directory for an ordinary installed CLI invocation. A package host applies its configured filesystem base and capability policy. NUL, an empty path, a missing file, a directory, and denied read or write access return Err containing an error string.

An open error follows the filesystem error context contract with open as the public operation. An error result does not grant a handle, and path validation does not bypass operating system or package permissions.

File values refer to a resource identity. Copies share the open state and cursor. The handle continues to identify the opened file when the directory entry is renamed or replaced. This is the host resource exception in collection value semantics.

read consumes the remaining bytes from the shared cursor through EOF. UTF-8 validity and text preservation follow UTF-8 decoding. A successful read returns Ok containing text, and a successful read at EOF returns an empty string.

A read error returns Err containing an error string without a text value. Bytes already consumed before a host or decoding error are not restored. Callers must not assume the previous cursor position after a read error.

write encodes its string as UTF-8 and writes all bytes at the shared cursor. It adds no newline. Success advances the cursor by the encoded byte count, overwrites those bytes, and preserves an existing suffix beyond them. A write at EOF extends the file.

An empty write succeeds without moving the cursor. A closed handle, denied access, or host write failure returns Err. A host failure may leave a written prefix and an advanced cursor. It does not roll back earlier argument effects or file changes.

close returns unit, releases the resource, and marks every alias closed. Closing an already closed resource also returns unit. A later read or write through any alias returns Err. A host failure while closing produces a structured runtime fault at the close call.

The Topaz 6.0 host close fault is TPZ4009. Its primary location is the close call. A successful write or close does not promise persistence across a system crash.

Receiver and argument expressions are evaluated once in source order before each resource operation. Use std.fs for whole file replacement or whole file reads. Use File when successive operations must share a cursor and lifetime.

Причина

A handle gives successive operations one cursor and one lifetime. Whole file operations already belong to std.fs, so rereading and replacing by path would duplicate their meaning. An existing file open avoids surprising creation or truncation, and recoverable access failures stay in Result.

Примеры Open and close an existing file without changing its bytes →Reject a directory when opening a file →Share the cursor across file aliases →Write at the cursor and retain the rest of the file →Extend a file after reading through EOF →Close every alias and reject later access →Return a file read error for invalid UTF-8 →

Open and close an existing file without changing its bytes

Ссылка

run · running · Проверка · Не выполнялось

main.tpzOpen and close an existing file without changing its bytesОткрыть песочницу →

import std.io
import std.fs
import std.test
let file = test.assertOk(io.open("source.txt"))
file.close()
io.writeLine(test.assertOk(fs.readText("source.txt")))
let missing = test.assertErr(io.open("missing.txt"))
let named = missing.contains("missing.txt")
io.writeLine("missing {named}")

Ожидаемый выводКод завершения 0

original
missing true

$ topaz run main.tpz · Целевой продукт 5.21.3

source.txtOpen and close an existing file without changing its bytesОткрыть песочницу →

original

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

original
missing true

Этот пример ещё не выполнялся.

Reject a directory when opening a file

Ссылка

run · running · Проверка · Не выполнялось

main.tpzReject a directory when opening a fileОткрыть песочницу →

import std.io
match (io.open(".")) {
case Err(_) => io.writeLine("directory rejected")
case Ok(file) => {
file.close()
io.writeLine("directory accepted")
}
}

Ожидаемый выводКод завершения 0

directory rejected

$ topaz run main.tpz · Целевой продукт 5.21.3

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

directory rejected

Этот пример ещё не выполнялся.

Share the cursor across file aliases

Ссылка

run · running · Проверка · Не выполнялось

main.tpzShare the cursor across file aliasesОткрыть песочницу →

import std.io
import std.test
let file = test.assertOk(io.open("source.txt"))
let alias = file
io.writeLine(test.assertOk(file.read()))
let tail = test.assertOk(alias.read())
let atEnd = tail == ""
io.writeLine("{atEnd}")
alias.close()

Ожидаемый выводКод завершения 0

alpha
true

$ topaz run main.tpz · Целевой продукт 5.21.3

source.txtShare the cursor across file aliasesОткрыть песочницу →

alpha

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

alpha
true

Этот пример ещё не выполнялся.

Write at the cursor and retain the rest of the file

Ссылка

run · running · Проверка · Не выполнялось

main.tpzWrite at the cursor and retain the rest of the fileОткрыть песочницу →

import std.io
import std.fs
import std.test
let file = test.assertOk(io.open("source.txt"))
test.assertOk(file.write("XY"))
let tail = test.assertOk(file.read())
io.writeLine("tail {tail}")
file.close()
let whole = test.assertOk(fs.readText("source.txt"))
io.writeLine("whole {whole}")

Ожидаемый выводКод завершения 0

tail cdef
whole XYcdef

$ topaz run main.tpz · Целевой продукт 5.21.3

source.txtWrite at the cursor and retain the rest of the fileОткрыть песочницу →

abcdef

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

tail cdef
whole XYcdef

Этот пример ещё не выполнялся.

Extend a file after reading through EOF

Ссылка

run · running · Проверка · Не выполнялось

main.tpzExtend a file after reading through EOFОткрыть песочницу →

import std.io
import std.fs
import std.test
let file = test.assertOk(io.open("source.txt"))
test.assertOk(file.read())
test.assertOk(file.write("β"))
file.close()
io.writeLine(test.assertOk(fs.readText("source.txt")))

Ожидаемый выводКод завершения 0

alphaβ

$ topaz run main.tpz · Целевой продукт 5.21.3

source.txtExtend a file after reading through EOFОткрыть песочницу →

alpha

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

alphaβ

Этот пример ещё не выполнялся.

Close every alias and reject later access

Ссылка

run · running · Проверка · Не выполнялось

main.tpzClose every alias and reject later accessОткрыть песочницу →

import std.io
import std.fs
import std.test
let file = test.assertOk(io.open("source.txt"))
let alias = file
file.close()
alias.close()
test.assertErr(alias.read())
io.writeLine("read rejected")
test.assertErr(alias.write("changed"))
io.writeLine("write rejected")
io.writeLine(test.assertOk(fs.readText("source.txt")))

Ожидаемый выводКод завершения 0

read rejected
write rejected
original

$ topaz run main.tpz · Целевой продукт 5.21.3

source.txtClose every alias and reject later accessОткрыть песочницу →

original

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

read rejected
write rejected
original

Этот пример ещё не выполнялся.

Return a file read error for invalid UTF-8

Ссылка

run · running · Проверка · Не выполнялось

main.tpzReturn a file read error for invalid UTF-8Открыть песочницу →

import std.io
import std.fs
import std.bytes { Bytes }
import std.test
let invalid = test.assertOk(Bytes.fromArray([255]))
test.assertOk(fs.writeBytes("invalid.txt", invalid))
let file = test.assertOk(io.open("invalid.txt"))
test.assertErr(file.read())
file.close()
io.writeLine("invalid text rejected")

Ожидаемый выводКод завершения 0

invalid text rejected

$ topaz run main.tpz · Целевой продукт 5.21.3

Ожидаемый результат

Выполнение завершается. Код завершения 0.

Нет вывода ошибок.

Ожидаемый стандартный вывод

invalid text rejected

Этот пример ещё не выполнялся.

Поиск в документации

API этого модуля

Module

Why

Availability

Public API

Pending contracts

Read standard input through its end

Read standard input through its end

Причина

Preserve redirected text and its line endings

Ожидаемый результат

Return empty text at an empty input stream

Ожидаемый результат

Observe EOF after standard input has been consumed

Ожидаемый результат

Use a file handle with a shared cursor

Use a file handle with a shared cursor

Причина

Open and close an existing file without changing its bytes

Ожидаемый результат

Reject a directory when opening a file

Ожидаемый результат

Share the cursor across file aliases

Ожидаемый результат

Write at the cursor and retain the rest of the file

Ожидаемый результат

Extend a file after reading through EOF

Ожидаемый результат

Close every alias and reject later access

Ожидаемый результат

Return a file read error for invalid UTF-8

Ожидаемый результат

Меню