Struct Path 

pub struct Path { /* private fields */ }

An immutable Willow Path. Thread-safe, cheap to clone, cheap to take prefixes of, expensive to append to (linear time complexity).

A Willow25 Path is any sequence of bytestrings — called Components — fulfilling certain constraints:

• each Component has a length of at most 4096 (MCL),
• each Path has at most 4096 (MCC) components, and
• the total size in bytes of all Components is at most 4096 (MPL).

This type statically enforces these invariants for all (safely) created instances.

Because appending Components takes time linear in the length of the full Path, you should not build up Paths this way. Instead, use Path::from_components, Path::from_slices, Path::from_components_iter, Path::from_slices_iter, or a PathBuilder. If you statically know the path in advance, use the path! macro.

use willow25::prelude::*;
let p: Path = path!("/hi/ho");

assert_eq!(p.component_count(), 2);
assert_eq!(p.component(1), Some(Component::new(b"ho")?));
assert_eq!(p.total_length(), 4);
assert!(p.is_prefixed_by(&Path::from_slice(b"hi")?));
assert_eq!(
    p.longest_common_prefix(&path!("/hi/he")),
    Path::from_slice(b"hi")?
);

Implementations

impl Path

pub fn new() -> Self

Returns an empty Path, i.e., a Path of zero Components.

Complexity

Runs in O(1).

Examples

use willow25::prelude::*;
assert_eq!(Path::new().component_count(), 0);
assert_eq!(Path::new(), Path::default());
assert_eq!(Path::new(), path!(""));

pub fn from_component(comp: &Component) -> Result<Self, PathFromComponentsError>

Creates a singleton Path, consisting of exactly one Component.

Copies the bytes of the Component into an owned allocation on the heap.

Complexity

Runs in O(n), where n is the length of the Component. Performs a single allocation of O(n) bytes.

Examples

use willow25::prelude::*;
let p = Path::from_component(component!("hi"))?;
assert_eq!(p.component_count(), 1);

pub fn from_slice(comp: &[u8]) -> Result<Self, PathError>

Creates a singleton Path, consisting of exactly one Component, from a raw slice of bytes.

Copies the bytes into an owned allocation on the heap.

Complexity

Runs in O(n), where n is the length of the Component. Performs a single allocation of O(n) bytes.

Examples

use willow25::prelude::*;
let p = Path::from_slice(b"hi")?;
assert_eq!(p.component_count(), 1);

assert_eq!(
    Path::from_slice(b"too_loooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong"),
    Err(PathError::ComponentTooLong),
);

pub fn from_components( components: &[&Component], ) -> Result<Self, PathFromComponentsError>

Creates a Path from a slice of Components.

Copies the bytes of the Components into an owned allocation on the heap.

Complexity

Runs in O(n + m), where n is the total length of the created Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let components: Vec<&Component> = vec![
    component!("hi"),
    component!("ho"),
];

assert!(Path::from_components(&components[..]).is_ok());

pub fn from_slices(slices: &[&[u8]]) -> Result<Self, PathError>

Create a new Path from a slice of byte slices.

Complexity

Runs in O(n + m), where n is the total length of the created Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Example

use willow25::prelude::*;
// Ok
let path = Path::from_slices(&[b"alfie", b"notes"]).unwrap();

// Err
let result1 = Path::from_slices(&[
  b"tooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo",
  b"looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong",
]);
assert_eq!(result1, Err(PathError::PathTooLong));

// Err
let result2 = Path::from_slices(vec![b"".as_slice(); MCC + 1].as_slice());
assert_eq!(result2, Err(PathError::TooManyComponents));

pub fn from_components_iter<'c, I>( total_length: usize, iter: &mut I, ) -> Result<Self, PathFromComponentsError>

where I: ExactSizeIterator<Item = &'c Component>,

Creates a Path of known total length from an ExactSizeIterator of Components.

Copies the bytes of the Components into an owned allocation on the heap.

Panics if the claimed total_length does not match the sum of the lengths of all the Components.

Complexity

Runs in O(n + m), where n is the total length of the created Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let components: Vec<&Component> = vec![
    component!("hi"),
    component!("ho"),
];

assert!(Path::from_components_iter(4, &mut components.into_iter()).is_ok());

pub fn from_slices_iter<'a, I>( total_length: usize, iter: &mut I, ) -> Result<Self, PathError>

where I: ExactSizeIterator<Item = &'a [u8]>,

Creates a Path of known total length from an ExactSizeIterator of byte slices.

Copies the bytes of the Components into an owned allocation on the heap.

Panics if the claimed total_length does not match the sum of the lengths of all the Components.

Complexity

Runs in O(n + m), where n is the total length of the created Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let components: Vec<&[u8]> = vec![b"hi", b"!"];
assert!(Path::from_slices_iter(3, &mut components.into_iter()).is_ok());

pub fn append_component( &self, comp: &Component, ) -> Result<Self, PathFromComponentsError>

Creates a new Path by appending a Component to &self.

Creates a fully separate copy of the new data on the heap; which includes cloning all data in &self. To efficiently construct Paths, use Path::from_components, Path::from_slices, Path::from_components_iter, Path::from_slices_iter, or a PathBuilder.

Complexity

Runs in O(n + m), where n is the total length of the resulting Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let p0: Path = Path::new();
let p1 = p0.append_component(component!("hi"))?;
let p2 = p1.append_component(component!("ho"))?;
assert_eq!(
    p2.append_component(component!("too_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong")),
    Err(PathFromComponentsError::PathTooLong),
);

pub fn append_slice(&self, comp: &[u8]) -> Result<Self, PathError>

Creates a new Path by appending a slice as a new Component to &self.

Creates a fully separate copy of the new data on the heap; which includes cloning all data in &self. To efficiently construct Paths, use Path::from_components, Path::from_slices, Path::from_components_iter, Path::from_slices_iter, or a PathBuilder.

Complexity

Runs in O(n + m), where n is the total length of the resulting Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let p0: Path = Path::new();
let p1 = p0.append_slice(b"hi")?;
let p2 = p1.append_slice(b"ho")?;
assert_eq!(
    p2.append_slice(b"too_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong"),
    Err(PathError::PathTooLong),
);

pub fn append_components( &self, components: &[&Component], ) -> Result<Self, PathFromComponentsError>

Creates a new Path by appending a slice of Components to &self.

Creates a fully separate copy of the new data on the heap; which includes cloning all data in &self. To efficiently construct Paths, use Path::from_components, Path::from_slices, Path::from_components_iter, Path::from_slices_iter, or a PathBuilder.

Complexity

Runs in O(n + m), where n is the total length of the resulting Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let p0: Path = Path::new();
let p1 = p0.append_components(&[component!("hi"), component!("ho")])?;
assert_eq!(
    p1.append_components(&[Component::new(b"too_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong")?]),
    Err(PathFromComponentsError::PathTooLong),
);

pub fn append_slices(&self, components: &[&[u8]]) -> Result<Self, PathError>

Creates a new Path by appending a slice of byte slices as new Components to &self.

Creates a fully separate copy of the new data on the heap; which includes cloning all data in &self. To efficiently construct Paths, use Path::from_components, Path::from_slices, Path::from_components_iter, Path::from_slices_iter, or a PathBuilder.

Complexity

Runs in O(n + m), where n is the total length of the resulting Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let p0: Path = Path::new();
let p1 = p0.append_slices(&[b"hi", b"ho"])?;
assert_eq!(
    p1.append_slices(&[b"too_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong"]),
    Err(PathError::PathTooLong),
);

pub fn append_path(&self, other: &Path) -> Result<Self, PathFromComponentsError>

Creates a new Path by appending another Path to &self.

Creates a fully separate copy of the new data on the heap; which includes cloning all data in &self and in &other.

Complexity

Runs in O(n + m), where n is the total length of the resulting Path in bytes, and m is the number of its Components. Performs a single allocation of O(n + m) bytes.

Examples

use willow25::prelude::*;
let p0: Path = Path::new();
let p1 = p0.append_path(&path!("/hi/ho"))?;
assert_eq!(
    p1.append_path(&Path::from_slice(b"too_looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong")?),
    Err(PathFromComponentsError::PathTooLong),
);

pub fn greater_but_not_prefixed(&self) -> Option<Self>

Returns the least Path which is strictly greater (lexicographically) than self and which is not prefixed by self; or None if no such Path exists.

Complexity

Runs in O(n + m), where n is the total length of the Path in bytes, and m is the number of Components. Performs a single allocation of O(n + m) bytes.

pub fn component_count(&self) -> usize

Returns the number of Components in &self.

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.component_count(), 2);

pub fn is_empty(&self) -> bool

Returns whether &self has zero Components.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
assert_eq!(Path::new().is_empty(), true);

let p: Path = path!("/hi/ho");
assert_eq!(p.is_empty(), false);

pub fn total_length(&self) -> usize

Returns the sum of the lengths of all Components in &self.

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.total_length(), 4);

pub fn total_length_of_prefix(&self, i: usize) -> usize

Returns the sum of the lengths of the first i Components in &self; panics if i >= self.component_count(). More efficient than path.create_prefix(i).path_length().

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.total_length_of_prefix(0), 0);
assert_eq!(p.total_length_of_prefix(1), 2);
assert_eq!(p.total_length_of_prefix(2), 4);

pub fn is_prefix_of(&self, other: &Self) -> bool

Tests whether &self is a prefix of the given Path. Paths are always a prefix of themselves, and the empty Path is a prefix of every Path.

Complexity

Runs in O(n + m), where n is the total length of the longer Path in bytes, and m is the greatest number of Components.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert!(Path::new().is_prefix_of(&p));
assert!(path!("/hi").is_prefix_of(&p));
assert!(path!("/hi/ho").is_prefix_of(&p));
assert!(!path!("/hi/gh").is_prefix_of(&p));

pub fn is_prefixed_by(&self, other: &Self) -> bool

Tests whether &self is prefixed by the given Path. Paths are always prefixed by themselves, and by the empty Path.

Complexity

Runs in O(n + m), where n is the total length of the longer Path in bytes, and m is the greatest number of Components.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert!(p.is_prefixed_by(&Path::new()));
assert!(p.is_prefixed_by(&path!("/hi")));
assert!(p.is_prefixed_by(&path!("/hi/ho")));
assert!(!p.is_prefixed_by(&path!("/hi/gh")));

pub fn is_related_to(&self, other: &Self) -> bool

Tests whether &self is related to the given Path, that is, whether either one is a prefix of the other.

Complexity

Runs in O(n + m), where n is the total length of the longer Path in bytes, and m is the greatest number of Components.

Examples

use willow25::prelude::*;
let p: Path = Path::from_slice(b"hi")?;
assert!(p.is_related_to(&Path::new()));
assert!(p.is_related_to(&path!("/hi")));
assert!(p.is_related_to(&path!("/hi/ho")));
assert!(!p.is_related_to(&path!("/no")));

pub fn prefix_cmp(&self, other: &Self) -> Option<Ordering>

Returns the Ordering describing the prefix relation between self and other.

Complexity

Runs in O(n + m), where n is the total length of the longer Path in bytes, and m is the greatest number of Components.

Examples

use core::cmp::Ordering;
use willow25::prelude::*;
let p: Path = Path::from_slice(b"hi")?;
assert_eq!(p.prefix_cmp(&Path::new()), Some(Ordering::Greater));
assert_eq!(p.prefix_cmp(&path!("/hi")), Some(Ordering::Equal));
assert_eq!(p.prefix_cmp(&path!("/hi/ho")), Some(Ordering::Less));
assert_eq!(p.prefix_cmp(&path!("/no")), None);

pub fn component(&self, i: usize) -> Option<&Component>

Returns the i-th Component of &self.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.component(0), Some(component!("hi")));
assert_eq!(p.component(1), Some(Component::new(b"ho")?));
assert_eq!(p.component(2), None);

pub unsafe fn component_unchecked(&self, i: usize) -> &Component

Returns the i-th Component of &self, without checking whether i < self.component_count().

Safety

Undefined behaviour if i >= self.component_count().

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(unsafe { p.component_unchecked(0) }, component!("hi"));
assert_eq!(unsafe { p.component_unchecked(1) }, Component::new(b"ho")?);

pub fn owned_component(&self, i: usize) -> Option<OwnedComponent>

Returns an owned handle to the i-th component of &self.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.owned_component(0), Some(OwnedComponent::new(b"hi")?));
assert_eq!(p.owned_component(1), Some(OwnedComponent::new(b"ho")?));
assert_eq!(p.owned_component(2), None);

pub unsafe fn owned_component_unchecked(&self, i: usize) -> OwnedComponent

Returns an owned handle to the i-th component of &self, without checking whether i < self.component_count().

Safety

Undefined behaviour if i >= self.component_count().

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.owned_component(0), Some(OwnedComponent::new(b"hi")?));
assert_eq!(p.owned_component(1), Some(OwnedComponent::new(b"ho")?));
assert_eq!(p.owned_component(2), None);

pub fn components( &self, ) -> impl DoubleEndedIterator<Item = &Component> + ExactSizeIterator<Item = &Component>

Creates an iterator over the Components of &self.

Stepping the iterator takes O(1) time and performs no memory allocations.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
let mut comps = p.components();
assert_eq!(comps.next(), Some(component!("hi")));
assert_eq!(comps.next(), Some(Component::new(b"ho")?));
assert_eq!(comps.next(), None);

pub fn suffix_components( &self, i: usize, ) -> impl DoubleEndedIterator<Item = &Component> + ExactSizeIterator<Item = &Component>

Creates an iterator over the Components of &self, starting at the i-th Component. If i is greater than or equal to the number of Components, the iterator yields zero items.

Stepping the iterator takes O(1) time and performs no memory allocations.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
let mut comps = p.suffix_components(1);
assert_eq!(comps.next(), Some(Component::new(b"ho")?));
assert_eq!(comps.next(), None);

pub fn owned_components( &self, ) -> impl DoubleEndedIterator<Item = OwnedComponent> + ExactSizeIterator<Item = OwnedComponent> + '_

Creates an iterator over owned handles to the components of &self.

Stepping the iterator takes O(1) time and performs no memory allocations.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
let mut comps = p.owned_components();
assert_eq!(comps.next(), Some(OwnedComponent::new(b"hi")?));
assert_eq!(comps.next(), Some(OwnedComponent::new(b"ho")?));
assert_eq!(comps.next(), None);

pub fn suffix_owned_components( &self, i: usize, ) -> impl DoubleEndedIterator<Item = OwnedComponent> + ExactSizeIterator<Item = OwnedComponent> + '_

Creates an iterator over owned handles to the components of &self, starting at the i-th OwnedComponent. If i is greater than or equal to the number of OwnedComponent, the iterator yields zero items.

Stepping the iterator takes O(1) time and performs no memory allocations.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
let mut comps = p.suffix_owned_components(1);
assert_eq!(comps.next(), Some(OwnedComponent::new(b"ho")?));
assert_eq!(comps.next(), None);

pub fn create_prefix(&self, component_count: usize) -> Option<Self>

Creates a new Path that consists of the first component_count Components of &self. More efficient than creating a new Path from scratch.

Returns None if component_count is greater than self.get_component_count().

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(p.create_prefix(0), Some(Path::new()));
assert_eq!(p.create_prefix(1), Some(Path::from_slice(b"hi")?));
assert_eq!(p.create_prefix(2), Some(path!("/hi/ho")));
assert_eq!(p.create_prefix(3), None);

pub unsafe fn create_prefix_unchecked(&self, component_count: usize) -> Self

Creates a new Path that consists of the first component_count Components of &self. More efficient than creating a new Path from scratch.

Safety

Undefined behaviour if component_count is greater than self.component_count(). May manifest directly, or at any later function invocation that operates on the resulting Path.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
assert_eq!(unsafe { p.create_prefix_unchecked(0) }, Path::new());
assert_eq!(unsafe { p.create_prefix_unchecked(1) }, Path::from_slice(b"hi")?);
assert_eq!(unsafe { p.create_prefix_unchecked(2) }, path!("/hi/ho"));

pub fn all_prefixes(&self) -> impl DoubleEndedIterator<Item = Self> + '_

Creates an iterator over all prefixes of &self (including the empty Path and &self itself).

Stepping the iterator takes O(1) time and performs no memory allocations.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow25::prelude::*;
let p: Path = path!("/hi/ho");
let mut prefixes = p.all_prefixes();
assert_eq!(prefixes.next(), Some(Path::new()));
assert_eq!(prefixes.next(), Some(Path::from_slice(b"hi")?));
assert_eq!(prefixes.next(), Some(path!("/hi/ho")));
assert_eq!(prefixes.next(), None);

pub fn longest_common_prefix(&self, other: &Self) -> Self

Returns the longest common prefix of &self and the given Path.

Complexity

Runs in O(n + m), where n is the total length of the shorter of the two Paths, and m is the lesser number of Components. Performs a single allocation of O(n + m) bytes to create the return value.

Examples

use willow25::prelude::*;
let p1: Path = path!("/hi/ho");
let p2: Path = path!("/hi/he");
assert_eq!(p1.longest_common_prefix(&p2), Path::from_slice(b"hi")?);

pub unsafe fn create_slice_unchecked<R>(&self, range: R) -> Self

where R: RangeBounds<usize>,

Creates a Path whose Components are those of &self indexed by the given range, without checking that those components exist.

Safety

Undefined behaviour if either the start or the end of range are explicitly greater than self.component_count(), or if range is decreasing.

Complexity

Runs in O(1) and performs no allocations.

Examples

use willow25::prelude::*;
let p = path!("/hi/ho");
assert_eq!(unsafe{p.create_slice_unchecked(..)}, p);
assert_eq!(unsafe{p.create_slice_unchecked(..1)}, path!("/hi"));
assert_eq!(unsafe{p.create_slice_unchecked(1..)}, path!("/ho"));
assert_eq!(unsafe{p.create_slice_unchecked(1..1)}, Path::new());

pub fn create_slice<R>(&self, range: R) -> Option<Self>

where R: RangeBounds<usize>,

Creates a Path whose Components are those of &self indexed by the given range. Returns None if either the start or end of range are explicitly greater than &self.component_count() or if range is decreasing.

Complexity

Runs in O(1) and performs no allocations.

Examples

use willow25::prelude::*;
let p = path!("/hi/ho");
assert_eq!(p.create_slice(..), Some(p.clone()));
assert_eq!(p.create_slice(1..2), Some(path!("/ho")));
assert_eq!(p.create_slice(1..3), None);
assert_eq!(p.create_slice(2..1), None);

pub unsafe fn create_suffix_unchecked(&self, component_count: usize) -> Self

Creates a Path whose Components are the last component_count components of &self, without checking that &self has at least component_count components.

Safety

Undefined behaviour if component_count > self.component_count.

Complexity

Runs in O(1) and performs no allocations.

Examples

use willow25::prelude::*;
let p = path!("/a/b/c/d");
assert_eq!(unsafe{p.create_suffix_unchecked(2)}, path!("/c/d"));
assert_eq!(unsafe{p.create_suffix_unchecked(0)}, Path::new());

pub fn create_suffix(&self, component_count: usize) -> Option<Self>

Creates a Path whose Components are the last component_count components of &self. Returns None if &self does not have at least component_count components.

Complexity

Runs in O(1) and performs no allocations.

Examples

use willow25::prelude::*;

let p = path!("/hi/ho");
assert_eq!(p.create_suffix(0), Some(Path::new()));
assert_eq!(p.create_suffix(1), Some(path!("/ho")));
assert_eq!(p.create_suffix(2), Some(path!("/hi/ho")));
assert_eq!(p.create_suffix(3), None);

Trait Implementations

impl Clone for Path

fn clone(&self) -> Path

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Path

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

Formats the value using the given formatter.

impl Decodable for Path

Implements EncodePath.

type ErrorReason = Blame

Reason why decoding can fail (beyond an unexpected end of input or a producer error).

async fn decode<P>( producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>

where P: BulkProducer<Item = u8> + ?Sized,

Decodes the symbols produced by the given bulk producer into a Self, or yields an error if the producer does not produce a valid encoding.

impl DecodableCanonic for Path

Implements encode_path.

type ErrorCanonic = Blame

The type for reporting that the sequence of symbols to decode was not a valid canonic encoding of any value of type Self.

async fn decode_canonic<P>( producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorCanonic>>

where P: BulkProducer<Item = u8> + ?Sized,

Decodes the symbols produced by the given bulk producer into a Self, and errors if the input encoding is not the canonical one.

impl Default for Path

The default Path is the empty Path.

fn default() -> Self

Returns an empty Path.

Examples

use willow25::prelude::*;
assert_eq!(Path::default().component_count(), 0);
assert_eq!(Path::default(), Path::new());

impl Display for Path

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

Formats the value using the given formatter.

impl Encodable for Path

Implements encode_path.

async fn encode<C>(&self, consumer: &mut C) -> Result<(), C::Error>

where C: BulkConsumer<Item = u8> + ?Sized,

Writes an encoding of &self into the given bulk consumer.

impl EncodableKnownLength for Path

Implements encode_path.

fn len_of_encoding(&self) -> usize

Computes the number of symbols of the encoding of self. A successful call to encode must feed exactly that many symbols into the bulk consumer.

impl Eq for Path

impl GreatestElement for Path

fn greatest() -> Self

Creates the greatest possible Path (with respect to lexicographical ordering, which is also the Ord implementation of Path).

It consists of a single component of 255 bytes, followed by 4095 empty components.

Complexity

Runs in O(MCC + MPL). Performs a single allocation of O(MPL) bytes.

Examples

use willow25::prelude::*;
use order_theory::GreatestElement;

let p = Path::greatest();
assert_eq!(p.component_count(), 4096);
assert_eq!(p.component(0).unwrap().len(), 4096);
assert!(p.component(1).unwrap().is_empty());
assert!(p.component(4095).unwrap().is_empty());

fn is_greatest(&self) -> bool

Returns true if and only if self is the greatest element.

impl Hash for Path

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LeastElement for Path

The least path is the empty path.

fn least() -> Self

Returns the least path.

fn is_least(&self) -> bool

Returns true if and only if self is the least element.

impl LowerSemilattice for Path

fn greatest_lower_bound(&self, other: &Self) -> Self

Returns the greatest lower bound of self and other, i.e., the unique greatest element in the type which is less than or equal to both self and other.

impl Ord for Path

Compares paths lexicographically, since that is the path ordering that the Willow spec always uses.

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Path

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Path

Compares paths lexicographically, since that is the path ordering that the Willow spec always uses.

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PredecessorExceptForLeast for Path

impl RangeBounds<Path> for Range3d

fn start_bound(&self) -> Bound<&Path>

Start index bound.

fn end_bound(&self) -> Bound<&Path>

End index bound.

fn contains<U>(&self, item: &U) -> bool

where T: PartialOrd<U>, U: PartialOrd<T> + ?Sized,

Returns true if item is contained in the range.

fn is_empty(&self) -> bool

where T: PartialOrd,

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

Returns true if the range contains no items. One-sided ranges (RangeFrom, etc) always return false.

impl RelativeDecodable<Path> for Path

Implements EncodePathRelativePath.

type ErrorReason = Blame

Reason why decoding can fail (beyond an unexpected end of input or a producer error).

async fn relative_decode<P>( rel: &Path, producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Blame>>

where P: BulkProducer<Item = u8> + ?Sized,

Decodes the symbols produced by the given bulk producer relative to rel into a Self, or yields an error if the producer does not produce a valid relative encoding.

impl RelativeDecodable<Path> for CodecPathExtendsPath

Implements EncodePathExtendsPath.

type ErrorReason = Blame

Reason why decoding can fail (beyond an unexpected end of input or a producer error).

async fn relative_decode<P>( rel: &Path, producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>

where P: BulkProducer<Item = u8> + ?Sized, Self: Sized,

Decodes the symbols produced by the given bulk producer relative to rel into a Self, or yields an error if the producer does not produce a valid relative encoding.

impl RelativeDecodable<PrivatePathContext> for Path

type ErrorReason = Blame

Reason why decoding can fail (beyond an unexpected end of input or a producer error).

async fn relative_decode<P>( rel: &PrivatePathContext, producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>

where P: BulkProducer<Item = u8> + ?Sized, Self: Sized,

Decodes the symbols produced by the given bulk producer relative to rel into a Self, or yields an error if the producer does not produce a valid relative encoding.

impl RelativeDecodableCanonic<Path> for Path

Implements path_relative_path.

type ErrorCanonic = Blame

The type for reporting that the sequence of symbols to decode was not a valid canonic encoding of any value of type Self.

async fn relative_decode_canonic<P>( rel: &Path, producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Blame>>

where P: BulkProducer<Item = u8> + ?Sized,

Decodes the symbols produced by the given bulk producer relative to rel into a Self, and errors if the input encoding is not the canonical one.

impl RelativeDecodableCanonic<Path> for CodecPathExtendsPath

Implements path_extends_path.

type ErrorCanonic = Blame

The type for reporting that the sequence of symbols to decode was not a valid canonic encoding of any value of type Self.

async fn relative_decode_canonic<P>( rel: &Path, producer: &mut P, ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>

where P: BulkProducer<Item = u8> + ?Sized, Self: Sized,

Decodes the symbols produced by the given bulk producer relative to rel into a Self, and errors if the input encoding is not the canonical one.

impl RelativeEncodable<Path> for Path

Implements path_rel_path.

fn can_be_encoded_relative_to(&self, _rel: &Path) -> bool

Any path can be encoded relative to every path.

async fn relative_encode<Consumer>( &self, rel: &Path, consumer: &mut Consumer, ) -> Result<(), Consumer::Error>

where Consumer: BulkConsumer<Item = u8> + ?Sized,

Writes an encoding of &self relative to rel into the given bulk consumer.

impl RelativeEncodable<Path> for CodecPathExtendsPath

Implements path_extends_path.

fn can_be_encoded_relative_to(&self, rel: &Path) -> bool

Returns true iff rel is a prefix of self.

async fn relative_encode<C>( &self, rel: &Path, consumer: &mut C, ) -> Result<(), C::Error>

where C: BulkConsumer<Item = u8> + ?Sized,

Writes an encoding of &self relative to rel into the given bulk consumer.

impl RelativeEncodable<PrivatePathContext> for Path

fn can_be_encoded_relative_to(&self, rel: &PrivatePathContext) -> bool

Reports false if the path is not a prefix of rel.rel, OR if self is not related to to rel.private.

async fn relative_encode<C>( &self, rel: &PrivatePathContext, consumer: &mut C, ) -> Result<(), C::Error>

where C: BulkConsumer<Item = u8> + ?Sized,

Writes an encoding of &self relative to rel into the given bulk consumer.

impl RelativeEncodableKnownLength<Path> for Path

Implements path_rel_path.

fn len_of_relative_encoding(&self, rel: &Path) -> usize

Computes the number of symbols of the encoding of self, relative to rel. A successful call to relative_encode must feed exactly that many symbols into the bulk consumer.

impl RelativeEncodableKnownLength<Path> for CodecPathExtendsPath

Implements path_extends_path.

fn len_of_relative_encoding(&self, rel: &Path) -> usize

Computes the number of symbols of the encoding of self, relative to rel. A successful call to relative_encode must feed exactly that many symbols into the bulk consumer.

impl SuccessorExceptForGreatest for Path

impl TryPredecessor for Path

fn try_predecessor(&self) -> Option<Self>

If self has a predecessor, i.e., a unique greatest value which is strictly less than self, returns it. If there is no unique predecessor, returns None.

fn is_predecessor_of(&self, other: &Self) -> bool

Returns true iff self is the predecessor of other.

fn is_not_predecessor_of(&self, other: &Self) -> bool

Returns true iff self is not the predecessor of other.

impl TrySuccessor for Path

fn try_successor(&self) -> Option<Self>

Returns the least path which is strictly greater than self, or return None if self is the greatest possible path.

Complexity

Runs in O(n + m), where n is the total length of the Path in bytes, and m is the number of Components. Performs a single allocation of O(n + m) bytes.

fn is_successor_of(&self, other: &Self) -> bool

Returns true iff self is the successor of other.

fn is_not_successor_of(&self, other: &Self) -> bool

Returns true iff self is not the successor of other.

impl UpperSemilattice for Path

fn least_upper_bound(&self, other: &Self) -> Self

Returns the least upper bound of self and other, i.e., the unique least element in the type which is greater than or equal to both self and other.