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).

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

Returns 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>

Creates 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>>,

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), 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>

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), 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>

Creates 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>

Creates 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 component_count(&self) -> usize

Returns 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

Returns whether this path has zero components.

Complexity

Runs in O(1), performs no allocations.

pub fn path_length(&self) -> usize

Returns 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 component(&self, i: usize) -> Option<Component<'_, MCL>>

Returns the i-th Component of this path.

Complexity

Runs in O(1), performs no allocations.

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

Returns 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>>

Creates 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>>

Creates 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>> + '_

Creates 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>> + '_

Creates 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, component_count: usize) -> Option<Self>

Creates a new path that consists of the first component_count components. 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.

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

Creates a new path that consists of the first component_count components. 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.

pub fn path_length_of_prefix(&self, component_count: usize) -> usize

Returns the sum of the lengths of the first component_count components in this path. More efficient than path.create_prefix(component_count).path_length().

Guaranteed to be at most MCC.

Complexity

Runs in O(1), performs no allocations.

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

Creates 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

Tests 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

Tests 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 is_related(&self, other: &Self) -> bool

Tests whether this path is related to the given path, that is, whether either one is a prefix of the other.

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

Returns 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>

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), 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>

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

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

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

fn decode_from_slice( enc: &[u8], ) -> impl Future<Output = Result<Self, DecodeError<(), Infallible, Self::ErrorReason>>>

Decodes from a slice instead of a producer.

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

type ErrorCanonic = Blame

The type for reporting that the bytestring 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>, Self: Sized,

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

fn decode_canonic_from_slice( enc: &[u8], ) -> impl Future<Output = Result<Self, DecodeError<(), Infallible, Self::ErrorCanonic>>>

Decodes from a slice instead of a producer, and errors if the input encoding is not the canonical one.

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

fn sync_decode_from_slice( enc: &[u8], ) -> Result<Self, DecodeError<(), Infallible, Self::ErrorReason>>

Synchronously decodes from a slice instead of a producer.

fn sync_decode_canonic_from_slice( enc: &[u8], ) -> Result<Self, DecodeError<(), Infallible, Self::ErrorCanonic>>

where Self: DecodableCanonic,

Synchronously and absolutely decodes from a slice instead of a producer, and errors if the input encoding is not the canonical one.

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>,

Writes an encoding of &self into the given consumer.

fn encode_into_vec(&self) -> impl Future<Output = Vec<u8>>

Encodes into a Vec instead of a given consumer.

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

fn len_of_encoding(&self) -> usize

Computes the size of the encoding in bytes. Calling encode must feed exactly that many bytes into the consumer.

fn encode_into_boxed_slice(&self) -> impl Future<Output = Box<[u8]>>

Encodes into a boxed slice instead of a given consumer.

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

fn sync_encode_into_vec(&self) -> Vec<u8>

Synchronously encodes into a Vec instead of a given consumer.

fn sync_encode_into_boxed_slice(&self) -> Box<[u8]>

where Self: EncodableKnownSize,

Synchronously encodes into a boxed slice instead of a given consumer.

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>

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

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

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

Decodes a Path relative to a reference Path.

Definition

fn relative_decode_from_slice( enc: &[u8], r: &RelativeTo, ) -> impl Future<Output = Result<Self, DecodeError<(), Infallible, ErrorReason>>>

Decodes from a slice instead of a producer.

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

async fn relative_decode<P>( producer: &mut P, r: &PrivatePathContext<MCL, MCC, MPL>, ) -> Result<Self, DecodeError<P::Final, P::Error, Blame>>

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

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

fn relative_decode_from_slice( enc: &[u8], r: &RelativeTo, ) -> impl Future<Output = Result<Self, DecodeError<(), Infallible, ErrorReason>>>

Decodes from a slice instead of a producer.

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

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

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

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

fn relative_decode_canonic_from_slice( enc: &[u8], r: &RelativeTo, ) -> impl Future<Output = Result<Self, DecodeError<(), Infallible, ErrorCanonic>>>

Decodes from a slice instead of a producer, and errors if the input encoding is not the canonical one.

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

fn sync_relative_decode_from_slice( enc: &[u8], r: &RelativeTo, ) -> Result<Self, DecodeError<(), Infallible, ErrorReason>>

Synchronously decodes from a slice instead of a producer.

fn sync_relative_decode_canonic_from_slice<ErrorCanonic>( enc: &[u8], r: &RelativeTo, ) -> Result<Self, DecodeError<(), Infallible, ErrorCanonic>>

where ErrorCanonic: From<ErrorReason>, Self: RelativeDecodableCanonic<RelativeTo, ErrorReason, ErrorCanonic>,

Synchronously decodes from a slice instead of a producer, and errors if the input encoding is not the canonical one.

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, consumer: &mut Consumer, reference: &Path<MCL, MCC, MPL>, ) -> Result<(), Consumer::Error>

where Consumer: BulkConsumer<Item = u8>,

Encodes this Path relative to a reference Path.

Definition

fn relative_encode_into_vec( &self, r: &RelativeTo, ) -> impl Future<Output = Vec<u8>>

Encodes into a Vec instead of a given consumer.

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

async fn relative_encode<C>( &self, consumer: &mut C, r: &PrivatePathContext<MCL, MCC, MPL>, ) -> Result<(), C::Error>

where C: BulkConsumer<Item = u8>,

Writes an encoding of &self into the given consumer.

fn relative_encode_into_vec( &self, r: &RelativeTo, ) -> impl Future<Output = Vec<u8>>

Encodes into a Vec instead of a given consumer.

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

fn relative_len_of_encoding(&self, r: &Path<MCL, MCC, MPL>) -> usize

Computes the size of the encoding in bytes. Calling encode must feed exactly that many bytes into the consumer.

fn relative_encode_into_boxed_slice( &self, r: &RelativeTo, ) -> impl Future<Output = Box<[u8]>>

Encodes into a boxed slice instead of a given consumer.

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

fn sync_relative_encode_into_vec(&self, r: &RelativeTo) -> Vec<u8>

Synchronously encodes into a Vec instead of a given consumer.

fn sync_relative_encode_into_boxed_slice(&self, r: &RelativeTo) -> Box<[u8]>

where Self: RelativeEncodableKnownSize<RelativeTo>,

Synchronously encodes into a boxed slice instead of a given consumer.

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