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. This module keeps fs.exists as a compatibility surface for existing code.

Error Handling

IoError is the stable user-facing error enum for file-system failures. Use the try_* wrappers in this module—such as try_read, try_write, try_rename, and try_copy—with Result<T, IoError> and the ? operator for clean error propagation:

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

fn main() {
    match load_config("config.toml") {
        Ok(data) => println(data),
        Err(e) => {
            match e {
                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).

Covers both file-system and network errno values so this function can be shared across fs, net, stream, http, tls, quic, dns, and websocket modules.

Function io_error_message

pub fn io_error_message(e: IoError) -> string

Return a human-readable description of an IoError.

The returned string includes the variant name and the raw OS errno so callers can log or surface structured errors without matching on every arm:

match result {
    Err(e) => panic("operation failed: " + fs.io_error_message(e)),
    Ok(_) => {},
}

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(path: string) -> string

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

Panics if the file does not exist or cannot be read. Use try_read for a structured Result<string, IoError> surface.

Examples

let src = fs.read("main.hew");

Function try_read

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

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

Returns Err(IoError) instead of panicking on open failures.

Function write

pub fn write(path: string, content: string) -> i64

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

Returns 0 on success, non-zero on error. Use try_write for a structured Result<i64, IoError> surface.

Function try_write

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

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

Lifts the native status code into Result<i64, IoError>.

Function append

pub fn append(path: string, content: string) -> i64

Append a string to the end of a file.

Creates the file if it does not exist. Returns 0 on success. Use try_append for a structured Result<i64, IoError> surface.

Function try_append

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

Append a string to the end of a file.

Lifts the native status code into Result<i64, IoError>.

Function exists

pub fn exists(path: string) -> bool

Check whether a file exists at the given path.

Examples

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

Function delete

pub fn delete(path: string) -> i64

Delete a file. Returns 0 on success.

Function try_delete

pub fn try_delete(file_path: string) -> Result<i64, 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(path: string) -> bytes

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

Returns an empty bytes buffer on error. Use try_read_bytes for a structured Result<bytes, IoError> surface.

Examples

let data = fs.read_bytes("image.png");
println(data.len());

Function try_read_bytes

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

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

Returns Err(IoError) instead of an ambiguous empty buffer on failure.

Function write_bytes

pub fn write_bytes(path: string, data: bytes) -> i64

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

Returns 0 on success, non-zero on error. Use try_write_bytes for a structured Result<i64, IoError> surface.

Function try_write_bytes

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

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

Lifts the native status code into Result<i64, IoError>.

Function mkdir

pub fn mkdir(path: string) -> i64

Create a directory. Returns 0 on success, -1 on error.

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

Function try_mkdir

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

Create a directory with structured IoError results.

Function mkdir_all

pub fn mkdir_all(path: string) -> i64

Create a directory and all its parent components.

Returns 0 on success, -1 on error.

Function try_mkdir_all

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

Create a directory and all its parent components.

Lifts the native status code into Result<i64, IoError>.

Function list_dir

pub fn list_dir(path: string) -> Vec<string>

List the entries in a directory.

Returns a list of entry names (not full paths). Returns an empty list on error. Use try_list_dir when missing-path handling matters.

Examples

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

Function try_list_dir

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

List the entries in a directory.

Distinguishes missing and non-directory paths from a successful listing.

Function rename

pub fn rename(from: string, to: string) -> i64

Rename or move a file or directory.

Returns 0 on success, -1 on error.

Function try_rename

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

Rename or move a file or directory.

Lifts the native status code into Result<i64, IoError>.

Function copy

pub fn copy(from: string, to: string) -> i64

Copy a file.

Returns 0 on success, -1 on error.

Function try_copy

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

Copy a file.

Lifts the native status code into Result<i64, IoError>.

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 and network operations.

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

Variants below cover both file-system and TCP/network failure codes so callers can handle connection errors uniformly across fs, net, quic, http, tls, dns, and websocket modules.

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.

ConnectionRefused(i64)

The remote host actively refused the connection (ECONNREFUSED).

AddressInUse(i64)

The local address is already in use (EADDRINUSE).

TimedOut(i64)

The connection attempt or I/O operation timed out (ETIMEDOUT).

Cancelled(i64)

Operation was cancelled (e.g., a deadline expired before the I/O could complete).

Distinct from TimedOut: TimedOut means the deadline expired; Cancelled means the operation was abandoned for another reason (e.g. the blocking pool was shut down mid-call).

AddressNotAvailable(i64)

The address or hostname could not be resolved (EADDRNOTAVAIL).

Other(i64)

Any other OS-level I/O failure.

Struct FileReadStream

Opaque stream handle returned by stream_from_file_read.