HewStandard Library

Module std::fs

File system operations.

Read, write, and query files on the local file system.

For path-only helpers prefer std.path, and for stdin/stdout prefer std.io. fs.exists(path) checks whether a file-system entry exists.

Error Handling

IoError is the stable user-facing error enum for file-system failures. Use the Result-returning operations in this module—such as read, write, rename, and copy—with Result<T, IoError> and the ? operator for clean error propagation:

import std.fs;

fn load_config(path: string) -> Result<string, fs.IoError> {
    fs.read(path)
}

fn main() {
    match load_config("config.toml") {
        .Ok(data) => println(data),
        .Err(e) => {
            match e {
                fs.IoError.NotFound(_) => println("missing"),
                _ => println("i/o error"),
            }
        }
    }
}

Contents

Functions

Function io_error_from_errno

pub fn io_error_from_errno(errno: i64) -> IoError

Map an OS errno integer to a structured IoError variant.

The i64 payload carried in each variant is the raw OS errno so callers can inspect the platform value. errno=0 (no OS error) maps to Other(0).

This is a raw-integer helper: it recognises POSIX errno values plus the few Windows Win32 codes that do not collide with a POSIX errno (only ERROR_ALREADY_EXISTS = 183 today). Codes that mean different things on each platform — for example 5 (EIO on POSIX, ERROR_ACCESS_DENIED on Windows) — cannot be disambiguated from the integer alone; the Result-returning operations classify those correctly through the runtime's canonical error-kind channel (hew_stream_last_error_kind) and only fall back to this function for kinds without a canonical tag.

Covers file-system errno values. For network errno values use net.net_error_from_errno in std.net.

Function io_error_from_kind

pub fn io_error_from_kind(kind: i64, errno: i64) -> IoError

Map the runtime's canonical, platform-independent error-kind tag (from hew_stream_last_error_kind) plus the raw OS errno to an IoError.

The tag classifies the failure identically on every platform — POSIX and Windows raw codes diverge and collide, so classification cannot be done from the errno alone — while the raw errno is preserved as the variant payload. Tag 0 (IO_ERROR_KIND_UNCLASSIFIED) means "no canonical kind": fall back to io_error_from_errno, which keeps platform detail for kinds without a tag (e.g. EISDIR/ENOTDIR -> Other(raw)). Keep the tag values in sync with the IO_ERROR_KIND_* constants in hew-runtime/src/stream_error.rs.

Public so sibling operations that read the same runtime error channel classify failures through this one authority rather than re-deriving it from the raw errno.

Function io_error_timed_out

pub fn io_error_timed_out() -> IoError

Construct an IoError.TimedOut(0) value without a platform-specific errno. Useful for in-process deadline expiry where there is no OS error to map (e.g. fs.io_error_from_errno would need a platform-aware errno constant that the caller does not have).

Function io_error_cancelled

pub fn io_error_cancelled() -> IoError

Construct an IoError.Cancelled(0) value without a platform-specific errno. Useful for in-process cancellation (e.g. blocking pool stopped) where there is no OS error to map.

Function read

pub fn read(file_path: string) -> Result<string, IoError>

Read the entire contents of a file as a UTF-8 string.

Returns a structured error if the file does not exist or cannot be read. Invalid UTF-8 returns IoError.Other(0); an empty file is valid empty text.

Examples

import std.fs;

fn main() {
    match fs.read("main.hew") {
        .Ok(src) => println(src),
        .Err(_) => println("could not read main.hew"),
    }
}

Function write

pub fn write(file_path: string, content: string) -> Result<(), IoError>

Write a string to a file, creating or overwriting it.

Returns Ok(()) on success.

Function append

pub fn append(file_path: string, content: string) -> Result<(), IoError>

Append a string to the end of a file.

Creates the file if it does not exist.

Function exists

pub fn exists(path: string) -> bool

Check whether a file exists at the given path.

Examples

import std.fs;

fn main() {
    if fs.exists("config.toml") {
        println("found config");
    }
}

Function delete

pub fn delete(file_path: string) -> Result<(), IoError>

Delete a file.

Returns Err(IoError.NotFound(_)) when the path is missing.

Function size

pub fn size(path: string) -> i64

Returns the size of a file in bytes.

Function read_bytes

pub fn read_bytes(file_path: string) -> Result<bytes, IoError>

Read the raw bytes of a file into a bytes value.

Returns a structured error on failure.

Examples

import std.fs;

fn main() {
    let data = (fs.read_bytes("image.png")).expect("the call succeeds");
    println(data.len());
}

Function write_bytes

pub fn write_bytes(file_path: string, data: bytes) -> Result<(), IoError>

Write a bytes value to a file, creating or overwriting it.

Write a bytes value to a file, creating or overwriting it.

Function mkdir

pub fn mkdir(dir_path: string) -> Result<(), IoError>

Create a directory.

Fails if any parent directory does not exist. Use mkdir_all to create parent directories automatically.

Function mkdir_all

pub fn mkdir_all(dir_path: string) -> Result<(), IoError>

Create a directory and all its parent components.

Create a directory and all its parent components.

Function list_dir

pub fn list_dir(dir_path: string) -> Result<Vec<string>, IoError>

List the entries in a directory.

Returns a list of entry names (not full paths).

Examples

import std.fs;

fn main() {
    let entries = fs.list_dir("/tmp").expect("list_dir succeeds");
    for entry in entries {
        println(entry);
    }
}

Function rename

pub fn rename(from: string, to: string) -> Result<(), IoError>

Rename or move a file or directory.

Function copy

pub fn copy(from: string, to: string) -> Result<(), IoError>

Copy a file.

Function is_dir

pub fn is_dir(path: string) -> bool

Check whether a path is a directory.

Types

Enum IoError

Structured error type for file-system operations.

Define Result<T, IoError> return types in your own functions for structured error handling with the ? operator.

For network errors (ConnectionRefused, AddressInUse, etc.) see net.NetError in std.net.

Variants

NotFound(i64)

The target path does not exist.

PermissionDenied(i64)

The process lacks permission for the operation.

AlreadyExists(i64)

A file or directory already exists at the target path.

TimedOut(i64)

The operation timed out (e.g. the blocking pool exceeded its deadline).

Cancelled(i64)

Operation was cancelled (e.g., the blocking pool was shut down mid-call).

Distinct from TimedOut: TimedOut means the deadline expired; Cancelled means the operation was abandoned for another reason.

Other(i64)

Any other I/O failure. The raw code is 0 when there is no OS error, including invalid UTF-8 file contents.

Struct FileReadStream