Trait constriction::backends::ReadWords[−][src]

pub trait ReadWords<Word, S: Semantics> {
    type ReadError: Debug;
    fn read(&mut self) -> Result<Option<Word>, Self::ReadError>;

    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.

Associated Types

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

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

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

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

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.

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

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.

Implementors

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

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