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

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

Implementations

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>

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)]);

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)]);

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)]);

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)]);

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)]);

Trait Implementations

Converts this type into a mutable reference of the (usually inferred) input type.
Converts this type into a shared reference of the (usually inferred) input type.
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
The resulting type after dereferencing.
Dereferences the value.
Mutably dereferences the value.
Executes the destructor for this type. Read more
The raw C type.
The type representing a reference to this type.
Constructs an instance of this type from its raw type. Read more
Returns a raw pointer to the wrapped value.
Consumes the wrapper and returns the raw pointer.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.