source: appstream-generator/build/girepo/glib/Regex.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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