Path

Owns immutable native filename units with explicit fallible text conversion. Native-byte and UTF-16 constructors preserve non-Unicode filenames while rejecting NUL. TryCreate uses the selected target's UTF-8 encoder. Construction copies fallibly; movement transfers backing, and TryClone explicitly copies it. No cwd lookup, filename normalization or filesystem operation occurs. Borrowed View/text views expire on owner movement/destruction. Concurrent reads of a published unmoved owner are safe under ordinary backing/lifetime rules.

Module std.fs

import std.fs;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

pub final class Path

Example

module example.native_paths;
from std.fs import Path, PathView;
fn Main() -> i32 {
    var Text = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var TextCreation = Path.TryCreate("assets/λ.txt");
        switch TextCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 1;
        }
    };
    if Text.IsEmpty || Text.TryViewUtf8().Unwrap() != "assets/λ.txt" { return 2; }
    var Copy = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var CopyCreation = Text.TryClone();
        switch CopyCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 3;
        }
    };
    var Moved = move(Text);
    if !Text.IsEmpty || Copy.TryViewUtf8().Unwrap() != Moved.TryViewUtf8().Unwrap() { return 4; }
    let Bytes: byte[2] = [0xFF_byte, 0x61_byte];
    var Native = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var NativeCreation = Path.TryFromNativeBytes(Bytes);
        switch NativeCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 5;
        }
    };
    if Native.TryViewUtf8() is .Some { Value = _ } { return 6; }
    switch Native.TryToString() { case .Err { Error = Error } if (Error is .InvalidUtf8) => {} default => return 7; }
    let Wide: u16[2] = [0xD83D_u16, 0xDE42_u16];
    var Unicode = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var UnicodeCreation = Path.TryFromNativeUtf16(Wide);
        switch UnicodeCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 8;
        }
    };
    var UnicodeText = switch Unicode.TryToString() { case .Ok { Value = Value } => break Value; case .Err => return 9; };
    if UnicodeText.View != "\u{1F642}" { return 10; }
    let Unpaired: u16[1] = [0xD800_u16];
    var Preserved = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var PreservedCreation = Path.TryFromNativeUtf16(Unpaired);
        switch PreservedCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 11;
        }
    };
    switch Preserved.TryToString() { case .Err { Error = Error } if (Error is .InvalidUtf16) => {} default => return 12; }
    let Zero: byte[1] = [0_byte];
    switch PathView.TryFromNativeBytes(Zero) { case .Err { Error = Error } if (Error is .EmbeddedNul) => {} default => return 13; }
    return 0;
}

Path.init

pub init()

Creates allocation-free empty native-byte owner.

Path.init

pub init(Source: readonly Self&) = delete;

Rejects implicit allocation/copy. Source: Existing path.

Path.init

pub init(Source: mut Self&&)

Transfers native backing without conversion/allocation. Source: Path left empty.

Path.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects implicit allocating copy. Source: Existing path. Return: No runtime result; this assignment is deleted and cannot be invoked.

Path.operator

pub fn operator =(Source: mut Self&&) -> void

Replaces backing by ownership transfer, invalidating previous views. Source: Path left empty; vector transport handles self-move. Return: No value after replacing the encoded backing; previous borrowed views are invalidated.

Path.Encoding

pub Encoding: PathEncoding;

Observes the exact native unit kind.

Path.UnitLength

pub UnitLength: usize;

Counts active native units, not Unicode scalars.

Path.IsEmpty

pub IsEmpty: bool;

Observes empty native representation.

Path.View

pub View: PathView;

Borrows immutable native units without allocating or retaining owner. Return: View expiring on this owner's move/destruction.

Path.TryCreate

pub static fn TryCreate(Text: str) -> Result<Self, PathError>

Encodes valid UTF-8 for the selected target without filesystem lookup. Text: Borrowed valid UTF-8 copied into native units; NUL rejected. Return: Owned path or portable representation/allocation failure.

Path.TryFromNativeBytes

pub static fn TryFromNativeBytes(Units: readonly byte[]) -> Result<Self, PathError>

Copies exact non-NUL byte units, preserving non-UTF-8 names. Units: Borrowed input copied without normalization. Return: Owned path or portable NUL/storage failure.

Path.TryFromNativeUtf16

pub static fn TryFromNativeUtf16(Units: readonly u16[]) -> Result<Self, PathError>

Copies exact non-NUL UTF-16 units, preserving unpaired surrogates. Units: Borrowed native units copied without text validation. Return: Owned path or portable NUL/storage failure.

Path.TryClone

pub readonly fn TryClone() -> Result<Self, PathError>

Explicitly copies native backing without text conversion. Return: Independent owner or portable allocation failure; source unchanged. Warning: May allocate and performs linear copying.

Path.TryViewUtf8

pub readonly fn TryViewUtf8() -> str?

Validates a borrowed UTF-8 view of native bytes. Return: Borrowed text, or none for invalid UTF-8/UTF-16 representation.

Path.TryToString

pub readonly fn TryToString() -> Result<String, PathError>

Converts native units to owned UTF-8 text fallibly. Return: Owned String or exact Unicode/storage failure; path unchanged. Warning: May allocate.