Struct pcre::Pcre

pub struct Pcre { /* fields omitted */ }

Wrapper for libpcre's pcre object (representing a compiled regular expression).

Methods

impl Pcre

fn compile(pattern: &str) -> Result<Pcre, CompilationError>

Compiles the given regular expression.

Argument

• pattern - The regular expression.

fn compile_with_options(
    pattern: &str,
    options: &EnumSet<CompileOption>
) -> Result<Pcre, CompilationError>

Compiles a regular expression using the given bitwise-OR'd options options.

Arguments

• pattern - The regular expression.
• options - Bitwise-OR'd compilation options. See the libpcre manpages, man 3 pcre_compile, for more information.

fn capture_count(&self) -> usize

Returns the number of capture groups in the regular expression, including one for each named capture group.

This count does not include "group 0", which is the full substring within a subject string that matches the regular expression.

See also

• name_count() - Returns the number of named capture groups.

fn enable_mark(&mut self) -> bool

Enables the use of the mark field when matching the compiled regular expression. The pattern must have been previously studied and an extra block must have been created.

To ensure that an extra block has been created, call study_with_options() passing the StudyExtraNeeded study option.

Return value

true if the use of the mark field could be enabled. false otherwise, which signifies that an extra block needs to be created.

fn extra(&mut self) -> Option<&mut PcreExtra>

Returns the extra block, if one has been created.

fn exec<'a, 'p>(&'p mut self, subject: &'a str) -> Option<Match<'a>>

Matches the compiled regular expression against a given subject string subject. If no match is found, then None is returned. Otherwise, a Match object is returned which provides access to the captured substrings as slices of the subject string.

Argument

• subject - The subject string.

Performance notes

This method is intended to be used to find individual matches. If multiple matches are desired, then a MatchIterator should be used because it is more efficient.

If a regular expression will be used often, it might be worth studying it to possibly speed up matching. See the study() method.

fn exec_from<'a, 'p>(
    &'p mut self,
    subject: &'a str,
    startoffset: usize
) -> Option<Match<'a>>

Matches the compiled regular expression against a given subject string subject starting at offset startoffset within the subject string. If no match is found, then None is returned. Otherwise, a Match object is returned which provides access to the captured substrings as slices of the subject string.

Arguments

• subject - The subject string.
• startoffset - Starting offset within subject at which to begin looking for a match.

Performance notes

This method is intended to be used to find individual matches. If multiple matches are desired, then a MatchIterator should be used because it is more efficient.

If a regular expression will be used often, it might be worth studying it to possibly speed up matching. See the study() method.

fn exec_from_with_options<'a, 'p>(
    &'p mut self,
    subject: &'a str,
    startoffset: usize,
    options: &EnumSet<ExecOption>
) -> Option<Match<'a>>

Matches the compiled regular expression against a given subject string subject starting at offset startoffset within the subject string and using the given bitwise-OR'd matching options options. If no match is found, then None is returned. Otherwise, a Match object is returned which provides access to the captured substrings as slices of the subject string.

Arguments

• subject - The subject string.
• startoffset - Starting offset within subject at which to begin looking for a match.
• options - Bitwise-OR'd matching options. See the libpcre manpages, man 3 pcre_exec, for more information.

Performance notes

This method is intended to be used to find individual matches. If multiple matches are desired, then a MatchIterator should be used because it is more efficient.

If a regular expression will be used often, it might be worth studying it to possibly speed up matching. See the study() method.

fn mark(&self) -> Option<String>

Returns the mark name from PCRE if set.

Return value

Some(str) if PCRE returned a value for the mark. None if either there was no mark set or enable_mark() was not called, or was unsuccessful.

fn mark_bytes(&self) -> Option<&[u8]>

Returns the mark name from PCRE if set.

Return value

Some(&[u8]) if PCRE returned a value for the mark. None if either there was no mark set or enable_mark() was not called, or was unsuccessful.

fn matches<'a, 'p>(&'p mut self, subject: &'a str) -> MatchIterator<'a, 'p>

Creates a MatchIterator for iterating through matches within the given subject string subject.

Argument

• subject - The subject string.

fn matches_with_options<'a, 'p>(
    &'p mut self,
    subject: &'a str,
    options: &EnumSet<ExecOption>
) -> MatchIterator<'a, 'p>

Creates a MatchIterator for iterating through matches within the given subject string subject using the given bitwise-OR'd matching options options.

Arguments

• subject - The subject string.
• options - Bitwise-OR'd matching options. See the libpcre manpages, man 3 pcre_exec, for more information.

fn name_count(&self) -> usize

Returns the number of named capture groups in the regular expression.

fn name_table(&self) -> BTreeMap<String, Vec<usize>>

Creates a name-to-number translation table that maps the name of each named capture group to the assigned group numbers.

The value type of the returned BTreeMap is a usize vector because there can be more than one group number for a given name if the PCRE_DUPNAMES option is used when compiling the regular expression.

fn study(&mut self) -> bool

Studies the regular expression to see if additional information can be extracted which might speed up matching.

Return value

true if additional information could be extracted. false otherwise.

fn study_with_options(&mut self, options: &EnumSet<StudyOption>) -> bool

Studies the regular expression using the given bitwise-OR'd study options options to see if additional information can be extracted which might speed up matching.

Argument

• options - Study options. See the libpcre manpages, man 3 pcre_study, for more information about each option.

Return value

true if additional information could be extracted or the StudyExtraNeeded option was passed. false otherwise.

Trait Implementations

impl Debug for Pcre

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

Formats the value using the given formatter.

impl Drop for Pcre

fn drop(&mut self)

A method called when the value goes out of scope.