Trait constriction::backends::ReadWords

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 { ... }
}

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

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

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); or
• Err(err) if an error err 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

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

impl<Array> ReadWords<<Array as Array>::Item, Stack> for SmallVec<Array>

where Array: Array,

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).

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

impl<Word> ReadWords<Word, Stack> for Vec<Word>

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).

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

impl<Iter, S, Word> ReadWords<Word, S> for InfallibleIteratorReadWords<Iter>

where Iter: Iterator<Item = Word>, S: Semantics,

Since InfallibleIteratorReadWords doesn’t implement WriteWords, it is allowed to implement ReadWords for all ReadWriteLogics

type ReadError = Infallible

impl<Iter, S, Word, ReadError> ReadWords<Word, S> for FallibleIteratorReadWords<Iter>

where Iter: Iterator<Item = Result<Word, ReadError>>, S: Semantics, ReadError: Debug,

Since FallibleIteratorReadWords doesn’t implement WriteWords, it is allowed to implement ReadWords for all ReadWriteLogics

type ReadError = ReadError

impl<Word, B: ReadWords<Word, Queue>> ReadWords<Word, Stack> for Reverse<B>

type ReadError = <B as ReadWords<Word, Queue>>::ReadError

impl<Word, B: ReadWords<Word, Stack>> ReadWords<Word, Queue> for Reverse<B>

type ReadError = <B as ReadWords<Word, Stack>>::ReadError

impl<Word: Clone, Buf: AsRef<[Word]>> ReadWords<Word, Queue> for Cursor<Word, Buf>

type ReadError = Infallible

impl<Word: Clone, Buf: SafeBuf<Word>> ReadWords<Word, Stack> for Cursor<Word, Buf>

type ReadError = Infallible