relative-path

relative-path is a Rust crate providing a module analogous to std::path, but purpose-built for portable relative paths. It fixes the path separator to / regardless of platform, guarantees paths are always valid UTF-8, and requires you to explicitly say what a relative path is relative to before resolving it to a real filesystem location.

This makes it ideal for paths that need to behave identically across operating systems - configuration files, archive entries, manifests, and serialized data - where the platform-dependent behavior of the standard library’s Path would otherwise cause subtle bugs.

What You Get

• RelativePath and owned RelativePathBuf types mirroring the std::path API
• A fixed / separator and guaranteed valid UTF-8 on every platform
• Explicit resolution to real paths via to_path and to_logical_path
• Cross-platform-consistent operations like join, normalize, components, and strip_prefix
• Optional Serde support for serializing and deserializing relative paths

Common Use Cases

• Storing file references in config files or manifests that must be identical across operating systems
• Representing entries inside archives, bundles, or virtual filesystems
• Serializing paths to JSON or other formats with deterministic, portable output
• Building path logic that must not accidentally depend on the host platform’s separator or encoding

Under The Hood

Architecture - The crate mirrors std::path’s split between a borrowed slice type and an owned buffer: RelativePath (an unsized str-backed type in src/lib.rs) and RelativePathBuf (src/relative_path_buf.rs). Iteration is modeled with Component/Components/Iter, and conversions from OS paths go through FromPathError/FromPathErrorKind. Because separators are fixed to /, normalization and component parsing are implemented directly rather than deferring to the platform, and path_ext.rs adds extension traits for interop with std::path.

Tech Stack - Pure Rust with no required runtime dependencies; Serde is an optional feature-gated dependency for (de)serialization. Distributed as part of a small two-crate Cargo workspace alongside relative-path-utils.

Code Quality - The crate is well tested with an in-crate tests.rs plus numerous inline #[test] cases across lib.rs and path_ext.rs, is thoroughly documented (the README is generated from crate docs), and follows idiomatic Rust API conventions closely modeled on the standard library.

API Design - By deliberately mirroring std::path, the crate has almost no learning curve for Rust developers: the method names (join, components, strip_prefix, normalize) are the ones they already know. The key design choice - forcing an explicit anchor before resolving to a filesystem path - turns a common cross-platform footgun into a compile-time-visible step.