close() -- Модуль
- std.
io → - Получатель
- File
- Минимальное число аргументов
- 0
- Максимальное число аргументов
- 0
Declaration and parameters
СсылкаДоступность
Включено по умолчанию · Не определено
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.
Получатель
File
Ограничения параметров
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.
Связанное правило · Use a file handle with a shared cursor →Результат
The declared result type is ().
Эффекты
Ошибки
Result and effects
СсылкаClose the shared file resource and return unit. Every alias becomes closed, and repeated closing also returns unit.
Related entries
СсылкаUse a file handle with a shared cursor
Ссылка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
Ссылкаimport std.ioimport std.fsimport std.testlet 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}")
original
missing true
original
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
originalmissing true
Reject a directory when opening a file
Ссылкаimport std.iomatch (io.open(".")) {case Err(_) => io.writeLine("directory rejected")case Ok(file) => {file.close()io.writeLine("directory accepted")}}
directory rejected
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
directory rejected
Share the cursor across file aliases
Ссылкаimport std.ioimport std.testlet file = test.assertOk(io.open("source.txt"))let alias = fileio.writeLine(test.assertOk(file.read()))let tail = test.assertOk(alias.read())let atEnd = tail == ""io.writeLine("{atEnd}")alias.close()
alpha
true
alpha
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
alphatrue
Write at the cursor and retain the rest of the file
Ссылкаimport std.ioimport std.fsimport std.testlet 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}")
tail cdef
whole XYcdef
abcdef
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
tail cdefwhole XYcdef
Extend a file after reading through EOF
Ссылкаimport std.ioimport std.fsimport std.testlet 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")))
alphaβ
alpha
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
alphaβ
Close every alias and reject later access
Ссылкаimport std.ioimport std.fsimport std.testlet file = test.assertOk(io.open("source.txt"))let alias = filefile.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")))
read rejected
write rejected
original
original
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
read rejectedwrite rejectedoriginal
Return a file read error for invalid UTF-8
Ссылкаimport std.ioimport std.fsimport std.bytes { Bytes }import std.testlet 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")
invalid text rejected
Ожидаемый результат
Ожидаемый результат
Выполнение завершается. Код завершения 0.
invalid text rejected