Struct memchr::arch::all::packedpair::Pair

source ·
pub struct Pair { /* private fields */ }
Expand description

A pair of byte offsets into a needle to use as a predicate.

This pair is used as a predicate to quickly filter out positions in a haystack in which a needle cannot match. In some cases, this pair can even be used in vector algorithms such that the vector algorithm only switches over to scalar code once this pair has been found.

A pair of offsets can be used in both substring search implementations and in prefilters. The former will report matches of a needle in a haystack where as the latter will only report possible matches of a needle.

The offsets are limited each to a maximum of 255 to keep memory usage low. Moreover, it’s rarely advantageous to create a predicate using offsets greater than 255 anyway.

The only guarantee enforced on the pair of offsets is that they are not equivalent. It is not necessarily the case that index1 < index2 for example. By convention, index1 corresponds to the byte in the needle that is believed to be most the predictive. Note also that because of the requirement that the indices be both valid for the needle used to build the pair and not equal, it follows that a pair can only be constructed for needles with length at least 2.

Implementations§

source§

impl Pair

source

pub fn new(needle: &[u8]) -> Option<Pair>

Create a new pair of offsets from the given needle.

If a pair could not be created (for example, if the needle is too short), then None is returned.

This chooses the pair in the needle that is believed to be as predictive of an overall match of the needle as possible.

source

pub fn with_ranker<R: HeuristicFrequencyRank>( needle: &[u8], ranker: R ) -> Option<Pair>

Create a new pair of offsets from the given needle and ranker.

This permits the caller to choose a background frequency distribution with which bytes are selected. The idea is to select a pair of bytes that is believed to strongly predict a match in the haystack. This usually means selecting bytes that occur rarely in a haystack.

If a pair could not be created (for example, if the needle is too short), then None is returned.

source

pub fn with_indices(needle: &[u8], index1: u8, index2: u8) -> Option<Pair>

Create a new pair using the offsets given for the needle given.

This bypasses any sort of heuristic process for choosing the offsets and permits the caller to choose the offsets themselves.

Indices are limited to valid u8 values so that a Pair uses less memory. It is not possible to create a Pair with offsets bigger than u8::MAX. It’s likely that such a thing is not needed, but if it is, it’s suggested to build your own bespoke algorithm because you’re likely working on a very niche case. (File an issue if this suggestion does not make sense to you.)

If a pair could not be created (for example, if the needle is too short), then None is returned.

source

pub fn index1(&self) -> u8

Returns the first offset of the pair.

source

pub fn index2(&self) -> u8

Returns the second offset of the pair.

Trait Implementations§

source§

impl Clone for Pair

source§

fn clone(&self) -> Pair

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Pair

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Copy for Pair

Auto Trait Implementations§

§

impl RefUnwindSafe for Pair

§

impl Send for Pair

§

impl Sync for Pair

§

impl Unpin for Pair

§

impl UnwindSafe for Pair

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.