Struct Cache

pub struct Cache { /* private fields */ }

A cache represents mutable state that a BoundedBacktracker requires during a search.

For a given BoundedBacktracker, its corresponding cache may be created either via BoundedBacktracker::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 BoundedBacktracker from which it was created. It may only be used with that BoundedBacktracker. A cache and its allocations may be re-purposed via Cache::reset, in which case, it can only be used with the new BoundedBacktracker (and not the old one).

Implementations

impl Cache

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

Create a new BoundedBacktracker cache.

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

If you want to reuse the returned Cache with some other BoundedBacktracker, then you must call Cache::reset with the desired BoundedBacktracker.

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

Reset this cache such that it can be used for searching with different BoundedBacktracker.

A cache reset permits reusing memory already allocated in this cache with a different BoundedBacktracker.

Example

This shows how to re-purpose a cache for use with a different BoundedBacktracker.

use regex_automata::{
    nfa::thompson::backtrack::BoundedBacktracker,
    Match,
};

let re1 = BoundedBacktracker::new(r"\w")?;
let re2 = BoundedBacktracker::new(r"\W")?;

let mut cache = re1.create_cache();
assert_eq!(
    Some(Ok(Match::must(0, 0..2))),
    re1.try_find_iter(&mut cache, "Δ").next(),
);

// 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 BoundedBacktracker we'd like to use it with.
//
// Similarly, after this reset, using the cache with 're1' is also not
// allowed.
cache.reset(&re2);
assert_eq!(
    Some(Ok(Match::must(0, 0..3))),
    re2.try_find_iter(&mut cache, "☃").next(),
);

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>().

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.