Skip to main content

Crate gix_path

Crate gix_path 

Source
Expand description

This crate contains an assortment of utilities to deal with paths and their conversions.

Git treats paths as bytes, using UTF-8 for native path conversion on Windows. Paths in Git files use slashes as separators, with conversions to native separators performed on Windows as needed.

§Examples

use bstr::ByteSlice;

use std::path::Path;

let normalized = gix_path::normalize(Path::new("a/./b/..").into(), Path::new("/cwd")).unwrap();
assert_eq!(normalized.as_ref(), Path::new("a"));

let unix = gix_path::to_unix_separators(b"dir\\subdir\\file".as_bstr());
assert_eq!(unix.as_ref(), b"dir/subdir/file".as_bstr());

§Path encodings

Unix paths contain arbitrary bytes, which these conversions preserve without UTF-8 validation. Windows paths use potentially ill-formed UTF-16: even modern Windows permits unpaired surrogate code units. Such paths cannot be represented losslessly as UTF-8, so conversion to Git path bytes returns an error. Likewise, converting Git path bytes to a native path requires valid UTF-8 on non-Unix platforms. Valid surrogate pairs, including those used for emoji, convert normally.

Conversions preserve borrowed and owned inputs and report encoding failures through gix_error::Result, retaining the concrete encoding error as a source.

Modules§

env
Information about the environment in terms of locations of resources.
realpath
relative_path

Structs§

RelativePath
A wrapper for BStr. It is used to enforce the following constraints:

Functions§

from_bstr
Similar to from_byte_slice(), but takes either borrowed or owned input.
from_bstring
Similar to from_bstr(), but takes and produces owned data.
from_byte_slice
Given input bytes, produce a Path from them ignoring encoding entirely if on Unix.
into_bstr
Convert the given path either into its raw bytes on Unix or its UTF-8 encoded counterpart on non-Unix platforms.
is_absolute
return true if path is absolute, which depends on the platform but is always true if it starts with a slash, hence looks like a linux path.
join_bstr_unix_pathsep
Join path to base such that they are separated with a /, i.e. base/path.
normalize
Resolve relative components virtually, eliminating intermediate .. without accessing the filesystem.
normalize_and_clean
Like normalize(), but also removes . components and duplicate or trailing separators.
normalize_saturating
Like normalize(), but treats .. components beyond the filesystem root as no-ops. Returns an error if normalization exhausts an empty or relative current_dir.
os_str_into_bstr
Like into_bstr(), but takes OsStr as input for a lossless, but fallible, conversion.
os_string_into_bstring
Like into_bstr(), but takes OsString as input for a lossless, but fallible, conversion.
realpath
Check each component of path and see if it is a symlink. If so, resolve it. Do not fail for non-existing components, but assume these are as is.
realpath_opts
The same as realpath(), but allow to configure max_symlinks to configure how many symbolic links we are going to follow. This serves to avoid running into cycles or doing unreasonable amounts of work.
relativize_with_prefix
Rebuild relative_path to be relative to prefix, such as the user’s current working directory.
to_native_path_on_windows
Convert paths with slashes to backslashes on Windows and do nothing on Unix, returning an error for invalid UTF-8 on non-Unix platforms.
to_native_separators
Assures the given bytes use the native path separator.
to_unix_separators
Replace Windows path separators with slashes, which typically resembles a Unix path, unconditionally.
to_unix_separators_on_windows
Replace Windows path separators with slashes, but only do so on Windows.
to_windows_separators
Find slashes and replace them with backslashes, unconditionally.
try_os_str_into_bstr
Like into_bstr(), but takes Cow<OsStr> as input for a lossless, but fallible, conversion.
windows_drive_prefix
Return the leading Windows drive prefix, including :, if present, on any platform. Virtual drives created with subst can use any Unicode character instead of an ASCII letter.