Struct reed_solomon_erasure::ReedSolomon [−][src]
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>
[src]
pub fn new(
data_shards: usize,
parity_shards: usize
) -> Result<ReedSolomon<F>, Error>
[src]
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
[src]
pub fn parity_shard_count(&self) -> usize
[src]
pub fn total_shard_count(&self) -> usize
[src]
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]>,
[src]
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>
[src]
&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]>,
[src]
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>
[src]
&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>
[src]
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]>,
[src]
&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>
[src]
&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>
[src]
&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>
[src]
fn clone(&self) -> ReedSolomon<F>
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl<F: Debug + Field> Debug for ReedSolomon<F>
[src]
impl<F: Field> PartialEq<ReedSolomon<F>> for ReedSolomon<F>
[src]
Auto Trait Implementations
impl<F> RefUnwindSafe for ReedSolomon<F> where
<F as Field>::Elem: RefUnwindSafe,
<F as Field>::Elem: RefUnwindSafe,
impl<F> Send for ReedSolomon<F> where
<F as Field>::Elem: Send + Sync,
<F as Field>::Elem: Send + Sync,
impl<F> Sync for ReedSolomon<F> where
<F as Field>::Elem: Send + Sync,
<F as Field>::Elem: Send + Sync,
impl<F> Unpin for ReedSolomon<F> where
<F as Field>::Elem: Unpin,
<F as Field>::Elem: Unpin,
impl<F> UnwindSafe for ReedSolomon<F> where
<F as Field>::Elem: RefUnwindSafe + UnwindSafe,
<F as Field>::Elem: RefUnwindSafe + UnwindSafe,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,