Struct bellframe::block::AnnotBlock

pub struct AnnotBlock<A> { /* fields omitted */ }

An AnnotBlock is in essence a multi-permutation: it describes the transposition of a single start Row into many Rows, the first of which is always the one supplied. The last Row of an AnnotBlock is considered ‘left-over’, and represents the first Row that should be rung after this AnnotBlock.

A few things to note about Blocks:

• All Blocks must have non-zero length. Zero-length blocks cannot be created with safe code, and will cause undefined behaviour or panic!s.

Implementations

impl<A> AnnotBlock<A>

pub fn parse(s: &str) -> Result<Self, ParseError> where
    A: Default, 

Parse a multi-line string into an unannotated Block. The last Row parsed will be considered ‘left over’ - i.e. it isn’t directly part of this Block but rather will be the first Row of any Block which gets appended to this one. Each Row has the default annotation (thus requiring that A implements Default).

pub fn from_annot_rows(annot_rows: Vec<AnnotRow<A>>) -> Result<Self, ParseError>

Creates a new AnnotBlock from a Vec of annotated Rows, checking that the result is valid.

pub unsafe fn from_annot_rows_unchecked(rows: Vec<AnnotRow<A>>) -> Self

Creates a new AnnotBlock from a Vec of annotated Rows, without performing any safety checks.

Safety

This is safe when the following properties hold:

• rows has length at least 2. This is so that there is at least one Row in the AnnotBlock, plus one leftover Row.
• All the rows have the same Stage.

pub unsafe fn empty(stage: Stage) -> Self where
    A: Default, 

Creates an empty AnnotBlock on a given Stage (i.e. an AnnotBlock containing only rounds as the leftover row). This function is wildly unsafe; it should only be used if you are going to extend the block before passing it out of the unsafe boundary.

Safety

This function is never safe on its own. In order to make the result safe, you have to push more AnnotRows onto the AnnotBlock (using AnnotBlock::extend_with, AnnotBlock::extend_from_iter_transposed, etc.).

pub fn stage(&self) -> Stage

Gets the Stage of this Block.

pub fn get_row(&self, index: usize) -> Option<&Row>

Gets the Row at a given index, along with its annotation.

pub fn get_annot(&self, index: usize) -> Option<&A>

Gets an immutable reference to the annotation of the Row at a given index, if it exists.

pub fn get_annot_mut(&mut self, index: usize) -> Option<&mut A>

Gets an mutable reference to the annotation of the Row at a given index, if it exists.

pub fn get_annot_row(&self, index: usize) -> Option<&AnnotRow<A>>

Gets the Row at a given index, along with its annotation.

pub fn first_annot_row(&self) -> &AnnotRow<A>

Gets the first Row of this AnnotBlock, along with its annotation.

pub fn len(&self) -> usize

Gets the length of this Block (excluding the left-over Row). This is guarunteed to be at least 1.

pub fn iter(&self) -> AnnotRowIter<'_, A>

Returns an Iterator over all the Rows in this AnnotBlock, along with their annotations.

pub fn annot_rows(&self) -> &[AnnotRow<A>]

Returns an immutable reference to the slice of annotated Rows making up this Block

pub fn rows(&self) -> impl Iterator<Item = &Row> + '_

Returns an Iterator over all the Rows in this Block, without their annotations.

pub fn annots(&self) -> impl Iterator<Item = &A> + '_

Returns an Iterator over all the annotations in this Block.

pub fn annots_mut(&mut self) -> impl Iterator<Item = &mut A> + '_

Returns an Iterator yielding mutable references to the annotations in this Block.

pub fn pre_mul(&mut self, perm_row: &Row) -> Result<(), IncompatibleStages>

Pre-multiplies every Row in this Block by another Row. The resulting Block is equivalent to self (inasmuch as the relations between the Rows are identical), but it will start from a different Row.

pub fn leftover_annot_row(&self) -> &AnnotRow<A>

Returns the ‘left-over’ Row of this Block, along with its annotation. This Row represents the overall transposition of the Block, and should not be used when generating rows for truth checking.

pub fn leftover_row(&self) -> &Row

Returns the ‘left-over’ Row of this Block. This Row represents the overall transposition of the Block, and should not be used when generating rows for truth checking.

pub fn leftover_annot_mut(&mut self) -> &mut A

Returns a mutable reference to the annotation of the ‘left-over’ Row of this Block.

pub fn map_annots<B>(self, f: impl Fn(A) -> B) -> AnnotBlock<B>

Convert this AnnotBlock into another AnnotBlock with identical Rows, but where each annotation is passed through the given function.

pub fn into_rows(self) -> Vec<Row>

Convert this AnnotBlock into another AnnotBlock with identical Rows, but where each annotation is passed through the given function.

pub fn prefix(&self, limit: usize) -> Self where
    A: Clone, 

Convert this AnnotBlock into another AnnotBlock with identical Rows, but where each annotation is passed through the given function.

#[must_use]

pub fn split(&mut self, index: usize) -> Option<(Row, Self)> where
    A: Default, 

Splits this AnnotBlock into two separate AnnotBlocks at a specified index. This makes self shorter, whilst returning the remainder as a new AnnotBlock (along with its first Row). This returns None without mutation if either of the blocks would have zero length. During the course of this, the row at the split point will be used twice so the annotation is moved to the second block (and the leftover row of self is annotated with a default value).

pub fn extend_from_iter_transposed(
    &mut self,
    annot_rows: impl IntoIterator<Item = AnnotRow<A>>
) -> Result<(), IncompatibleStages>

Extend this AnnotBlock with AnnotRows generated by a given Iterator, transposing them so that the first new Row matches self.leftover_row().

pub fn extend_with(&mut self, other: Self) -> Result<(), IncompatibleStages>

Extend this AnnotBlock with the contents of another AnnotBlock. This modifies self to have the effect of ringing self then other. Note that this overwrites the leftover Row of self, replacing its annotation with that of other’s first Row.

pub fn extend_with_cloned(
    &mut self,
    other: &Self
) -> Result<(), IncompatibleStages> where
    A: Clone, 

Extend this AnnotBlock with the contents of another AnnotBlock, cloning the annotations. This modifies self to have the effect of ringing self then other. Note that this overwrites the leftover Row of self, replacing its annotation with that of other’s first Row.

Trait Implementations

impl<A: Clone> Clone for AnnotBlock<A>

fn clone(&self) -> AnnotBlock<A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: Debug> Debug for AnnotBlock<A>

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

Formats the value using the given formatter.

impl<A: Hash> Hash for AnnotBlock<A>

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, 

Feeds a slice of this type into the given Hasher.

impl<A> Index<usize> for AnnotBlock<A>

type Output = AnnotRow<A>

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<A: PartialEq> PartialEq<AnnotBlock<A>> for AnnotBlock<A>

fn eq(&self, other: &AnnotBlock<A>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &AnnotBlock<A>) -> bool

This method tests for !=.

impl<A: Eq> Eq for AnnotBlock<A>

impl<A> StructuralEq for AnnotBlock<A>

impl<A> StructuralPartialEq for AnnotBlock<A>