Trait Matcher 

pub trait Matcher {
    // Required methods
    fn get_next_space(&mut self) -> Vec<u8> ;
    fn get_last_space(&self) -> &[u8] ;
    fn commit_space(&mut self, space: Vec<u8>);
    fn skip_matching(&mut self);
    fn start_matching(
        &mut self,
        handle_sequence: impl for<'a> FnMut(Sequence<'a>),
    );
    fn reset(&mut self, level: CompressionLevel);
    fn window_size(&self) -> u64;

    // Provided methods
    fn set_file_type_hint(&mut self, _file_type: CompressionFileType) { ... }
    fn set_internal_file_profile_hint(&mut self, _file_profile_code: u8) { ... }
    fn set_repeat_offsets(&mut self, _newest: u32, _second: u32, _third: u32) { ... }
    fn skip_matching_for_incompressible(&mut self) { ... }
    fn skip_matching_for_rle(&mut self) { ... }
}

Trait used by the encoder that users can use to extend the matching facilities with their own algorithm making their own tradeoffs between runtime, memory usage and compression ratio

This trait operates on buffers that represent the chunks of data the matching algorithm wants to work on. Each one of these buffers is referred to as a space. One or more of these buffers represent the window the decoder will need to decode the data again.

This library asks the Matcher for a new buffer using get_next_space to allow reusing of allocated buffers when they are no longer part of the window of data that is being used for matching.

The library fills the buffer with data that is to be compressed and commits them back to the matcher using commit_space.

Then it will either call start_matching or, if the space is deemed not worth compressing, skip_matching is called.

This is repeated until no more data is left to be compressed.

Required Methods

fn get_next_space(&mut self) -> Vec<u8>

Get a space where we can put data to be matched on. Will be encoded as one block. The maximum allowed size is 128 kB.

fn get_last_space(&self) -> &[u8]

Get a reference to the last commited space

fn commit_space(&mut self, space: Vec<u8>)

Commit a space to the matcher so it can be matched against

fn skip_matching(&mut self)

Just process the data in the last commited space for future matching

fn start_matching(&mut self, handle_sequence: impl for<'a> FnMut(Sequence<'a>))

Process the data in the last commited space for future matching AND generate matches for the data

fn reset(&mut self, level: CompressionLevel)

Reset this matcher so it can be used for the next new frame

fn window_size(&self) -> u64

The size of the window the decoder will need to execute all sequences produced by this matcher

May change after a call to reset with a different compression level

Provided Methods

fn set_file_type_hint(&mut self, _file_type: CompressionFileType)

Provide a coarse file-type hint so the matcher can choose an internal starting point.

Implementations that do not care about path/extension hints can ignore this hook.

fn set_internal_file_profile_hint(&mut self, _file_profile_code: u8)

Provide a narrower internal file profile when one is known.

This is encoded as a small integer so the public matcher trait does not expose the encoder’s private profile enum.

fn set_repeat_offsets(&mut self, _newest: u32, _second: u32, _third: u32)

Synchronize the matcher with the encoder’s current repeat-offset history.

Matchers that do not use repeat-offset history can ignore this hook.

fn skip_matching_for_incompressible(&mut self)

Mark the last committed space as processed without indexing it for future matches.

This is intended for data that has already been classified as very unlikely to be useful match history, such as incompressible raw blocks.

fn skip_matching_for_rle(&mut self)

Mark the last committed space as processed after it was emitted as an RLE block.

The default behavior preserves the existing matcher contract by indexing the block normally. Matchers can specialize this because every minimum-match suffix in an RLE block has the same key.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Matcher for MatchGeneratorDriver