Struct Path 

pub struct Path<const MCL: usize, const MCC: usize, const MPL: usize> { /* private fields */ }

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

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

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

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.

use willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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::from_slices(&[b"hi", b"he"])?),
    Path::from_slice(b"hi")?
);

Implementations

impl<const MCL: usize, const MCC: usize, const MPL: usize> Path<MCL, MCC, MPL>

pub fn new() -> Self

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

Complexity

Runs in O(1).

Examples

use willow_data_model::prelude::*;
assert_eq!(Path::<4, 4, 4>::new().component_count(), 0);
assert_eq!(Path::<4, 4, 4>::new(), Path::<4, 4, 4>::default());

pub fn from_component( comp: &Component<MCL>, ) -> 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 willow_data_model::prelude::*;
let p = Path::<4, 4, 4>::from_component(Component::new(b"hi!")?)?;
assert_eq!(p.component_count(), 1);

assert_eq!(
    Path::<4, 4, 2>::from_component(Component::new(b"hi!")?),
    Err(PathFromComponentsError::PathTooLong),
);

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 willow_data_model::prelude::*;
let p = Path::<4, 4, 4>::from_slice(b"hi!")?;
assert_eq!(p.component_count(), 1);

assert_eq!(
    Path::<4, 4, 4>::from_slice(b"too_long_for_single_component"),
    Err(PathError::ComponentTooLong),
);
assert_eq!(
    Path::<4, 3, 1>::from_slice(b"nope"),
    Err(PathError::PathTooLong),
);

pub fn from_components( components: &[&Component<MCL>], ) -> 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 willow_data_model::prelude::*;
let components: Vec<&Component<4>> = vec![
    &Component::new(b"hi")?,
    &Component::new(b"!")?,
];

assert!(Path::<4, 4, 4>::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 willow_data_model::prelude::*;
// Ok
let path = Path::<12, 3, 30>::from_slices(&[b"alfie", b"notes"]).unwrap();

// Err
let result1 = Path::<12, 3, 30>::from_slices(&[b"themaxpath", b"lengthis30", b"thisislonger"]);
assert_eq!(result1, Err(PathError::PathTooLong));

// Err
let result2 = Path::<12, 3, 30>::from_slices(&[b"too", b"many", b"components", b"error"]);
assert_eq!(result2, Err(PathError::TooManyComponents));

// Err
let result3 = Path::<12, 3, 30>::from_slices(&[b"overencumbered"]);
assert_eq!(result3, Err(PathError::ComponentTooLong));

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

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

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 willow_data_model::prelude::*;
let components: Vec<&Component<4>> = vec![
    &Component::new(b"hi")?,
    &Component::new(b"!")?,
];

assert!(Path::<4, 4, 4>::from_components_iter(3, &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 willow_data_model::prelude::*;
let components: Vec<&[u8]> = vec![b"hi", b"!"];
assert!(Path::<4, 4, 4>::from_slices_iter(3, &mut components.into_iter()).is_ok());

pub fn append_component( &self, comp: &Component<MCL>, ) -> 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 willow_data_model::prelude::*;
let p0: Path<4, 4, 4> = Path::new();
let p1 = p0.append_component(Component::new(b"hi")?)?;
let p2 = p1.append_component(Component::new(b"!")?)?;
assert_eq!(
    p2.append_component(Component::new(b"no!")?),
    Err(PathFromComponentsError::PathTooLong),
);

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

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 willow_data_model::prelude::*;
let p0: Path<4, 4, 4> = Path::new();
let p1 = p0.append_slice(b"hi")?;
let p2 = p1.append_slice(b"!")?;
assert_eq!(
    p2.append_slice(b"no!"),
    Err(PathError::PathTooLong),
);

pub fn append_components( &self, components: &[&Component<MCL>], ) -> 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 willow_data_model::prelude::*;
let p0: Path<4, 4, 4> = Path::new();
let p1 = p0.append_components(&[Component::new(b"hi")?, Component::new(b"!")?])?;
assert_eq!(
    p1.append_components(&[Component::new(b"no!")?]),
    Err(PathFromComponentsError::PathTooLong),
);

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

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 willow_data_model::prelude::*;
let p0: Path<4, 4, 4> = Path::new();
let p1 = p0.append_slices(&[b"hi", b"ho"])?;
assert_eq!(
    p1.append_slices(&[b"no!"]),
    Err(PathError::PathTooLong),
);

pub fn append_path( &self, other: &Path<MCL, MCC, MPL>, ) -> 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 willow_data_model::prelude::*;
let p0: Path<4, 4, 4> = Path::new();
let p1 = p0.append_path(&Path::from_slices(&[b"hi", b"ho"])?)?;
assert_eq!(
    p1.append_path(&Path::from_slice(b"no!")?),
    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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
assert_eq!(Path::<4, 4, 4>::new().is_empty(), true);

let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
assert!(Path::new().is_prefix_of(&p));
assert!(Path::from_slice(b"hi")?.is_prefix_of(&p));
assert!(Path::from_slices(&[b"hi", b"ho"])?.is_prefix_of(&p));
assert!(!Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
assert!(p.is_prefixed_by(&Path::new()));
assert!(p.is_prefixed_by(&Path::from_slice(b"hi")?));
assert!(p.is_prefixed_by(&Path::from_slices(&[b"hi", b"ho"])?));
assert!(!p.is_prefixed_by(&Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slice(b"hi")?;
assert!(p.is_related_to(&Path::new()));
assert!(p.is_related_to(&Path::from_slice(b"hi")?));
assert!(p.is_related_to(&Path::from_slices(&[b"hi", b"ho"])?));
assert!(!p.is_related_to(&Path::from_slices(&[b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slice(b"hi")?;
assert_eq!(p.prefix_cmp(&Path::new()), Some(Ordering::Greater));
assert_eq!(p.prefix_cmp(&Path::from_slice(b"hi")?), Some(Ordering::Equal));
assert_eq!(p.prefix_cmp(&Path::from_slices(&[b"hi", b"ho"])?), Some(Ordering::Less));
assert_eq!(p.prefix_cmp(&Path::from_slice(b"no")?), None);

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

Returns the i-th Component of &self.

Complexity

Runs in O(1), performs no allocations.

Examples

use willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
assert_eq!(p.component(0), Some(Component::new(b"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<MCL>

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
assert_eq!(unsafe { p.component_unchecked(0) }, Component::new(b"hi")?);
assert_eq!(unsafe { p.component_unchecked(1) }, Component::new(b"ho")?);

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

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

Complexity

Runs in O(1), performs no allocations.

Examples

use willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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<MCL>

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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<MCL>> + ExactSizeIterator<Item = &Component<MCL>>

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
let mut comps = p.components();
assert_eq!(comps.next(), Some(Component::new(b"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<MCL>> + ExactSizeIterator<Item = &Component<MCL>>

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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<MCL>> + ExactSizeIterator<Item = OwnedComponent<MCL>> + '_

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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<MCL>> + ExactSizeIterator<Item = OwnedComponent<MCL>> + '_

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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"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::from_slices(&[b"hi", b"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 willow_data_model::prelude::*;
let p1: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"ho"])?;
let p2: Path<4, 4, 4> = Path::from_slices(&[b"hi", b"he"])?;
assert_eq!(p1.longest_common_prefix(&p2), Path::from_slice(b"hi")?);

Trait Implementations

impl<'a, const MCL: usize, const MCC: usize, const MPL: usize> Arbitrary<'a> for Path<MCL, MCC, MPL>

Available on crate feature dev only.

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self, ArbitraryError>

Generate an arbitrary value of Self from the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl<const MCL: usize, const MCC: usize, const MPL: usize> Clone for Path<MCL, MCC, MPL>

fn clone(&self) -> Path<MCL, MCC, MPL>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const MCL: usize, const MCC: usize, const MPL: usize> Debug for Path<MCL, MCC, MPL>

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

Formats the value using the given formatter.

impl<const MCL: usize, const MCC: usize, const MPL: usize> Default for Path<MCL, MCC, MPL>

The default Path is the empty Path.

fn default() -> Self

Returns an empty Path.

Examples

use willow_data_model::prelude::*;
assert_eq!(Path::<4, 4, 4>::default().component_count(), 0);
assert_eq!(Path::<4, 4, 4>::default(), Path::<4, 4, 4>::new());

impl<const MCL: usize, const MCC: usize, const MPL: usize> Display for Path<MCL, MCC, MPL>

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

Formats the value using the given formatter.

impl<const MCL: usize, const MCC: usize, const MPL: usize> GreatestElement for Path<MCL, MCC, MPL>

fn greatest() -> Self

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

Complexity

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

Examples

use willow_data_model::prelude::*;
use order_theory::GreatestElement;

let p = Path::<4, 4, 4>::greatest();
assert_eq!(p.component_count(), 4);
assert_eq!(p.component(0).unwrap().as_ref(), &[255, 255, 255, 255]);
assert!(p.component(1).unwrap().is_empty());
assert!(p.component(2).unwrap().is_empty());
assert!(p.component(3).unwrap().is_empty());

fn is_greatest(&self) -> bool

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

impl<const MCL: usize, const MCC: usize, const MPL: usize> Hash for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> LeastElement for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> LowerSemilattice for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> Ord for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> PartialEq for Path<MCL, MCC, MPL>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const MCL: usize, const MCC: usize, const MPL: usize> PartialOrd for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> TryPredecessor for Path<MCL, MCC, MPL>

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<const MCL: usize, const MCC: usize, const MPL: usize> TrySuccessor for Path<MCL, MCC, MPL>

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.

Examples

use willow_data_model::prelude::*;
use order_theory::TrySuccessor;

let p: Path<3, 3, 3> = Path::from_slices(&[
    [255].as_slice(),
    [9, 255].as_slice(),
    [].as_slice(),
])?;
assert_eq!(p.try_successor(), Some(Path::from_slices(&[
    [255].as_slice(),
    [10].as_slice(),
])?));

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<const MCL: usize, const MCC: usize, const MPL: usize> UpperSemilattice for Path<MCL, MCC, MPL>

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.

impl<const MCL: usize, const MCC: usize, const MPL: usize> Eq for Path<MCL, MCC, MPL>

impl<const MCL: usize, const MCC: usize, const MPL: usize> PredecessorExceptForLeast for Path<MCL, MCC, MPL>

impl<const MCL: usize, const MCC: usize, const MPL: usize> SuccessorExceptForGreatest for Path<MCL, MCC, MPL>