Struct grep_searcher::SearcherBuilder

pub struct SearcherBuilder { /* private fields */ }

A builder for configuring a searcher.

A search builder permits specifying the configuration of a searcher, including options like whether to invert the search or to enable multi line search.

Once a searcher has been built, it is beneficial to reuse that searcher for multiple searches, if possible.

Implementations

impl SearcherBuilder

pub fn new() -> SearcherBuilder

Create a new searcher builder with a default configuration.

pub fn build(&self) -> Searcher

Build a searcher with the given matcher.

pub fn line_terminator( &mut self, line_term: LineTerminator, ) -> &mut SearcherBuilder

Set the line terminator that is used by the searcher.

When using a searcher, if the matcher provided has a line terminator set, then it must be the same as this one. If they aren’t, building a searcher will return an error.

By default, this is set to b'\n'.

pub fn invert_match(&mut self, yes: bool) -> &mut SearcherBuilder

Whether to invert matching, whereby lines that don’t match are reported instead of reporting lines that do match.

By default, this is disabled.

pub fn line_number(&mut self, yes: bool) -> &mut SearcherBuilder

Whether to count and include line numbers with matching lines.

This is enabled by default. There is a small performance penalty associated with computing line numbers, so this can be disabled when this isn’t desirable.

pub fn multi_line(&mut self, yes: bool) -> &mut SearcherBuilder

Whether to enable multi line search or not.

When multi line search is enabled, matches may match across multiple lines. Conversely, when multi line search is disabled, it is impossible for any match to span more than one line.

Warning: multi line search requires having the entire contents to search mapped in memory at once. When searching files, memory maps will be used if possible and if they are enabled, which avoids using your program’s heap. However, if memory maps cannot be used (e.g., for searching streams like stdin or if transcoding is necessary), then the entire contents of the stream are read on to the heap before starting the search.

This is disabled by default.

pub fn after_context(&mut self, line_count: usize) -> &mut SearcherBuilder

Whether to include a fixed number of lines after every match.

When this is set to a non-zero number, then the searcher will report line_count contextual lines after every match.

This is set to 0 by default.

pub fn before_context(&mut self, line_count: usize) -> &mut SearcherBuilder

Whether to include a fixed number of lines before every match.

When this is set to a non-zero number, then the searcher will report line_count contextual lines before every match.

This is set to 0 by default.

pub fn passthru(&mut self, yes: bool) -> &mut SearcherBuilder

Whether to enable the “passthru” feature or not.

When passthru is enabled, it effectively treats all non-matching lines as contextual lines. In other words, enabling this is akin to requesting an unbounded number of before and after contextual lines.

When passthru mode is enabled, any before_context or after_context settings are ignored by setting them to 0.

This is disabled by default.

pub fn heap_limit(&mut self, bytes: Option<usize>) -> &mut SearcherBuilder

Set an approximate limit on the amount of heap space used by a searcher.

The heap limit is enforced in two scenarios:

• When searching using a fixed size buffer, the heap limit controls how big this buffer is allowed to be. Assuming contexts are disabled, the minimum size of this buffer is the length (in bytes) of the largest single line in the contents being searched. If any line exceeds the heap limit, then an error will be returned.
• When performing a multi line search, a fixed size buffer cannot be used. Thus, the only choices are to read the entire contents on to the heap, or use memory maps. In the former case, the heap limit set here is enforced.

If a heap limit is set to 0, then no heap space is used. If there are no alternative strategies available for searching without heap space (e.g., memory maps are disabled), then the searcher wil return an error immediately.

By default, no limit is set.

pub fn memory_map(&mut self, strategy: MmapChoice) -> &mut SearcherBuilder

Set the strategy to employ use of memory maps.

Currently, there are only two strategies that can be employed:

• Automatic - A searcher will use heuristics, including but not limited to file size and platform, to determine whether to use memory maps or not.
• Never - Memory maps will never be used. If multi line search is enabled, then the entire contents will be read on to the heap before searching begins.

The default behavior is never. Generally speaking, and perhaps against conventional wisdom, memory maps don’t necessarily enable faster searching. For example, depending on the platform, using memory maps while searching a large directory can actually be quite a bit slower than using normal read calls because of the overhead of managing the memory maps.

Memory maps can be faster in some cases however. On some platforms, when searching a very large file that is already in memory, it can be slightly faster to search it as a memory map instead of using normal read calls.

Finally, memory maps have a somewhat complicated safety story in Rust. If you aren’t sure whether enabling memory maps is worth it, then just don’t bother with it.

WARNING: If your process is searching a file backed memory map at the same time that file is truncated, then it’s possible for the process to terminate with a bus error.

pub fn binary_detection( &mut self, detection: BinaryDetection, ) -> &mut SearcherBuilder

Set the binary detection strategy.

The binary detection strategy determines not only how the searcher detects binary data, but how it responds to the presence of binary data. See the BinaryDetection type for more information.

By default, binary detection is disabled.

pub fn encoding(&mut self, encoding: Option<Encoding>) -> &mut SearcherBuilder

Set the encoding used to read the source data before searching.

When an encoding is provided, then the source data is unconditionally transcoded using the encoding, unless a BOM is present. If a BOM is present, then the encoding indicated by the BOM is used instead. If the transcoding process encounters an error, then bytes are replaced with the Unicode replacement codepoint.

When no encoding is specified (the default), then BOM sniffing is used (if it’s enabled, which it is, by default) to determine whether the source data is UTF-8 or UTF-16, and transcoding will be performed automatically. If no BOM could be found, then the source data is searched as if it were UTF-8. However, so long as the source data is at least ASCII compatible, then it is possible for a search to produce useful results.

pub fn bom_sniffing(&mut self, yes: bool) -> &mut SearcherBuilder

Enable automatic transcoding based on BOM sniffing.

When this is enabled and an explicit encoding is not set, then this searcher will try to detect the encoding of the bytes being searched by sniffing its byte-order mark (BOM). In particular, when this is enabled, UTF-16 encoded files will be searched seamlessly.

When this is disabled and if an explicit encoding is not set, then the bytes from the source stream will be passed through unchanged, including its BOM, if one is present.

This is enabled by default.

pub fn stop_on_nonmatch( &mut self, stop_on_nonmatch: bool, ) -> &mut SearcherBuilder

Stop searching a file when a non-matching line is found after a matching line.

This is useful for searching sorted files where it is expected that all the matches will be on adjacent lines.

Trait Implementations

impl Clone for SearcherBuilder

fn clone(&self) -> SearcherBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SearcherBuilder

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

Formats the value using the given formatter.

impl Default for SearcherBuilder

fn default() -> SearcherBuilder

Returns the “default value” for a type.