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.

Enforces that each component has a length of at most MCL (max_component_length), that each path has at most MCC (max_component_ccount) components, and that the total size in bytes of all components is at most MPL (max_path_length).

Implementations

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

pub fn new_empty() -> Self

Construct an empty path, i.e., a path of zero components.

Complexity

Runs in O(1), performs no allocations.

pub fn new_singleton(comp: Component<'_, MCL>) -> Result<Self, InvalidPathError>

Construct a singleton path, i.e., a path 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.

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

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

Construct 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), where n is the total length of the path in bytes. Performs a single allocation of O(n) bytes.

pub fn new_from_slice( components: &[Component<'_, MCL>], ) -> Result<Self, InvalidPathError>

Construct 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), where n is the total length of the path in bytes. Performs a single allocation of O(n) bytes.

pub fn append(&self, comp: Component<'_, MCL>) -> Result<Self, InvalidPathError>

Construct a new path by appending a component to this one.

Creates a fully separate copy of the new data on the heap; this function is not more efficient than constructing the new path from scratch.

Complexity

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

pub fn append_slice( &self, components: &[Component<'_, MCL>], ) -> Result<Self, InvalidPathError>

Construct a new path by appending a slice of components to this one.

Creates a fully separate copy of the new data on the heap; this function is not more efficient than constructing the new path from scratch.

Complexity

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

pub fn get_component_count(&self) -> usize

Get the number of components in this path.

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

pub fn is_empty(&self) -> bool

Return whether this path has zero components.

Complexity

Runs in O(1), performs no allocations.

pub fn get_path_length(&self) -> usize

Get the sum of the lengths of all components in this path.

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

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

Get the i-th Component of this path.

Complexity

Runs in O(1), performs no allocations.

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

Get an owned handle to the i-th Component of this path.

Complexity

Runs in O(1), performs no allocations.

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

Create an iterator over the components of this path.

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

Complexity

Runs in O(1), performs no allocations.

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

Create an iterator over the components of this path, 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.

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

Create an iterator over owned handles to the components of this path.

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

Complexity

Runs in O(1), performs no allocations.

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

Create an iterator over owned handles to the components of this path, 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.

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

Create a new path that consists of the first length components. More efficient than creating a new Path from scratch.

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

Complexity

Runs in O(1), performs no allocations.

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

Create a new path that consists of the first length components. More efficient than creating a new Path from scratch.

Safety

Undefined behaviour if length is greater than self.get_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.

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

Create an iterator over all prefixes of this path (including th empty path and the path itself).

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

Complexity

Runs in O(1), performs no allocations.

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

Test whether this path 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), where n is the total length of the shorter of the two paths. Performs no allocations.

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

Test whether this path is prefixed by the given path. Paths are always a prefix of themselves.

Complexity

Runs in O(n), where n is the total length of the shorter of the two paths. Performs no allocations.

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

Return the longest common prefix of this path and the given path.

Complexity

Runs in O(n), where n is the total length of the shorter of the two paths. Performs a single allocation to create the return value.

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

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

Complexity

Runs in O(n), where n is the total length of the shorter of the two paths. Performs a single allocation to create the return value.

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

Return the least path that is strictly greater than self and which is not prefixed by self, or None if no such path exists.

Complexity

Runs in O(n), where n is the total length of the shorter of the two paths. Performs a single allocation to create the return value.

Trait Implementations

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

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 copy 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> Decodable for Path<MCL, MCC, MPL>

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

where P: BulkProducer<Item = u8>,

Decade a value to a bytestring in a specific way that is best described over at willowprotocol.org.

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

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

where P: BulkProducer<Item = u8>,

Decode a value to a bytestring in a specific way that is best described over at willowprotocol.org.

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

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

where C: BulkConsumer<Item = u8>,

Encode a value to a bytestring in a specific way that is best described over at willowprotocol.org.

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

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

where C: BulkConsumer<Item = u8>,

Encode a value to a bytestring in a specific way that is best described over at willowprotocol.org.

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

Compare paths lexicogrphically, 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<RangeEnd<Path<MCL, MCC, MPL>>> for Path<MCL, MCC, MPL>

fn eq(&self, other: &RangeEnd<Path<MCL, MCC, MPL>>) -> 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> 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<RangeEnd<Path<MCL, MCC, MPL>>> for Path<MCL, MCC, MPL>

fn partial_cmp(&self, other: &RangeEnd<Path<MCL, MCC, MPL>>) -> 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> 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> RelativeDecodable<Path<MCL, MCC, MPL>> for Path<MCL, MCC, MPL>

async fn relative_decode<Producer>( reference: &Path<MCL, MCC, MPL>, producer: &mut Producer, ) -> Result<Self, DecodeError<Producer::Error>>

where Producer: BulkProducer<Item = u8>, Self: Sized,

Decode a path relative to this path.

Definition

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

fn relative_decode<Producer>( reference: &Path<MCL, MCC, MPL>, producer: &mut Producer, ) -> Result<Self, DecodeError<Producer::Error>>

where Producer: BulkProducer<Item = u8>, Self: Sized,

Decode a path relative to this path.

Definition

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

async fn relative_encode<Consumer>( &self, reference: &Path<MCL, MCC, MPL>, consumer: &mut Consumer, ) -> Result<(), Consumer::Error>

where Consumer: BulkConsumer<Item = u8>,

Encode a path relative to another path.

Definition

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

fn relative_encode<Consumer>( &self, reference: &Path<MCL, MCC, MPL>, consumer: &mut Consumer, ) -> Result<(), Consumer::Error>

where Consumer: BulkConsumer<Item = u8>,

Encode a path relative to another path.

Definition

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