Struct regex_automata::dfa::onepass::Cache

pub struct Cache {
    explicit_slots: Vec<Option<NonMaxUsize>>,
    explicit_slot_len: usize,
}

A cache represents mutable state that a one-pass DFA requires during a search.

For a given one-pass DFA, its corresponding cache may be created either via DFA::create_cache, or via Cache::new. They are equivalent in every way, except the former does not require explicitly importing Cache.

A particular Cache is coupled with the one-pass DFA from which it was created. It may only be used with that one-pass DFA. A cache and its allocations may be re-purposed via Cache::reset, in which case, it can only be used with the new one-pass DFA (and not the old one).

Fields

explicit_slots: Vec<Option<NonMaxUsize>>

Scratch space used to store slots during a search. Basically, we use the caller provided slots to store slots known when a match occurs. But after a match occurs, we might continue a search but ultimately fail to extend the match. When continuing the search, we need some place to store candidate capture offsets without overwriting the slot offsets recorded for the most recently seen match.

explicit_slot_len: usize

The number of slots in the caller-provided ‘Captures’ value for the current search. This is always at most ‘explicit_slots.len()’, but might be less than it, if the caller provided fewer slots to fill.

Implementations

impl Cache

pub fn new(re: &DFA) -> Cache

Create a new onepass::DFA cache.

A potentially more convenient routine to create a cache is DFA::create_cache, as it does not require also importing the Cache type.

If you want to reuse the returned Cache with some other one-pass DFA, then you must call Cache::reset with the desired one-pass DFA.

pub fn reset(&mut self, re: &DFA)

Reset this cache such that it can be used for searching with a different onepass::DFA.

A cache reset permits reusing memory already allocated in this cache with a different one-pass DFA.

Example

This shows how to re-purpose a cache for use with a different one-pass DFA.

use regex_automata::{dfa::onepass::DFA, Match};

let re1 = DFA::new(r"\w")?;
let re2 = DFA::new(r"\W")?;
let mut caps1 = re1.create_captures();
let mut caps2 = re2.create_captures();

let mut cache = re1.create_cache();
assert_eq!(
    Some(Match::must(0, 0..2)),
    { re1.captures(&mut cache, "Δ", &mut caps1); caps1.get_match() },
);

// Using 'cache' with re2 is not allowed. It may result in panics or
// incorrect results. In order to re-purpose the cache, we must reset
// it with the one-pass DFA we'd like to use it with.
//
// Similarly, after this reset, using the cache with 're1' is also not
// allowed.
re2.reset_cache(&mut cache);
assert_eq!(
    Some(Match::must(0, 0..3)),
    { re2.captures(&mut cache, "☃", &mut caps2); caps2.get_match() },
);

pub fn memory_usage(&self) -> usize

Returns the heap memory usage, in bytes, of this cache.

This does not include the stack size used up by this cache. To compute that, use std::mem::size_of::<Cache>().

fn explicit_slots(&mut self) -> &mut [Option<NonMaxUsize>]

fn setup_search(&mut self, explicit_slot_len: usize)

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Cache

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

Formats the value using the given formatter.