Struct `PatternSet`

pub struct PatternSet { /* private fields */ }

A set of PatternIDs.

A set of pattern identifiers is useful for recording which patterns have matched a particular haystack. A pattern set only includes pattern identifiers. It does not include offset information.

Example

This shows basic usage of a set.

use regex_automata::{PatternID, PatternSet};

let pid1 = PatternID::must(5);
let pid2 = PatternID::must(8);
// Create a new empty set.
let mut set = PatternSet::new(10);
// Insert pattern IDs.
set.insert(pid1);
set.insert(pid2);
// Test membership.
assert!(set.contains(pid1));
assert!(set.contains(pid2));
// Get all members.
assert_eq!(
    vec![5, 8],
    set.iter().map(|p| p.as_usize()).collect::<Vec<usize>>(),
);
// Clear the set.
set.clear();
// Test that it is indeed empty.
assert!(set.is_empty());

Implementations

`impl PatternSet`

fn new(capacity: usize) -> PatternSet

Create a new set of pattern identifiers with the given capacity.

The given capacity typically corresponds to (at least) the number of patterns in a compiled regex object.

Panics

This panics if the given capacity exceeds PatternID::LIMIT. This is impossible if you use the pattern_len() method as defined on any of the regex engines in this crate. Namely, a regex will fail to build by returning an error if the number of patterns given to it exceeds the limit. Therefore, the number of patterns in a valid regex is always a correct capacity to provide here.

fn clear(&mut self)

Clear this set such that it contains no pattern IDs.

fn contains(&self, pid: PatternID) -> bool

Return true if and only if the given pattern identifier is in this set.

fn insert(&mut self, pid: PatternID) -> bool

Insert the given pattern identifier into this set and return true if the given pattern ID was not previously in this set.

If the pattern identifier is already in this set, then this is a no-op.

Use PatternSet::try_insert for a fallible version of this routine.

Panics

This panics if this pattern set has insufficient capacity to store the given pattern ID.

fn try_insert(&mut self, pid: PatternID) -> Result<bool, PatternSetInsertError>

Insert the given pattern identifier into this set and return true if the given pattern ID was not previously in this set.

If the pattern identifier is already in this set, then this is a no-op.

Errors

This returns an error if this pattern set has insufficient capacity to store the given pattern ID.

fn is_empty(&self) -> bool

Return true if and only if this set has no pattern identifiers in it.

fn is_full(&self) -> bool

Return true if and only if this set has the maximum number of pattern identifiers in the set. This occurs precisely when PatternSet::len() == PatternSet::capacity().

This particular property is useful to test because it may allow one to stop a search earlier than you might otherwise. Namely, if a search is only reporting which patterns match a haystack and if you know all of the patterns match at a given point, then there's no new information that can be learned by continuing the search. (Because a pattern set does not keep track of offset information.)

fn len(&self) -> usize