Struct weezl::encode::Encoder

pub struct Encoder {
    state: Box<dyn Stateful + Send + 'static>,
}

The state for encoding data with an LZW algorithm.

The same structure can be utilized with streams as well as your own buffers and driver logic. It may even be possible to mix them if you are sufficiently careful not to lose any written data in the process.

This is a sans-IO implementation, meaning that it only contains the state of the encoder and the caller will provide buffers for input and output data when calling the basic encode_bytes method. Nevertheless, a number of adapters are provided in the into_* methods for enoding with a particular style of common IO.

• encode for encoding once without any IO-loop.
• into_async for encoding with the futures traits for asynchronous IO.
• into_stream for encoding with the standard io traits.
• into_vec for in-memory encoding.

Fields

state: Box<dyn Stateful + Send + 'static>

Internally dispatch via a dynamic trait object. This did not have any significant performance impact as we batch data internally and this pointer does not change after creation!

Implementations

impl Encoder

pub fn new(order: BitOrder, size: u8) -> Self

Create a new encoder with the specified bit order and symbol size.

The algorithm for dynamically increasing the code symbol bit width is compatible with the original specification. In particular you will need to specify an Lsb bit oder to encode the data portion of a compressed gif image.

Panics

The size needs to be in the interval 2..=12.

pub fn with_tiff_size_switch(order: BitOrder, size: u8) -> Self

Create a TIFF compatible encoder with the specified bit order and symbol size.

The algorithm for dynamically increasing the code symbol bit width is compatible with the TIFF specification, which is a misinterpretation of the original algorithm for increasing the code size. It switches one symbol sooner.

Panics

The size needs to be in the interval 2..=12.

pub fn encode_bytes(&mut self, inp: &[u8], out: &mut [u8]) -> BufferResult

Encode some bytes from inp into out.

See into_stream for high-level functions (this interface is only available with the std feature) and finish for marking the input data as complete.

When some input byte is invalid, i.e. is not smaller than 1 << size, then that byte and all following ones will not be consumed and the status of the result will signal an error. The result will also indicate that all bytes up to but not including the offending byte have been consumed. You may try again with a fixed byte.

pub fn encode(&mut self, data: &[u8]) -> Result<Vec<u8>, LzwError>

Encode a single chunk of data.

This method will add an end marker to the encoded chunk.

This is a convenience wrapper around into_vec. Use the into_vec adapter to customize buffer size, to supply an existing vector, to control whether an end marker is required, or to preserve partial data in the case of a decoding error.

Example

use weezl::{BitOrder, encode::Encoder};

let data = b"Hello, world";
let encoded = Encoder::new(BitOrder::Msb, 9)
    .encode(data)
    .expect("All bytes valid for code size");

pub fn into_stream<W: Write>(&mut self, writer: W) -> IntoStream<'_, W>

Construct a encoder into a writer.

pub fn into_vec<'lt>(&'lt mut self, vec: &'lt mut Vec<u8>) -> IntoVec<'lt>

Construct an encoder into a vector.

All encoded data is appended and the vector is not cleared.

Compared to into_stream this interface allows a high-level access to encoding without requires the std-feature. Also, it can make full use of the extra buffer control that the special target exposes.

pub fn finish(&mut self)

Mark the encoding as in the process of finishing.

The next following call to encode_bytes which is able to consume the complete input will also try to emit an end code. It’s not recommended, but also not unsound, to use different byte slices in different calls from this point forward and thus to ‘delay’ the actual end of the data stream. The behaviour after the end marker has been written is unspecified but sound.

pub(crate) fn restart(&mut self)

Undo marking this data stream as ending. FIXME: clarify how this interacts with padding introduced after end code.

pub fn reset(&mut self)

Reset all internal state.

This produce an encoder as if just constructed with new but taking slightly less work. In particular it will not deallocate any internal allocations. It will also avoid some duplicate setup work.