glib/auto/
regex.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, translate::*, Error, RegexCompileFlags, RegexMatchFlags};
6
7crate::wrapper! {
8    /// A `GRegex` is the "compiled" form of a regular expression pattern.
9    ///
10    /// `GRegex` implements regular expression pattern matching using syntax and
11    /// semantics similar to Perl regular expression. See the
12    /// [PCRE documentation](man:pcrepattern(3)) for the syntax definition.
13    ///
14    /// Some functions accept a @start_position argument, setting it differs
15    /// from just passing over a shortened string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL]
16    /// in the case of a pattern that begins with any kind of lookbehind assertion.
17    /// For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
18    /// in the middle of words. ("\B" matches only if the current position in the
19    /// subject is not a word boundary.) When applied to the string "Mississipi"
20    /// from the fourth byte, namely "issipi", it does not match, because "\B" is
21    /// always false at the start of the subject, which is deemed to be a word
22    /// boundary. However, if the entire string is passed , but with
23    /// @start_position set to 4, it finds the second occurrence of "iss" because
24    /// it is able to look behind the starting point to discover that it is
25    /// preceded by a letter.
26    ///
27    /// Note that, unless you set the [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] flag, all the strings passed
28    /// to these functions must be encoded in UTF-8. The lengths and the positions
29    /// inside the strings are in bytes and not in characters, so, for instance,
30    /// "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
31    /// single character. If you set [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] the strings can be non-valid
32    /// UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
33    /// bytes and two characters long.
34    ///
35    /// When matching a pattern, "\n" matches only against a "\n" character in
36    /// the string, and "\r" matches only a "\r" character. To match any newline
37    /// sequence use "\R". This particular group matches either the two-character
38    /// sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
39    /// U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
40    /// CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
41    /// separator, U+2028), or PS (paragraph separator, U+2029).
42    ///
43    /// The behaviour of the dot, circumflex, and dollar metacharacters are
44    /// affected by newline characters, the default is to recognize any newline
45    /// character (the same characters recognized by "\R"). This can be changed
46    /// with `G_REGEX_NEWLINE_CR`, `G_REGEX_NEWLINE_LF` and `G_REGEX_NEWLINE_CRLF`
47    /// compile options, and with `G_REGEX_MATCH_NEWLINE_ANY`,
48    /// `G_REGEX_MATCH_NEWLINE_CR`, `G_REGEX_MATCH_NEWLINE_LF` and
49    /// `G_REGEX_MATCH_NEWLINE_CRLF` match options. These settings are also
50    /// relevant when compiling a pattern if `G_REGEX_EXTENDED` is set, and an
51    /// unescaped "#" outside a character class is encountered. This indicates
52    /// a comment that lasts until after the next newline.
53    ///
54    /// Creating and manipulating the same `GRegex` structure from different
55    /// threads is not a problem as `GRegex` does not modify its internal
56    /// state between creation and destruction, on the other hand `GMatchInfo`
57    /// is not threadsafe.
58    ///
59    /// The regular expressions low-level functionalities are obtained through
60    /// the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel.
61    // rustdoc-stripper-ignore-next-stop
62    /// A `GRegex` is the "compiled" form of a regular expression pattern.
63    ///
64    /// `GRegex` implements regular expression pattern matching using syntax and
65    /// semantics similar to Perl regular expression. See the
66    /// [PCRE documentation](man:pcrepattern(3)) for the syntax definition.
67    ///
68    /// Some functions accept a @start_position argument, setting it differs
69    /// from just passing over a shortened string and setting [`RegexMatchFlags::NOTBOL`][crate::RegexMatchFlags::NOTBOL]
70    /// in the case of a pattern that begins with any kind of lookbehind assertion.
71    /// For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
72    /// in the middle of words. ("\B" matches only if the current position in the
73    /// subject is not a word boundary.) When applied to the string "Mississipi"
74    /// from the fourth byte, namely "issipi", it does not match, because "\B" is
75    /// always false at the start of the subject, which is deemed to be a word
76    /// boundary. However, if the entire string is passed , but with
77    /// @start_position set to 4, it finds the second occurrence of "iss" because
78    /// it is able to look behind the starting point to discover that it is
79    /// preceded by a letter.
80    ///
81    /// Note that, unless you set the [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] flag, all the strings passed
82    /// to these functions must be encoded in UTF-8. The lengths and the positions
83    /// inside the strings are in bytes and not in characters, so, for instance,
84    /// "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
85    /// single character. If you set [`RegexCompileFlags::RAW`][crate::RegexCompileFlags::RAW] the strings can be non-valid
86    /// UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
87    /// bytes and two characters long.
88    ///
89    /// When matching a pattern, "\n" matches only against a "\n" character in
90    /// the string, and "\r" matches only a "\r" character. To match any newline
91    /// sequence use "\R". This particular group matches either the two-character
92    /// sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
93    /// U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
94    /// CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
95    /// separator, U+2028), or PS (paragraph separator, U+2029).
96    ///
97    /// The behaviour of the dot, circumflex, and dollar metacharacters are
98    /// affected by newline characters, the default is to recognize any newline
99    /// character (the same characters recognized by "\R"). This can be changed
100    /// with `G_REGEX_NEWLINE_CR`, `G_REGEX_NEWLINE_LF` and `G_REGEX_NEWLINE_CRLF`
101    /// compile options, and with `G_REGEX_MATCH_NEWLINE_ANY`,
102    /// `G_REGEX_MATCH_NEWLINE_CR`, `G_REGEX_MATCH_NEWLINE_LF` and
103    /// `G_REGEX_MATCH_NEWLINE_CRLF` match options. These settings are also
104    /// relevant when compiling a pattern if `G_REGEX_EXTENDED` is set, and an
105    /// unescaped "#" outside a character class is encountered. This indicates
106    /// a comment that lasts until after the next newline.
107    ///
108    /// Creating and manipulating the same `GRegex` structure from different
109    /// threads is not a problem as `GRegex` does not modify its internal
110    /// state between creation and destruction, on the other hand `GMatchInfo`
111    /// is not threadsafe.
112    ///
113    /// The regular expressions low-level functionalities are obtained through
114    /// the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel.
115    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
116    pub struct Regex(Shared<ffi::GRegex>);
117
118    match fn {
119        ref => |ptr| ffi::g_regex_ref(ptr),
120        unref => |ptr| ffi::g_regex_unref(ptr),
121        type_ => || ffi::g_regex_get_type(),
122    }
123}
124
125impl Regex {
126    /// Compiles the regular expression to an internal form, and does
127    /// the initial setup of the #GRegex structure.
128    /// ## `pattern`
129    /// the regular expression
130    /// ## `compile_options`
131    /// compile options for the regular expression, or 0
132    /// ## `match_options`
133    /// match options for the regular expression, or 0
134    ///
135    /// # Returns
136    ///
137    /// a #GRegex structure or [`None`] if an error occurred. Call
138    ///   g_regex_unref() when you are done with it
139    // rustdoc-stripper-ignore-next-stop
140    /// Compiles the regular expression to an internal form, and does
141    /// the initial setup of the #GRegex structure.
142    /// ## `pattern`
143    /// the regular expression
144    /// ## `compile_options`
145    /// compile options for the regular expression, or 0
146    /// ## `match_options`
147    /// match options for the regular expression, or 0
148    ///
149    /// # Returns
150    ///
151    /// a #GRegex structure or [`None`] if an error occurred. Call
152    ///   g_regex_unref() when you are done with it
153    #[doc(alias = "g_regex_new")]
154    pub fn new(
155        pattern: &str,
156        compile_options: RegexCompileFlags,
157        match_options: RegexMatchFlags,
158    ) -> Result<Option<Regex>, crate::Error> {
159        unsafe {
160            let mut error = std::ptr::null_mut();
161            let ret = ffi::g_regex_new(
162                pattern.to_glib_none().0,
163                compile_options.into_glib(),
164                match_options.into_glib(),
165                &mut error,
166            );
167            if error.is_null() {
168                Ok(from_glib_full(ret))
169            } else {
170                Err(from_glib_full(error))
171            }
172        }
173    }
174
175    /// Returns the number of capturing subpatterns in the pattern.
176    ///
177    /// # Returns
178    ///
179    /// the number of capturing subpatterns
180    // rustdoc-stripper-ignore-next-stop
181    /// Returns the number of capturing subpatterns in the pattern.
182    ///
183    /// # Returns
184    ///
185    /// the number of capturing subpatterns
186    #[doc(alias = "g_regex_get_capture_count")]
187    #[doc(alias = "get_capture_count")]
188    pub fn capture_count(&self) -> i32 {
189        unsafe { ffi::g_regex_get_capture_count(self.to_glib_none().0) }
190    }
191
192    /// Returns the compile options that @self was created with.
193    ///
194    /// Depending on the version of PCRE that is used, this may or may not
195    /// include flags set by option expressions such as `(?i)` found at the
196    /// top-level within the compiled pattern.
197    ///
198    /// # Returns
199    ///
200    /// flags from #GRegexCompileFlags
201    // rustdoc-stripper-ignore-next-stop
202    /// Returns the compile options that @self was created with.
203    ///
204    /// Depending on the version of PCRE that is used, this may or may not
205    /// include flags set by option expressions such as `(?i)` found at the
206    /// top-level within the compiled pattern.
207    ///
208    /// # Returns
209    ///
210    /// flags from #GRegexCompileFlags
211    #[doc(alias = "g_regex_get_compile_flags")]
212    #[doc(alias = "get_compile_flags")]
213    pub fn compile_flags(&self) -> RegexCompileFlags {
214        unsafe { from_glib(ffi::g_regex_get_compile_flags(self.to_glib_none().0)) }
215    }
216
217    /// Checks whether the pattern contains explicit CR or LF references.
218    ///
219    /// # Returns
220    ///
221    /// [`true`] if the pattern contains explicit CR or LF references
222    // rustdoc-stripper-ignore-next-stop
223    /// Checks whether the pattern contains explicit CR or LF references.
224    ///
225    /// # Returns
226    ///
227    /// [`true`] if the pattern contains explicit CR or LF references
228    #[doc(alias = "g_regex_get_has_cr_or_lf")]
229    #[doc(alias = "get_has_cr_or_lf")]
230    pub fn has_cr_or_lf(&self) -> bool {
231        unsafe { from_glib(ffi::g_regex_get_has_cr_or_lf(self.to_glib_none().0)) }
232    }
233
234    /// Returns the match options that @self was created with.
235    ///
236    /// # Returns
237    ///
238    /// flags from #GRegexMatchFlags
239    // rustdoc-stripper-ignore-next-stop
240    /// Returns the match options that @self was created with.
241    ///
242    /// # Returns
243    ///
244    /// flags from #GRegexMatchFlags
245    #[doc(alias = "g_regex_get_match_flags")]
246    #[doc(alias = "get_match_flags")]
247    pub fn match_flags(&self) -> RegexMatchFlags {
248        unsafe { from_glib(ffi::g_regex_get_match_flags(self.to_glib_none().0)) }
249    }
250
251    /// Returns the number of the highest back reference
252    /// in the pattern, or 0 if the pattern does not contain
253    /// back references.
254    ///
255    /// # Returns
256    ///
257    /// the number of the highest back reference
258    // rustdoc-stripper-ignore-next-stop
259    /// Returns the number of the highest back reference
260    /// in the pattern, or 0 if the pattern does not contain
261    /// back references.
262    ///
263    /// # Returns
264    ///
265    /// the number of the highest back reference
266    #[doc(alias = "g_regex_get_max_backref")]
267    #[doc(alias = "get_max_backref")]
268    pub fn max_backref(&self) -> i32 {
269        unsafe { ffi::g_regex_get_max_backref(self.to_glib_none().0) }
270    }
271
272    /// Gets the number of characters in the longest lookbehind assertion in the
273    /// pattern. This information is useful when doing multi-segment matching using
274    /// the partial matching facilities.
275    ///
276    /// # Returns
277    ///
278    /// the number of characters in the longest lookbehind assertion.
279    // rustdoc-stripper-ignore-next-stop
280    /// Gets the number of characters in the longest lookbehind assertion in the
281    /// pattern. This information is useful when doing multi-segment matching using
282    /// the partial matching facilities.
283    ///
284    /// # Returns
285    ///
286    /// the number of characters in the longest lookbehind assertion.
287    #[doc(alias = "g_regex_get_max_lookbehind")]
288    #[doc(alias = "get_max_lookbehind")]
289    pub fn max_lookbehind(&self) -> i32 {
290        unsafe { ffi::g_regex_get_max_lookbehind(self.to_glib_none().0) }
291    }
292
293    /// Gets the pattern string associated with @self, i.e. a copy of
294    /// the string passed to g_regex_new().
295    ///
296    /// # Returns
297    ///
298    /// the pattern of @self
299    // rustdoc-stripper-ignore-next-stop
300    /// Gets the pattern string associated with @self, i.e. a copy of
301    /// the string passed to g_regex_new().
302    ///
303    /// # Returns
304    ///
305    /// the pattern of @self
306    #[doc(alias = "g_regex_get_pattern")]
307    #[doc(alias = "get_pattern")]
308    pub fn pattern(&self) -> crate::GString {
309        unsafe { from_glib_none(ffi::g_regex_get_pattern(self.to_glib_none().0)) }
310    }
311
312    //#[doc(alias = "g_regex_replace_eval")]
313    //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> {
314    //    unsafe { TODO: call ffi:g_regex_replace_eval() }
315    //}
316}