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}