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.Regex;
26 
27 private import glib.ConstructionException;
28 private import glib.ErrorG;
29 private import glib.GException;
30 private import glib.MatchInfo;
31 private import glib.Str;
32 private import glib.c.functions;
33 public  import glib.c.types;
34 public  import gtkc.glibtypes;
35 private import gtkd.Loader;
36 
37 
38 /**
39  * The g_regex_*() functions implement regular
40  * expression pattern matching using syntax and semantics similar to
41  * Perl regular expression.
42  * 
43  * Some functions accept a @start_position argument, setting it differs
44  * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
45  * in the case of a pattern that begins with any kind of lookbehind assertion.
46  * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
47  * in the middle of words. ("\B" matches only if the current position in the
48  * subject is not a word boundary.) When applied to the string "Mississipi"
49  * from the fourth byte, namely "issipi", it does not match, because "\B" is
50  * always false at the start of the subject, which is deemed to be a word
51  * boundary. However, if the entire string is passed , but with
52  * @start_position set to 4, it finds the second occurrence of "iss" because
53  * it is able to look behind the starting point to discover that it is
54  * preceded by a letter.
55  * 
56  * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
57  * to these functions must be encoded in UTF-8. The lengths and the positions
58  * inside the strings are in bytes and not in characters, so, for instance,
59  * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
60  * single character. If you set #G_REGEX_RAW the strings can be non-valid
61  * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
62  * bytes and two characters long.
63  * 
64  * When matching a pattern, "\n" matches only against a "\n" character in
65  * the string, and "\r" matches only a "\r" character. To match any newline
66  * sequence use "\R". This particular group matches either the two-character
67  * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
68  * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
69  * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
70  * separator, U+2028), or PS (paragraph separator, U+2029).
71  * 
72  * The behaviour of the dot, circumflex, and dollar metacharacters are
73  * affected by newline characters, the default is to recognize any newline
74  * character (the same characters recognized by "\R"). This can be changed
75  * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF
76  * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY,
77  * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and
78  * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
79  * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
80  * unescaped "#" outside a character class is encountered. This indicates
81  * a comment that lasts until after the next newline.
82  * 
83  * When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern
84  * matching is changed to be compatible with the way that regular expressions
85  * work in JavaScript. More precisely, a lonely ']' character in the pattern
86  * is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and
87  * you must use the '\u' escape sequence with 4 hex digits to specify a unicode
88  * codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by
89  * the specified number of hex digits, they match 'x' and 'u' literally; also
90  * '\U' always matches 'U' instead of being an error in the pattern. Finally,
91  * pattern matching is modified so that back references to an unset subpattern
92  * group produces a match with the empty string instead of an error. See
93  * pcreapi(3) for more information.
94  * 
95  * Creating and manipulating the same #GRegex structure from different
96  * threads is not a problem as #GRegex does not modify its internal
97  * state between creation and destruction, on the other hand #GMatchInfo
98  * is not threadsafe.
99  * 
100  * The regular expressions low-level functionalities are obtained through
101  * the excellent
102  * [PCRE](http://www.pcre.org/)
103  * library written by Philip Hazel.
104  *
105  * Since: 2.14
106  */
107 public class Regex
108 {
109 	/** the main Gtk struct */
110 	protected GRegex* gRegex;
111 	protected bool ownedRef;
112 
113 	/** Get the main Gtk struct */
114 	public GRegex* getRegexStruct(bool transferOwnership = false)
115 	{
116 		if (transferOwnership)
117 			ownedRef = false;
118 		return gRegex;
119 	}
120 
121 	/** the main Gtk struct as a void* */
122 	protected void* getStruct()
123 	{
124 		return cast(void*)gRegex;
125 	}
126 
127 	/**
128 	 * Sets our main struct and passes it to the parent class.
129 	 */
130 	public this (GRegex* gRegex, bool ownedRef = false)
131 	{
132 		this.gRegex = gRegex;
133 		this.ownedRef = ownedRef;
134 	}
135 
136 	~this ()
137 	{
138 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
139 			g_regex_unref(gRegex);
140 	}
141 
142 
143 	/**
144 	 * Compiles the regular expression to an internal form, and does
145 	 * the initial setup of the #GRegex structure.
146 	 *
147 	 * Params:
148 	 *     pattern = the regular expression
149 	 *     compileOptions = compile options for the regular expression, or 0
150 	 *     matchOptions = match options for the regular expression, or 0
151 	 *
152 	 * Returns: a #GRegex structure or %NULL if an error occured. Call
153 	 *     g_regex_unref() when you are done with it
154 	 *
155 	 * Since: 2.14
156 	 *
157 	 * Throws: GException on failure.
158 	 * Throws: ConstructionException GTK+ fails to create the object.
159 	 */
160 	public this(string pattern, GRegexCompileFlags compileOptions, GRegexMatchFlags matchOptions)
161 	{
162 		GError* err = null;
163 
164 		auto p = g_regex_new(Str.toStringz(pattern), compileOptions, matchOptions, &err);
165 
166 		if (err !is null)
167 		{
168 			throw new GException( new ErrorG(err) );
169 		}
170 
171 		if(p is null)
172 		{
173 			throw new ConstructionException("null returned by new");
174 		}
175 
176 		this(cast(GRegex*) p);
177 	}
178 
179 	/**
180 	 * Returns the number of capturing subpatterns in the pattern.
181 	 *
182 	 * Returns: the number of capturing subpatterns
183 	 *
184 	 * Since: 2.14
185 	 */
186 	public int getCaptureCount()
187 	{
188 		return g_regex_get_capture_count(gRegex);
189 	}
190 
191 	/**
192 	 * Returns the compile options that @regex 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: flags from #GRegexCompileFlags
199 	 *
200 	 * Since: 2.26
201 	 */
202 	public GRegexCompileFlags getCompileFlags()
203 	{
204 		return g_regex_get_compile_flags(gRegex);
205 	}
206 
207 	/**
208 	 * Checks whether the pattern contains explicit CR or LF references.
209 	 *
210 	 * Returns: %TRUE if the pattern contains explicit CR or LF references
211 	 *
212 	 * Since: 2.34
213 	 */
214 	public bool getHasCrOrLf()
215 	{
216 		return g_regex_get_has_cr_or_lf(gRegex) != 0;
217 	}
218 
219 	/**
220 	 * Returns the match options that @regex was created with.
221 	 *
222 	 * Returns: flags from #GRegexMatchFlags
223 	 *
224 	 * Since: 2.26
225 	 */
226 	public GRegexMatchFlags getMatchFlags()
227 	{
228 		return g_regex_get_match_flags(gRegex);
229 	}
230 
231 	/**
232 	 * Returns the number of the highest back reference
233 	 * in the pattern, or 0 if the pattern does not contain
234 	 * back references.
235 	 *
236 	 * Returns: the number of the highest back reference
237 	 *
238 	 * Since: 2.14
239 	 */
240 	public int getMaxBackref()
241 	{
242 		return g_regex_get_max_backref(gRegex);
243 	}
244 
245 	/**
246 	 * Gets the number of characters in the longest lookbehind assertion in the
247 	 * pattern. This information is useful when doing multi-segment matching using
248 	 * the partial matching facilities.
249 	 *
250 	 * Returns: the number of characters in the longest lookbehind assertion.
251 	 *
252 	 * Since: 2.38
253 	 */
254 	public int getMaxLookbehind()
255 	{
256 		return g_regex_get_max_lookbehind(gRegex);
257 	}
258 
259 	/**
260 	 * Gets the pattern string associated with @regex, i.e. a copy of
261 	 * the string passed to g_regex_new().
262 	 *
263 	 * Returns: the pattern of @regex
264 	 *
265 	 * Since: 2.14
266 	 */
267 	public string getPattern()
268 	{
269 		return Str.toString(g_regex_get_pattern(gRegex));
270 	}
271 
272 	/**
273 	 * Retrieves the number of the subexpression named @name.
274 	 *
275 	 * Params:
276 	 *     name = name of the subexpression
277 	 *
278 	 * Returns: The number of the subexpression or -1 if @name
279 	 *     does not exists
280 	 *
281 	 * Since: 2.14
282 	 */
283 	public int getStringNumber(string name)
284 	{
285 		return g_regex_get_string_number(gRegex, Str.toStringz(name));
286 	}
287 
288 	/**
289 	 * Scans for a match in string for the pattern in @regex.
290 	 * The @match_options are combined with the match options specified
291 	 * when the @regex structure was created, letting you have more
292 	 * flexibility in reusing #GRegex structures.
293 	 *
294 	 * A #GMatchInfo structure, used to get information on the match,
295 	 * is stored in @match_info if not %NULL. Note that if @match_info
296 	 * is not %NULL then it is created even if the function returns %FALSE,
297 	 * i.e. you must free it regardless if regular expression actually matched.
298 	 *
299 	 * To retrieve all the non-overlapping matches of the pattern in
300 	 * string you can use g_match_info_next().
301 	 *
302 	 * |[<!-- language="C" -->
303 	 * static void
304 	 * print_uppercase_words (const gchar *string)
305 	 * {
306 	 * // Print all uppercase-only words.
307 	 * GRegex *regex;
308 	 * GMatchInfo *match_info;
309 	 *
310 	 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
311 	 * g_regex_match (regex, string, 0, &match_info);
312 	 * while (g_match_info_matches (match_info))
313 	 * {
314 	 * gchar *word = g_match_info_fetch (match_info, 0);
315 	 * g_print ("Found: %s\n", word);
316 	 * g_free (word);
317 	 * g_match_info_next (match_info, NULL);
318 	 * }
319 	 * g_match_info_free (match_info);
320 	 * g_regex_unref (regex);
321 	 * }
322 	 * ]|
323 	 *
324 	 * @string is not copied and is used in #GMatchInfo internally. If
325 	 * you use any #GMatchInfo method (except g_match_info_free()) after
326 	 * freeing or modifying @string then the behaviour is undefined.
327 	 *
328 	 * Params:
329 	 *     str = the string to scan for matches
330 	 *     matchOptions = match options
331 	 *     matchInfo = pointer to location where to store
332 	 *         the #GMatchInfo, or %NULL if you do not need it
333 	 *
334 	 * Returns: %TRUE is the string matched, %FALSE otherwise
335 	 *
336 	 * Since: 2.14
337 	 */
338 	public bool match(string str, GRegexMatchFlags matchOptions, out MatchInfo matchInfo)
339 	{
340 		GMatchInfo* outmatchInfo = null;
341 
342 		auto p = g_regex_match(gRegex, Str.toStringz(str), matchOptions, &outmatchInfo) != 0;
343 
344 		matchInfo = new MatchInfo(outmatchInfo);
345 
346 		return p;
347 	}
348 
349 	/**
350 	 * Using the standard algorithm for regular expression matching only
351 	 * the longest match in the string is retrieved. This function uses
352 	 * a different algorithm so it can retrieve all the possible matches.
353 	 * For more documentation see g_regex_match_all_full().
354 	 *
355 	 * A #GMatchInfo structure, used to get information on the match, is
356 	 * stored in @match_info if not %NULL. Note that if @match_info is
357 	 * not %NULL then it is created even if the function returns %FALSE,
358 	 * i.e. you must free it regardless if regular expression actually
359 	 * matched.
360 	 *
361 	 * @string is not copied and is used in #GMatchInfo internally. If
362 	 * you use any #GMatchInfo method (except g_match_info_free()) after
363 	 * freeing or modifying @string then the behaviour is undefined.
364 	 *
365 	 * Params:
366 	 *     str = the string to scan for matches
367 	 *     matchOptions = match options
368 	 *     matchInfo = pointer to location where to store
369 	 *         the #GMatchInfo, or %NULL if you do not need it
370 	 *
371 	 * Returns: %TRUE is the string matched, %FALSE otherwise
372 	 *
373 	 * Since: 2.14
374 	 */
375 	public bool matchAll(string str, GRegexMatchFlags matchOptions, out MatchInfo matchInfo)
376 	{
377 		GMatchInfo* outmatchInfo = null;
378 
379 		auto p = g_regex_match_all(gRegex, Str.toStringz(str), matchOptions, &outmatchInfo) != 0;
380 
381 		matchInfo = new MatchInfo(outmatchInfo);
382 
383 		return p;
384 	}
385 
386 	/**
387 	 * Using the standard algorithm for regular expression matching only
388 	 * the longest match in the string is retrieved, it is not possible
389 	 * to obtain all the available matches. For instance matching
390 	 * "<a> <b> <c>" against the pattern "<.*>"
391 	 * you get "<a> <b> <c>".
392 	 *
393 	 * This function uses a different algorithm (called DFA, i.e. deterministic
394 	 * finite automaton), so it can retrieve all the possible matches, all
395 	 * starting at the same point in the string. For instance matching
396 	 * "<a> <b> <c>" against the pattern "<.*>;"
397 	 * you would obtain three matches: "<a> <b> <c>",
398 	 * "<a> <b>" and "<a>".
399 	 *
400 	 * The number of matched strings is retrieved using
401 	 * g_match_info_get_match_count(). To obtain the matched strings and
402 	 * their position you can use, respectively, g_match_info_fetch() and
403 	 * g_match_info_fetch_pos(). Note that the strings are returned in
404 	 * reverse order of length; that is, the longest matching string is
405 	 * given first.
406 	 *
407 	 * Note that the DFA algorithm is slower than the standard one and it
408 	 * is not able to capture substrings, so backreferences do not work.
409 	 *
410 	 * Setting @start_position differs from just passing over a shortened
411 	 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
412 	 * that begins with any kind of lookbehind assertion, such as "\b".
413 	 *
414 	 * A #GMatchInfo structure, used to get information on the match, is
415 	 * stored in @match_info if not %NULL. Note that if @match_info is
416 	 * not %NULL then it is created even if the function returns %FALSE,
417 	 * i.e. you must free it regardless if regular expression actually
418 	 * matched.
419 	 *
420 	 * @string is not copied and is used in #GMatchInfo internally. If
421 	 * you use any #GMatchInfo method (except g_match_info_free()) after
422 	 * freeing or modifying @string then the behaviour is undefined.
423 	 *
424 	 * Params:
425 	 *     str = the string to scan for matches
426 	 *     startPosition = starting index of the string to match, in bytes
427 	 *     matchOptions = match options
428 	 *     matchInfo = pointer to location where to store
429 	 *         the #GMatchInfo, or %NULL if you do not need it
430 	 *
431 	 * Returns: %TRUE is the string matched, %FALSE otherwise
432 	 *
433 	 * Since: 2.14
434 	 *
435 	 * Throws: GException on failure.
436 	 */
437 	public bool matchAllFull(string str, int startPosition, GRegexMatchFlags matchOptions, out MatchInfo matchInfo)
438 	{
439 		GMatchInfo* outmatchInfo = null;
440 		GError* err = null;
441 
442 		auto p = g_regex_match_all_full(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, matchOptions, &outmatchInfo, &err) != 0;
443 
444 		if (err !is null)
445 		{
446 			throw new GException( new ErrorG(err) );
447 		}
448 
449 		matchInfo = new MatchInfo(outmatchInfo);
450 
451 		return p;
452 	}
453 
454 	/**
455 	 * Scans for a match in string for the pattern in @regex.
456 	 * The @match_options are combined with the match options specified
457 	 * when the @regex structure was created, letting you have more
458 	 * flexibility in reusing #GRegex structures.
459 	 *
460 	 * Setting @start_position differs from just passing over a shortened
461 	 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
462 	 * that begins with any kind of lookbehind assertion, such as "\b".
463 	 *
464 	 * A #GMatchInfo structure, used to get information on the match, is
465 	 * stored in @match_info if not %NULL. Note that if @match_info is
466 	 * not %NULL then it is created even if the function returns %FALSE,
467 	 * i.e. you must free it regardless if regular expression actually
468 	 * matched.
469 	 *
470 	 * @string is not copied and is used in #GMatchInfo internally. If
471 	 * you use any #GMatchInfo method (except g_match_info_free()) after
472 	 * freeing or modifying @string then the behaviour is undefined.
473 	 *
474 	 * To retrieve all the non-overlapping matches of the pattern in
475 	 * string you can use g_match_info_next().
476 	 *
477 	 * |[<!-- language="C" -->
478 	 * static void
479 	 * print_uppercase_words (const gchar *string)
480 	 * {
481 	 * // Print all uppercase-only words.
482 	 * GRegex *regex;
483 	 * GMatchInfo *match_info;
484 	 * GError *error = NULL;
485 	 *
486 	 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
487 	 * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
488 	 * while (g_match_info_matches (match_info))
489 	 * {
490 	 * gchar *word = g_match_info_fetch (match_info, 0);
491 	 * g_print ("Found: %s\n", word);
492 	 * g_free (word);
493 	 * g_match_info_next (match_info, &error);
494 	 * }
495 	 * g_match_info_free (match_info);
496 	 * g_regex_unref (regex);
497 	 * if (error != NULL)
498 	 * {
499 	 * g_printerr ("Error while matching: %s\n", error->message);
500 	 * g_error_free (error);
501 	 * }
502 	 * }
503 	 * ]|
504 	 *
505 	 * Params:
506 	 *     str = the string to scan for matches
507 	 *     startPosition = starting index of the string to match, in bytes
508 	 *     matchOptions = match options
509 	 *     matchInfo = pointer to location where to store
510 	 *         the #GMatchInfo, or %NULL if you do not need it
511 	 *
512 	 * Returns: %TRUE is the string matched, %FALSE otherwise
513 	 *
514 	 * Since: 2.14
515 	 *
516 	 * Throws: GException on failure.
517 	 */
518 	public bool matchFull(string str, int startPosition, GRegexMatchFlags matchOptions, out MatchInfo matchInfo)
519 	{
520 		GMatchInfo* outmatchInfo = null;
521 		GError* err = null;
522 
523 		auto p = g_regex_match_full(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, matchOptions, &outmatchInfo, &err) != 0;
524 
525 		if (err !is null)
526 		{
527 			throw new GException( new ErrorG(err) );
528 		}
529 
530 		matchInfo = new MatchInfo(outmatchInfo);
531 
532 		return p;
533 	}
534 
535 	/**
536 	 * Increases reference count of @regex by 1.
537 	 *
538 	 * Returns: @regex
539 	 *
540 	 * Since: 2.14
541 	 */
542 	public Regex doref()
543 	{
544 		auto p = g_regex_ref(gRegex);
545 
546 		if(p is null)
547 		{
548 			return null;
549 		}
550 
551 		return new Regex(cast(GRegex*) p, true);
552 	}
553 
554 	/**
555 	 * Replaces all occurrences of the pattern in @regex with the
556 	 * replacement text. Backreferences of the form '\number' or
557 	 * '\g<number>' in the replacement text are interpolated by the
558 	 * number-th captured subexpression of the match, '\g<name>' refers
559 	 * to the captured subexpression with the given name. '\0' refers
560 	 * to the complete match, but '\0' followed by a number is the octal
561 	 * representation of a character. To include a literal '\' in the
562 	 * replacement, write '\\'.
563 	 *
564 	 * There are also escapes that changes the case of the following text:
565 	 *
566 	 * - \l: Convert to lower case the next character
567 	 * - \u: Convert to upper case the next character
568 	 * - \L: Convert to lower case till \E
569 	 * - \U: Convert to upper case till \E
570 	 * - \E: End case modification
571 	 *
572 	 * If you do not need to use backreferences use g_regex_replace_literal().
573 	 *
574 	 * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
575 	 * passed to g_regex_new(). If you want to use not UTF-8 encoded stings
576 	 * you can use g_regex_replace_literal().
577 	 *
578 	 * Setting @start_position differs from just passing over a shortened
579 	 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
580 	 * begins with any kind of lookbehind assertion, such as "\b".
581 	 *
582 	 * Params:
583 	 *     str = the string to perform matches against
584 	 *     startPosition = starting index of the string to match, in bytes
585 	 *     replacement = text to replace each match with
586 	 *     matchOptions = options for the match
587 	 *
588 	 * Returns: a newly allocated string containing the replacements
589 	 *
590 	 * Since: 2.14
591 	 *
592 	 * Throws: GException on failure.
593 	 */
594 	public string replace(string str, int startPosition, string replacement, GRegexMatchFlags matchOptions)
595 	{
596 		GError* err = null;
597 
598 		auto retStr = g_regex_replace(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, Str.toStringz(replacement), matchOptions, &err);
599 
600 		if (err !is null)
601 		{
602 			throw new GException( new ErrorG(err) );
603 		}
604 
605 		scope(exit) Str.freeString(retStr);
606 		return Str.toString(retStr);
607 	}
608 
609 	/**
610 	 * Replaces occurrences of the pattern in regex with the output of
611 	 * @eval for that occurrence.
612 	 *
613 	 * Setting @start_position differs from just passing over a shortened
614 	 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
615 	 * that begins with any kind of lookbehind assertion, such as "\b".
616 	 *
617 	 * The following example uses g_regex_replace_eval() to replace multiple
618 	 * strings at once:
619 	 * |[<!-- language="C" -->
620 	 * static gboolean
621 	 * eval_cb (const GMatchInfo *info,
622 	 * GString          *res,
623 	 * gpointer          data)
624 	 * {
625 	 * gchar *match;
626 	 * gchar *r;
627 	 *
628 	 * match = g_match_info_fetch (info, 0);
629 	 * r = g_hash_table_lookup ((GHashTable *)data, match);
630 	 * g_string_append (res, r);
631 	 * g_free (match);
632 	 *
633 	 * return FALSE;
634 	 * }
635 	 *
636 	 * ...
637 	 *
638 	 * GRegex *reg;
639 	 * GHashTable *h;
640 	 * gchar *res;
641 	 *
642 	 * h = g_hash_table_new (g_str_hash, g_str_equal);
643 	 *
644 	 * g_hash_table_insert (h, "1", "ONE");
645 	 * g_hash_table_insert (h, "2", "TWO");
646 	 * g_hash_table_insert (h, "3", "THREE");
647 	 * g_hash_table_insert (h, "4", "FOUR");
648 	 *
649 	 * reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
650 	 * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
651 	 * g_hash_table_destroy (h);
652 	 *
653 	 * ...
654 	 * ]|
655 	 *
656 	 * Params:
657 	 *     str = string to perform matches against
658 	 *     startPosition = starting index of the string to match, in bytes
659 	 *     matchOptions = options for the match
660 	 *     eval = a function to call for each match
661 	 *     userData = user data to pass to the function
662 	 *
663 	 * Returns: a newly allocated string containing the replacements
664 	 *
665 	 * Since: 2.14
666 	 *
667 	 * Throws: GException on failure.
668 	 */
669 	public string replaceEval(string str, int startPosition, GRegexMatchFlags matchOptions, GRegexEvalCallback eval, void* userData)
670 	{
671 		GError* err = null;
672 
673 		auto retStr = g_regex_replace_eval(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, matchOptions, eval, userData, &err);
674 
675 		if (err !is null)
676 		{
677 			throw new GException( new ErrorG(err) );
678 		}
679 
680 		scope(exit) Str.freeString(retStr);
681 		return Str.toString(retStr);
682 	}
683 
684 	/**
685 	 * Replaces all occurrences of the pattern in @regex with the
686 	 * replacement text. @replacement is replaced literally, to
687 	 * include backreferences use g_regex_replace().
688 	 *
689 	 * Setting @start_position differs from just passing over a
690 	 * shortened string and setting #G_REGEX_MATCH_NOTBOL in the
691 	 * case of a pattern that begins with any kind of lookbehind
692 	 * assertion, such as "\b".
693 	 *
694 	 * Params:
695 	 *     str = the string to perform matches against
696 	 *     startPosition = starting index of the string to match, in bytes
697 	 *     replacement = text to replace each match with
698 	 *     matchOptions = options for the match
699 	 *
700 	 * Returns: a newly allocated string containing the replacements
701 	 *
702 	 * Since: 2.14
703 	 *
704 	 * Throws: GException on failure.
705 	 */
706 	public string replaceLiteral(string str, int startPosition, string replacement, GRegexMatchFlags matchOptions)
707 	{
708 		GError* err = null;
709 
710 		auto retStr = g_regex_replace_literal(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, Str.toStringz(replacement), matchOptions, &err);
711 
712 		if (err !is null)
713 		{
714 			throw new GException( new ErrorG(err) );
715 		}
716 
717 		scope(exit) Str.freeString(retStr);
718 		return Str.toString(retStr);
719 	}
720 
721 	/**
722 	 * Breaks the string on the pattern, and returns an array of the tokens.
723 	 * If the pattern contains capturing parentheses, then the text for each
724 	 * of the substrings will also be returned. If the pattern does not match
725 	 * anywhere in the string, then the whole string is returned as the first
726 	 * token.
727 	 *
728 	 * As a special case, the result of splitting the empty string "" is an
729 	 * empty vector, not a vector containing a single string. The reason for
730 	 * this special case is that being able to represent a empty vector is
731 	 * typically more useful than consistent handling of empty elements. If
732 	 * you do need to represent empty elements, you'll need to check for the
733 	 * empty string before calling this function.
734 	 *
735 	 * A pattern that can match empty strings splits @string into separate
736 	 * characters wherever it matches the empty string between characters.
737 	 * For example splitting "ab c" using as a separator "\s*", you will get
738 	 * "a", "b" and "c".
739 	 *
740 	 * Params:
741 	 *     str = the string to split with the pattern
742 	 *     matchOptions = match time option flags
743 	 *
744 	 * Returns: a %NULL-terminated gchar ** array. Free
745 	 *     it using g_strfreev()
746 	 *
747 	 * Since: 2.14
748 	 */
749 	public string[] split(string str, GRegexMatchFlags matchOptions)
750 	{
751 		auto retStr = g_regex_split(gRegex, Str.toStringz(str), matchOptions);
752 
753 		scope(exit) Str.freeStringArray(retStr);
754 		return Str.toStringArray(retStr);
755 	}
756 
757 	/**
758 	 * Breaks the string on the pattern, and returns an array of the tokens.
759 	 * If the pattern contains capturing parentheses, then the text for each
760 	 * of the substrings will also be returned. If the pattern does not match
761 	 * anywhere in the string, then the whole string is returned as the first
762 	 * token.
763 	 *
764 	 * As a special case, the result of splitting the empty string "" is an
765 	 * empty vector, not a vector containing a single string. The reason for
766 	 * this special case is that being able to represent a empty vector is
767 	 * typically more useful than consistent handling of empty elements. If
768 	 * you do need to represent empty elements, you'll need to check for the
769 	 * empty string before calling this function.
770 	 *
771 	 * A pattern that can match empty strings splits @string into separate
772 	 * characters wherever it matches the empty string between characters.
773 	 * For example splitting "ab c" using as a separator "\s*", you will get
774 	 * "a", "b" and "c".
775 	 *
776 	 * Setting @start_position differs from just passing over a shortened
777 	 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
778 	 * that begins with any kind of lookbehind assertion, such as "\b".
779 	 *
780 	 * Params:
781 	 *     str = the string to split with the pattern
782 	 *     startPosition = starting index of the string to match, in bytes
783 	 *     matchOptions = match time option flags
784 	 *     maxTokens = the maximum number of tokens to split @string into.
785 	 *         If this is less than 1, the string is split completely
786 	 *
787 	 * Returns: a %NULL-terminated gchar ** array. Free
788 	 *     it using g_strfreev()
789 	 *
790 	 * Since: 2.14
791 	 *
792 	 * Throws: GException on failure.
793 	 */
794 	public string[] splitFull(string str, int startPosition, GRegexMatchFlags matchOptions, int maxTokens)
795 	{
796 		GError* err = null;
797 
798 		auto retStr = g_regex_split_full(gRegex, Str.toStringz(str), cast(ptrdiff_t)str.length, startPosition, matchOptions, maxTokens, &err);
799 
800 		if (err !is null)
801 		{
802 			throw new GException( new ErrorG(err) );
803 		}
804 
805 		scope(exit) Str.freeStringArray(retStr);
806 		return Str.toStringArray(retStr);
807 	}
808 
809 	/**
810 	 * Decreases reference count of @regex by 1. When reference count drops
811 	 * to zero, it frees all the memory associated with the regex structure.
812 	 *
813 	 * Since: 2.14
814 	 */
815 	public void unref()
816 	{
817 		g_regex_unref(gRegex);
818 	}
819 
820 	/**
821 	 * Checks whether @replacement is a valid replacement string
822 	 * (see g_regex_replace()), i.e. that all escape sequences in
823 	 * it are valid.
824 	 *
825 	 * If @has_references is not %NULL then @replacement is checked
826 	 * for pattern references. For instance, replacement text 'foo\n'
827 	 * does not contain references and may be evaluated without information
828 	 * about actual match, but '\0\1' (whole match followed by first
829 	 * subpattern) requires valid #GMatchInfo object.
830 	 *
831 	 * Params:
832 	 *     replacement = the replacement string
833 	 *     hasReferences = location to store information about
834 	 *         references in @replacement or %NULL
835 	 *
836 	 * Returns: whether @replacement is a valid replacement string
837 	 *
838 	 * Since: 2.14
839 	 *
840 	 * Throws: GException on failure.
841 	 */
842 	public static bool checkReplacement(string replacement, out bool hasReferences)
843 	{
844 		int outhasReferences;
845 		GError* err = null;
846 
847 		auto p = g_regex_check_replacement(Str.toStringz(replacement), &outhasReferences, &err) != 0;
848 
849 		if (err !is null)
850 		{
851 			throw new GException( new ErrorG(err) );
852 		}
853 
854 		hasReferences = (outhasReferences == 1);
855 
856 		return p;
857 	}
858 
859 	/** */
860 	public static GQuark errorQuark()
861 	{
862 		return g_regex_error_quark();
863 	}
864 
865 	/**
866 	 * Escapes the nul characters in @string to "\x00".  It can be used
867 	 * to compile a regex with embedded nul characters.
868 	 *
869 	 * For completeness, @length can be -1 for a nul-terminated string.
870 	 * In this case the output string will be of course equal to @string.
871 	 *
872 	 * Params:
873 	 *     str = the string to escape
874 	 *     length = the length of @string
875 	 *
876 	 * Returns: a newly-allocated escaped string
877 	 *
878 	 * Since: 2.30
879 	 */
880 	public static string escapeNul(string str, int length)
881 	{
882 		auto retStr = g_regex_escape_nul(Str.toStringz(str), length);
883 
884 		scope(exit) Str.freeString(retStr);
885 		return Str.toString(retStr);
886 	}
887 
888 	/**
889 	 * Escapes the special characters used for regular expressions
890 	 * in @string, for instance "a.b*c" becomes "a\.b\*c". This
891 	 * function is useful to dynamically generate regular expressions.
892 	 *
893 	 * @string can contain nul characters that are replaced with "\0",
894 	 * in this case remember to specify the correct length of @string
895 	 * in @length.
896 	 *
897 	 * Params:
898 	 *     str = the string to escape
899 	 *
900 	 * Returns: a newly-allocated escaped string
901 	 *
902 	 * Since: 2.14
903 	 */
904 	public static string escapeString(string str)
905 	{
906 		auto retStr = g_regex_escape_string(Str.toStringz(str), cast(int)str.length);
907 
908 		scope(exit) Str.freeString(retStr);
909 		return Str.toString(retStr);
910 	}
911 
912 	/**
913 	 * Scans for a match in @string for @pattern.
914 	 *
915 	 * This function is equivalent to g_regex_match() but it does not
916 	 * require to compile the pattern with g_regex_new(), avoiding some
917 	 * lines of code when you need just to do a match without extracting
918 	 * substrings, capture counts, and so on.
919 	 *
920 	 * If this function is to be called on the same @pattern more than
921 	 * once, it's more efficient to compile the pattern once with
922 	 * g_regex_new() and then use g_regex_match().
923 	 *
924 	 * Params:
925 	 *     pattern = the regular expression
926 	 *     str = the string to scan for matches
927 	 *     compileOptions = compile options for the regular expression, or 0
928 	 *     matchOptions = match options, or 0
929 	 *
930 	 * Returns: %TRUE if the string matched, %FALSE otherwise
931 	 *
932 	 * Since: 2.14
933 	 */
934 	public static bool matchSimple(string pattern, string str, GRegexCompileFlags compileOptions, GRegexMatchFlags matchOptions)
935 	{
936 		return g_regex_match_simple(Str.toStringz(pattern), Str.toStringz(str), compileOptions, matchOptions) != 0;
937 	}
938 
939 	/**
940 	 * Breaks the string on the pattern, and returns an array of
941 	 * the tokens. If the pattern contains capturing parentheses,
942 	 * then the text for each of the substrings will also be returned.
943 	 * If the pattern does not match anywhere in the string, then the
944 	 * whole string is returned as the first token.
945 	 *
946 	 * This function is equivalent to g_regex_split() but it does
947 	 * not require to compile the pattern with g_regex_new(), avoiding
948 	 * some lines of code when you need just to do a split without
949 	 * extracting substrings, capture counts, and so on.
950 	 *
951 	 * If this function is to be called on the same @pattern more than
952 	 * once, it's more efficient to compile the pattern once with
953 	 * g_regex_new() and then use g_regex_split().
954 	 *
955 	 * As a special case, the result of splitting the empty string ""
956 	 * is an empty vector, not a vector containing a single string.
957 	 * The reason for this special case is that being able to represent
958 	 * a empty vector is typically more useful than consistent handling
959 	 * of empty elements. If you do need to represent empty elements,
960 	 * you'll need to check for the empty string before calling this
961 	 * function.
962 	 *
963 	 * A pattern that can match empty strings splits @string into
964 	 * separate characters wherever it matches the empty string between
965 	 * characters. For example splitting "ab c" using as a separator
966 	 * "\s*", you will get "a", "b" and "c".
967 	 *
968 	 * Params:
969 	 *     pattern = the regular expression
970 	 *     str = the string to scan for matches
971 	 *     compileOptions = compile options for the regular expression, or 0
972 	 *     matchOptions = match options, or 0
973 	 *
974 	 * Returns: a %NULL-terminated array of strings. Free
975 	 *     it using g_strfreev()
976 	 *
977 	 * Since: 2.14
978 	 */
979 	public static string[] splitSimple(string pattern, string str, GRegexCompileFlags compileOptions, GRegexMatchFlags matchOptions)
980 	{
981 		auto retStr = g_regex_split_simple(Str.toStringz(pattern), Str.toStringz(str), compileOptions, matchOptions);
982 
983 		scope(exit) Str.freeStringArray(retStr);
984 		return Str.toStringArray(retStr);
985 	}
986 }