Struct ironpath::Relative

pub struct Relative(_);

A relative path that may be joined to an absolute path.

This path obeys the following invariants:

• It is relative, containing no prefix or root directory components.
• It contains only named path components, no /./ or /../ ones.
• It uses the platform-native path-component separator (/ on POSIX, \ on Windows).

Therefore:

• It's always reasonably straight-forward for humans to understand.
• It can safely be appended to an Absolute path or another Relative path without having to revalidatet the invariants.
• Joining a Relative to an Absolute will always produce a path that refers to a child of the Absolute, unless the directory named by the Absolute contains a symilnk to a directory outside it.

Since this type implements AsRef<Path>, it can be used with almost any standard library function that expects a path, but you probably only want to join it to an Absolute path.

Methods

impl Relative

pub fn new<P: AsRef<Path>>(path: P) -> Result<Relative, Error>

Convert an arbitrary path to follow the rules for a Relative path.

• Any /./ components in the path are removed.
• If a named component is followed by a /../ component, they cancel each other out and both are removed. We cannot resolve symlinks here since we do not know what absolute path this path is relative to.

Performance

This validation is performed entirely in memory, with no reference to the filesystem.

Errors

Returns Error::PathIsAbsolute if the given path contains prefix or root directory components, like /usr/share or C:file.txt.

Returns Error::RelativePathEscapesPrefix if any /../ components cannot be normalized away, like a/b/../../../c.

pub fn join<P: AsRef<Path>>(&self, path: P) -> Result<Relative, Error>

Clone this path, attempting to add an arbitrary relative path on the end.

Performance

An expression like:

other_relative_path.join(path)?

...is the same as doing:

other_relative_path.join_relative(&Relative::new(path)?)

...and therefore involves the same allocation and other costs as calling Relative::new() yourself.

If you plan on joining the same relative path to many other Relative paths, it's more efficient to call Relative::new() once yourself and call .join_relative() each time.

Errors

Returns the same errors as Relative::new().

Examples

let config_base = Relative::new("SuperSoftwareCo/MyCoolApp")?;

let video_config = config_base.join("video.cfg")?;
let audio_config = config_base.join("audio.cfg")?;

pub fn join_relative(&self, tail: &Relative) -> Relative

Clone this path, adding the given Relative path on the end.

Performance

Since Relative paths all have the same invariants, no additional checks or processing need to be done, just straight concatenation.

pub fn as_path(&self) -> &Path

Coerces to a Path slice.

Since Relative implements AsRef<Path>, this method is not needed very often—you can often just pass it directly to the thing that needs a Path.

Examples

If you really, really need to convert a Relative to a PathBuf:

let owned_path: std::path::PathBuf = relative.as_path().into();

pub fn as_os_str(&self) -> &OsStr

Coerces to an OsStr slice.

Since Relative implements AsRef<OsStr>, this method is not needed very often—you can often just pass it directly to the thing that needs an OsStr.

Examples

If you really, really need to convert a Relative to a OsString:

let owned_string: std::ffi::OsString = relative.as_os_str().into();

Trait Implementations

impl Eq for Relative

impl PartialOrd<Relative> for Relative

fn partial_cmp(&self, other: &Relative) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Relative) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Relative) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Relative) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Relative) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialEq<Relative> for Relative

fn eq(&self, other: &Relative) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Relative) -> bool

This method tests for !=.

impl AsRef<Path> for Relative

fn as_ref(&self) -> &Path

Performs the conversion.

impl AsRef<OsStr> for Relative

fn as_ref(&self) -> &OsStr

Performs the conversion.

impl Clone for Relative

fn clone(&self) -> Relative

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Ord for Relative

fn cmp(&self, other: &Relative) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl Debug for Relative

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for Relative

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].