File.read

read() -> Result<string, string>

모듈: 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.

결과

추가 계약은 미정입니다.

The declared result type is Result<string, string>.

효과

미정

실패

미정

Result and effects

링크

Consume strict UTF-8 text from the shared cursor through EOF. Return empty text at EOF and Err after closing or on a read failure.

링크

std.io →

Use a file handle with a shared cursor

링크

규칙topaz.stdlib.contract.file-resources.rule

Use a file handle with a shared cursor

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.

이유

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

이 예제는 아직 실행하지 않았습니다.

문서 검색

Declaration and parameters

사용 조건

수신자

매개변수 제약

결과

효과

실패

Result and effects

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

기대 결과

메뉴

Declaration and parameters

사용 조건

수신자

매개변수 제약

결과

효과

실패

Result and effects

Related entries

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

기대 결과