Struct reed_solomon_erasure::ReedSolomon

pub struct ReedSolomon<F: Field> { /* private fields */ }

Reed-Solomon erasure code encoder/decoder.

Common error handling

For encode, encode_shards, verify, verify_shards, reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards

Return Error::TooFewShards or Error::TooManyShards when the number of provided shards does not match the codec’s one.

Return Error::EmptyShard when the first shard provided is of zero length.

Return Error::IncorrectShardSize when the provided shards are of different lengths.

For reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards

Return Error::TooFewShardsPresent when there are not enough shards for reconstruction.

Return Error::InvalidShardFlags when the number of flags does not match the total number of shards.

Variants of encoding methods

sep

Methods ending in _sep takes an immutable reference to data shards, and a mutable reference to parity shards.

They are useful as they do not need to borrow the data shards mutably, and other work that only needs read-only access to data shards can be done in parallel/concurrently during the encoding.

Following is a table of all the sep variants

not sep	sep
encode_single	encode_single_sep
encode	encode_sep

The sep variants do similar checks on the provided data shards and parity shards.

Return Error::TooFewDataShards, Error::TooManyDataShards, Error::TooFewParityShards, or Error::TooManyParityShards when applicable.

single

Methods containing single facilitate shard by shard encoding, where the parity shards are partially constructed using one data shard at a time. See ShardByShard struct for more details on how shard by shard encoding can be useful.

They are prone to misuse, and it is recommended to use the ShardByShard bookkeeping struct instead for shard by shard encoding.

The ones that are also sep are ESPECIALLY prone to misuse. Only use them when you actually need the flexibility.

Following is a table of all the shard by shard variants

all shards at once	shard by shard
encode	encode_single
encode_sep	encode_single_sep

The single variants do similar checks on the provided data shards and parity shards, and also do index check on i_data.

Return Error::InvalidIndex if i_data >= data_shard_count.

Encoding behaviour

For encode

You do not need to clear the parity shards beforehand, as the methods will overwrite them completely.

For encode_single, encode_single_sep

Calling them with i_data being 0 will overwrite the parity shards completely. If you are using the methods correctly, then you do not need to clear the parity shards beforehand.

Variants of verifying methods

verify allocate sa buffer on the heap of the same size as the parity shards, and encode the input once using the buffer to store the computed parity shards, then check if the provided parity shards match the computed ones.

verify_with_buffer, allows you to provide the buffer to avoid making heap allocation(s) for the buffer in every call.

The with_buffer variants also guarantee that the buffer contains the correct parity shards if the result is Ok(_) (i.e. it does not matter whether the verification passed or not, as long as the result is not an error, the buffer will contain the correct parity shards after the call).

Following is a table of all the with_buffer variants

not with_buffer	with_buffer
verify	verify_with_buffer

The with_buffer variants also check the dimensions of the buffer and return Error::TooFewBufferShards, Error::TooManyBufferShards, Error::EmptyShard, or Error::IncorrectShardSize when applicable.

Implementations

impl<F: Field> ReedSolomon<F>

pub fn new(
    data_shards: usize,
    parity_shards: usize
) -> Result<ReedSolomon<F>, Error>

Creates a new instance of Reed-Solomon erasure code encoder/decoder.

Returns Error::TooFewDataShards if data_shards == 0.

Returns Error::TooFewParityShards if parity_shards == 0.

Returns Error::TooManyShards if data_shards + parity_shards > F::ORDER.

pub fn data_shard_count(&self) -> usize

pub fn parity_shard_count(&self) -> usize

pub fn total_shard_count(&self) -> usize

pub fn encode_single<T, U>(&self, i_data: usize, shards: T) -> Result<(), Error>where
    T: AsRef<[U]> + AsMut<[U]>,
    U: AsRef<[F::Elem]> + AsMut<[F::Elem]>,

Constructs the parity shards partially using only the data shard indexed by i_data.

The slots where the parity shards sit at will be overwritten.

Warning

You must apply this method on the data shards in strict sequential order (0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

pub fn encode_single_sep<U: AsRef<[F::Elem]> + AsMut<[F::Elem]>>(
    &self,
    i_data: usize,
    single_data: &[F::Elem],
    parity: &mut [U]
) -> Result<(), Error>

Constructs the parity shards partially using only the data shard provided.

The data shard must match the index i_data.

The slots where the parity shards sit at will be overwritten.

Warning

You must apply this method on the data shards in strict sequential order (0..data shard count), otherwise the parity shards will be incorrect.

It is recommended to use the ShardByShard bookkeeping struct instead of this method directly.

pub fn encode<T, U>(&self, shards: T) -> Result<(), Error>where
    T: AsRef<[U]> + AsMut<[U]>,
    U: AsRef<[F::Elem]> + AsMut<[F::Elem]>,

Constructs the parity shards.

The slots where the parity shards sit at will be overwritten.

pub fn encode_sep<T: AsRef<[F::Elem]>, U: AsRef<[F::Elem]> + AsMut<[F::Elem]>>(
    &self,
    data: &[T],
    parity: &mut [U]
) -> Result<(), Error>

Constructs the parity shards using a read-only view into the data shards.

The slots where the parity shards sit at will be overwritten.

pub fn verify<T: AsRef<[F::Elem]>>(&self, slices: &[T]) -> Result<bool, Error>

Checks if the parity shards are correct.

This is a wrapper of verify_with_buffer.

pub fn verify_with_buffer<T, U>(
    &self,
    slices: &[T],
    buffer: &mut [U]
) -> Result<bool, Error>where
    T: AsRef<[F::Elem]>,
    U: AsRef<[F::Elem]> + AsMut<[F::Elem]>,

Checks if the parity shards are correct.

pub fn reconstruct<T: ReconstructShard<F>>(
    &self,
    slices: &mut [T]
) -> Result<(), Error>

Reconstructs all shards.

The shards marked not present are only overwritten when no error is detected. All provided shards must have the same length.

This means if the method returns an Error, then nothing is touched.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

pub fn reconstruct_data<T: ReconstructShard<F>>(
    &self,
    slices: &mut [T]
) -> Result<(), Error>

Reconstructs only the data shards.

The shards marked not present are only overwritten when no error is detected. All provided shards must have the same length.

This means if the method returns an Error, then nothing is touched.

reconstruct, reconstruct_data, reconstruct_shards, reconstruct_data_shards share the same core code base.

Trait Implementations

impl<F: Field> Clone for ReedSolomon<F>

fn clone(&self) -> ReedSolomon<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Debug + Field> Debug for ReedSolomon<F>

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

Formats the value using the given formatter.

impl<F: Field> PartialEq<ReedSolomon<F>> for ReedSolomon<F>

fn eq(&self, rhs: &ReedSolomon<F>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.