Struct MatchOpts 

#[non_exhaustive]
pub struct MatchOpts<'a> {
    pub highlight: Option<&'a [Vec<u8>]>,
    pub typo: u32,
    pub offset: usize,
    pub scope: &'a [Vec<u8>],
    pub filters: &'a [ValueFilter<'a>],
    pub sort: Option<(&'a [u8], SortOrder)>,
    pub distinct: Option<&'a [u8]>,
    pub facets: &'a [Vec<u8>],
}

Everything a text MATCH carries beyond its index, query text and result limit — the embedded twin of the wire’s optional clauses.

Grouping them keeps one entry point instead of one per clause, and MatchOpts::default is the plain query, so a caller opts into exactly the clauses it names.

use kevy_embedded::MatchOpts;

let every_field: &[Vec<u8>] = &[];
let opts = MatchOpts::default().with_highlight(every_field).with_typo(1);
assert_eq!(opts.typo, 1);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

highlight: Option<&'a [Vec<u8>]>

HIGHLIGHT: None = not requested, Some(&[]) = every indexed field, Some(names) = only those.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let hl = MatchOpts::default().with_highlight(&[]);
let hits = s.idx_match_with(b"ft", b"engine", 10, hl)?;
// d:1 matched in `body`, bytes 7..13 ("engine")
assert_eq!(hits[0].2, [(b"body".to_vec(), vec![(7, 13)])]);
assert!(s.idx_match_with(b"ft", b"engine", 10, MatchOpts::default())?[0].2.is_empty());

typo: u32

TYPO n: edit budget for each bare term; 0 = exact.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
assert!(keys(b"rusr", MatchOpts::default())?.is_empty());
let one_edit = MatchOpts::default().with_typo(1);
assert_eq!(keys(b"rusr", one_edit)?.len(), 3);

offset: usize

OFFSET n: hits to skip before limit takes effect.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let all = s.idx_match_with(b"ft", b"rust", 10, MatchOpts::default())?;
let skip = MatchOpts::default().with_offset(1);
let rest = s.idx_match_with(b"ft", b"rust", 10, skip)?;
assert_eq!(rest[0].0, all[1].0);

scope: &'a [Vec<u8>]

IN <field…>: the declared field names to score within; empty = the whole document.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let title = [b"title".to_vec()];
let opts = MatchOpts::default().with_scope(&title);
assert_eq!(keys(b"rust", opts)?, [b"d:1".to_vec(), b"d:3".to_vec()], "d:2 has it only in body");

filters: &'a [ValueFilter<'a>]

FILTER …: non-scoring predicates over stored values, ANDed. They decide which documents are eligible, not what a term is worth, so the corpus statistics stay whole-corpus.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let en = [ValueFilter::Eq { field: b"lang", value: b"en" }];
let opts = MatchOpts::default().with_filters(&en);
assert_eq!(keys(b"rust", opts)?, [b"d:1".to_vec(), b"d:2".to_vec()]);

sort: Option<(&'a [u8], SortOrder)>

SORT <field> ASC|DESC: select by a stored value instead of by score. Selecting, not re-ordering — a document that wins on the key is chosen even when its score would never have reached the page.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let newest = MatchOpts::default().with_sort(b"ts", SortOrder::Desc);
let hits = s.idx_match_with(b"ft", b"rust", 2, newest)?;
assert_eq!((&hits[0].0[..], &hits[1].0[..]), (&b"d:3"[..], &b"d:2"[..]));

distinct: Option<&'a [u8]>

DISTINCT <field>: at most one hit per value of a stored field, applied during selection so the page holds limit distinct documents rather than limit that then collapse.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let per_lang = MatchOpts::default().with_distinct(b"lang");
assert_eq!(s.idx_match_with(b"ft", b"rust", 10, per_lang)?.len(), 2, "one en hit, one ja hit");

facets: &'a [Vec<u8>]

FACET <field…>: count each field’s values over the whole match set. Reported alongside the page rather than shaping it.

// d:1 title "rust" (en, ts 1), d:2 body "written in rust" (en, 2), d:3 title "rust notes" (ja, 3)
let lang = [b"lang".to_vec()];
let opts = MatchOpts::default().with_facets(&lang);
let page = s.idx_match_faceted(b"ft", b"rust", 1, opts)?;
assert_eq!(page.hits.len(), 1);
assert_eq!(page.facets[0], [(b"en".to_vec(), 2), (b"ja".to_vec(), 1)]);

Implementations

impl<'a> MatchOpts<'a>

pub fn with_highlight(self, fields: &'a [Vec<u8>]) -> Self

Set Self::highlight to these field names (&[] = every indexed field).

let o = kevy_embedded::MatchOpts::default().with_highlight(&[]);
assert!(o.highlight.is_some());

pub fn with_typo(self, typo: u32) -> Self

Set Self::typo.

assert_eq!(kevy_embedded::MatchOpts::default().with_typo(2).typo, 2);

pub fn with_offset(self, offset: usize) -> Self

Set Self::offset.

assert_eq!(kevy_embedded::MatchOpts::default().with_offset(10).offset, 10);

pub fn with_scope(self, scope: &'a [Vec<u8>]) -> Self

Set Self::scope.

let fields = [b"title".to_vec()];
assert_eq!(kevy_embedded::MatchOpts::default().with_scope(&fields).scope.len(), 1);

pub fn with_filters(self, filters: &'a [ValueFilter<'a>]) -> Self

Set Self::filters.

let f = [kevy_embedded::ValueFilter::Eq { field: b"lang", value: b"en" }];
assert_eq!(kevy_embedded::MatchOpts::default().with_filters(&f).filters.len(), 1);

pub fn with_sort(self, field: &'a [u8], order: SortOrder) -> Self

Set Self::sort: select by field, in order.

use kevy_embedded::{MatchOpts, SortOrder};
assert!(MatchOpts::default().with_sort(b"ts", SortOrder::Desc).sort.is_some());

pub fn with_distinct(self, field: &'a [u8]) -> Self

Set Self::distinct.

let o = kevy_embedded::MatchOpts::default().with_distinct(b"author");
assert_eq!(o.distinct, Some(&b"author"[..]));

pub fn with_facets(self, facets: &'a [Vec<u8>]) -> Self

Set Self::facets.

let fields = [b"lang".to_vec()];
assert_eq!(kevy_embedded::MatchOpts::default().with_facets(&fields).facets.len(), 1);

Trait Implementations

impl<'a> Clone for MatchOpts<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for MatchOpts<'a>

impl<'a> Debug for MatchOpts<'a>

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

Formats the value using the given formatter.

impl<'a> Default for MatchOpts<'a>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Eq for MatchOpts<'a>

impl<'a> Hash for MatchOpts<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for MatchOpts<'a>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for MatchOpts<'a>