Struct hyperscan::Stream

source · [−]

#[repr(transparent)]
pub struct Stream(_);

Expand description

A pattern matching state can be maintained across multiple blocks of target data

Implementations

source

impl Stream

source

pub fn close<F>(self, scratch: &ScratchRef, on_match_event: F) -> Result<()>where
F: MatchEventHandler,

Close a stream.

This function completes matching on the given stream and frees the memory associated with the stream state. After this call, the stream is invalid and can no longer be used. To reuse the stream state after completion, rather than closing it, the StreamRef::reset function can be used.

This function must be called for any stream created with StreamingDatabase::open_stream, even if scanning has been terminated by a non-zero return from the match callback function.

Methods from Deref<Target = StreamRef>

source

pub fn scan<T, F>(
 &self,
 data: T,
 scratch: &ScratchRef,
 on_match_event: F
) -> Result<()>where
 T: AsRef<[u8]>,
 F: MatchEventHandler,

Write data to be scanned to the opened stream.

This is the function call in which the actual pattern matching takes place as data is written to the stream. Matches will be returned via the on_match_event callback supplied.

Examples

let db: StreamingDatabase = pattern! {"test"; SOM_LEFTMOST}.build().unwrap();

let s = db.alloc_scratch().unwrap();
let st = db.open_stream().unwrap();

let data = vec!["foo t", "es", "t bar"];
let mut matches = vec![];

let mut callback = |_, from, to, _| {
    matches.push((from, to));

    Matching::Continue
};

for d in data {
    st.scan(d, &s, &mut callback).unwrap();
}

st.close(&s, callback).unwrap();

assert_eq!(matches, vec![(4, 8)]);

source

pub fn reset<F>(&self, scratch: &ScratchRef, on_match_event: F) -> Result<()>where
F: MatchEventHandler,

Reset a stream to an initial state.

Conceptually, this is equivalent to performing Stream::close on the given stream, followed by StreamingDatabase::open_stream. This new stream replaces the original stream in memory, avoiding the overhead of freeing the old stream and allocating the new one.

Note: This operation may result in matches being returned (via calls to the match event callback) for expressions anchored to the end of the original data stream (for example, via the use of the $ meta-character).

Examples

let db: StreamingDatabase = pattern! {"test"; SOM_LEFTMOST}.build().unwrap();

let s = db.alloc_scratch().unwrap();
let st = db.open_stream().unwrap();

let data = vec!["foo t", "es", "t bar"];
let mut matches = vec![];

let mut callback = |_, from, to, _| {
    matches.push((from, to));

    Matching::Continue
};

for d in &data {
    st.scan(d, &s, &mut callback).unwrap();
}

st.reset(&s, &mut callback).unwrap();

for d in &data {
    st.scan(d, &s, &mut callback).unwrap();
}

st.close(&s, callback).unwrap();

assert_eq!(matches, vec![(4, 8), (4, 8)]);

source

pub fn reset_and_copy_stream<F>(
 &self,
 from: &StreamRef,
 scratch: &ScratchRef,
 on_match_event: F
) -> Result<()>where
 F: MatchEventHandler,

Duplicate the given from stream state onto the stream.

The stream will first be reset (reporting any EOD matches if a on_match_event callback handler is provided).

Note: the stream and the from stream must be open against the same database.

Examples

let db: StreamingDatabase = pattern! {"test"; SOM_LEFTMOST}.build().unwrap();

let s = db.alloc_scratch().unwrap();
let st = db.open_stream().unwrap();

let mut matches = vec![];

let mut callback = |_, from, to, _| {
    matches.push((from, to));

    Matching::Continue
};

st.scan("foo t", &s, &mut callback).unwrap();
st.scan("es", &s, &mut callback).unwrap();

let st2 = db.open_stream().unwrap();

st2.scan("test", &s, &mut callback).unwrap();
st2.reset_and_copy_stream(&st, &s, &mut callback).unwrap();
st2.scan("t bar", &s, &mut callback).unwrap();
st2.close(&s, &mut callback).unwrap();

st.close(&s, Matching::Terminate).unwrap();

assert_eq!(matches, vec![(0, 4), (4, 8)]);

source

pub fn compress(&self, buf: &mut [u8]) -> Result<usize>

Creates a compressed representation of the provided stream in the buffer provided.

This compressed representation can be converted back into a stream state by using expand() or reset_and_expand().

Examples

let db: StreamingDatabase = pattern! {"test"; SOM_LEFTMOST}.build().unwrap();

let s = db.alloc_scratch().unwrap();
let st = db.open_stream().unwrap();

let mut matches = vec![];

let mut callback = |_, from, to, _| {
    matches.push((from, to));

    Matching::Continue
};

st.scan("foo t", &s, &mut callback).unwrap();
st.scan("es", &s, &mut callback).unwrap();

let mut buf = [0; 8192];
let len = st.compress(&mut buf).unwrap();
st.close(&s, Matching::Terminate).unwrap();

let st2 = db.expand_stream(&buf[..len]).unwrap();
st2.scan("t bar", &s, &mut callback).unwrap();
st2.close(&s, &mut callback).unwrap();

assert_eq!(matches, vec![(4, 8)]);

source

pub fn reset_and_expand<F>(
 &self,
 buf: &[u8],
 scratch: &ScratchRef,
 on_match_event: F
) -> Result<()>where
 F: MatchEventHandler,

Decompresses a compressed representation created by StreamRef::compress on top of the stream. The stream will first be reset (reporting any EOD matches).

Note: the stream must be opened against the same database as the compressed stream.

Note: buf must correspond to a complete compressed representation created by StreamRef::compress of a stream that was opened against db. It is not always possible to detect misuse of this API and behaviour is undefined if these properties are not satisfied.

Examples

let db: StreamingDatabase = pattern! {"test"; SOM_LEFTMOST}.build().unwrap();

let s = db.alloc_scratch().unwrap();
let st = db.open_stream().unwrap();

let mut matches = vec![];

let mut callback = |_, from, to, _| {
    matches.push((from, to));

    Matching::Continue
};

st.scan("foo t", &s, &mut callback).unwrap();
st.scan("es", &s, &mut callback).unwrap();

let mut buf = [0; 8192];
let len = st.compress(&mut buf).unwrap();
st.scan("t bar", &s, &mut callback).unwrap();

st.reset_and_expand(&buf[..len], &s, &mut callback).unwrap();
st.scan("t bar", &s, &mut callback).unwrap();
st.close(&s, &mut callback).unwrap();

assert_eq!(matches, vec![(4, 8), (4, 8)]);