glib/auto/

regex.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, translate::*, Error, RegexCompileFlags, RegexMatchFlags};

crate::wrapper! {
    /// A `GRegex` is a compiled form of a regular expression.
    ///
    /// After instantiating a `GRegex`, you can use its methods to find matches
    /// in a string, replace matches within a string, or split the string at matches.
    ///
    /// `GRegex` implements regular expression pattern matching using syntax and
    /// semantics (such as character classes, quantifiers, and capture groups)
    /// similar to Perl regular expression. See the
    /// [PCRE documentation](man:pcre2pattern(3)) for details.
    ///
    /// A typical scenario for regex pattern matching is to check if a string
    /// matches a pattern. The following statements implement this scenario.
    ///
    /// **⚠️ The following code is in  { .c } ⚠️**
    ///
    /// ``` { .c }
    /// const char *regex_pattern = ".*GLib.*";
    /// const char *string_to_search = "You will love the GLib implementation of regex";
    /// g_autoptr(GMatchInfo) match_info = NULL;
    /// g_autoptr(GRegex) regex = NULL;
    ///
    /// regex = g_regex_new (regex_pattern, G_REGEX_DEFAULT, G_REGEX_MATCH_DEFAULT, NULL);
    /// g_assert (regex != NULL);
    ///
    /// if (g_regex_match (regex, string_to_search, G_REGEX_MATCH_DEFAULT, &match_info))
    ///   {
    ///     int start_pos, end_pos;
    ///     g_match_info_fetch_pos (match_info, 0, &start_pos, &end_pos);
    ///     g_print ("Match successful! Overall pattern matches bytes %d to %d\n", start_pos, end_pos);
    ///   }
    /// else
    ///   {
    ///     g_print ("No match!\n");
    ///   }
    /// ```
    ///
    /// The constructor for `GRegex` includes two sets of bitmapped flags:
    ///
    /// * [`RegexCompileFlags`][crate::RegexCompileFlags]—These flags
    /// control how GLib compiles the regex. There are options for case
    /// sensitivity, multiline, ignoring whitespace, etc.
    /// * [`RegexMatchFlags`][crate::RegexMatchFlags]—These flags control
    /// `GRegex`’s matching behavior, such as anchoring and customizing definitions
    /// for newline characters.
    ///
    /// Some regex patterns include backslash assertions, such as `\d` (digit) or
    /// `\D` (non-digit). The regex pattern must escape those backslashes. For
    /// example, the pattern `"\\d\\D"` matches a digit followed by a non-digit.
    ///
    /// GLib’s implementation of pattern matching includes a `start_position`
    /// argument for some of the match, replace, and split methods. Specifying
    /// a start position provides flexibility when you want to ignore the first
    /// _n_ characters of a string, but want to incorporate backslash assertions
    /// at character _n_ - 1. For example, a database field contains inconsistent
    /// spelling for a job title: `healthcare provider` and `health-care provider`.
    /// The database manager wants to make the spelling consistent by adding a
    /// hyphen when it is missing. The following regex pattern tests for the string
    /// `care` preceded by a non-word boundary character (instead of a hyphen)
    /// and followed by a space.
    ///
    /// **⚠️ The following code is in  { .c } ⚠️**
    ///
    /// ``` { .c }
    /// const char *regex_pattern = "\\Bcare\\s";
    /// ```
    ///
    /// An efficient way to match with this pattern is to start examining at
    /// `start_position` 6 in the string `healthcare` or `health-care`.
    ///
    /// **⚠️ The following code is in  { .c } ⚠️**
    ///
    /// ``` { .c }
    /// const char *regex_pattern = "\\Bcare\\s";
    /// const char *string_to_search = "healthcare provider";
    /// g_autoptr(GMatchInfo) match_info = NULL;
    /// g_autoptr(GRegex) regex = NULL;
    ///
    /// regex = g_regex_new (
    ///   regex_pattern,
    ///   G_REGEX_DEFAULT,
    ///   G_REGEX_MATCH_DEFAULT,
    ///   NULL);
    /// g_assert (regex != NULL);
    ///
    /// g_regex_match_full (
    ///   regex,
    ///   string_to_search,
    ///   -1,
    ///   6, // position of 'c' in the test string.
    ///   G_REGEX_MATCH_DEFAULT,
    ///   &match_info,
    ///   NULL);
    /// ```
    ///
    /// The method [`match_full()`][Self::match_full()] (and other methods implementing
    /// `start_pos`) allow for lookback before the start position to determine if
    /// the previous character satisfies an assertion.
    ///
    /// Unless you set the [flags@GLib.RegexCompileFlags.RAW] as one of
    /// the `GRegexCompileFlags`, all the strings passed to `GRegex` methods must
    /// be encoded in UTF-8. The lengths and the positions inside the strings are
    /// in bytes and not in characters, so, for instance, `\xc3\xa0` (i.e., `à`)
    /// is two bytes long but it is treated as a single character. If you set
    /// `G_REGEX_RAW`, the strings can be non-valid UTF-8 strings and a byte is
    /// treated as a character, so `\xc3\xa0` is two bytes and two characters long.
    ///
    /// Regarding line endings, `\n` matches a `\n` character, and `\r` matches
    /// a `\r` character. More generally, `\R` matches all typical line endings:
    /// CR + LF (`\r\n`), LF (linefeed, U+000A, `\n`), VT (vertical tab, U+000B,
    /// `\v`), FF (formfeed, U+000C, `\f`), CR (carriage return, U+000D, `\r`),
    /// NEL (next line, U+0085), LS (line separator, U+2028), and PS (paragraph
    /// separator, U+2029).
    ///
    /// The behaviour of the dot, circumflex, and dollar metacharacters are
    /// affected by newline characters. By default, `GRegex` matches any newline
    /// character matched by `\R`. You can limit the matched newline characters by
    /// specifying the [flags@GLib.RegexMatchFlags.NEWLINE_CR],
    /// [flags@GLib.RegexMatchFlags.NEWLINE_LF], and
    /// [flags@GLib.RegexMatchFlags.NEWLINE_CRLF] compile options, and
    /// with [flags@GLib.RegexMatchFlags.NEWLINE_ANY],
    /// [flags@GLib.RegexMatchFlags.NEWLINE_CR],
    /// [flags@GLib.RegexMatchFlags.NEWLINE_LF] and
    /// [flags@GLib.RegexMatchFlags.NEWLINE_CRLF] match options.
    /// These settings are also relevant when compiling a pattern if
    /// [flags@GLib.RegexCompileFlags.EXTENDED] is set and an unescaped
    /// `#` outside a character class is encountered. This indicates a comment
    /// that lasts until after the next newline.
    ///
    /// Because `GRegex` does not modify its internal state between creation and
    /// destruction, you can create and modify the same `GRegex` instance from
    /// different threads. In contrast, [`MatchInfo`][crate::MatchInfo] is not thread safe.
    ///
    /// The regular expression low-level functionalities are obtained through
    /// the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Regex(Shared<ffi::GRegex>);

    match fn {
        ref => |ptr| ffi::g_regex_ref(ptr),
        unref => |ptr| ffi::g_regex_unref(ptr),
        type_ => || ffi::g_regex_get_type(),
    }
}

impl Regex {
    /// Compiles the regular expression to an internal form, and does
    /// the initial setup of the #GRegex structure.
    /// ## `pattern`
    /// the regular expression
    /// ## `compile_options`
    /// compile options for the regular expression, or 0
    /// ## `match_options`
    /// match options for the regular expression, or 0
    ///
    /// # Returns
    ///
    /// a #GRegex structure or [`None`] if an error occurred. Call
    ///   g_regex_unref() when you are done with it
    #[doc(alias = "g_regex_new")]
    pub fn new(
        pattern: &str,
        compile_options: RegexCompileFlags,
        match_options: RegexMatchFlags,
    ) -> Result<Option<Regex>, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_regex_new(
                pattern.to_glib_none().0,
                compile_options.into_glib(),
                match_options.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the number of capturing subpatterns in the pattern.
    ///
    /// # Returns
    ///
    /// the number of capturing subpatterns
    #[doc(alias = "g_regex_get_capture_count")]
    #[doc(alias = "get_capture_count")]
    pub fn capture_count(&self) -> i32 {
        unsafe { ffi::g_regex_get_capture_count(self.to_glib_none().0) }
    }

    /// Returns the compile options that @self was created with.
    ///
    /// Depending on the version of PCRE that is used, this may or may not
    /// include flags set by option expressions such as `(?i)` found at the
    /// top-level within the compiled pattern.
    ///
    /// # Returns
    ///
    /// flags from #GRegexCompileFlags
    #[doc(alias = "g_regex_get_compile_flags")]
    #[doc(alias = "get_compile_flags")]
    pub fn compile_flags(&self) -> RegexCompileFlags {
        unsafe { from_glib(ffi::g_regex_get_compile_flags(self.to_glib_none().0)) }
    }

    /// Checks whether the pattern contains explicit CR or LF references.
    ///
    /// # Returns
    ///
    /// [`true`] if the pattern contains explicit CR or LF references
    #[doc(alias = "g_regex_get_has_cr_or_lf")]
    #[doc(alias = "get_has_cr_or_lf")]
    pub fn has_cr_or_lf(&self) -> bool {
        unsafe { from_glib(ffi::g_regex_get_has_cr_or_lf(self.to_glib_none().0)) }
    }

    /// Returns the match options that @self was created with.
    ///
    /// # Returns
    ///
    /// flags from #GRegexMatchFlags
    #[doc(alias = "g_regex_get_match_flags")]
    #[doc(alias = "get_match_flags")]
    pub fn match_flags(&self) -> RegexMatchFlags {
        unsafe { from_glib(ffi::g_regex_get_match_flags(self.to_glib_none().0)) }
    }

    /// Returns the number of the highest back reference
    /// in the pattern, or 0 if the pattern does not contain
    /// back references.
    ///
    /// # Returns
    ///
    /// the number of the highest back reference
    #[doc(alias = "g_regex_get_max_backref")]
    #[doc(alias = "get_max_backref")]
    pub fn max_backref(&self) -> i32 {
        unsafe { ffi::g_regex_get_max_backref(self.to_glib_none().0) }
    }

    /// Gets the number of characters in the longest lookbehind assertion in the
    /// pattern. This information is useful when doing multi-segment matching using
    /// the partial matching facilities.
    ///
    /// # Returns
    ///
    /// the number of characters in the longest lookbehind assertion.
    #[doc(alias = "g_regex_get_max_lookbehind")]
    #[doc(alias = "get_max_lookbehind")]
    pub fn max_lookbehind(&self) -> i32 {
        unsafe { ffi::g_regex_get_max_lookbehind(self.to_glib_none().0) }
    }

    /// Gets the pattern string associated with @self, i.e. a copy of
    /// the string passed to g_regex_new().
    ///
    /// # Returns
    ///
    /// the pattern of @self
    #[doc(alias = "g_regex_get_pattern")]
    #[doc(alias = "get_pattern")]
    pub fn pattern(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_regex_get_pattern(self.to_glib_none().0)) }
    }

    //#[doc(alias = "g_regex_replace_eval")]
    //pub fn replace_eval(&self, string: &[&str], start_position: i32, match_options: RegexMatchFlags, eval: /*Unimplemented*/FnMut(&MatchInfo, /*Ignored*/String) -> bool, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Result<crate::GString, crate::Error> {
    //    unsafe { TODO: call ffi:g_regex_replace_eval() }
    //}
}