File model

• The module loads or saves one whole file per call.
• The interface exposes no persistent file-handle object, no streamed iterator, and no filesystem traversal helper.
• loadFile and saveFile operate on raw bytes.
• loadString, saveString, and appendString operate on the current UTF-8 byte sequence of the supplied or returned String value.
• File names are normalized through addTerminator and String.makeStringView, so file-name inputs accept StringView, Text, and String.
• saveString and appendString normalize their text argument through String.makeStringView.
• SEEK_SET, SEEK_CUR, and SEEK_END are exposed because the implementation uses whole-file seeks internally.

getErrnoText (errnum -- textView)

Returns one StringView for the supplied error number.

loadFile (name -- result)

Loads one whole file into a byte-array result record.

• The result record has fields result and data.
• data holds the loaded bytes as Nat8 Array.
• result holds one error string; success leaves it empty.
• On failure after partial progress, data is not guaranteed to represent the whole file contents.

saveFile (name data -- result)

Saves contiguous byte storage to one file.

• data supplies bytes through its data and size selectors.
• The result is one error String; success returns the empty string.

loadString (name -- result)

Loads one whole file into a string result record.

• The result record has fields success and data.
• success reports whether the whole operation succeeded.
• data holds the loaded String.
• The loaded bytes are stored directly in the string; no UTF-8 validation is performed.
• The returned string storage includes the internal trailing terminator required by String, but String.size excludes that terminator.
• On failure after partial progress, data is not guaranteed to represent the whole file contents.

saveString (name text -- success)

Saves text bytes to one file and reports whether the whole operation succeeded.

• The file is opened for writing and previous contents are replaced.
• The written bytes are the current UTF-8 bytes of the normalized text source.

appendString (name text -- success)

Appends text bytes to the end of one file and reports whether the whole operation succeeded.

• The appended bytes are the current UTF-8 bytes of the normalized text source.

Examples

Compile-time example: signature-level result schemas

"file" use
"control" use

{} () {} [
  "sample.txt" "alpha" saveString printStack _:;
  "sample.txt" loadString.success printStack _:;
  "sample.txt" loadString.data.size printStack _:;
  "sample.txt" "beta" appendString printStack _:;
] "main" exportFunction

Expected Output During Compilation

Cond
Cond Cref
Int32
Cond

Runtime example

"file" use
"String" use
"control" use

{} Int32 {} [
  "sample.txt" "alpha" saveString drop
  "sample.txt" "beta" appendString drop
  loaded: "sample.txt" loadString;
  loaded.data print
  0
] "main" exportFunction

Expected Output

alphabeta

See also

• String: UTF-8 string views, owned strings, formatting helpers, and text conversion utilities.
• Array: Growable array.
• Span: Contiguous non-owning view of items of the same schema.
• linux/errno · macos/errno · windows/errno: Accessor for platform error-number storage.