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 const 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) -> P::Scalar

Get a field element at the given index.

Preconditions

• the index is in the range 0..self.len()

pub fn get_checked(&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 iter_scalars( &self, ) -> impl Iterator<Item = P::Scalar> + Send + Clone + '_

Returns an iterator over the scalar elements in the buffer.

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>> + Clone, 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 > log_len.

pub fn split_half_ref( &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)

Set a field element at the given index.

Preconditions

• the index is in the range 0..self.len()

pub fn set_checked( &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 chunk_mut( &mut self, log_chunk_size: usize, chunk_index: usize, ) -> Result<FieldBufferChunkMut<'_, P>, Error>

Get a mutable aligned chunk of size 2^log_chunk_size.

This method behaves like FieldBuffer::chunk but returns a mutable reference. For small chunks (log_chunk_size < P::LOG_WIDTH), this returns a wrapper that implements deferred writes - modifications are written back when the wrapper is dropped.

Throws

• Error::ArgumentRangeError if log_chunk_size > log_len or chunk_index is out of range.

pub fn split_half(self) -> Result<FieldBufferSplitMut<P, Data>, Error>

Consumes the buffer and splits it in half, returning a FieldBufferSplitMut.

This returns an object that owns the buffer data and can be used to access mutable references to the two halves. If the buffer contains a single packed element that needs to be split, the returned struct will create temporary copies and write the results back to the original buffer when dropped.

Throws

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

pub fn split_half_mut( &mut self, ) -> Result<FieldBufferSplitMut<P, &mut [P]>, Error>

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

This is a convenience method equivalent to self.to_mut().split_half().

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, &'a mut [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<F: Field, Data: Deref<Target = [F]>> Index<usize> for FieldBuffer<F, Data>

type Output = F

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<F: Field, Data: DerefMut<Target = [F]>> IndexMut<usize> for FieldBuffer<F, Data>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

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>