Struct PathBuilder 

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

A helper struct for creating a Path with exactly one memory allocation. Requires total length and component count to be known in advance.

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

use willow_data_model::prelude::*;
let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_component(Component::new(b"hi")?);
builder.append_slice(b"ho")?;
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

Implementations

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

pub fn new( total_length: usize, component_count: usize, ) -> Result<Self, PathFromComponentsError>

Creates a builder for a Path of known total length and component count. The component data must be filled in before building.

Complexity

Runs in O(total_length + component_count), performs a single allocation of O(total_length + component_count) bytes.

Examples

use willow_data_model::prelude::*;
let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_component(Component::new(b"hi")?);
builder.append_slice(b"ho")?;
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub fn new_from_prefix( target_total_length: usize, target_component_count: usize, reference: &Path<MCL, MCC, MPL>, prefix_component_count: usize, ) -> Result<Self, PathFromComponentsError>

Creates a builder for a Path of known total length and component count, efficiently prefilled with the first prefix_component_count Components of a given reference Path. Panics if there are not enough Components in the reference.

The missing component data must be filled in before building.

Complexity

Runs in O(target_total_length + target_component_count), performs a single allocation of O(total_length + component_count) bytes.

use willow_data_model::prelude::*;
let p = Path::<4, 4, 4>::from_slices(&[b"hi", b"he"])?;
let mut builder = PathBuilder::new_from_prefix(4, 2, &p, 1)?;
builder.append_component(Component::new(b"ho")?);
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub fn append_component(&mut self, component: &Component<MCL>)

Appends the data for the next Component.

Complexity

Runs in O(component_length) time. Performs no allocations.

Examples

use willow_data_model::prelude::*;
let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_component(Component::new(b"hi")?);
builder.append_component(Component::new(b"ho")?);
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub fn append_slice( &mut self, component: &[u8], ) -> Result<(), InvalidComponentError>

Appends the data for the next Component, from a slice of bytes.

Complexity

Runs in O(component_length) time. Performs no allocations.

Examples

use willow_data_model::prelude::*;
let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_slice(b"hi")?;
builder.append_slice(b"ho")?;
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub async fn append_component_from_bulk_producer<P>( &mut self, component_length: usize, p: &mut P, ) -> Result<(), DecodeError<P::Final, P::Error, Blame>>

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

Appends data for a component of known length by reading data from a BulkProducer of bytes. Panics if component_length > MCL.

Complexity

Runs in O(component_length) time (assuming the producer takes O(1) time per byte). Performs no allocations.

Examples

use willow_data_model::prelude::*;
use ufotofu::{codec_prelude::*, producer::clone_from_slice};

let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_component_from_bulk_producer(2, &mut clone_from_slice(b"hi")).await.unwrap();
builder.append_component_from_bulk_producer(2, &mut clone_from_slice(b"ho")).await.unwrap();
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub fn build(self) -> Path<MCL, MCC, MPL>

Turns this builder into an immutable Path.

Panics if the number of Components or the total length does not match what was claimed in PathBuilder::new.

Complexity

Runs in O(1) time. Performs no allocations.

Examples

use willow_data_model::prelude::*;
let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
builder.append_component(Component::new(b"hi")?);
builder.append_slice(b"ho")?;
assert_eq!(builder.build(), Path::from_slices(&[b"hi", b"ho"])?);

pub fn total_length(&self) -> usize

Returns the total length of all components added to the builder so far.

use willow_data_model::prelude::*;

let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
assert_eq!(builder.total_length(), 0);

builder.append_component(Component::new(b"hi")?);
assert_eq!(builder.total_length(), 2);

builder.append_slice(b"ho")?;
assert_eq!(builder.total_length(), 4);

pub fn component_count(&self) -> usize

Returns the number of components added to the builder so far.

use willow_data_model::prelude::*;

let mut builder = PathBuilder::<4, 4, 4>::new(4, 2)?;
assert_eq!(builder.component_count(), 0);

builder.append_component(Component::new(b"hi")?);
assert_eq!(builder.component_count(), 1);

builder.append_slice(b"ho")?;
assert_eq!(builder.component_count(), 2);

Trait Implementations

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

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

Formats the value using the given formatter.