Struct grep_searcher::Searcher

pub struct Searcher { /* fields omitted */ }

A searcher executes searches over a haystack and writes results to a caller provided sink.

Matches are detected via implementations of the Matcher trait, which must be provided by the caller when executing a search.

When possible, a searcher should be reused.

Methods

impl Searcher

pub fn new() -> Searcher

Create a new searcher with a default configuration.

To configure the searcher (e.g., invert matching, enable memory maps, enable contexts, etc.), use the SearcherBuilder.

pub fn search_path<P, M, S>(
    &mut self,
    matcher: M,
    path: P,
    write_to: S
) -> Result<(), S::Error> where
    P: AsRef<Path>,
    M: Matcher,
    S: Sink, 

Execute a search over the file with the given path and write the results to the given sink.

If memory maps are enabled and the searcher heuristically believes memory maps will help the search run faster, then this will use memory maps. For this reason, callers should prefer using this method or search_file over the more generic search_reader when possible.

pub fn search_file<M, S>(
    &mut self,
    matcher: M,
    file: &File,
    write_to: S
) -> Result<(), S::Error> where
    M: Matcher,
    S: Sink, 

Execute a search over a file and write the results to the given sink.

If memory maps are enabled and the searcher heuristically believes memory maps will help the search run faster, then this will use memory maps. For this reason, callers should prefer using this method or search_path over the more generic search_reader when possible.

pub fn search_reader<M, R, S>(
    &mut self,
    matcher: M,
    read_from: R,
    write_to: S
) -> Result<(), S::Error> where
    M: Matcher,
    R: Read,
    S: Sink, 

Execute a search over any implementation of io::Read and write the results to the given sink.

When possible, this implementation will search the reader incrementally without reading it into memory. In some cases---for example, if multi line search is enabled---an incremental search isn't possible and the given reader is consumed completely and placed on the heap before searching begins. For this reason, when multi line search is enabled, one should try to use higher level APIs (e.g., searching by file or file path) so that memory maps can be used if they are available and enabled.

pub fn search_slice<M, S>(
    &mut self,
    matcher: M,
    slice: &[u8],
    write_to: S
) -> Result<(), S::Error> where
    M: Matcher,
    S: Sink, 

Execute a search over the given slice and write the results to the given sink.

pub fn set_binary_detection(&mut self, detection: BinaryDetection)

Set the binary detection method used on this searcher.

impl Searcher

The following methods permit querying the configuration of a searcher. These can be useful in generic implementations of Sink, where the output may be tailored based on how the searcher is configured.

pub fn line_terminator(&self) -> LineTerminator

Returns the line terminator used by this searcher.

pub fn binary_detection(&self) -> &BinaryDetection

Returns the type of binary detection configured on this searcher.

pub fn invert_match(&self) -> bool

Returns true if and only if this searcher is configured to invert its search results. That is, matching lines are lines that do not match the searcher's matcher.

pub fn line_number(&self) -> bool

Returns true if and only if this searcher is configured to count line numbers.

pub fn multi_line(&self) -> bool

Returns true if and only if this searcher is configured to perform multi line search.

pub fn multi_line_with_matcher<M: Matcher>(&self, matcher: M) -> bool

Returns true if and only if this searcher will choose a multi-line strategy given the provided matcher.

This may diverge from the result of multi_line in cases where the searcher has been configured to execute a search that can report matches over multiple lines, but where the matcher guarantees that it will never produce a match over multiple lines.

pub fn after_context(&self) -> usize

Returns the number of "after" context lines to report. When context reporting is not enabled, this returns 0.

pub fn before_context(&self) -> usize

Returns the number of "before" context lines to report. When context reporting is not enabled, this returns 0.

pub fn passthru(&self) -> bool

Returns true if and only if the searcher has "passthru" mode enabled.

Trait Implementations

impl Clone for Searcher

fn clone(&self) -> Searcher

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Searcher

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

Formats the value using the given formatter.