Module

std::path

Filesystem Paths

Owned, mutable filesystem path type for building, inspecting, and decomposing POSIX paths.

All public API lives under the Path namespace (imported as Path from "std::path").

Types

Type Description
PathBuf Owned path backed by a String — the main type

Constructors

Method Source Cost
PathBuf::new() (empty) One String alloc
PathBuf::create(s) str literal Copy into String
PathBuf::fromString(s) &String Clone the String

Query Methods

Method Returns Description
isEmpty boolean True if the path has no bytes
isAbsolute boolean True if the path starts with /
isRelative boolean True if the path does not start with /
asStr str Borrow as const char* (NUL-terminated)
toString String Clone the inner String
fileName Option<String> Last component after final /
extension Option<String> After last . in fileName
parent Option<PathBuf> Everything before last component

Mutation Methods

Method Signature Description
push push(&mut self, part: str): void Append a path component
pop pop(&mut self): boolean Remove the last component

Operations (return new PathBuf)

Method Signature Description
join join(&self, part: str): PathBuf Clone self, then push part
normalize normalize(&self): PathBuf Lexically resolve ./..

Platform Notes

This module is POSIX-oriented: the separator is / and there is no drive-letter or UNC prefix handling. Windows support will be added when @platform attributes land.

Design Decisions

  • No Path (borrowed view) type yet. Ignis str is const char* with no length — it cannot represent a sub-range without copying. A borrowed Path will be added when string slices land.
  • fileName, extension, and parent return owned values (String / PathBuf) because there is no zero-copy substring today.
  • push with an absolute path (/...) replaces self entirely, matching POSIX join semantics (and Rust’s PathBuf::push).

Example

import Path from "std::path";
import Option from "std::option";

function main(): i32 {
  let mut p: Path::PathBuf = Path::PathBuf::create("/usr/local");
  p.push("bin");
  p.push("ignis");

  // p.asStr() == "/usr/local/bin/ignis"

  let name: Option<String> = p.fileName();
  // name == Option::SOME("ignis")

  let ext: Option<String> = p.extension();
  // ext == Option::NONE (no extension)

  let par: Option<Path::PathBuf> = p.parent();
  // par.unwrap().asStr() == "/usr/local/bin"

  p.pop();
  // p.asStr() == "/usr/local/bin"

  let joined: Path::PathBuf = p.join("rustc");
  // joined.asStr() == "/usr/local/bin/rustc"

  return 0;
}
namespace Path

Owned filesystem path construction and normalization helpers.

PathBuf is string-backed and uses / as the separator on the currently supported POSIX targets. Operations are lexical unless explicitly documented otherwise; they do not query the filesystem.

Records

record PathBuf

Owned, mutable filesystem path.

Backed by a String — all mutation goes through String methods. Drop frees the underlying String buffer.

Members
data: String
static create(s: str): PathBuf

Creates a path from a str literal.

Copies the bytes into a new owned String.

static fromString(s: &String): PathBuf

Creates a path by cloning an existing String.

static new(): PathBuf

Creates an empty path.

appendChildSegment(&self, normalized: &mut String, segment: &String, absolute: boolean): void
appendNormalizedSegment(&self, normalized: &mut String, segment: &String, absolute: boolean): void
appendParentSegment(&self, normalized: &mut String, segment: &String, absolute: boolean): void
asStr(&self): str

Borrows the path as a str (const char*).

The returned pointer is valid for the lifetime of this PathBuf. Suitable for passing to libc functions that expect C strings.

clone(&self): PathBuf

Returns a deep copy of this PathBuf.

drop(&mut self): void

Releases the backing String buffer.

Called automatically when the PathBuf goes out of scope.

extension(&self): Option<String>

Returns the extension of the file name, or NONE if there is no file name or no extension.

The extension is the portion after the last . in the file name. A leading dot (.bashrc, .gitignore) is not treated as an extension separator — those files have no extension.

  • "photo.tar.gz" → SOME("gz")
  • ".bashrc" → NONE
  • "Makefile" → NONE
  • "archive.tar" → SOME("tar")
fileName(&self): Option<String>

Returns the final component of the path, or NONE if the path is empty or consists entirely of separators (i.e. root /).

Trailing separators are ignored:

  • "/usr/bin/" → SOME("bin")
  • "/usr/bin" → SOME("bin")
  • "/" → NONE
  • "" → NONE
isAbsolute(&self): boolean

Returns true if the path starts with /.

isCurrentDirSegment(&self, segment: &String): boolean
isEmpty(&self): boolean

Returns true if the path contains no bytes.

isParentDirSegment(&self, segment: &String): boolean
isRelative(&self): boolean

Returns true when the path is not absolute.

isSegmentBoundary(&self, index: u64, len: u64): boolean
isSeparatorAt(&self, index: u64): boolean
join(&self, part: str): PathBuf

Returns a new PathBuf with part joined onto self.

Equivalent to cloning self and calling push(part).

lastSegmentIsParent(&self, normalized: &mut String): boolean
lastSegmentStart(&self, value: &mut String): u64
lastSepBefore(&self, limit: u64): u64

Index of the last / within bytes 0..limit.

Returns limit (an impossible index) if no separator is found, to avoid Option overhead in internal helpers.

normalize(&self): PathBuf

Returns a lexically normalized path without touching the filesystem.

parent(&self): Option<PathBuf>

Returns the parent directory, or NONE if the path has no parent (empty path, single component, or root /).

  • "/usr/local/bin" → SOME("/usr/local")
  • "/usr/local/bin/" → SOME("/usr/local")
  • "/foo" → SOME("/")
  • "/" → NONE
  • "foo" → NONE
  • "" → NONE
pop(&mut self): boolean

Removes the last component from the path.

Returns true if a component was removed, false if the path has no parent (and was left unchanged).

After pop, the path equals what parent() would have returned.

popLastSegment(&self, normalized: &mut String, keepRoot: boolean): void
push(&mut self, part: str): void

Appends a path component to this path.

POSIX join semantics:

  • If part starts with /, it is absolute and replaces the entire path.
  • If self is empty, self becomes part.
  • If self already ends with /, part is concatenated directly.
  • Otherwise a / separator is inserted between self and part.
stringCharEquals(&self, value: &String, index: u64, expected: char): boolean
stringMutCharEquals(&self, value: &mut String, index: u64, expected: char): boolean
stripTrailingLen(&self): u64

Effective length ignoring trailing /.

"/foo/bar/" → 8, "/" → 0, "" → 0.

toString(&self): String

Returns a clone of the inner String.

truncateNormalized(&self, normalized: &mut String, index: i64, keepRoot: boolean): void

Functions

function __closure_thunk_0(__closure_env_0: *mut u8, b: u8): boolean

Constants

const DOT_BYTE: u8
const SEP: char