path

import std::fs::path; · source

Both Path and PathBuf are length-typed UTF-8 byte sequences with no NUL terminator. Path borrows; PathBuf owns. Crossing into libc goes through a NUL-terminated String built with String::with_null, or PathBuf::into_raw, which hands the buffer over with a terminator appended.

Path syntax is per-target. On Unix / separates and a leading / means absolute — the whole path is one flat sequence of segments. On Windows both / and \ separate, and a path may open with a root that is not a segment and must never be split off or reordered:

C:\dir\file        drive-absolute   root `C:\`
C:dir              drive-relative   root `C:`, resolved against that drive's own cwd
\\server\share     UNC

Path#

type struct Path {
    inner: Str;

    static from(source: Str) -> Path;
    as_str(&this) -> Str;
    length(&this) -> u64;
    is_empty(&this) -> boolean;
    static is_separator(byte: u8) -> boolean;
    static byte_or_zero(source: Str, index: u64) -> u8;
    static is_drive_letter(byte: u8) -> boolean;
    static root_len(source: Str) -> u64;
    static is_absolute_str(source: Str) -> boolean;
    static last_separator(source: Str, floor: u64) -> i64;
    static last_dot(name: Str) -> i64;
    is_absolute(&this) -> boolean;
    file_name(&this) -> Option<Str>;
    parent(&this) -> Option<Path>;
    extension(&this) -> Option<Str>;
    join(&this, segment: Str) -> PathBuf;
}

root_len, is_separator, and is_absolute_str are the target-aware primitives the methods are built on, exposed for code that has a Str in hand and no reason to wrap it.

Method	Returns	Notes
from(source)	Path
is_absolute()	boolean
file_name()	Option<Str>	The last segment. None for a trailing separator, an empty path, or a bare root. Does not consult the filesystem.
parent()	Option<Path>	None for a single relative segment, a bare root, or empty. A rooted path yields the root itself, never "".
extension()	Option<Str>	See below.
join(segment)	PathBuf	Appends to a copy, leaving the borrowed path untouched.

extension() consults only the file name, so a dot in a directory component cannot leak in:

foo.rs      -> Some("rs")
foo.tar.gz  -> Some("gz")      last dot only
foo.        -> Some("")        trailing dot, empty extension
foo         -> None            no dot
.bashrc     -> None            a leading dot is not an extension
..          -> None
a/b         -> None            ends in a directory

A leading dot only disqualifies when it is the only dot — .foo.rs still has extension rs.

PathBuf<A>#

type struct PathBuf<A = GlobalAlloc> {
    inner: String<A>;

    static new() -> PathBuf;
    static from(source: Str) -> PathBuf;
    as_path(&this) -> Path;
    length(&this) -> u64;
    is_empty(&this) -> boolean;
    push(mut &this, segment: Str) -> void;
    pop(mut &this) -> boolean;
    join(&this, segment: Str) -> PathBuf;
    extension(&this) -> Option<Str>;
    into_raw(mut this) -> string;
}

push and join share their root semantics: a segment carrying its own root — /etc, C:\dir, \\server\share — replaces rather than extends. pop removes the last segment and returns whether anything was removed.

Trait implementations#

implement<A> trait Drop for struct PathBuf<A>
where A: Allocator

Path is a borrowed view and has nothing to drop.