Trait constriction::backends::ReadWords
source · pub trait ReadWords<Word, S: Semantics> {
type ReadError: Debug;
// Required method
fn read(&mut self) -> Result<Option<Word>, Self::ReadError>;
// Provided method
fn maybe_exhausted(&self) -> bool { ... }
}
Expand description
A trait for sources of compressed data (mainly used by decoders).
See the module-level documentation for more information, in particular regarding
the type parameter S: Semantics
.
Required Associated Types§
sourcetype ReadError: Debug
type ReadError: Debug
The error type that can occur when reading from the data source, or Infallible
.
Note that “end of file” / “out of data” is not considered an error. The read
method indicates “end of file” by returning Ok(None)
, not Err(...)
. If reading
the data source cannot fail (except for “end of file”) then ReadError
should be
Infallible
so that the compiler can optimize out any error checks (see also
UnwrapInfallible
).
Required Methods§
sourcefn read(&mut self) -> Result<Option<Word>, Self::ReadError>
fn read(&mut self) -> Result<Option<Word>, Self::ReadError>
Reads a single Word
from the data source and advances the state of the data source
accordingly (i.e., so that the next read
won’t read the same Word
again).
Returns
Ok(Some(word))
if the read succeeded;Ok(None)
if the backend is exhausted (i.e., there’s no more data left); orErr(err)
if an errorerr
other than “end of file” occurred during reading (e.g., a file system error)
Note that ReadWords::read
has stricter requirements than the standard library’s
Iterator::next
. Once ReadWords::read
indicates end of file by returning
Ok(None)
, it must never return Ok(Some(_))
when called again (i.e., types that
implement ReadWords
have to be “fused”, in iterator terminology). Entropy coders
may rely on this contract for correctness of the encoded and decoded data but not
for memory safety.
Provided Methods§
sourcefn maybe_exhausted(&self) -> bool
fn maybe_exhausted(&self) -> bool
Returns true
if the data source could be out of data.
The default implementation always returns true
since returning true
makes no
statement. Overwrite the default implementation if you may in some cases be able to
say with certainty that there is still data left to be read, and return false
in
these cases.
If maybe_exhausted()
returns false
then the next call to read
must return
either Ok(Some(_))
or Err(_)
but not Ok(None)
.
Implementations on Foreign Types§
source§impl<Array> ReadWords<<Array as Array>::Item, Stack> for SmallVec<Array>where
Array: Array,
impl<Array> ReadWords<<Array as Array>::Item, Stack> for SmallVec<Array>where
Array: Array,
§type ReadError = Infallible
type ReadError = Infallible
The only way how reading from a vector can fail is if the vector is empty, but
that’s not considered an error (it returns Ok(None)
instead).
source§fn read(&mut self) -> Result<Option<Array::Item>, Self::ReadError>
fn read(&mut self) -> Result<Option<Array::Item>, Self::ReadError>
Pops the word off the end of the vector (= top of the stack). If you instead want to
keep the data unchanged (e.g., because you want to reuse it later) then wrap either
the vector v
or or the slice &v[..]
in a Cursor
.
fn maybe_exhausted(&self) -> bool
source§impl<Word> ReadWords<Word, Stack> for Vec<Word>
impl<Word> ReadWords<Word, Stack> for Vec<Word>
§type ReadError = Infallible
type ReadError = Infallible
The only way how reading from a vector can fail is if the vector is empty, but
that’s not considered an error (it returns Ok(None)
instead).
source§fn read(&mut self) -> Result<Option<Word>, Self::ReadError>
fn read(&mut self) -> Result<Option<Word>, Self::ReadError>
Pops the word off the end of the vector (= top of the stack). If you instead want to
keep the data unchanged (e.g., because you want to reuse it later) then wrap either
the vector v
or or the slice &v[..]
in a Cursor
.
fn maybe_exhausted(&self) -> bool
Implementors§
source§impl<Iter, S, Word> ReadWords<Word, S> for InfallibleIteratorReadWords<Iter>
impl<Iter, S, Word> ReadWords<Word, S> for InfallibleIteratorReadWords<Iter>
Since InfallibleIteratorReadWords
doesn’t implement WriteWords
, it is allowed to
implement ReadWords
for all ReadWriteLogic
s
type ReadError = Infallible
source§impl<Iter, S, Word, ReadError> ReadWords<Word, S> for FallibleIteratorReadWords<Iter>
impl<Iter, S, Word, ReadError> ReadWords<Word, S> for FallibleIteratorReadWords<Iter>
Since FallibleIteratorReadWords
doesn’t implement WriteWords
, it is allowed to
implement ReadWords
for all ReadWriteLogic
s