1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.MatchInfo;
26 
27 private import glib.ErrorG;
28 private import glib.GException;
29 private import glib.Regex;
30 private import glib.Str;
31 private import glib.c.functions;
32 public  import glib.c.types;
33 public  import gtkc.glibtypes;
34 private import gtkd.Loader;
35 
36 
37 /**
38  * A GMatchInfo is an opaque struct used to return information about
39  * matches.
40  */
41 public class MatchInfo
42 {
43 	/** the main Gtk struct */
44 	protected GMatchInfo* gMatchInfo;
45 	protected bool ownedRef;
46 
47 	/** Get the main Gtk struct */
48 	public GMatchInfo* getMatchInfoStruct(bool transferOwnership = false)
49 	{
50 		if (transferOwnership)
51 			ownedRef = false;
52 		return gMatchInfo;
53 	}
54 
55 	/** the main Gtk struct as a void* */
56 	protected void* getStruct()
57 	{
58 		return cast(void*)gMatchInfo;
59 	}
60 
61 	/**
62 	 * Sets our main struct and passes it to the parent class.
63 	 */
64 	public this (GMatchInfo* gMatchInfo, bool ownedRef = false)
65 	{
66 		this.gMatchInfo = gMatchInfo;
67 		this.ownedRef = ownedRef;
68 	}
69 
70 	~this ()
71 	{
72 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
73 			g_match_info_unref(gMatchInfo);
74 	}
75 
76 
77 	/**
78 	 * Returns a new string containing the text in @string_to_expand with
79 	 * references and escape sequences expanded. References refer to the last
80 	 * match done with @string against @regex and have the same syntax used by
81 	 * g_regex_replace().
82 	 *
83 	 * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
84 	 * passed to g_regex_new().
85 	 *
86 	 * The backreferences are extracted from the string passed to the match
87 	 * function, so you cannot call this function after freeing the string.
88 	 *
89 	 * @match_info may be %NULL in which case @string_to_expand must not
90 	 * contain references. For instance "foo\n" does not refer to an actual
91 	 * pattern and '\n' merely will be replaced with \n character,
92 	 * while to expand "\0" (whole match) one needs the result of a match.
93 	 * Use g_regex_check_replacement() to find out whether @string_to_expand
94 	 * contains references.
95 	 *
96 	 * Params:
97 	 *     stringToExpand = the string to expand
98 	 *
99 	 * Returns: the expanded string, or %NULL if an error occurred
100 	 *
101 	 * Since: 2.14
102 	 *
103 	 * Throws: GException on failure.
104 	 */
105 	public string expandReferences(string stringToExpand)
106 	{
107 		GError* err = null;
108 
109 		auto retStr = g_match_info_expand_references(gMatchInfo, Str.toStringz(stringToExpand), &err);
110 
111 		if (err !is null)
112 		{
113 			throw new GException( new ErrorG(err) );
114 		}
115 
116 		scope(exit) Str.freeString(retStr);
117 		return Str.toString(retStr);
118 	}
119 
120 	/**
121 	 * Retrieves the text matching the @match_num'th capturing
122 	 * parentheses. 0 is the full text of the match, 1 is the first paren
123 	 * set, 2 the second, and so on.
124 	 *
125 	 * If @match_num is a valid sub pattern but it didn't match anything
126 	 * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
127 	 * string is returned.
128 	 *
129 	 * If the match was obtained using the DFA algorithm, that is using
130 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
131 	 * string is not that of a set of parentheses but that of a matched
132 	 * substring. Substrings are matched in reverse order of length, so
133 	 * 0 is the longest match.
134 	 *
135 	 * The string is fetched from the string passed to the match function,
136 	 * so you cannot call this function after freeing the string.
137 	 *
138 	 * Params:
139 	 *     matchNum = number of the sub expression
140 	 *
141 	 * Returns: The matched substring, or %NULL if an error
142 	 *     occurred. You have to free the string yourself
143 	 *
144 	 * Since: 2.14
145 	 */
146 	public string fetch(int matchNum)
147 	{
148 		auto retStr = g_match_info_fetch(gMatchInfo, matchNum);
149 
150 		scope(exit) Str.freeString(retStr);
151 		return Str.toString(retStr);
152 	}
153 
154 	/**
155 	 * Bundles up pointers to each of the matching substrings from a match
156 	 * and stores them in an array of gchar pointers. The first element in
157 	 * the returned array is the match number 0, i.e. the entire matched
158 	 * text.
159 	 *
160 	 * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
161 	 * "b" against "(a)?b") then an empty string is inserted.
162 	 *
163 	 * If the last match was obtained using the DFA algorithm, that is using
164 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
165 	 * strings are not that matched by sets of parentheses but that of the
166 	 * matched substring. Substrings are matched in reverse order of length,
167 	 * so the first one is the longest match.
168 	 *
169 	 * The strings are fetched from the string passed to the match function,
170 	 * so you cannot call this function after freeing the string.
171 	 *
172 	 * Returns: a %NULL-terminated array of gchar *
173 	 *     pointers.  It must be freed using g_strfreev(). If the previous
174 	 *     match failed %NULL is returned
175 	 *
176 	 * Since: 2.14
177 	 */
178 	public string[] fetchAll()
179 	{
180 		auto retStr = g_match_info_fetch_all(gMatchInfo);
181 
182 		scope(exit) Str.freeStringArray(retStr);
183 		return Str.toStringArray(retStr);
184 	}
185 
186 	/**
187 	 * Retrieves the text matching the capturing parentheses named @name.
188 	 *
189 	 * If @name is a valid sub pattern name but it didn't match anything
190 	 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
191 	 * then an empty string is returned.
192 	 *
193 	 * The string is fetched from the string passed to the match function,
194 	 * so you cannot call this function after freeing the string.
195 	 *
196 	 * Params:
197 	 *     name = name of the subexpression
198 	 *
199 	 * Returns: The matched substring, or %NULL if an error
200 	 *     occurred. You have to free the string yourself
201 	 *
202 	 * Since: 2.14
203 	 */
204 	public string fetchNamed(string name)
205 	{
206 		auto retStr = g_match_info_fetch_named(gMatchInfo, Str.toStringz(name));
207 
208 		scope(exit) Str.freeString(retStr);
209 		return Str.toString(retStr);
210 	}
211 
212 	/**
213 	 * Retrieves the position in bytes of the capturing parentheses named @name.
214 	 *
215 	 * If @name is a valid sub pattern name but it didn't match anything
216 	 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
217 	 * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
218 	 *
219 	 * Params:
220 	 *     name = name of the subexpression
221 	 *     startPos = pointer to location where to store
222 	 *         the start position, or %NULL
223 	 *     endPos = pointer to location where to store
224 	 *         the end position, or %NULL
225 	 *
226 	 * Returns: %TRUE if the position was fetched, %FALSE otherwise.
227 	 *     If the position cannot be fetched, @start_pos and @end_pos
228 	 *     are left unchanged.
229 	 *
230 	 * Since: 2.14
231 	 */
232 	public bool fetchNamedPos(string name, out int startPos, out int endPos)
233 	{
234 		return g_match_info_fetch_named_pos(gMatchInfo, Str.toStringz(name), &startPos, &endPos) != 0;
235 	}
236 
237 	/**
238 	 * Retrieves the position in bytes of the @match_num'th capturing
239 	 * parentheses. 0 is the full text of the match, 1 is the first
240 	 * paren set, 2 the second, and so on.
241 	 *
242 	 * If @match_num is a valid sub pattern but it didn't match anything
243 	 * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
244 	 * and @end_pos are set to -1 and %TRUE is returned.
245 	 *
246 	 * If the match was obtained using the DFA algorithm, that is using
247 	 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
248 	 * position is not that of a set of parentheses but that of a matched
249 	 * substring. Substrings are matched in reverse order of length, so
250 	 * 0 is the longest match.
251 	 *
252 	 * Params:
253 	 *     matchNum = number of the sub expression
254 	 *     startPos = pointer to location where to store
255 	 *         the start position, or %NULL
256 	 *     endPos = pointer to location where to store
257 	 *         the end position, or %NULL
258 	 *
259 	 * Returns: %TRUE if the position was fetched, %FALSE otherwise. If
260 	 *     the position cannot be fetched, @start_pos and @end_pos are left
261 	 *     unchanged
262 	 *
263 	 * Since: 2.14
264 	 */
265 	public bool fetchPos(int matchNum, out int startPos, out int endPos)
266 	{
267 		return g_match_info_fetch_pos(gMatchInfo, matchNum, &startPos, &endPos) != 0;
268 	}
269 
270 	/**
271 	 * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
272 	 * nothing.
273 	 *
274 	 * Since: 2.14
275 	 */
276 	public void free()
277 	{
278 		g_match_info_free(gMatchInfo);
279 		ownedRef = false;
280 	}
281 
282 	/**
283 	 * Retrieves the number of matched substrings (including substring 0,
284 	 * that is the whole matched text), so 1 is returned if the pattern
285 	 * has no substrings in it and 0 is returned if the match failed.
286 	 *
287 	 * If the last match was obtained using the DFA algorithm, that is
288 	 * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
289 	 * count is not that of the number of capturing parentheses but that of
290 	 * the number of matched substrings.
291 	 *
292 	 * Returns: Number of matched substrings, or -1 if an error occurred
293 	 *
294 	 * Since: 2.14
295 	 */
296 	public int getMatchCount()
297 	{
298 		return g_match_info_get_match_count(gMatchInfo);
299 	}
300 
301 	/**
302 	 * Returns #GRegex object used in @match_info. It belongs to Glib
303 	 * and must not be freed. Use g_regex_ref() if you need to keep it
304 	 * after you free @match_info object.
305 	 *
306 	 * Returns: #GRegex object used in @match_info
307 	 *
308 	 * Since: 2.14
309 	 */
310 	public Regex getRegex()
311 	{
312 		auto p = g_match_info_get_regex(gMatchInfo);
313 
314 		if(p is null)
315 		{
316 			return null;
317 		}
318 
319 		return new Regex(cast(GRegex*) p, true);
320 	}
321 
322 	/**
323 	 * Returns the string searched with @match_info. This is the
324 	 * string passed to g_regex_match() or g_regex_replace() so
325 	 * you may not free it before calling this function.
326 	 *
327 	 * Returns: the string searched with @match_info
328 	 *
329 	 * Since: 2.14
330 	 */
331 	public string getString()
332 	{
333 		return Str.toString(g_match_info_get_string(gMatchInfo));
334 	}
335 
336 	/**
337 	 * Usually if the string passed to g_regex_match*() matches as far as
338 	 * it goes, but is too short to match the entire pattern, %FALSE is
339 	 * returned. There are circumstances where it might be helpful to
340 	 * distinguish this case from other cases in which there is no match.
341 	 *
342 	 * Consider, for example, an application where a human is required to
343 	 * type in data for a field with specific formatting requirements. An
344 	 * example might be a date in the form ddmmmyy, defined by the pattern
345 	 * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
346 	 * If the application sees the user’s keystrokes one by one, and can
347 	 * check that what has been typed so far is potentially valid, it is
348 	 * able to raise an error as soon as a mistake is made.
349 	 *
350 	 * GRegex supports the concept of partial matching by means of the
351 	 * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags.
352 	 * When they are used, the return code for
353 	 * g_regex_match() or g_regex_match_full() is, as usual, %TRUE
354 	 * for a complete match, %FALSE otherwise. But, when these functions
355 	 * return %FALSE, you can check if the match was partial calling
356 	 * g_match_info_is_partial_match().
357 	 *
358 	 * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and
359 	 * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
360 	 * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
361 	 * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching
362 	 * stops at the partial match.
363 	 * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD
364 	 * are set, the latter takes precedence.
365 	 *
366 	 * There were formerly some restrictions on the pattern for partial matching.
367 	 * The restrictions no longer apply.
368 	 *
369 	 * See pcrepartial(3) for more information on partial matching.
370 	 *
371 	 * Returns: %TRUE if the match was partial, %FALSE otherwise
372 	 *
373 	 * Since: 2.14
374 	 */
375 	public bool isPartialMatch()
376 	{
377 		return g_match_info_is_partial_match(gMatchInfo) != 0;
378 	}
379 
380 	/**
381 	 * Returns whether the previous match operation succeeded.
382 	 *
383 	 * Returns: %TRUE if the previous match operation succeeded,
384 	 *     %FALSE otherwise
385 	 *
386 	 * Since: 2.14
387 	 */
388 	public bool matches()
389 	{
390 		return g_match_info_matches(gMatchInfo) != 0;
391 	}
392 
393 	/**
394 	 * Scans for the next match using the same parameters of the previous
395 	 * call to g_regex_match_full() or g_regex_match() that returned
396 	 * @match_info.
397 	 *
398 	 * The match is done on the string passed to the match function, so you
399 	 * cannot free it before calling this function.
400 	 *
401 	 * Returns: %TRUE is the string matched, %FALSE otherwise
402 	 *
403 	 * Since: 2.14
404 	 *
405 	 * Throws: GException on failure.
406 	 */
407 	public bool next()
408 	{
409 		GError* err = null;
410 
411 		auto p = g_match_info_next(gMatchInfo, &err) != 0;
412 
413 		if (err !is null)
414 		{
415 			throw new GException( new ErrorG(err) );
416 		}
417 
418 		return p;
419 	}
420 
421 	/**
422 	 * Increases reference count of @match_info by 1.
423 	 *
424 	 * Returns: @match_info
425 	 *
426 	 * Since: 2.30
427 	 */
428 	public MatchInfo doref()
429 	{
430 		auto p = g_match_info_ref(gMatchInfo);
431 
432 		if(p is null)
433 		{
434 			return null;
435 		}
436 
437 		return new MatchInfo(cast(GMatchInfo*) p, true);
438 	}
439 
440 	/**
441 	 * Decreases reference count of @match_info by 1. When reference count drops
442 	 * to zero, it frees all the memory associated with the match_info structure.
443 	 *
444 	 * Since: 2.30
445 	 */
446 	public void unref()
447 	{
448 		g_match_info_unref(gMatchInfo);
449 	}
450 }