glib/

regex.rs

// Take a look at the license at the top of the repository in the LICENSE file.

// rustdoc-stripper-ignore-next
//! This module is inefficient and should not be used by Rust programs except for
//! compatibility with GLib.Regex based APIs.

use crate::{
    GStr, GStringPtr, MatchInfo, PtrSlice, Regex, RegexCompileFlags, RegexMatchFlags, ffi,
    translate::*,
};
use std::{mem, ptr};

impl Regex {
    /// Retrieves the number of the subexpression named @name.
    /// ## `name`
    /// name of the subexpression
    ///
    /// # Returns
    ///
    /// The number of the subexpression or -1 if @name
    ///   does not exists
    #[doc(alias = "g_regex_get_string_number")]
    #[doc(alias = "get_string_number")]
    pub fn string_number(&self, name: impl IntoGStr) -> i32 {
        name.run_with_gstr(|name| unsafe {
            ffi::g_regex_get_string_number(self.to_glib_none().0, name.to_glib_none().0)
        })
    }

    /// Escapes the nul characters in @string to "\x00".  It can be used
    /// to compile a regex with embedded nul characters.
    ///
    /// For completeness, @length can be -1 for a nul-terminated string.
    /// In this case the output string will be of course equal to @string.
    /// ## `string`
    /// the string to escape
    /// ## `length`
    /// the length of @string
    ///
    /// # Returns
    ///
    /// a newly-allocated escaped string
    #[doc(alias = "g_regex_escape_nul")]
    pub fn escape_nul(string: impl IntoGStr) -> crate::GString {
        unsafe {
            string.run_with_gstr(|string| {
                from_glib_full(ffi::g_regex_escape_nul(
                    string.to_glib_none().0,
                    string.len() as _,
                ))
            })
        }
    }

    /// Escapes the special characters used for regular expressions
    /// in @string, for instance "a.b*c" becomes "a\.b\*c". This
    /// function is useful to dynamically generate regular expressions.
    ///
    /// @string can contain nul characters that are replaced with "\0",
    /// in this case remember to specify the correct length of @string
    /// in @length.
    /// ## `string`
    /// the string to escape
    /// ## `length`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    ///
    /// # Returns
    ///
    /// a newly-allocated escaped string
    #[doc(alias = "g_regex_escape_string")]
    pub fn escape_string(string: impl IntoGStr) -> crate::GString {
        unsafe {
            string.run_with_gstr(|string| {
                from_glib_full(ffi::g_regex_escape_string(
                    string.to_glib_none().0,
                    string.len() as _,
                ))
            })
        }
    }

    /// Checks whether @replacement is a valid replacement string
    /// (see g_regex_replace()), i.e. that all escape sequences in
    /// it are valid.
    ///
    /// If @has_references is not [`None`] then @replacement is checked
    /// for pattern references. For instance, replacement text 'foo\n'
    /// does not contain references and may be evaluated without information
    /// about actual match, but '\0\1' (whole match followed by first
    /// subpattern) requires valid #GMatchInfo object.
    /// ## `replacement`
    /// the replacement string
    ///
    /// # Returns
    ///
    /// whether @replacement is a valid replacement string
    ///
    /// ## `has_references`
    /// location to store information about
    ///   references in @replacement or [`None`]
    #[doc(alias = "g_regex_check_replacement")]
    pub fn check_replacement(replacement: impl IntoGStr) -> Result<bool, crate::Error> {
        replacement.run_with_gstr(|replacement| unsafe {
            let mut has_references = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let is_ok = ffi::g_regex_check_replacement(
                replacement.to_glib_none().0,
                has_references.as_mut_ptr(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(from_glib(has_references.assume_init()))
            } else {
                Err(from_glib_full(error))
            }
        })
    }

    /// Scans for a match in @string for @pattern.
    ///
    /// This function is equivalent to g_regex_match() but it does not
    /// require to compile the pattern with g_regex_new(), avoiding some
    /// lines of code when you need just to do a match without extracting
    /// substrings, capture counts, and so on.
    ///
    /// If this function is to be called on the same @pattern more than
    /// once, it's more efficient to compile the pattern once with
    /// g_regex_new() and then use g_regex_match().
    /// ## `pattern`
    /// the regular expression
    /// ## `string`
    /// the string to scan for matches
    /// ## `compile_options`
    /// compile options for the regular expression, or 0
    /// ## `match_options`
    /// match options, or 0
    ///
    /// # Returns
    ///
    /// [`true`] if the string matched, [`false`] otherwise
    #[doc(alias = "g_regex_match_simple")]
    pub fn match_simple(
        pattern: impl IntoGStr,
        string: impl IntoGStr,
        compile_options: RegexCompileFlags,
        match_options: RegexMatchFlags,
    ) -> bool {
        pattern.run_with_gstr(|pattern| {
            string.run_with_gstr(|string| unsafe {
                from_glib(ffi::g_regex_match_simple(
                    pattern.to_glib_none().0,
                    string.to_glib_none().0,
                    compile_options.into_glib(),
                    match_options.into_glib(),
                ))
            })
        })
    }

    /// ` refers
    /// to the captured subexpression with the given name. `\0` refers
    /// to the complete match, but `\0` followed by a number is the octal
    /// representation of a character. To include a literal `\` in the
    /// replacement, write `\\\\`.
    ///
    /// There are also escapes that changes the case of the following text:
    ///
    /// - `\l`: Convert to lower case the next character
    /// - `\u`: Convert to upper case the next character
    /// - `\L`: Convert to lower case until the next `\E`
    /// - `\U`: Convert to upper case until the next `\E`
    /// - `\E`: End case modification
    ///
    /// If you do not need to use backreferences use g_regex_replace_literal().
    ///
    /// The @replacement string must be UTF-8 encoded even if [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] was
    /// passed to g_regex_new(). If you want to use not UTF-8 encoded strings
    /// you can use g_regex_replace_literal().
    ///
    /// Setting @start_position differs from just passing over a shortened
    /// string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL] in the case of a pattern that
    /// begins with any kind of lookbehind assertion, such as `"\b"`.
    /// ## `string`
    /// the string to perform matches against
    /// ## `string_len`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    /// ## `start_position`
    /// starting index of the string to match, in bytes
    /// ## `replacement`
    /// text to replace each match with
    /// ## `match_options`
    /// options for the match
    ///
    /// # Returns
    ///
    /// a newly allocated string containing the replacements
    #[doc(alias = "g_regex_replace")]
    pub fn replace(
        &self,
        string: impl IntoGStr,
        start_position: i32,
        replacement: impl IntoGStr,
        match_options: RegexMatchFlags,
    ) -> Result<crate::GString, crate::Error> {
        unsafe {
            string.run_with_gstr(|string| {
                replacement.run_with_gstr(|replacement| {
                    let mut error = ptr::null_mut();
                    let ret = ffi::g_regex_replace(
                        self.to_glib_none().0,
                        string.as_ptr() as *const _,
                        string.len() as _,
                        start_position,
                        replacement.to_glib_none().0,
                        match_options.into_glib(),
                        &mut error,
                    );
                    debug_assert_eq!(ret.is_null(), !error.is_null());
                    if error.is_null() {
                        Ok(from_glib_full(ret))
                    } else {
                        Err(from_glib_full(error))
                    }
                })
            })
        }
    }

    /// Using the standard algorithm for regular expression matching only
    /// the longest match in the string is retrieved. This function uses
    /// a different algorithm so it can retrieve all the possible matches.
    /// For more documentation see g_regex_match_all_full().
    ///
    /// A #GMatchInfo structure, used to get information on the match, is
    /// stored in @match_info if not [`None`]. Note that if @match_info is
    /// not [`None`] then it is created even if the function returns [`false`],
    /// i.e. you must free it regardless if regular expression actually
    /// matched.
    ///
    /// @string is not copied and is used in #GMatchInfo internally. If
    /// you use any #GMatchInfo method (except g_match_info_free()) after
    /// freeing or modifying @string then the behaviour is undefined.
    /// ## `string`
    /// the string to scan for matches
    /// ## `match_options`
    /// match options
    ///
    /// # Returns
    ///
    /// [`true`] is the string matched, [`false`] otherwise
    ///
    /// ## `match_info`
    /// pointer to location where to store
    ///     the #GMatchInfo, or [`None`] if you do not need it
    #[doc(alias = "g_regex_match_all")]
    pub fn match_all<'input>(
        &self,
        string: &'input GStr,
        match_options: RegexMatchFlags,
    ) -> Result<MatchInfo<'input>, crate::Error> {
        self.match_all_full(string, 0, match_options)
    }

    /// "`.
    ///
    /// The number of matched strings is retrieved using
    /// g_match_info_get_match_count(). To obtain the matched strings and
    /// their position you can use, respectively, g_match_info_fetch() and
    /// g_match_info_fetch_pos(). Note that the strings are returned in
    /// reverse order of length; that is, the longest matching string is
    /// given first.
    ///
    /// Note that the DFA algorithm is slower than the standard one and it
    /// is not able to capture substrings, so backreferences do not work.
    ///
    /// Setting @start_position differs from just passing over a shortened
    /// string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL] in the case of a pattern
    /// that begins with any kind of lookbehind assertion, such as "\b".
    ///
    /// Unless [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] is specified in the options, @string must be valid UTF-8.
    ///
    /// A #GMatchInfo structure, used to get information on the match, is
    /// stored in @match_info if not [`None`]. Note that if @match_info is
    /// not [`None`] then it is created even if the function returns [`false`],
    /// i.e. you must free it regardless if regular expression actually
    /// matched.
    ///
    /// @string is not copied and is used in #GMatchInfo internally. If
    /// you use any #GMatchInfo method (except g_match_info_free()) after
    /// freeing or modifying @string then the behaviour is undefined.
    /// ## `string`
    /// the string to scan for matches
    /// ## `string_len`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    /// ## `start_position`
    /// starting index of the string to match, in bytes
    /// ## `match_options`
    /// match options
    ///
    /// # Returns
    ///
    /// [`true`] is the string matched, [`false`] otherwise
    ///
    /// ## `match_info`
    /// pointer to location where to store
    ///     the #GMatchInfo, or [`None`] if you do not need it
    #[doc(alias = "g_regex_match_all_full")]
    pub fn match_all_full<'input>(
        &self,
        string: &'input GStr,
        start_position: i32,
        match_options: RegexMatchFlags,
    ) -> Result<MatchInfo<'input>, crate::Error> {
        unsafe {
            let mut match_info = ptr::null_mut();
            let mut error = ptr::null_mut();
            let res = ffi::g_regex_match_all_full(
                self.to_glib_none().0,
                string.to_glib_none().0,
                string.len() as _,
                start_position,
                match_options.into_glib(),
                &mut match_info,
                &mut error,
            );
            if error.is_null() {
                let match_info = MatchInfo::from_glib_full(match_info);
                debug_assert_eq!(match_info.matches(), from_glib(res));
                Ok(match_info)
            } else {
                debug_assert!(match_info.is_null());
                Err(from_glib_full(error))
            }
        }
    }

    /// match_info);
    ///   while (g_match_info_matches (match_info))
    ///     {
    ///       gchar *word = g_match_info_fetch (match_info, 0);
    ///       g_print ("Found: `s`\n", word);
    ///       g_free (word);
    ///       g_match_info_next (match_info, NULL);
    ///     }
    ///   g_match_info_free (match_info);
    ///   g_regex_unref (regex);
    /// }
    /// ]|
    ///
    /// @string is not copied and is used in #GMatchInfo internally. If
    /// you use any #GMatchInfo method (except g_match_info_free()) after
    /// freeing or modifying @string then the behaviour is undefined.
    /// ## `string`
    /// the string to scan for matches
    /// ## `match_options`
    /// match options
    ///
    /// # Returns
    ///
    /// [`true`] is the string matched, [`false`] otherwise
    ///
    /// ## `match_info`
    /// pointer to location where to store
    ///     the #GMatchInfo, or [`None`] if you do not need it
    #[doc(alias = "g_regex_match")]
    pub fn match_<'input>(
        &self,
        string: &'input GStr,
        match_options: RegexMatchFlags,
    ) -> Result<MatchInfo<'input>, crate::Error> {
        self.match_full(string, 0, match_options)
    }

    /// message);
    ///       g_error_free (error);
    ///     }
    /// }
    /// ]|
    /// ## `string`
    /// the string to scan for matches
    /// ## `string_len`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    /// ## `start_position`
    /// starting index of the string to match, in bytes
    /// ## `match_options`
    /// match options
    ///
    /// # Returns
    ///
    /// [`true`] is the string matched, [`false`] otherwise
    ///
    /// ## `match_info`
    /// pointer to location where to store
    ///     the #GMatchInfo, or [`None`] if you do not need it
    #[doc(alias = "g_regex_match_full")]
    pub fn match_full<'input>(
        &self,
        string: &'input GStr,
        start_position: i32,
        match_options: RegexMatchFlags,
    ) -> Result<MatchInfo<'input>, crate::Error> {
        unsafe {
            let mut match_info = ptr::null_mut();
            let mut error = ptr::null_mut();
            let res = ffi::g_regex_match_full(
                self.to_glib_none().0,
                string.to_glib_none().0,
                string.len() as _,
                start_position,
                match_options.into_glib(),
                &mut match_info,
                &mut error,
            );
            if error.is_null() {
                let match_info = MatchInfo::from_glib_full(match_info);
                debug_assert_eq!(match_info.matches(), from_glib(res));
                Ok(match_info)
            } else {
                debug_assert!(match_info.is_null());
                Err(from_glib_full(error))
            }
        }
    }

    /// Replaces all occurrences of the pattern in @self with the
    /// replacement text. @replacement is replaced literally, to
    /// include backreferences use g_regex_replace().
    ///
    /// Setting @start_position differs from just passing over a
    /// shortened string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL] in the
    /// case of a pattern that begins with any kind of lookbehind
    /// assertion, such as "\b".
    /// ## `string`
    /// the string to perform matches against
    /// ## `string_len`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    /// ## `start_position`
    /// starting index of the string to match, in bytes
    /// ## `replacement`
    /// text to replace each match with
    /// ## `match_options`
    /// options for the match
    ///
    /// # Returns
    ///
    /// a newly allocated string containing the replacements
    #[doc(alias = "g_regex_replace_literal")]
    pub fn replace_literal(
        &self,
        string: impl IntoGStr,
        start_position: i32,
        replacement: impl IntoGStr,
        match_options: RegexMatchFlags,
    ) -> Result<crate::GString, crate::Error> {
        unsafe {
            string.run_with_gstr(|string| {
                replacement.run_with_gstr(|replacement| {
                    let mut error = ptr::null_mut();
                    let ret = ffi::g_regex_replace_literal(
                        self.to_glib_none().0,
                        string.to_glib_none().0,
                        string.len() as _,
                        start_position,
                        replacement.to_glib_none().0,
                        match_options.into_glib(),
                        &mut error,
                    );
                    debug_assert_eq!(ret.is_null(), !error.is_null());
                    if error.is_null() {
                        Ok(from_glib_full(ret))
                    } else {
                        Err(from_glib_full(error))
                    }
                })
            })
        }
    }

    /// Breaks the string on the pattern, and returns an array of the tokens.
    /// If the pattern contains capturing parentheses, then the text for each
    /// of the substrings will also be returned. If the pattern does not match
    /// anywhere in the string, then the whole string is returned as the first
    /// token.
    ///
    /// As a special case, the result of splitting the empty string "" is an
    /// empty vector, not a vector containing a single string. The reason for
    /// this special case is that being able to represent an empty vector is
    /// typically more useful than consistent handling of empty elements. If
    /// you do need to represent empty elements, you'll need to check for the
    /// empty string before calling this function.
    ///
    /// A pattern that can match empty strings splits @string into separate
    /// characters wherever it matches the empty string between characters.
    /// For example splitting "ab c" using as a separator "\s*", you will get
    /// "a", "b" and "c".
    /// ## `string`
    /// the string to split with the pattern
    /// ## `match_options`
    /// match time option flags
    ///
    /// # Returns
    ///
    /// a [`None`]-terminated gchar ** array. Free
    /// it using g_strfreev()
    #[doc(alias = "g_regex_split")]
    pub fn split(
        &self,
        string: impl IntoGStr,
        match_options: RegexMatchFlags,
    ) -> PtrSlice<GStringPtr> {
        self.split_full(string, 0, match_options, 0)
            .unwrap_or_default()
    }

    /// Breaks the string on the pattern, and returns an array of the tokens.
    /// If the pattern contains capturing parentheses, then the text for each
    /// of the substrings will also be returned. If the pattern does not match
    /// anywhere in the string, then the whole string is returned as the first
    /// token.
    ///
    /// As a special case, the result of splitting the empty string "" is an
    /// empty vector, not a vector containing a single string. The reason for
    /// this special case is that being able to represent an empty vector is
    /// typically more useful than consistent handling of empty elements. If
    /// you do need to represent empty elements, you'll need to check for the
    /// empty string before calling this function.
    ///
    /// A pattern that can match empty strings splits @string into separate
    /// characters wherever it matches the empty string between characters.
    /// For example splitting "ab c" using as a separator "\s*", you will get
    /// "a", "b" and "c".
    ///
    /// Setting @start_position differs from just passing over a shortened
    /// string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL] in the case of a pattern
    /// that begins with any kind of lookbehind assertion, such as "\b".
    /// ## `string`
    /// the string to split with the pattern
    /// ## `string_len`
    /// the length of @string, in bytes, or -1 if @string is nul-terminated
    /// ## `start_position`
    /// starting index of the string to match, in bytes
    /// ## `match_options`
    /// match time option flags
    /// ## `max_tokens`
    /// the maximum number of tokens to split @string into.
    ///   If this is less than 1, the string is split completely
    ///
    /// # Returns
    ///
    /// a [`None`]-terminated gchar ** array. Free
    /// it using g_strfreev()
    #[doc(alias = "g_regex_split_full")]
    pub fn split_full(
        &self,
        string: impl IntoGStr,
        start_position: i32,
        match_options: RegexMatchFlags,
        max_tokens: i32,
    ) -> Result<PtrSlice<GStringPtr>, crate::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            string.run_with_gstr(|string| {
                let ret = ffi::g_regex_split_full(
                    self.to_glib_none().0,
                    string.to_glib_none().0,
                    string.len() as _,
                    start_position,
                    match_options.into_glib(),
                    max_tokens,
                    &mut error,
                );
                debug_assert_eq!(ret.is_null(), !error.is_null());
                if error.is_null() {
                    Ok(FromGlibPtrContainer::from_glib_full(ret))
                } else {
                    Err(from_glib_full(error))
                }
            })
        }
    }

    /// Breaks the string on the pattern, and returns an array of
    /// the tokens. If the pattern contains capturing parentheses,
    /// then the text for each of the substrings will also be returned.
    /// If the pattern does not match anywhere in the string, then the
    /// whole string is returned as the first token.
    ///
    /// This function is equivalent to g_regex_split() but it does
    /// not require to compile the pattern with g_regex_new(), avoiding
    /// some lines of code when you need just to do a split without
    /// extracting substrings, capture counts, and so on.
    ///
    /// If this function is to be called on the same @pattern more than
    /// once, it's more efficient to compile the pattern once with
    /// g_regex_new() and then use g_regex_split().
    ///
    /// As a special case, the result of splitting the empty string ""
    /// is an empty vector, not a vector containing a single string.
    /// The reason for this special case is that being able to represent
    /// an empty vector is typically more useful than consistent handling
    /// of empty elements. If you do need to represent empty elements,
    /// you'll need to check for the empty string before calling this
    /// function.
    ///
    /// A pattern that can match empty strings splits @string into
    /// separate characters wherever it matches the empty string between
    /// characters. For example splitting "ab c" using as a separator
    /// "\s*", you will get "a", "b" and "c".
    /// ## `pattern`
    /// the regular expression
    /// ## `string`
    /// the string to scan for matches
    /// ## `compile_options`
    /// compile options for the regular expression, or 0
    /// ## `match_options`
    /// match options, or 0
    ///
    /// # Returns
    ///
    /// a [`None`]-terminated array of strings. Free
    /// it using g_strfreev()
    #[doc(alias = "g_regex_split_simple")]
    pub fn split_simple(
        pattern: impl IntoGStr,
        string: impl IntoGStr,
        compile_options: RegexCompileFlags,
        match_options: RegexMatchFlags,
    ) -> PtrSlice<GStringPtr> {
        pattern.run_with_gstr(|pattern| {
            string.run_with_gstr(|string| unsafe {
                FromGlibPtrContainer::from_glib_full(ffi::g_regex_split_simple(
                    pattern.to_glib_none().0,
                    string.to_glib_none().0,
                    compile_options.into_glib(),
                    match_options.into_glib(),
                ))
            })
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_replace_literal() {
        let regex = Regex::new(
            "s[ai]mple",
            RegexCompileFlags::OPTIMIZE,
            RegexMatchFlags::DEFAULT,
        )
        .expect("Regex new")
        .expect("Null regex");

        let quote = "This is a simple sample.";
        let result = regex
            .replace_literal(quote, 0, "XXX", RegexMatchFlags::DEFAULT)
            .expect("regex replace");

        assert_eq!(result, "This is a XXX XXX.");
    }

    #[test]
    fn test_split() {
        let regex = Regex::new(
            "s[ai]mple",
            RegexCompileFlags::OPTIMIZE,
            RegexMatchFlags::DEFAULT,
        )
        .expect("Regex new")
        .expect("Null regex");

        let quote = "This is a simple sample.";
        let result = regex.split(quote, RegexMatchFlags::DEFAULT);

        assert_eq!(result.len(), 3);
        assert_eq!(result[0], "This is a ");
        assert_eq!(result[1], " ");
        assert_eq!(result[2], ".");
    }

    #[test]
    fn test_match() {
        let regex = Regex::new(r"\d", RegexCompileFlags::DEFAULT, RegexMatchFlags::DEFAULT)
            .expect("Regex new")
            .expect("Null regex");

        let input = crate::GString::from("87");
        let m = regex.match_(input.as_gstr(), RegexMatchFlags::DEFAULT);
        let m = m.unwrap();
        assert!(m.matches());
        assert_eq!(m.match_count(), 1);
        assert_eq!(m.fetch(0).as_deref(), Some("8"));
        assert!(m.next().unwrap());
        assert_eq!(m.fetch(0).as_deref(), Some("7"));
        assert!(!m.next().unwrap());
        assert!(m.fetch(0).is_none());

        let input = crate::GString::from("a");
        let m = regex.match_(input.as_gstr(), RegexMatchFlags::DEFAULT);
        let m = m.unwrap();
        assert!(!m.matches());
        assert_eq!(m.match_count(), 0);
        assert!(m.fetch(0).is_none());
    }
}