Struct FieldBuffer

pub struct FieldBuffer<P: PackedField, Data: Deref<Target = [P]> = Box<[P]>> { /* private fields */ }

A power-of-two-sized buffer containing field elements, stored in packed fields.

This struct maintains a set of invariants:

1. values.len() is a power of two
2. values.len() >= 1 << log_len.saturating_sub(P::LOG_WIDTH).

Implementations

impl<P: PackedField> FieldBuffer<P>

pub fn from_values(values: &[P::Scalar]) -> Result<Self, Error>

Create a new FieldBuffer from a vector of values.

Throws

• PowerOfTwoLengthRequired if the number of values is not a power of two.

pub fn from_values_truncated( values: &[P::Scalar], log_cap: usize, ) -> Result<Self, Error>

Create a new FieldBuffer from a vector of values.

Capacity log_cap is bumped to at least P::LOG_WIDTH.

Throws

• PowerOfTwoLengthRequired if the number of values is not a power of two.
• IncorrectArgumentLength if the number of values exceeds 1 << log_cap.

pub fn zeros(log_len: usize) -> Self

Create a new FieldBuffer of zeros with the given log_len.

pub fn zeros_truncated(log_len: usize, log_cap: usize) -> Result<Self, Error>

Create a new FieldBuffer of zeros with the given log_len and capacity log_cap.

Capacity log_cap is bumped to at least P::LOG_WIDTH.

impl<P: PackedField, Data: Deref<Target = [P]>> FieldBuffer<P, Data>

pub fn new(log_len: usize, values: Data) -> Result<Self, Error>

Create a new FieldBuffer from a slice of packed values.

Throws

• IncorrectArgumentLength if the number of field elements does not fit the values.len() exactly.

pub fn new_truncated(log_len: usize, values: Data) -> Result<Self, Error>

Create a new FieldBuffer from a slice of packed values.

Throws

• IncorrectArgumentLength if the number of field elements does not fit into the values.
• PowerOfTwoLengthRequired if the values.len() is not a power of two.

pub fn log_cap(&self) -> usize

Returns log2 the number of field elements that the underlying collection may take.

pub fn cap(&self) -> usize

Returns the number of field elements that the underlying collection may take.

pub fn log_len(&self) -> usize

Returns log2 the number of field elements.

pub fn len(&self) -> usize

Returns the number of field elements.

pub fn to_ref(&self) -> FieldSlice<'_, P>

Borrows the buffer as a FieldSlice.

pub fn get(&self, index: usize) -> Result<P::Scalar, Error>

Get a field element at the given index.

Throws

• Error::ArgumentRangeError if the index is out of bounds.

pub fn chunk( &self, log_chunk_size: usize, chunk_index: usize, ) -> Result<FieldSlice<'_, P>, Error>

Get an aligned chunk of size 2^log_chunk_size.

Chunk start offset divides chunk size; the result is essentially chunks(log_chunk_size).nth(chunk_index) but unlike chunks it does support sizes smaller than packing width.

pub fn chunks( &self, log_chunk_size: usize, ) -> Result<impl Iterator<Item = FieldSlice<'_, P>>, Error>

Split the buffer into chunks of size 2^log_chunk_size.

Errors

• Error::ArgumentRangeError if log_chunk_size < P::LOG_WIDTH or log_chunk_size > log_len.

pub fn chunks_par( &self, log_chunk_size: usize, ) -> Result<impl IndexedParallelIterator<Item = FieldSlice<'_, P>>, Error>

Creates an iterator over chunks of size 2^log_chunk_size in parallel.

Throws

• Error::ArgumentRangeError if log_chunk_size < P::LOG_WIDTH or log_chunk_size > log_len.

pub fn split_half( &self, ) -> Result<(FieldSlice<'_, P>, FieldSlice<'_, P>), Error>

Splits the buffer in half and returns a pair of borrowed slices.

Throws

• Error::CannotSplit if self.log_len() == 0

impl<P: PackedField, Data: DerefMut<Target = [P]>> FieldBuffer<P, Data>

pub fn to_mut(&mut self) -> FieldSliceMut<'_, P>

Borrows the buffer mutably as a FieldSliceMut.

pub fn set(&mut self, index: usize, value: P::Scalar) -> Result<(), Error>

Set a field element at the given index.

Throws

• Error::ArgumentRangeError if the index is out of bounds.

pub fn truncate(&mut self, new_log_len: usize)

Truncates a field buffer to a shorter length.

If new_log_len is not less than current log_len(), this has no effect.

pub fn zero_extend(&mut self, new_log_len: usize) -> Result<(), Error>

Zero extends a field buffer to a longer length.

If new_log_len is not greater than current log_len(), this has no effect.

Throws

• Error::IncorrectArgumentLength if the zero extended size exceeds underlying capacity.

pub fn resize(&mut self, new_log_len: usize) -> Result<(), Error>

Sets the new log length. If the new log length is bigger than the current log length, the new values (in case when self.log_len < new_log_len) will be filled with the values from the existing buffer.

Throws

• Error::IncorrectArgumentLength if the new log length exceeds the buffer’s capacity.

pub fn chunks_mut( &mut self, log_chunk_size: usize, ) -> Result<impl Iterator<Item = FieldSliceMut<'_, P>>, Error>

Split the buffer into mutable chunks of size 2^log_chunk_size.

Throws

• Error::ArgumentRangeError if log_chunk_size < P::LOG_WIDTH or log_chunk_size > log_len.

pub fn split_half_mut<F, R>(&mut self, f: F) -> Result<R, Error>

where F: FnOnce(&mut FieldSliceMut<'_, P>, &mut FieldSliceMut<'_, P>) -> R,

Splits the buffer in half and calls a closure with the two halves.

If the buffer contains a single packed element that needs to be split, this method will create temporary copies, call the closure, and then write the results back to the original buffer.

Throws

• Error::CannotSplit if self.log_len() == 0

pub fn split_half_mut_no_closure( &mut self, ) -> Result<FieldBufferSplitMut<'_, P>, Error>

Splits the buffer in half and returns a FieldBufferSplitMut for accessing the halves.

This returns an object that can be used to access mutable references to the two halves. This method unfortunately can’t simply return a tuple of slices because the buffer may have only one packed element. If the buffer contains a single packed element that needs to be split, this method will create temporary copies, call the closure, and then write the results back to the original buffer when the returned FieldBufferSplitMut is dropped.

Throws

• Error::CannotSplit if self.log_len() == 0

impl<'a, P: PackedField> FieldBuffer<P, FieldSliceData<'a, P>>

pub fn from_slice(log_len: usize, slice: &'a [P]) -> Result<Self, Error>

Create a new FieldSlice from a slice of packed values.

Throws

• IncorrectArgumentLength if the number of field elements does not fit the slice.len() exactly.

impl<'a, P: PackedField> FieldBuffer<P, FieldSliceDataMut<'a, P>>

pub fn from_slice(log_len: usize, slice: &'a mut [P]) -> Result<Self, Error>

Create a new FieldSliceMut from a mutable slice of packed values.

Throws

• IncorrectArgumentLength if the number of field elements does not fit the slice.len() exactly.

Trait Implementations

impl<P: PackedField, Data: DerefMut<Target = [P]>> AsMut<[P]> for FieldBuffer<P, Data>

fn as_mut(&mut self) -> &mut [P]

Converts this type into a mutable reference of the (usually inferred) input type.

impl<P: PackedField, Data: Deref<Target = [P]>> AsRef<[P]> for FieldBuffer<P, Data>

fn as_ref(&self) -> &[P]

Converts this type into a shared reference of the (usually inferred) input type.

impl<P: Clone + PackedField, Data: Clone + Deref<Target = [P]>> Clone for FieldBuffer<P, Data>

fn clone(&self) -> FieldBuffer<P, Data>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<P: Debug + PackedField, Data: Debug + Deref<Target = [P]>> Debug for FieldBuffer<P, Data>

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

Formats the value using the given formatter.

impl<'a, P: PackedField, Data: Deref<Target = [P]>> From<&'a FieldBuffer<P, Data>> for FieldSlice<'a, P>

fn from(buffer: &'a FieldBuffer<P, Data>) -> Self

Converts to this type from the input type.

impl<'a, P: PackedField, Data: DerefMut<Target = [P]>> From<&'a mut FieldBuffer<P, Data>> for FieldSliceMut<'a, P>

fn from(buffer: &'a mut FieldBuffer<P, Data>) -> Self

Converts to this type from the input type.

impl<P: PackedField, Data: Deref<Target = [P]>> PartialEq for FieldBuffer<P, Data>

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<P: Eq + PackedField, Data: Eq + Deref<Target = [P]>> Eq for FieldBuffer<P, Data>