Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.io

    File.write

    Writes text through this File resource.

    write(s: string) -> Result<(), string>
    Module
    std.io
    Receiver
    File
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    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.

    Source evidence

    Receiver

    File

    Parameter constraints

    Additional contracts are Pending.

    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.

    Related rule: Use a file handle with a shared cursor

    Result

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Write UTF-8 bytes at the shared cursor without adding a newline or removing a later suffix. Return a recoverable error on failure.

    Related entries

    Link

    std.io

    Use a file handle with a shared cursor

    Link
    Ruletopaz.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.

    Why

    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.

    Examples Open and close an existing file without changing its bytesReject a directory when opening a fileShare the cursor across file aliasesWrite at the cursor and retain the rest of the fileExtend a file after reading through EOFClose every alias and reject later accessReturn a file read error for invalid UTF-8

    Source evidence

    Open and close an existing file without changing its bytes

    Link

    run · running · Verification: not-run

    main.tpzOpen and close an existing file without changing its bytesOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. file.close()
    7. io.writeLine(test.assertOk(fs.readText("source.txt")))
    8. let missing = test.assertErr(io.open("missing.txt"))
    9. let named = missing.contains("missing.txt")
    10. io.writeLine("missing {named}")
    Expected outputexit 0
    original
missing true
    $ topaz run main.tpz · target product 5.21.3
    source.txtOpen and close an existing file without changing its bytesOpen in Playground
    1. original
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. original
    2. missing true

    This exact example has not been executed.

    Source evidence

    Reject a directory when opening a file

    Link

    run · running · Verification: not-run

    main.tpzReject a directory when opening a fileOpen in Playground
    1. import std.io
    3. match (io.open(".")) {
    4. case Err(_) => io.writeLine("directory rejected")
    5. case Ok(file) => {
    6. file.close()
    7. io.writeLine("directory accepted")
    8. }
    9. }
    Expected outputexit 0
    directory rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. directory rejected

    This exact example has not been executed.

    Source evidence

    Share the cursor across file aliases

    Link

    run · running · Verification: not-run

    main.tpzShare the cursor across file aliasesOpen in Playground
    1. import std.io
    2. import std.test
    4. let file = test.assertOk(io.open("source.txt"))
    5. let alias = file
    6. io.writeLine(test.assertOk(file.read()))
    7. let tail = test.assertOk(alias.read())
    8. let atEnd = tail == ""
    9. io.writeLine("{atEnd}")
    10. alias.close()
    Expected outputexit 0
    alpha
true
    $ topaz run main.tpz · target product 5.21.3
    source.txtShare the cursor across file aliasesOpen in Playground
    1. alpha
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alpha
    2. true

    This exact example has not been executed.

    Source evidence

    Write at the cursor and retain the rest of the file

    Link

    run · running · Verification: not-run

    main.tpzWrite at the cursor and retain the rest of the fileOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. test.assertOk(file.write("XY"))
    7. let tail = test.assertOk(file.read())
    8. io.writeLine("tail {tail}")
    9. file.close()
    10. let whole = test.assertOk(fs.readText("source.txt"))
    11. io.writeLine("whole {whole}")
    Expected outputexit 0
    tail cdef
whole XYcdef
    $ topaz run main.tpz · target product 5.21.3
    source.txtWrite at the cursor and retain the rest of the fileOpen in Playground
    1. abcdef
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. tail cdef
    2. whole XYcdef

    This exact example has not been executed.

    Source evidence

    Extend a file after reading through EOF

    Link

    run · running · Verification: not-run

    main.tpzExtend a file after reading through EOFOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. test.assertOk(file.read())
    7. test.assertOk(file.write("β"))
    8. file.close()
    9. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    alphaβ
    $ topaz run main.tpz · target product 5.21.3
    source.txtExtend a file after reading through EOFOpen in Playground
    1. alpha
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alphaβ

    This exact example has not been executed.

    Source evidence

    Close every alias and reject later access

    Link

    run · running · Verification: not-run

    main.tpzClose every alias and reject later accessOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. let alias = file
    7. file.close()
    8. alias.close()
    9. test.assertErr(alias.read())
    10. io.writeLine("read rejected")
    11. test.assertErr(alias.write("changed"))
    12. io.writeLine("write rejected")
    13. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    read rejected
write rejected
original
    $ topaz run main.tpz · target product 5.21.3
    source.txtClose every alias and reject later accessOpen in Playground
    1. original
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. read rejected
    2. write rejected
    3. original

    This exact example has not been executed.

    Source evidence

    Return a file read error for invalid UTF-8

    Link

    run · running · Verification: not-run

    main.tpzReturn a file read error for invalid UTF-8Open in Playground
    1. import std.io
    2. import std.fs
    3. import std.bytes { Bytes }
    4. import std.test
    6. let invalid = test.assertOk(Bytes.fromArray([255]))
    7. test.assertOk(fs.writeBytes("invalid.txt", invalid))
    8. let file = test.assertOk(io.open("invalid.txt"))
    9. test.assertErr(file.read())
    10. file.close()
    11. io.writeLine("invalid text rejected")
    Expected outputexit 0
    invalid text rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid text rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download