sugar_path

Ergonomic path manipulation for Rust — normalize, absolutize, relativize, and slash-convert with zero-cost Cow returns.

Quick start

cargo add sugar_path

use sugar_path::SugarPath;

// Normalize messy paths
assert_eq!("foo/./bar/../baz".normalize(), "foo/baz".as_path());

// Absolutize relative paths
let abs = "src/main.rs".absolutize();

// Get relative paths between two locations
assert_eq!("/a/b/c/d".as_path().relative("/a/b/f/g"), "../../c/d".as_path());

// Cross-platform slash conversion
assert_eq!("hello/world".as_path().to_slash_lossy(), "hello/world");

API overview

All methods are provided by the SugarPath trait, implemented for Path, &str, and String.

Path conversion

Method	Description
`as_path()`	Convert `&str` / `String` to `&Path` — lets you call `SugarPath` methods on strings directly
`to_slash()`	Convert a path to a `/`-separated string (`None` if invalid UTF-8)
`to_slash_lossy()`	Like `to_slash()`, but replaces invalid UTF-8 with `U+FFFD`

use std::path::Path;
use sugar_path::SugarPath;

assert_eq!("foo".as_path().join("bar"), Path::new("foo/bar"));

Normalization

normalize() resolves . and .. segments and collapses repeated separators. Returns Cow::Borrowed when the path is already clean.

use std::path::Path;
use sugar_path::SugarPath;

#[cfg(target_family = "unix")]
assert_eq!(
  Path::new("/foo/bar//baz/asdf/quux/..").normalize(),
  Path::new("/foo/bar/baz/asdf")
);

Absolutize

absolutize() resolves a relative path against the current working directory. absolutize_with() lets you supply a custom base.

use sugar_path::SugarPath;

#[cfg(target_family = "unix")]
{
  assert_eq!("./world".absolutize_with("/hello"), "/hello/world".as_path());
  assert_eq!("../world".absolutize_with("/hello"), "/world".as_path());
}

Relative paths

relative() computes the relative path from self to a target.

use std::path::Path;
use sugar_path::SugarPath;

assert_eq!(Path::new("/base").relative("/base/lib"), Path::new(".."));
assert_eq!(Path::new("/base").relative("/var/lib"), Path::new("../../base"));
assert_eq!(Path::new("/a/b/c/d").relative("/a/b/f/g"), Path::new("../../c/d"));

Features

Feature	Description
`cached_current_dir`	Cache `std::env::current_dir()` so `absolutize()` only reads it once

sugar_path = { version = "2", features = ["cached_current_dir"] }

Performance

Zero-alloc fast paths — methods return Cow<'_, Path>, borrowing the input when no transformation is needed.
memchr-accelerated scanning for separator detection.
SmallVec<[_; 8]> keeps component lists on the stack for typical path depths.

Platform support

Unix and Windows, tested in CI on Ubuntu, macOS, and Windows.
to_slash / to_slash_lossy provide consistent /-separated output across all platforms.
On Windows, forward slashes in input are normalized to \.

License

MIT

sugar_path 2.0.1