Struct tre_regex::Regex

source · 
pub struct Regex(_);
Expand description

The base regex object.

This object takes care of freeing itself upon dropping, so you don’t have to call tre_regfree yourself.

This object provides an API similar to the function API. See the documentation on the individual functions for more information.

Implementations§

source§

impl Regex

source

pub fn regaexec<'a>( &self, string: &'a str, params: &RegApproxParams, nmatches: usize, flags: RegexecFlags ) -> Result<RegApproxMatchStr<'a>>

Performs an approximate regex search on the passed string, returning nmatches results.

Non-matching subexpressions or patterns will return None in the results.

Arguments
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, Results will be returned, containing either errors or substrings of the matches. Errors may be returned due to decoding problems, such as split codepoints.

Errors

If an error is encountered during matching, it returns a RegexError. Match results may also return errors, if decoding into UTF-8 was unsuccessful for whatever reason.

Caveats

Unless copied, the match results must live at least as long as string. This is because they are slices into string under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, RegApproxParams, Regex};

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE);
let regaexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);
let regaexec_params = RegApproxParams::new()
    .cost_ins(1)
    .cost_del(1)
    .cost_subst(1)
    .max_cost(2)
    .max_del(2)
    .max_ins(2)
    .max_subst(2)
    .max_err(2);

let compiled_reg = Regex::new("^(hello).*(world)$", regcomp_flags)?;
let result = compiled_reg.regaexec(
    "hello world",      // String to match against
    &regaexec_params,   // Matching parameters
    3,                  // Number of matches we want
    regaexec_flags      // Flags
)?;

for (i, matched) in result.get_matches().into_iter().enumerate() {
    match matched {
        Some(substr) => println!("Match {i}: {}", substr.as_ref().unwrap()),
        None => println!("Match {i}: <None>"),
    }
}
source

pub fn regaexec_bytes<'a>( &self, data: &'a [u8], params: &RegApproxParams, nmatches: usize, flags: RegexecFlags ) -> Result<RegApproxMatchBytes<'a>>

Performs an approximate regex search on the passed bytes, returning nmatches results.

This function should only be used if you need to match raw bytes, or bytes which may not be UTF-8 compliant. Otherwise, regaexec is recommended instead.

Arguments
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, u8 slices will be returned.

Errors

If an error is encountered during matching, it returns a RegexError.

Caveats

Unless copied, the match results must live at least as long as data. This is because they are slices into data under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, RegApproxParams, Regex};

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE);
let regaexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);
let regaexec_params = RegApproxParams::new()
    .cost_ins(1)
    .cost_del(1)
    .cost_subst(1)
    .max_cost(2)
    .max_del(2)
    .max_ins(2)
    .max_subst(2)
    .max_err(2);

let compiled_reg = Regex::new("^(hello).*(world)$", regcomp_flags)?;
let result = compiled_reg.regaexec_bytes(
    b"hello world",     // Bytes to match against
    &regaexec_params,   // Matching parameters
    3,                  // Number of matches we want
    regaexec_flags      // Flags
)?;

for (i, matched) in result.get_matches().into_iter().enumerate() {
    match matched {
        Some(substr) => println!(
            "Match {i}: {}",
            std::str::from_utf8(substr).unwrap()
        ),
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub fn new(reg: &str, flags: RegcompFlags) -> Result<Self>

Compiles a regex and wraps it in a Regex object.

Arguments
  • reg: regular expression to compile, as a string.
  • flags: RegcompFlags to pass to the function.
Returns

An opaque Regex object will be returned. It will be freed automatically when dropped.

Errors

Will return a RegexError upon failure.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};

let regcomp_flags = RegcompFlags::new().add(RegcompFlags::BASIC);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new("[A-Za-z0-9]*", regcomp_flags)?;
let matches = compiled_reg.regexec("hello", 1, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(res) => {
            match res {
                Ok(substr) => println!("Match {i}: '{}'", substr),
                Err(e) => println!("Match {i}: <Error: {e}>"),
            }
        },
        None => println!("Match {i}: <None>"),
    }
}
source

pub fn new_bytes(reg: &[u8], flags: RegcompFlags) -> Result<Self>

Compiles a regex contained in a u8 slice and wraps it in a Regex object.

Arguments
  • reg: regular expression to compile, as a string.
  • flags: RegcompFlags to pass to the function.
Returns

An opaque Regex object will be returned. It will be freed automatically when dropped.

Errors

Will return a RegexError upon failure.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};

let regcomp_flags = RegcompFlags::new().add(RegcompFlags::BASIC);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new_bytes(b"[A-Za-z0-9]*", regcomp_flags)?;
let matches = compiled_reg.regexec("hello", 1, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(res) => {
            match res {
                Ok(substr) => println!("Match {i}: '{}'", substr),
                Err(e) => println!("Match {i}: <Error: {e}>"),
            }
        },
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub fn regerror(&self, result: ErrorInt) -> RegexError

Given the ErrorInt code and this object, build a RegexError.

Arguments
Returns

A RegexError object. If creating the object fails, there is no way to know for sure. Fortunately, this should be a nonexistent occurence if the API is used correctly.

source§

impl Regex

source

pub fn regexec<'a>( &self, string: &'a str, nmatches: usize, flags: RegexecFlags ) -> Result<RegMatchStr<'a>>

Performs a regex search on the passed string, returning nmatches results.

Non-matching subexpressions or patterns will return None in the results.

Arguments
  • string: string to match against compiled_reg
  • nmatches: number of matches to return
  • flags: RegexecFlags to pass to tre_regnexec.
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, Results will be returned, containing either errors or substrings of the matches. Errors may be returned due to decoding problems, such as split codepoints.

Errors

If an error is encountered during matching, it returns a RegexError. Match results may also return errors, if decoding into UTF-8 was unsuccessful for whatever reason.

Caveats

Unless copied, the match results must live at least as long as string. This is because they are slices into string under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE)
    .add(RegcompFlags::UNGREEDY);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new("^(hello).*(world)$", regcomp_flags)?;
let matches = compiled_reg.regexec("hello world", 3, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(res) => {
            match res {
                Ok(substr) => println!("Match {i}: '{}'", substr),
                Err(e) => println!("Match {i}: <Error: {e}>"),
            }
        },
        None => println!("Match {i}: <None>"),
    }
}
source

pub fn regexec_bytes<'a>( &self, data: &'a [u8], nmatches: usize, flags: RegexecFlags ) -> Result<RegMatchBytes<'a>>

Performs a regex search on the passed bytes, returning nmatches results.

This function should only be used if you need to match raw bytes, or bytes which may not be UTF-8 compliant. Otherwise, regexec is recommended instead.

Arguments
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, u8 slices will be returned.

Errors

If an error is encountered during matching, it returns a RegexError.

Caveats

Unless copied, the match results must live at least as long as data. This is because they are slices into data under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new("^(hello).*(world)$", regcomp_flags)?;
let matches = compiled_reg.regexec_bytes(b"hello world", 2, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(substr) => println!(
            "Match {i}: {}",
            std::str::from_utf8(substr.as_ref()).unwrap()
        ),
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub fn regawexec<'a>( &self, string: &'a WideStr, params: &RegApproxParams, nmatches: usize, flags: RegexecFlags ) -> Result<RegApproxMatchWideStr<'a>>

Performs an approximate regex search on the passed wide string, returning nmatches results.

This function should only be used if you need to match raw wide string. Otherwise, regaexec is recommended instead.

Arguments
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, a WideStr will be returned.

Errors

If an error is encountered during matching, it returns a RegexError.

Caveats

Unless copied, the match results must live at least as long as string. This is because they are slices into string under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, RegApproxParams, Regex};
use widestring::widestr;

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE);
let regaexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);
let regaexec_params = RegApproxParams::new()
    .cost_ins(1)
    .cost_del(1)
    .cost_subst(1)
    .max_cost(2)
    .max_del(2)
    .max_ins(2)
    .max_subst(2)
    .max_err(2);

let compiled_reg = Regex::new_wide(widestr!("^(hello).*(world)$"), regcomp_flags)?;
let result = compiled_reg.regawexec(
    widestr!("hello world"),    // Bytes to match against
    &regaexec_params,           // Matching parameters
    3,                          // Number of matches we want
    regaexec_flags              // Flags
)?;

for (i, matched) in result.get_matches().into_iter().enumerate() {
    match matched {
        Some(substr) => println!("Match {i}: {}", substr.display()),
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub fn new_wide(reg: &WideStr, flags: RegcompFlags) -> Result<Self>

Compiles a regex contained in a WideStr and wraps it in a Regex object.

Arguments
  • reg: regular expression to compile, as a WideStr .
  • flags: RegcompFlags to pass to the function.
Returns

An opaque Regex object will be returned. It will be freed automatically when dropped.

Errors

Will return a RegexError upon failure.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};
use widestring::widestr;

let regcomp_flags = RegcompFlags::new().add(RegcompFlags::BASIC);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new_wide(widestr!("[A-Za-z0-9]*"), regcomp_flags)?;
let matches = compiled_reg.regwexec(widestr!("hello"), 1, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(substr) => println!("Match {i}: '{}'", substr.display()),
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub fn regwexec<'a>( &self, string: &'a WideStr, nmatches: usize, flags: RegexecFlags ) -> Result<RegMatchWideStr<'a>>

Performs a regex search on the passed wide string, returning nmatches results.

This function should only be used if you need to match wide strings. Otherwise, regexec is recommended instead.

Arguments
Returns

If no error was found, a Vec of Options will be returned.

If a given match index is empty, The Option will be None. Otherwise, the Option will contain a WideStr.

Errors

If an error is encountered during matching, it returns a RegexError.

Caveats

Unless copied, the match results must live at least as long as string. This is because they are slices into string under the hood, for efficiency.

Examples
use tre_regex::{RegcompFlags, RegexecFlags, Regex};
use widestring::widestr;

let regcomp_flags = RegcompFlags::new()
    .add(RegcompFlags::EXTENDED)
    .add(RegcompFlags::ICASE);
let regexec_flags = RegexecFlags::new().add(RegexecFlags::NONE);

let compiled_reg = Regex::new_wide(widestr!("^(hello).*(world)$"), regcomp_flags)?;
let matches = compiled_reg.regwexec(widestr!("hello world"), 2, regexec_flags)?;

for (i, matched) in matches.into_iter().enumerate() {
    match matched {
        Some(substr) => println!("Match {i}: {}", substr.display()),
        None => println!("Match {i}: <None>"),
    }
}
source§

impl Regex

source

pub const unsafe fn new_from(regex: regex_t) -> Self

Create a new Regex object from the given regex_t.

This function is for advanced use only. Don’t mess with it unless you know exactly what you are doing.

WARNING: Do NOT place a regex_t here that you didn’t get from regcomp or tre_regcomp. Otherwise, when the Regex object drops, it will call tre_regfree on memory not allocated by TRE itself. This is undefined behaviour and will likely cause a segfault. This is why the function is marked unsafe.

Arguments
Returns

A new Regex object, containing the passed-in regex_t.

Safety

The regex parameter must have been initalised by tre_regcomp or taken from another Regex object.

source

pub unsafe fn release(&mut self) -> Option<regex_t>

Relinquish the underlying regex_t object.

This is an advanced function and should not be used unless you know what you are doing.

Returns

None if the object is vacant, otherwise Some(regex_t).

Safety

A leak could result if the object is not properly freed with tre_regfree if the object was initalised by the TRE API.

source

pub const fn get(&self) -> &Option<regex_t>

Gets an immutable reference to the underlying regex_t object.

source

pub fn get_mut(&mut self) -> &mut Option<regex_t>

Gets a mutable reference to the underlying regex_t object.

Trait Implementations§

source§

impl Debug for Regex

source§

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

Formats the value using the given formatter. Read more
source§

impl Drop for Regex

source§

fn drop(&mut self)

Executes the destructor for this type.

The destructor will call tre_regfree on the internal regex_t.

Auto Trait Implementations§

§

impl RefUnwindSafe for Regex

§

impl Send for Regex

§

impl Sync for Regex

§

impl Unpin for Regex

§

impl UnwindSafe for Regex

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.