std.fs

API summary (generated from the Beans source by npm run coverage): 7 package functions.

std.fs gives you one-call helpers to read or write a whole file. Under the hood it opens a File, does the work, and closes it. Read the source at stdlib/std/fs/fs.b.

Every function returns a Result, because filesystem work can fail. Use ? to pass the error up.

import std.fs

Reading

pub fn read_bytes(path: string) -> Result<Bytes>
pub fn read(path: string) -> Result<string>

read_bytes opens the file, reads it whole from offset 0, and returns the bytes.
read does the same and fills its returned string directly. It does not build an intermediate Bytes value.

Writing

pub fn write_bytes(path: string, data: Bytes) -> Result<int>
pub fn write(path: string, data: string) -> Result<int>
pub fn append_bytes(path: string, data: Bytes) -> Result<int>
pub fn append(path: string, data: string) -> Result<int>
pub fn copy(from: string, to: string) -> Result<int>

All five return the number of bytes written.

write_bytes and write open the file in “create” mode, truncate it to empty, and write starting at position 0. write takes a string; write_bytes takes Bytes. Text writes use the string storage directly.
append_bytes and append open the file in “append” mode and add data to the end instead of truncating.
copy uses the platform file-copy path when available and a fixed-size fallback. It does not hold the whole source file in a Beans buffer. A same-file or hard-link copy fails before the destination can be truncated.

import std.io
import std.fs

fn main() {
    fs.write("greeting.txt", "hello\n").expect("write")
    fs.append("greeting.txt", "again\n").expect("append")
    let text: string = fs.read("greeting.txt").expect("read")
    io.print(text)                          // hello / again
}

std.fs

Reading

Writing

See also