Crate pth 

Module :: pth

Collection of algorithms and structures to handle paths properly.

All functions in the crate don’t touch file system, but only process paths.

Scope

Responsibility:

• Pure path manipulation library with zero filesystem access
• Type-safe absolute path enforcement (AbsolutePath type)
• Zero-allocation path conversion traits (AsPath, TryIntoPath, TryIntoCowPath)
• Architecture improvement via absolute path preference

In Scope:

• Path manipulation algorithms (no filesystem access)
• AbsolutePath type for guaranteed absolute paths
• AsPath trait (zero-allocation path reference)
• TryIntoPath trait (owned PathBuf conversion)
• TryIntoCowPath trait (borrowed/owned optimization)
• std::path integration (Path, PathBuf, Component types)
• Current directory access via std::env
• Error handling via std::io

Out of Scope:

• ❌ Filesystem operations (read, write, exists, create) → use std::fs
• ❌ no_std support → requires std::path types from stdlib
• ❌ Path validation → only manipulation, not verification
• ❌ File metadata access → use std::fs::metadata
• ❌ Platform-specific path handling → delegates to std::path

Requirements

This crate requires the Rust standard library (std) and is not no_std compatible. This is because:

• Path manipulation relies on std::path types (Path, PathBuf, Component) which are not available in core or alloc
• Many operations require std::io for error handling
• Some functionality depends on std::env for current directory access

If you need path manipulation in no_std environments, consider using simple string-based utilities instead.

Type AbsolutePath

The AbsolutePath type ensures that paths are absolute, which helps reduce issues and maintenance costs associated with relative paths. Relative paths can be problematic as they introduce additional variables and complexities, making code analysis, integration, refactoring, and testing more difficult. By using absolute paths, software architecture can be improved, similar to how avoiding global variables can enhance code quality. It is recommended to use relative paths only at the outskirts of an application.

Trait AsPath

This trait is used to avoid redundant allocation of memory by providing a reference to a Path. It is implemented only for types that can either be referenced or are references to Path itself. Unlike TryIntoPath, it does not allocate memory on the heap. However, TryIntoPath is implemented for a wider range of types because it is not restricted from allocating memory. Unlike AsRef< Path >, AsPath is implemented for a wider number of types, including those that are not directly convertible to a Path using AsRef. This is because AsPath is designed to provide a more flexible interface for path-like types, accommodating various representations that can logically be treated as paths.

Trait TryIntoPath

This trait is used to convert any path-like type into an owned PathBuf. Unlike TryIntoCowPath, it always returns an owned PathBuf, so there is no need to differentiate between borrowed and owned paths at runtime. Unlike AsPath, it is implemented for a wider range of path-like types, similar to TryIntoCowPath.

Trait TryIntoCowPath

This trait is designed to avoid redundant memory allocation. Unlike TryIntoPath, it does not allocate memory on the heap if it’s not necessary. Unlike AsPath, it is implemented for a wider number of path-like types, similar to TryIntoPath. The drawback is the necessity to differentiate borrowed and owned paths at runtime.

Modules

as_path

AsPath trait.

exposed

Exposed namespace of the module.

orphan

Orphan namespace of the module.

own

Own namespace of the module.

path

Basic functionality.

prelude

Prelude to use essentials: use my_module ::prelude :: *.

try_into_cow_path

TryIntoPath trait.

try_into_path

TryIntoPath trait.

Structs

AbsolutePath

A new type representing an absolute path.

CurrentPath

Symbolize current path.

NormalizedPath

A path that has been normalized via syntactic canonicalization.

Path

A slice of a path (akin to str).

PathBuf

An owned, mutable path (akin to String).

Utf8Path

A slice of a UTF-8 path (akin to str).

Utf8PathBuf

An owned, mutable UTF-8 path (akin to String).

Enums

Cow

A clone-on-write smart pointer.

Traits

AsPath

A trait for converting various types into a reference to a Path.

PathJoined

A trait for joining path components into a PathBuf.

TryIntoCowPath

A trait for converting various types into a Cow< Path >.

TryIntoPath

A trait for converting various types into a PathBuf.

Functions

canonicalizeDeprecated

Deprecated: Use normalize_unchecked() instead.

change_ext

Replaces the existing path extension with the provided extension.

ext

Extracts the extension from the given path.

exts

Extracts multiple extensions from the given path.

is_glob

Determines if a given path string contains unescaped glob pattern characters.

iter_join

Joins a list of file system paths into a single absolute path.

normalize

Normalizes a given filesystem path by syntactically removing occurrences of . and properly handling .. components.

normalize_unchecked

Returns the canonical, absolute form of the path with all intermediate components normalized and symbolic links resolved. This function does not touch fs.

path_common

Finds the common directory path among a collection of paths.

path_relative

Computes the relative path from one path to another.

rebase

Rebase the file path relative to a new base path, optionally removing a common prefix.

unique_folder_name

Generates a unique folder name using the current system time, process ID, thread ID, and an internal thread-local counter.

without_ext

Extracts the parent directory and file stem (without extension) from the given path.

Type Aliases

CanonicalPath

Type alias for NormalizedPath.

NativePath

Type alias for NormalizedPath.