glib/gregex.c

   1 /* GRegex -- regular expression API wrapper around PCRE.
   2  *
   3  * Copyright (C) 1999, 2000 Scott Wimer
   4  * Copyright (C) 2004, Matthias Clasen <mclasen@redhat.com>
   5  * Copyright (C) 2005 - 2007, Marco Barisione <marco@barisione.org>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20  */
  21
  22 #include "config.h"
  23
  24 #include <string.h>
  25
  26 #ifdef USE_SYSTEM_PCRE
  27 #include <pcre.h>
  28 #else
  29 #include "pcre/pcre.h"
  30 #endif
  31
  32 #include "gtypes.h"
  33 #include "gregex.h"
  34 #include "glibintl.h"
  35 #include "glist.h"
  36 #include "gmessages.h"
  37 #include "gstrfuncs.h"
  38 #include "gatomic.h"
  39 #include "gthread.h"
  40
  41 /**
  42  * SECTION:gregex
  43  * @title: Perl-compatible regular expressions
  44  * @short_description: matches strings against regular expressions
  45  * @see_also: <xref linkend="glib-regex-syntax"/>
  46  *
  47  * The <function>g_regex_*()</function> functions implement regular
  48  * expression pattern matching using syntax and semantics similar to
  49  * Perl regular expression.
  50  *
  51  * Some functions accept a @start_position argument, setting it differs
  52  * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
  53  * in the case of a pattern that begins with any kind of lookbehind assertion.
  54  * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
  55  * in the middle of words. ("\B" matches only if the current position in the
  56  * subject is not a word boundary.) When applied to the string "Mississipi"
  57  * from the fourth byte, namely "issipi", it does not match, because "\B" is
  58  * always false at the start of the subject, which is deemed to be a word
  59  * boundary. However, if the entire string is passed , but with
  60  * @start_position set to 4, it finds the second occurrence of "iss" because
  61  * it is able to look behind the starting point to discover that it is
  62  * preceded by a letter.
  63  *
  64  * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
  65  * to these functions must be encoded in UTF-8. The lengths and the positions
  66  * inside the strings are in bytes and not in characters, so, for instance,
  67  * "\xc3\xa0" (i.e. "&agrave;") is two bytes long but it is treated as a
  68  * single character. If you set #G_REGEX_RAW the strings can be non-valid
  69  * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
  70  * bytes and two characters long.
  71  *
  72  * When matching a pattern, "\n" matches only against a "\n" character in
  73  * the string, and "\r" matches only a "\r" character. To match any newline
  74  * sequence use "\R". This particular group matches either the two-character
  75  * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
  76  * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
  77  * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
  78  * separator, U+2028), or PS (paragraph separator, U+2029).
  79  *
  80  * The behaviour of the dot, circumflex, and dollar metacharacters are
  81  * affected by newline characters, the default is to recognize any newline
  82  * character (the same characters recognized by "\R"). This can be changed
  83  * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF
  84  * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY,
  85  * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and
  86  * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
  87  * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
  88  * unescaped "#" outside a character class is encountered. This indicates
  89  * a comment that lasts until after the next newline.
  90  *
  91  * Creating and manipulating the same #GRegex structure from different
  92  * threads is not a problem as #GRegex does not modify its internal
  93  * state between creation and destruction, on the other hand #GMatchInfo
  94  * is not threadsafe.
  95  *
  96  * The regular expressions low-level functionalities are obtained through
  97  * the excellent <ulink url="http://www.pcre.org/">PCRE</ulink> library
  98  * written by Philip Hazel.
  99  */
 100
 101 /* Mask of all the possible values for GRegexCompileFlags. */
 102 #define G_REGEX_COMPILE_MASK (G_REGEX_CASELESS          | \
 103                               G_REGEX_MULTILINE         | \
 104                               G_REGEX_DOTALL            | \
 105                               G_REGEX_EXTENDED          | \
 106                               G_REGEX_ANCHORED          | \
 107                               G_REGEX_DOLLAR_ENDONLY    | \
 108                               G_REGEX_UNGREEDY          | \
 109                               G_REGEX_RAW               | \
 110                               G_REGEX_NO_AUTO_CAPTURE   | \
 111                               G_REGEX_OPTIMIZE          | \
 112                               G_REGEX_DUPNAMES          | \
 113                               G_REGEX_NEWLINE_CR        | \
 114                               G_REGEX_NEWLINE_LF        | \
 115                               G_REGEX_NEWLINE_CRLF)
 116
 117 /* Mask of all the possible values for GRegexMatchFlags. */
 118 #define G_REGEX_MATCH_MASK (G_REGEX_MATCH_ANCHORED      | \
 119                             G_REGEX_MATCH_NOTBOL        | \
 120                             G_REGEX_MATCH_NOTEOL        | \
 121                             G_REGEX_MATCH_NOTEMPTY      | \
 122                             G_REGEX_MATCH_PARTIAL       | \
 123                             G_REGEX_MATCH_NEWLINE_CR    | \
 124                             G_REGEX_MATCH_NEWLINE_LF    | \
 125                             G_REGEX_MATCH_NEWLINE_CRLF  | \
 126                             G_REGEX_MATCH_NEWLINE_ANY)
 127
 128 /* we rely on these flags having the same values */
 129 G_STATIC_ASSERT (G_REGEX_CASELESS        == PCRE_CASELESS);
 130 G_STATIC_ASSERT (G_REGEX_MULTILINE       == PCRE_MULTILINE);
 131 G_STATIC_ASSERT (G_REGEX_DOTALL          == PCRE_DOTALL);
 132 G_STATIC_ASSERT (G_REGEX_EXTENDED        == PCRE_EXTENDED);
 133 G_STATIC_ASSERT (G_REGEX_ANCHORED        == PCRE_ANCHORED);
 134 G_STATIC_ASSERT (G_REGEX_DOLLAR_ENDONLY  == PCRE_DOLLAR_ENDONLY);
 135 G_STATIC_ASSERT (G_REGEX_UNGREEDY        == PCRE_UNGREEDY);
 136 G_STATIC_ASSERT (G_REGEX_NO_AUTO_CAPTURE == PCRE_NO_AUTO_CAPTURE);
 137 G_STATIC_ASSERT (G_REGEX_DUPNAMES        == PCRE_DUPNAMES);
 138 G_STATIC_ASSERT (G_REGEX_NEWLINE_CR      == PCRE_NEWLINE_CR);
 139 G_STATIC_ASSERT (G_REGEX_NEWLINE_LF      == PCRE_NEWLINE_LF);
 140 G_STATIC_ASSERT (G_REGEX_NEWLINE_CRLF    == PCRE_NEWLINE_CRLF);
 141
 142 G_STATIC_ASSERT (G_REGEX_MATCH_ANCHORED     == PCRE_ANCHORED);
 143 G_STATIC_ASSERT (G_REGEX_MATCH_NOTBOL       == PCRE_NOTBOL);
 144 G_STATIC_ASSERT (G_REGEX_MATCH_NOTEOL       == PCRE_NOTEOL);
 145 G_STATIC_ASSERT (G_REGEX_MATCH_NOTEMPTY     == PCRE_NOTEMPTY);
 146 G_STATIC_ASSERT (G_REGEX_MATCH_PARTIAL      == PCRE_PARTIAL);
 147 G_STATIC_ASSERT (G_REGEX_MATCH_NEWLINE_CR   == PCRE_NEWLINE_CR);
 148 G_STATIC_ASSERT (G_REGEX_MATCH_NEWLINE_LF   == PCRE_NEWLINE_LF);
 149 G_STATIC_ASSERT (G_REGEX_MATCH_NEWLINE_CRLF == PCRE_NEWLINE_CRLF);
 150 G_STATIC_ASSERT (G_REGEX_MATCH_NEWLINE_ANY  == PCRE_NEWLINE_ANY);
 151
 152 /* if the string is in UTF-8 use g_utf8_ functions, else use
 153  * use just +/- 1. */
 154 #define NEXT_CHAR(re, s) (((re)->compile_opts & PCRE_UTF8) ? \
 155                                 g_utf8_next_char (s) : \
 156                                 ((s) + 1))
 157 #define PREV_CHAR(re, s) (((re)->compile_opts & PCRE_UTF8) ? \
 158                                 g_utf8_prev_char (s) : \
 159                                 ((s) - 1))
 160
 161 struct _GMatchInfo
 162 {
 163   volatile gint ref_count;      /* the ref count */
 164   GRegex *regex;                /* the regex */
 165   GRegexMatchFlags match_opts;  /* options used at match time on the regex */
 166   gint matches;                 /* number of matching sub patterns */
 167   gint pos;                     /* position in the string where last match left off */
 168   gint  n_offsets;              /* number of offsets */
 169   gint *offsets;                /* array of offsets paired 0,1 ; 2,3 ; 3,4 etc */
 170   gint *workspace;              /* workspace for pcre_dfa_exec() */
 171   gint n_workspace;             /* number of workspace elements */
 172   const gchar *string;          /* string passed to the match function */
 173   gssize string_len;            /* length of string */
 174 };
 175
 176 struct _GRegex
 177 {
 178   volatile gint ref_count;      /* the ref count for the immutable part */
 179   gchar *pattern;               /* the pattern */
 180   pcre *pcre_re;                /* compiled form of the pattern */
 181   GRegexCompileFlags compile_opts;      /* options used at compile time on the pattern */
 182   GRegexMatchFlags match_opts;  /* options used at match time on the regex */
 183   pcre_extra *extra;            /* data stored when G_REGEX_OPTIMIZE is used */
 184 };
 185
 186 /* TRUE if ret is an error code, FALSE otherwise. */
 187 #define IS_PCRE_ERROR(ret) ((ret) < PCRE_ERROR_NOMATCH && (ret) != PCRE_ERROR_PARTIAL)
 188
 189 typedef struct _InterpolationData InterpolationData;
 190 static gboolean  interpolation_list_needs_match (GList *list);
 191 static gboolean  interpolate_replacement        (const GMatchInfo *match_info,
 192                                                  GString *result,
 193                                                  gpointer data);
 194 static GList    *split_replacement              (const gchar *replacement,
 195                                                  GError **error);
 196 static void      free_interpolation_data        (InterpolationData *data);
 197
 198
 199 static const gchar *
 200 match_error (gint errcode)
 201 {
 202   switch (errcode)
 203     {
 204     case PCRE_ERROR_NOMATCH:
 205       /* not an error */
 206       break;
 207     case PCRE_ERROR_NULL:
 208       /* NULL argument, this should not happen in GRegex */
 209       g_warning ("A NULL argument was passed to PCRE");
 210       break;
 211     case PCRE_ERROR_BADOPTION:
 212       return "bad options";
 213     case PCRE_ERROR_BADMAGIC:
 214       return _("corrupted object");
 215     case PCRE_ERROR_UNKNOWN_OPCODE:
 216       return N_("internal error or corrupted object");
 217     case PCRE_ERROR_NOMEMORY:
 218       return _("out of memory");
 219     case PCRE_ERROR_NOSUBSTRING:
 220       /* not used by pcre_exec() */
 221       break;
 222     case PCRE_ERROR_MATCHLIMIT:
 223       return _("backtracking limit reached");
 224     case PCRE_ERROR_CALLOUT:
 225       /* callouts are not implemented */
 226       break;
 227     case PCRE_ERROR_BADUTF8:
 228     case PCRE_ERROR_BADUTF8_OFFSET:
 229       /* we do not check if strings are valid */
 230       break;
 231     case PCRE_ERROR_PARTIAL:
 232       /* not an error */
 233       break;
 234     case PCRE_ERROR_BADPARTIAL:
 235       return _("the pattern contains items not supported for partial matching");
 236     case PCRE_ERROR_INTERNAL:
 237       return _("internal error");
 238     case PCRE_ERROR_BADCOUNT:
 239       /* negative ovecsize, this should not happen in GRegex */
 240       g_warning ("A negative ovecsize was passed to PCRE");
 241       break;
 242     case PCRE_ERROR_DFA_UITEM:
 243       return _("the pattern contains items not supported for partial matching");
 244     case PCRE_ERROR_DFA_UCOND:
 245       return _("back references as conditions are not supported for partial matching");
 246     case PCRE_ERROR_DFA_UMLIMIT:
 247       /* the match_field field is not used in GRegex */
 248       break;
 249     case PCRE_ERROR_DFA_WSSIZE:
 250       /* handled expanding the workspace */
 251       break;
 252     case PCRE_ERROR_DFA_RECURSE:
 253     case PCRE_ERROR_RECURSIONLIMIT:
 254       return _("recursion limit reached");
 255     case PCRE_ERROR_NULLWSLIMIT:
 256       return _("workspace limit for empty substrings reached");
 257     case PCRE_ERROR_BADNEWLINE:
 258       return _("invalid combination of newline flags");
 259     case PCRE_ERROR_BADOFFSET:
 260       return _("bad offset");
 261     case PCRE_ERROR_SHORTUTF8:
 262       return _("short utf8");
 263     case PCRE_ERROR_RECURSELOOP:
 264       return _("recursion loop");
 265     default:
 266       break;
 267     }
 268   return _("unknown error");
 269 }
 270
 271 static void
 272 translate_compile_error (gint *errcode, const gchar **errmsg)
 273 {
 274   /* Compile errors are created adding 100 to the error code returned
 275    * by PCRE.
 276    * If errcode is known we put the translatable error message in
 277    * erromsg. If errcode is unknown we put the generic
 278    * G_REGEX_ERROR_COMPILE error code in errcode and keep the
 279    * untranslated error message returned by PCRE.
 280    * Note that there can be more PCRE errors with the same GRegexError
 281    * and that some PCRE errors are useless for us.
 282    */
 283   *errcode += 100;
 284
 285   switch (*errcode)
 286     {
 287     case G_REGEX_ERROR_STRAY_BACKSLASH:
 288       *errmsg = _("\\ at end of pattern");
 289       break;
 290     case G_REGEX_ERROR_MISSING_CONTROL_CHAR:
 291       *errmsg = _("\\c at end of pattern");
 292       break;
 293     case G_REGEX_ERROR_UNRECOGNIZED_ESCAPE:
 294       *errmsg = _("unrecognized character follows \\");
 295       break;
 296     case G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER:
 297       *errmsg = _("numbers out of order in {} quantifier");
 298       break;
 299     case G_REGEX_ERROR_QUANTIFIER_TOO_BIG:
 300       *errmsg = _("number too big in {} quantifier");
 301       break;
 302     case G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS:
 303       *errmsg = _("missing terminating ] for character class");
 304       break;
 305     case G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS:
 306       *errmsg = _("invalid escape sequence in character class");
 307       break;
 308     case G_REGEX_ERROR_RANGE_OUT_OF_ORDER:
 309       *errmsg = _("range out of order in character class");
 310       break;
 311     case G_REGEX_ERROR_NOTHING_TO_REPEAT:
 312       *errmsg = _("nothing to repeat");
 313       break;
 314     case 111: /* internal error: unexpected repeat */
 315       *errcode = G_REGEX_ERROR_INTERNAL;
 316       *errmsg = _("unexpected repeat");
 317       break;
 318     case G_REGEX_ERROR_UNRECOGNIZED_CHARACTER:
 319       *errmsg = _("unrecognized character after (? or (?-");
 320       break;
 321     case G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS:
 322       *errmsg = _("POSIX named classes are supported only within a class");
 323       break;
 324     case G_REGEX_ERROR_UNMATCHED_PARENTHESIS:
 325       *errmsg = _("missing terminating )");
 326       break;
 327     case G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE:
 328       *errmsg = _("reference to non-existent subpattern");
 329       break;
 330     case G_REGEX_ERROR_UNTERMINATED_COMMENT:
 331       *errmsg = _("missing ) after comment");
 332       break;
 333     case G_REGEX_ERROR_EXPRESSION_TOO_LARGE:
 334       *errmsg = _("regular expression is too large");
 335       break;
 336     case G_REGEX_ERROR_MEMORY_ERROR:
 337       *errmsg = _("failed to get memory");
 338       break;
 339     case 122: /* unmatched parentheses */
 340       *errcode = G_REGEX_ERROR_UNMATCHED_PARENTHESIS;
 341       *errmsg = _(") without opening (");
 342       break;
 343     case 123: /* internal error: code overflow */
 344       *errcode = G_REGEX_ERROR_INTERNAL;
 345       *errmsg = _("code overflow");
 346       break;
 347     case 124: /* "unrecognized character after (?<\0 */
 348       *errcode = G_REGEX_ERROR_UNRECOGNIZED_CHARACTER;
 349       *errmsg = _("unrecognized character after (?<");
 350       break;
 351     case G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND:
 352       *errmsg = _("lookbehind assertion is not fixed length");
 353       break;
 354     case G_REGEX_ERROR_MALFORMED_CONDITION:
 355       *errmsg = _("malformed number or name after (?(");
 356       break;
 357     case G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES:
 358       *errmsg = _("conditional group contains more than two branches");
 359       break;
 360     case G_REGEX_ERROR_ASSERTION_EXPECTED:
 361       *errmsg = _("assertion expected after (?(");
 362       break;
 363     case 129:
 364       *errcode = G_REGEX_ERROR_UNMATCHED_PARENTHESIS;
 365       /* translators: '(?R' and '(?[+-]digits' are both meant as (groups of)
 366        * sequences here, '(?-54' would be an example for the second group.
 367        */
 368       *errmsg = _("(?R or (?[+-]digits must be followed by )");
 369       break;
 370     case G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME:
 371       *errmsg = _("unknown POSIX class name");
 372       break;
 373     case G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED:
 374       *errmsg = _("POSIX collating elements are not supported");
 375       break;
 376     case G_REGEX_ERROR_HEX_CODE_TOO_LARGE:
 377       *errmsg = _("character value in \\x{...} sequence is too large");
 378       break;
 379     case G_REGEX_ERROR_INVALID_CONDITION:
 380       *errmsg = _("invalid condition (?(0)");
 381       break;
 382     case G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND:
 383       *errmsg = _("\\C not allowed in lookbehind assertion");
 384       break;
 385     case 137: /* PCRE does not support \\L, \\l, \\N{name}, \\U, or \\u\0 */
 386       /* A number of Perl escapes are not handled by PCRE.
 387        * Therefore it explicitly raises ERR37.
 388        */
 389       *errcode = G_REGEX_ERROR_UNRECOGNIZED_ESCAPE;
 390       *errmsg = _("escapes \\L, \\l, \\N{name}, \\U, and \\u are not supported");
 391       break;
 392     case G_REGEX_ERROR_INFINITE_LOOP:
 393       *errmsg = _("recursive call could loop indefinitely");
 394       break;
 395     case 141: /* unrecognized character after (?P\0 */
 396       *errcode = G_REGEX_ERROR_UNRECOGNIZED_CHARACTER;
 397       *errmsg = _("unrecognized character after (?P");
 398       break;
 399     case G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR:
 400       *errmsg = _("missing terminator in subpattern name");
 401       break;
 402     case G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME:
 403       *errmsg = _("two named subpatterns have the same name");
 404       break;
 405     case G_REGEX_ERROR_MALFORMED_PROPERTY:
 406       *errmsg = _("malformed \\P or \\p sequence");
 407       break;
 408     case G_REGEX_ERROR_UNKNOWN_PROPERTY:
 409       *errmsg = _("unknown property name after \\P or \\p");
 410       break;
 411     case G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG:
 412       *errmsg = _("subpattern name is too long (maximum 32 characters)");
 413       break;
 414     case G_REGEX_ERROR_TOO_MANY_SUBPATTERNS:
 415       *errmsg = _("too many named subpatterns (maximum 10,000)");
 416       break;
 417     case G_REGEX_ERROR_INVALID_OCTAL_VALUE:
 418       *errmsg = _("octal value is greater than \\377");
 419       break;
 420     case 152: /* internal error: overran compiling workspace */
 421       *errcode = G_REGEX_ERROR_INTERNAL;
 422       *errmsg = _("overran compiling workspace");
 423       break;
 424     case 153: /* internal error: previously-checked referenced subpattern not found */
 425       *errcode = G_REGEX_ERROR_INTERNAL;
 426       *errmsg = _("previously-checked referenced subpattern not found");
 427       break;
 428     case G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE:
 429       *errmsg = _("DEFINE group contains more than one branch");
 430       break;
 431     case G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS:
 432       *errmsg = _("inconsistent NEWLINE options");
 433       break;
 434     case G_REGEX_ERROR_MISSING_BACK_REFERENCE:
 435       *errmsg = _("\\g is not followed by a braced, angle-bracketed, or quoted name or "
 436                   "number, or by a plain number");
 437       break;
 438     case G_REGEX_ERROR_INVALID_RELATIVE_REFERENCE:
 439       *errmsg = _("a numbered reference must not be zero");
 440       break;
 441     case G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_FORBIDDEN:
 442       *errmsg = _("an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT)");
 443       break;
 444     case G_REGEX_ERROR_UNKNOWN_BACKTRACKING_CONTROL_VERB:
 445       *errmsg = _("(*VERB) not recognized");
 446       break;
 447     case G_REGEX_ERROR_NUMBER_TOO_BIG:
 448       *errmsg = _("number is too bug");
 449       break;
 450     case G_REGEX_ERROR_MISSING_SUBPATTERN_NAME:
 451       *errmsg = _("missing subpattern name after (?&");
 452       break;
 453     case G_REGEX_ERROR_MISSING_DIGIT:
 454       *errmsg = _("digit expected after (?+");
 455       break;
 456     case G_REGEX_ERROR_EXTRA_SUBPATTERN_NAME:
 457       *errmsg = _("different names for subpatterns of the same number are not allowed");
 458       break;
 459     case G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_REQUIRED:
 460       *errmsg = _("(*MARK) must have an argument");
 461       break;
 462     case G_REGEX_ERROR_INVALID_CONTROL_CHAR:
 463       *errmsg = _( "\\c must be followed by an ASCII character");
 464       break;
 465     case G_REGEX_ERROR_MISSING_NAME:
 466       *errmsg = _("\\k is not followed by a braced, angle-bracketed, or quoted name");
 467       break;
 468     case G_REGEX_ERROR_NOT_SUPPORTED_IN_CLASS:
 469       *errmsg = _("\\N is not supported in a class");
 470       break;
 471     case G_REGEX_ERROR_TOO_MANY_FORWARD_REFERENCES:
 472       *errmsg = _("too many forward references");
 473       break;
 474     case G_REGEX_ERROR_NAME_TOO_LONG:
 475       *errmsg = _("name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN)");
 476       break;
 477
 478     case 116: /* erroffset passed as NULL */
 479       /* This should not happen as we never pass a NULL erroffset */
 480       g_warning ("erroffset passed as NULL");
 481       *errcode = G_REGEX_ERROR_COMPILE;
 482       break;
 483     case 117: /* unknown option bit(s) set */
 484       /* This should not happen as we check options before passing them
 485        * to pcre_compile2() */
 486       g_warning ("unknown option bit(s) set");
 487       *errcode = G_REGEX_ERROR_COMPILE;
 488       break;
 489     case 132: /* this version of PCRE is compiled without UTF support */
 490     case 144: /* invalid UTF-8 string */
 491     case 145: /* support for \\P, \\p, and \\X has not been compiled */
 492     case 167: /* this version of PCRE is not compiled with Unicode property support */
 493     case 173: /* disallowed Unicode code point (>= 0xd800 && <= 0xdfff) */
 494     case 174: /* invalid UTF-16 string */
 495       /* These errors should not happen as we are using an UTF-8 and UCP-enabled PCRE
 496        * and we do not check if strings are valid */
 497     case 164: /* ] is an invalid data character in JavaScript compatibility mode */
 498       /* This should not happen as we don't use PCRE_JAVASCRIPT_COMPAT */
 499       g_warning ("%s", *errmsg);
 500       *errcode = G_REGEX_ERROR_COMPILE;
 501       break;
 502     case 170: /* internal error: unknown opcode in find_fixedlength() */
 503       *errcode = G_REGEX_ERROR_INTERNAL;
 504       break;
 505
 506     default:
 507       *errcode = G_REGEX_ERROR_COMPILE;
 508     }
 509 }
 510
 511 /* GMatchInfo */
 512
 513 static GMatchInfo *
 514 match_info_new (const GRegex *regex,
 515                 const gchar  *string,
 516                 gint          string_len,
 517                 gint          start_position,
 518                 gint          match_options,
 519                 gboolean      is_dfa)
 520 {
 521   GMatchInfo *match_info;
 522
 523   if (string_len < 0)
 524     string_len = strlen (string);
 525
 526   match_info = g_new0 (GMatchInfo, 1);
 527   match_info->ref_count = 1;
 528   match_info->regex = g_regex_ref ((GRegex *)regex);
 529   match_info->string = string;
 530   match_info->string_len = string_len;
 531   match_info->matches = PCRE_ERROR_NOMATCH;
 532   match_info->pos = start_position;
 533   match_info->match_opts = match_options;
 534
 535   if (is_dfa)
 536     {
 537       /* These values should be enough for most cases, if they are not
 538        * enough g_regex_match_all_full() will expand them. */
 539       match_info->n_offsets = 24;
 540       match_info->n_workspace = 100;
 541       match_info->workspace = g_new (gint, match_info->n_workspace);
 542     }
 543   else
 544     {
 545       gint capture_count;
 546       pcre_fullinfo (regex->pcre_re, regex->extra,
 547                      PCRE_INFO_CAPTURECOUNT, &capture_count);
 548       match_info->n_offsets = (capture_count + 1) * 3;
 549     }
 550
 551   match_info->offsets = g_new0 (gint, match_info->n_offsets);
 552   /* Set an invalid position for the previous match. */
 553   match_info->offsets[0] = -1;
 554   match_info->offsets[1] = -1;
 555
 556   return match_info;
 557 }
 558
 559 /**
 560  * g_match_info_get_regex:
 561  * @match_info: a #GMatchInfo
 562  *
 563  * Returns #GRegex object used in @match_info. It belongs to Glib
 564  * and must not be freed. Use g_regex_ref() if you need to keep it
 565  * after you free @match_info object.
 566  *
 567  * Returns: #GRegex object used in @match_info
 568  *
 569  * Since: 2.14
 570  */
 571 GRegex *
 572 g_match_info_get_regex (const GMatchInfo *match_info)
 573 {
 574   g_return_val_if_fail (match_info != NULL, NULL);
 575   return match_info->regex;
 576 }
 577
 578 /**
 579  * g_match_info_get_string:
 580  * @match_info: a #GMatchInfo
 581  *
 582  * Returns the string searched with @match_info. This is the
 583  * string passed to g_regex_match() or g_regex_replace() so
 584  * you may not free it before calling this function.
 585  *
 586  * Returns: the string searched with @match_info
 587  *
 588  * Since: 2.14
 589  */
 590 const gchar *
 591 g_match_info_get_string (const GMatchInfo *match_info)
 592 {
 593   g_return_val_if_fail (match_info != NULL, NULL);
 594   return match_info->string;
 595 }
 596
 597 /**
 598  * g_match_info_ref:
 599  * @match_info: a #GMatchInfo
 600  *
 601  * Increases reference count of @match_info by 1.
 602  *
 603  * Returns: @match_info
 604  *
 605  * Since: 2.30
 606  */
 607 GMatchInfo       *
 608 g_match_info_ref (GMatchInfo *match_info)
 609 {
 610   g_return_val_if_fail (match_info != NULL, NULL);
 611   g_atomic_int_inc (&match_info->ref_count);
 612   return match_info;
 613 }
 614
 615 /**
 616  * g_match_info_unref:
 617  * @match_info: a #GMatchInfo
 618  *
 619  * Decreases reference count of @match_info by 1. When reference count drops
 620  * to zero, it frees all the memory associated with the match_info structure.
 621  *
 622  * Since: 2.30
 623  */
 624 void
 625 g_match_info_unref (GMatchInfo *match_info)
 626 {
 627   if (g_atomic_int_dec_and_test (&match_info->ref_count))
 628     {
 629       g_regex_unref (match_info->regex);
 630       g_free (match_info->offsets);
 631       g_free (match_info->workspace);
 632       g_free (match_info);
 633     }
 634 }
 635
 636 /**
 637  * g_match_info_free:
 638  * @match_info: (allow-none): a #GMatchInfo, or %NULL
 639  *
 640  * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
 641  * nothing.
 642  *
 643  * Since: 2.14
 644  */
 645 void
 646 g_match_info_free (GMatchInfo *match_info)
 647 {
 648   if (match_info == NULL)
 649     return;
 650
 651   g_match_info_unref (match_info);
 652 }
 653
 654 /**
 655  * g_match_info_next:
 656  * @match_info: a #GMatchInfo structure
 657  * @error: location to store the error occurring, or %NULL to ignore errors
 658  *
 659  * Scans for the next match using the same parameters of the previous
 660  * call to g_regex_match_full() or g_regex_match() that returned
 661  * @match_info.
 662  *
 663  * The match is done on the string passed to the match function, so you
 664  * cannot free it before calling this function.
 665  *
 666  * Returns: %TRUE is the string matched, %FALSE otherwise
 667  *
 668  * Since: 2.14
 669  */
 670 gboolean
 671 g_match_info_next (GMatchInfo  *match_info,
 672                    GError     **error)
 673 {
 674   gint prev_match_start;
 675   gint prev_match_end;
 676
 677   g_return_val_if_fail (match_info != NULL, FALSE);
 678   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 679   g_return_val_if_fail (match_info->pos >= 0, FALSE);
 680
 681   prev_match_start = match_info->offsets[0];
 682   prev_match_end = match_info->offsets[1];
 683
 684   if (match_info->pos > match_info->string_len)
 685     {
 686       /* we have reached the end of the string */
 687       match_info->pos = -1;
 688       match_info->matches = PCRE_ERROR_NOMATCH;
 689       return FALSE;
 690     }
 691
 692   match_info->matches = pcre_exec (match_info->regex->pcre_re,
 693                                    match_info->regex->extra,
 694                                    match_info->string,
 695                                    match_info->string_len,
 696                                    match_info->pos,
 697                                    match_info->regex->match_opts | match_info->match_opts,
 698                                    match_info->offsets,
 699                                    match_info->n_offsets);
 700   if (IS_PCRE_ERROR (match_info->matches))
 701     {
 702       g_set_error (error, G_REGEX_ERROR, G_REGEX_ERROR_MATCH,
 703                    _("Error while matching regular expression %s: %s"),
 704                    match_info->regex->pattern, match_error (match_info->matches));
 705       return FALSE;
 706     }
 707
 708   /* avoid infinite loops if the pattern is an empty string or something
 709    * equivalent */
 710   if (match_info->pos == match_info->offsets[1])
 711     {
 712       if (match_info->pos > match_info->string_len)
 713         {
 714           /* we have reached the end of the string */
 715           match_info->pos = -1;
 716           match_info->matches = PCRE_ERROR_NOMATCH;
 717           return FALSE;
 718         }
 719
 720       match_info->pos = NEXT_CHAR (match_info->regex,
 721                                    &match_info->string[match_info->pos]) -
 722                                    match_info->string;
 723     }
 724   else
 725     {
 726       match_info->pos = match_info->offsets[1];
 727     }
 728
 729   /* it's possible to get two identical matches when we are matching
 730    * empty strings, for instance if the pattern is "(?=[A-Z0-9])" and
 731    * the string is "RegExTest" we have:
 732    *  - search at position 0: match from 0 to 0
 733    *  - search at position 1: match from 3 to 3
 734    *  - search at position 3: match from 3 to 3 (duplicate)
 735    *  - search at position 4: match from 5 to 5
 736    *  - search at position 5: match from 5 to 5 (duplicate)
 737    *  - search at position 6: no match -> stop
 738    * so we have to ignore the duplicates.
 739    * see bug #515944: http://bugzilla.gnome.org/show_bug.cgi?id=515944 */
 740   if (match_info->matches >= 0 &&
 741       prev_match_start == match_info->offsets[0] &&
 742       prev_match_end == match_info->offsets[1])
 743     {
 744       /* ignore this match and search the next one */
 745       return g_match_info_next (match_info, error);
 746     }
 747
 748   return match_info->matches >= 0;
 749 }
 750
 751 /**
 752  * g_match_info_matches:
 753  * @match_info: a #GMatchInfo structure
 754  *
 755  * Returns whether the previous match operation succeeded.
 756  *
 757  * Returns: %TRUE if the previous match operation succeeded,
 758  *   %FALSE otherwise
 759  *
 760  * Since: 2.14
 761  */
 762 gboolean
 763 g_match_info_matches (const GMatchInfo *match_info)
 764 {
 765   g_return_val_if_fail (match_info != NULL, FALSE);
 766
 767   return match_info->matches >= 0;
 768 }
 769
 770 /**
 771  * g_match_info_get_match_count:
 772  * @match_info: a #GMatchInfo structure
 773  *
 774  * Retrieves the number of matched substrings (including substring 0,
 775  * that is the whole matched text), so 1 is returned if the pattern
 776  * has no substrings in it and 0 is returned if the match failed.
 777  *
 778  * If the last match was obtained using the DFA algorithm, that is
 779  * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
 780  * count is not that of the number of capturing parentheses but that of
 781  * the number of matched substrings.
 782  *
 783  * Returns: Number of matched substrings, or -1 if an error occurred
 784  *
 785  * Since: 2.14
 786  */
 787 gint
 788 g_match_info_get_match_count (const GMatchInfo *match_info)
 789 {
 790   g_return_val_if_fail (match_info, -1);
 791
 792   if (match_info->matches == PCRE_ERROR_NOMATCH)
 793     /* no match */
 794     return 0;
 795   else if (match_info->matches < PCRE_ERROR_NOMATCH)
 796     /* error */
 797     return -1;
 798   else
 799     /* match */
 800     return match_info->matches;
 801 }
 802
 803 /**
 804  * g_match_info_is_partial_match:
 805  * @match_info: a #GMatchInfo structure
 806  *
 807  * Usually if the string passed to g_regex_match*() matches as far as
 808  * it goes, but is too short to match the entire pattern, %FALSE is
 809  * returned. There are circumstances where it might be helpful to
 810  * distinguish this case from other cases in which there is no match.
 811  *
 812  * Consider, for example, an application where a human is required to
 813  * type in data for a field with specific formatting requirements. An
 814  * example might be a date in the form ddmmmyy, defined by the pattern
 815  * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
 816  * If the application sees the user’s keystrokes one by one, and can
 817  * check that what has been typed so far is potentially valid, it is
 818  * able to raise an error as soon as a mistake is made.
 819  *
 820  * GRegex supports the concept of partial matching by means of the
 821  * #G_REGEX_MATCH_PARTIAL flag. When this is set the return code for
 822  * g_regex_match() or g_regex_match_full() is, as usual, %TRUE
 823  * for a complete match, %FALSE otherwise. But, when these functions
 824  * return %FALSE, you can check if the match was partial calling
 825  * g_match_info_is_partial_match().
 826  *
 827  * When using partial matching you cannot use g_match_info_fetch*().
 828  *
 829  * Because of the way certain internal optimizations are implemented
 830  * the partial matching algorithm cannot be used with all patterns.
 831  * So repeated single characters such as "a{2,4}" and repeated single
 832  * meta-sequences such as "\d+" are not permitted if the maximum number
 833  * of occurrences is greater than one. Optional items such as "\d?"
 834  * (where the maximum is one) are permitted. Quantifiers with any values
 835  * are permitted after parentheses, so the invalid examples above can be
 836  * coded thus "(a){2,4}" and "(\d)+". If #G_REGEX_MATCH_PARTIAL is set
 837  * for a pattern that does not conform to the restrictions, matching
 838  * functions return an error.
 839  *
 840  * Returns: %TRUE if the match was partial, %FALSE otherwise
 841  *
 842  * Since: 2.14
 843  */
 844 gboolean
 845 g_match_info_is_partial_match (const GMatchInfo *match_info)
 846 {
 847   g_return_val_if_fail (match_info != NULL, FALSE);
 848
 849   return match_info->matches == PCRE_ERROR_PARTIAL;
 850 }
 851
 852 /**
 853  * g_match_info_expand_references:
 854  * @match_info: (allow-none): a #GMatchInfo or %NULL
 855  * @string_to_expand: the string to expand
 856  * @error: location to store the error occurring, or %NULL to ignore errors
 857  *
 858  * Returns a new string containing the text in @string_to_expand with
 859  * references and escape sequences expanded. References refer to the last
 860  * match done with @string against @regex and have the same syntax used by
 861  * g_regex_replace().
 862  *
 863  * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
 864  * passed to g_regex_new().
 865  *
 866  * The backreferences are extracted from the string passed to the match
 867  * function, so you cannot call this function after freeing the string.
 868  *
 869  * @match_info may be %NULL in which case @string_to_expand must not
 870  * contain references. For instance "foo\n" does not refer to an actual
 871  * pattern and '\n' merely will be replaced with \n character,
 872  * while to expand "\0" (whole match) one needs the result of a match.
 873  * Use g_regex_check_replacement() to find out whether @string_to_expand
 874  * contains references.
 875  *
 876  * Returns: (allow-none): the expanded string, or %NULL if an error occurred
 877  *
 878  * Since: 2.14
 879  */
 880 gchar *
 881 g_match_info_expand_references (const GMatchInfo  *match_info,
 882                                 const gchar       *string_to_expand,
 883                                 GError           **error)
 884 {
 885   GString *result;
 886   GList *list;
 887   GError *tmp_error = NULL;
 888
 889   g_return_val_if_fail (string_to_expand != NULL, NULL);
 890   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 891
 892   list = split_replacement (string_to_expand, &tmp_error);
 893   if (tmp_error != NULL)
 894     {
 895       g_propagate_error (error, tmp_error);
 896       return NULL;
 897     }
 898
 899   if (!match_info && interpolation_list_needs_match (list))
 900     {
 901       g_critical ("String '%s' contains references to the match, can't "
 902                   "expand references without GMatchInfo object",
 903                   string_to_expand);
 904       return NULL;
 905     }
 906
 907   result = g_string_sized_new (strlen (string_to_expand));
 908   interpolate_replacement (match_info, result, list);
 909
 910   g_list_free_full (list, (GDestroyNotify) free_interpolation_data);
 911
 912   return g_string_free (result, FALSE);
 913 }
 914
 915 /**
 916  * g_match_info_fetch:
 917  * @match_info: #GMatchInfo structure
 918  * @match_num: number of the sub expression
 919  *
 920  * Retrieves the text matching the @match_num<!-- -->'th capturing
 921  * parentheses. 0 is the full text of the match, 1 is the first paren
 922  * set, 2 the second, and so on.
 923  *
 924  * If @match_num is a valid sub pattern but it didn't match anything
 925  * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
 926  * string is returned.
 927  *
 928  * If the match was obtained using the DFA algorithm, that is using
 929  * g_regex_match_all() or g_regex_match_all_full(), the retrieved
 930  * string is not that of a set of parentheses but that of a matched
 931  * substring. Substrings are matched in reverse order of length, so
 932  * 0 is the longest match.
 933  *
 934  * The string is fetched from the string passed to the match function,
 935  * so you cannot call this function after freeing the string.
 936  *
 937  * Returns: (allow-none): The matched substring, or %NULL if an error
 938  *     occurred. You have to free the string yourself
 939  *
 940  * Since: 2.14
 941  */
 942 gchar *
 943 g_match_info_fetch (const GMatchInfo *match_info,
 944                     gint              match_num)
 945 {
 946   /* we cannot use pcre_get_substring() because it allocates the
 947    * string using pcre_malloc(). */
 948   gchar *match = NULL;
 949   gint start, end;
 950
 951   g_return_val_if_fail (match_info != NULL, NULL);
 952   g_return_val_if_fail (match_num >= 0, NULL);
 953
 954   /* match_num does not exist or it didn't matched, i.e. matching "b"
 955    * against "(a)?b" then group 0 is empty. */
 956   if (!g_match_info_fetch_pos (match_info, match_num, &start, &end))
 957     match = NULL;
 958   else if (start == -1)
 959     match = g_strdup ("");
 960   else
 961     match = g_strndup (&match_info->string[start], end - start);
 962
 963   return match;
 964 }
 965
 966 /**
 967  * g_match_info_fetch_pos:
 968  * @match_info: #GMatchInfo structure
 969  * @match_num: number of the sub expression
 970  * @start_pos: (out) (allow-none): pointer to location where to store
 971  *     the start position, or %NULL
 972  * @end_pos: (out) (allow-none): pointer to location where to store
 973  *     the end position, or %NULL
 974  *
 975  * Retrieves the position in bytes of the @match_num<!-- -->'th capturing
 976  * parentheses. 0 is the full text of the match, 1 is the first
 977  * paren set, 2 the second, and so on.
 978  *
 979  * If @match_num is a valid sub pattern but it didn't match anything
 980  * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
 981  * and @end_pos are set to -1 and %TRUE is returned.
 982  *
 983  * If the match was obtained using the DFA algorithm, that is using
 984  * g_regex_match_all() or g_regex_match_all_full(), the retrieved
 985  * position is not that of a set of parentheses but that of a matched
 986  * substring. Substrings are matched in reverse order of length, so
 987  * 0 is the longest match.
 988  *
 989  * Returns: %TRUE if the position was fetched, %FALSE otherwise. If
 990  *   the position cannot be fetched, @start_pos and @end_pos are left
 991  *   unchanged
 992  *
 993  * Since: 2.14
 994  */
 995 gboolean
 996 g_match_info_fetch_pos (const GMatchInfo *match_info,
 997                         gint              match_num,
 998                         gint             *start_pos,
 999                         gint             *end_pos)
1000 {
1001   g_return_val_if_fail (match_info != NULL, FALSE);
1002   g_return_val_if_fail (match_num >= 0, FALSE);
1003
1004   /* make sure the sub expression number they're requesting is less than
1005    * the total number of sub expressions that were matched. */
1006   if (match_num >= match_info->matches)
1007     return FALSE;
1008
1009   if (start_pos != NULL)
1010     *start_pos = match_info->offsets[2 * match_num];
1011
1012   if (end_pos != NULL)
1013     *end_pos = match_info->offsets[2 * match_num + 1];
1014
1015   return TRUE;
1016 }
1017
1018 /*
1019  * Returns number of first matched subpattern with name @name.
1020  * There may be more than one in case when DUPNAMES is used,
1021  * and not all subpatterns with that name match;
1022  * pcre_get_stringnumber() does not work in that case.
1023  */
1024 static gint
1025 get_matched_substring_number (const GMatchInfo *match_info,
1026                               const gchar      *name)
1027 {
1028   gint entrysize;
1029   gchar *first, *last;
1030   guchar *entry;
1031
1032   if (!(match_info->regex->compile_opts & G_REGEX_DUPNAMES))
1033     return pcre_get_stringnumber (match_info->regex->pcre_re, name);
1034
1035   /* This code is copied from pcre_get.c: get_first_set() */
1036   entrysize = pcre_get_stringtable_entries (match_info->regex->pcre_re,
1037                                             name,
1038                                             &first,
1039                                             &last);
1040
1041   if (entrysize <= 0)
1042     return entrysize;
1043
1044   for (entry = (guchar*) first; entry <= (guchar*) last; entry += entrysize)
1045     {
1046       gint n = (entry[0] << 8) + entry[1];
1047       if (match_info->offsets[n*2] >= 0)
1048         return n;
1049     }
1050
1051   return (first[0] << 8) + first[1];
1052 }
1053
1054 /**
1055  * g_match_info_fetch_named:
1056  * @match_info: #GMatchInfo structure
1057  * @name: name of the subexpression
1058  *
1059  * Retrieves the text matching the capturing parentheses named @name.
1060  *
1061  * If @name is a valid sub pattern name but it didn't match anything
1062  * (e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b")
1063  * then an empty string is returned.
1064  *
1065  * The string is fetched from the string passed to the match function,
1066  * so you cannot call this function after freeing the string.
1067  *
1068  * Returns: (allow-none): The matched substring, or %NULL if an error
1069  *     occurred. You have to free the string yourself
1070  *
1071  * Since: 2.14
1072  */
1073 gchar *
1074 g_match_info_fetch_named (const GMatchInfo *match_info,
1075                           const gchar      *name)
1076 {
1077   /* we cannot use pcre_get_named_substring() because it allocates the
1078    * string using pcre_malloc(). */
1079   gint num;
1080
1081   g_return_val_if_fail (match_info != NULL, NULL);
1082   g_return_val_if_fail (name != NULL, NULL);
1083
1084   num = get_matched_substring_number (match_info, name);
1085   if (num < 0)
1086     return NULL;
1087   else
1088     return g_match_info_fetch (match_info, num);
1089 }
1090
1091 /**
1092  * g_match_info_fetch_named_pos:
1093  * @match_info: #GMatchInfo structure
1094  * @name: name of the subexpression
1095  * @start_pos: (out) (allow-none): pointer to location where to store
1096  *     the start position, or %NULL
1097  * @end_pos: (out) (allow-none): pointer to location where to store
1098  *     the end position, or %NULL
1099  *
1100  * Retrieves the position in bytes of the capturing parentheses named @name.
1101  *
1102  * If @name is a valid sub pattern name but it didn't match anything
1103  * (e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b")
1104  * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
1105  *
1106  * Returns: %TRUE if the position was fetched, %FALSE otherwise.
1107  *     If the position cannot be fetched, @start_pos and @end_pos
1108  *     are left unchanged.
1109  *
1110  * Since: 2.14
1111  */
1112 gboolean
1113 g_match_info_fetch_named_pos (const GMatchInfo *match_info,
1114                               const gchar      *name,
1115                               gint             *start_pos,
1116                               gint             *end_pos)
1117 {
1118   gint num;
1119
1120   g_return_val_if_fail (match_info != NULL, FALSE);
1121   g_return_val_if_fail (name != NULL, FALSE);
1122
1123   num = get_matched_substring_number (match_info, name);
1124   if (num < 0)
1125     return FALSE;
1126
1127   return g_match_info_fetch_pos (match_info, num, start_pos, end_pos);
1128 }
1129
1130 /**
1131  * g_match_info_fetch_all:
1132  * @match_info: a #GMatchInfo structure
1133  *
1134  * Bundles up pointers to each of the matching substrings from a match
1135  * and stores them in an array of gchar pointers. The first element in
1136  * the returned array is the match number 0, i.e. the entire matched
1137  * text.
1138  *
1139  * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
1140  * "b" against "(a)?b") then an empty string is inserted.
1141  *
1142  * If the last match was obtained using the DFA algorithm, that is using
1143  * g_regex_match_all() or g_regex_match_all_full(), the retrieved
1144  * strings are not that matched by sets of parentheses but that of the
1145  * matched substring. Substrings are matched in reverse order of length,
1146  * so the first one is the longest match.
1147  *
1148  * The strings are fetched from the string passed to the match function,
1149  * so you cannot call this function after freeing the string.
1150  *
1151  * Returns: (allow-none): a %NULL-terminated array of gchar * pointers.
1152  *     It must be freed using g_strfreev(). If the previous match failed
1153  *     %NULL is returned
1154  *
1155  * Since: 2.14
1156  */
1157 gchar **
1158 g_match_info_fetch_all (const GMatchInfo *match_info)
1159 {
1160   /* we cannot use pcre_get_substring_list() because the returned value
1161    * isn't suitable for g_strfreev(). */
1162   gchar **result;
1163   gint i;
1164
1165   g_return_val_if_fail (match_info != NULL, NULL);
1166
1167   if (match_info->matches < 0)
1168     return NULL;
1169
1170   result = g_new (gchar *, match_info->matches + 1);
1171   for (i = 0; i < match_info->matches; i++)
1172     result[i] = g_match_info_fetch (match_info, i);
1173   result[i] = NULL;
1174
1175   return result;
1176 }
1177
1178
1179 /* GRegex */
1180
1181 GQuark
1182 g_regex_error_quark (void)
1183 {
1184   static GQuark error_quark = 0;
1185
1186   if (error_quark == 0)
1187     error_quark = g_quark_from_static_string ("g-regex-error-quark");
1188
1189   return error_quark;
1190 }
1191
1192 /**
1193  * g_regex_ref:
1194  * @regex: a #GRegex
1195  *
1196  * Increases reference count of @regex by 1.
1197  *
1198  * Returns: @regex
1199  *
1200  * Since: 2.14
1201  */
1202 GRegex *
1203 g_regex_ref (GRegex *regex)
1204 {
1205   g_return_val_if_fail (regex != NULL, NULL);
1206   g_atomic_int_inc (&regex->ref_count);
1207   return regex;
1208 }
1209
1210 /**
1211  * g_regex_unref:
1212  * @regex: a #GRegex
1213  *
1214  * Decreases reference count of @regex by 1. When reference count drops
1215  * to zero, it frees all the memory associated with the regex structure.
1216  *
1217  * Since: 2.14
1218  */
1219 void
1220 g_regex_unref (GRegex *regex)
1221 {
1222   g_return_if_fail (regex != NULL);
1223
1224   if (g_atomic_int_dec_and_test (&regex->ref_count))
1225     {
1226       g_free (regex->pattern);
1227       if (regex->pcre_re != NULL)
1228         pcre_free (regex->pcre_re);
1229       if (regex->extra != NULL)
1230         pcre_free (regex->extra);
1231       g_free (regex);
1232     }
1233 }
1234
1235 /**
1236  * g_regex_new:
1237  * @pattern: the regular expression
1238  * @compile_options: compile options for the regular expression, or 0
1239  * @match_options: match options for the regular expression, or 0
1240  * @error: return location for a #GError
1241  *
1242  * Compiles the regular expression to an internal form, and does
1243  * the initial setup of the #GRegex structure.
1244  *
1245  * Returns: a #GRegex structure. Call g_regex_unref() when you
1246  *   are done with it
1247  *
1248  * Since: 2.14
1249  */
1250 GRegex *
1251 g_regex_new (const gchar         *pattern,
1252              GRegexCompileFlags   compile_options,
1253              GRegexMatchFlags     match_options,
1254              GError             **error)
1255 {
1256   GRegex *regex;
1257   pcre *re;
1258   const gchar *errmsg;
1259   gint erroffset;
1260   gint errcode;
1261   gboolean optimize = FALSE;
1262   static gsize initialised;
1263   unsigned long int pcre_compile_options;
1264
1265   g_return_val_if_fail (pattern != NULL, NULL);
1266   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
1267   g_return_val_if_fail ((compile_options & ~G_REGEX_COMPILE_MASK) == 0, NULL);
1268   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
1269
1270   if (g_once_init_enter (&initialised))
1271     {
1272       gint support;
1273       const gchar *msg;
1274
1275       pcre_config (PCRE_CONFIG_UTF8, &support);
1276       if (!support)
1277         {
1278           msg = N_("PCRE library is compiled without UTF8 support");
1279           g_critical ("%s", msg);
1280           g_set_error_literal (error, G_REGEX_ERROR, G_REGEX_ERROR_COMPILE, gettext (msg));
1281           return NULL;
1282         }
1283
1284       pcre_config (PCRE_CONFIG_UNICODE_PROPERTIES, &support);
1285       if (!support)
1286         {
1287           msg = N_("PCRE library is compiled without UTF8 properties support");
1288           g_critical ("%s", msg);
1289           g_set_error_literal (error, G_REGEX_ERROR, G_REGEX_ERROR_COMPILE, gettext (msg));
1290           return NULL;
1291         }
1292
1293       g_once_init_leave (&initialised, TRUE);
1294     }
1295
1296   /* G_REGEX_OPTIMIZE has the same numeric value of PCRE_NO_UTF8_CHECK,
1297    * as we do not need to wrap PCRE_NO_UTF8_CHECK. */
1298   if (compile_options & G_REGEX_OPTIMIZE)
1299     optimize = TRUE;
1300
1301   /* In GRegex the string are, by default, UTF-8 encoded. PCRE
1302    * instead uses UTF-8 only if required with PCRE_UTF8. */
1303   if (compile_options & G_REGEX_RAW)
1304     {
1305       /* disable utf-8 */
1306       compile_options &= ~G_REGEX_RAW;
1307     }
1308   else
1309     {
1310       /* enable utf-8 */
1311       compile_options |= PCRE_UTF8 | PCRE_NO_UTF8_CHECK;
1312       match_options |= PCRE_NO_UTF8_CHECK;
1313     }
1314
1315   /* PCRE_NEWLINE_ANY is the default for the internal PCRE but
1316    * not for the system one. */
1317   if (!(compile_options & G_REGEX_NEWLINE_CR) &&
1318       !(compile_options & G_REGEX_NEWLINE_LF))
1319     {
1320       compile_options |= PCRE_NEWLINE_ANY;
1321     }
1322
1323   compile_options |= PCRE_UCP;
1324
1325   /* compile the pattern */
1326   re = pcre_compile2 (pattern, compile_options, &errcode,
1327                       &errmsg, &erroffset, NULL);
1328
1329   /* if the compilation failed, set the error member and return
1330    * immediately */
1331   if (re == NULL)
1332     {
1333       GError *tmp_error;
1334
1335       /* Translate the PCRE error code to GRegexError and use a translated
1336        * error message if possible */
1337       translate_compile_error (&errcode, &errmsg);
1338
1339       /* PCRE uses byte offsets but we want to show character offsets */
1340       erroffset = g_utf8_pointer_to_offset (pattern, &pattern[erroffset]);
1341
1342       tmp_error = g_error_new (G_REGEX_ERROR, errcode,
1343                                _("Error while compiling regular "
1344                                  "expression %s at char %d: %s"),
1345                                pattern, erroffset, errmsg);
1346       g_propagate_error (error, tmp_error);
1347
1348       return NULL;
1349     }
1350
1351   /* For options set at the beginning of the pattern, pcre puts them into
1352    * compile options, e.g. "(?i)foo" will make the pcre structure store
1353    * PCRE_CASELESS even though it wasn't explicitly given for compilation. */
1354   pcre_fullinfo (re, NULL, PCRE_INFO_OPTIONS, &pcre_compile_options);
1355   compile_options = pcre_compile_options;
1356
1357   if (!(compile_options & G_REGEX_DUPNAMES))
1358     {
1359       gboolean jchanged = FALSE;
1360       pcre_fullinfo (re, NULL, PCRE_INFO_JCHANGED, &jchanged);
1361       if (jchanged)
1362         compile_options |= G_REGEX_DUPNAMES;
1363     }
1364
1365   regex = g_new0 (GRegex, 1);
1366   regex->ref_count = 1;
1367   regex->pattern = g_strdup (pattern);
1368   regex->pcre_re = re;
1369   regex->compile_opts = compile_options;
1370   regex->match_opts = match_options;
1371
1372   if (optimize)
1373     {
1374       regex->extra = pcre_study (regex->pcre_re, 0, &errmsg);
1375       if (errmsg != NULL)
1376         {
1377           GError *tmp_error = g_error_new (G_REGEX_ERROR,
1378                                            G_REGEX_ERROR_OPTIMIZE,
1379                                            _("Error while optimizing "
1380                                              "regular expression %s: %s"),
1381                                            regex->pattern,
1382                                            errmsg);
1383           g_propagate_error (error, tmp_error);
1384
1385           g_regex_unref (regex);
1386           return NULL;
1387         }
1388     }
1389
1390   return regex;
1391 }
1392
1393 /**
1394  * g_regex_get_pattern:
1395  * @regex: a #GRegex structure
1396  *
1397  * Gets the pattern string associated with @regex, i.e. a copy of
1398  * the string passed to g_regex_new().
1399  *
1400  * Returns: the pattern of @regex
1401  *
1402  * Since: 2.14
1403  */
1404 const gchar *
1405 g_regex_get_pattern (const GRegex *regex)
1406 {
1407   g_return_val_if_fail (regex != NULL, NULL);
1408
1409   return regex->pattern;
1410 }
1411
1412 /**
1413  * g_regex_get_max_backref:
1414  * @regex: a #GRegex
1415  *
1416  * Returns the number of the highest back reference
1417  * in the pattern, or 0 if the pattern does not contain
1418  * back references.
1419  *
1420  * Returns: the number of the highest back reference
1421  *
1422  * Since: 2.14
1423  */
1424 gint
1425 g_regex_get_max_backref (const GRegex *regex)
1426 {
1427   gint value;
1428
1429   pcre_fullinfo (regex->pcre_re, regex->extra,
1430                  PCRE_INFO_BACKREFMAX, &value);
1431
1432   return value;
1433 }
1434
1435 /**
1436  * g_regex_get_capture_count:
1437  * @regex: a #GRegex
1438  *
1439  * Returns the number of capturing subpatterns in the pattern.
1440  *
1441  * Returns: the number of capturing subpatterns
1442  *
1443  * Since: 2.14
1444  */
1445 gint
1446 g_regex_get_capture_count (const GRegex *regex)
1447 {
1448   gint value;
1449
1450   pcre_fullinfo (regex->pcre_re, regex->extra,
1451                  PCRE_INFO_CAPTURECOUNT, &value);
1452
1453   return value;
1454 }
1455
1456 /**
1457  * g_regex_get_compile_flags:
1458  * @regex: a #GRegex
1459  *
1460  * Returns the compile options that @regex was created with.
1461  *
1462  * Returns: flags from #GRegexCompileFlags
1463  *
1464  * Since: 2.26
1465  */
1466 GRegexCompileFlags
1467 g_regex_get_compile_flags (const GRegex *regex)
1468 {
1469   g_return_val_if_fail (regex != NULL, 0);
1470
1471   return regex->compile_opts;
1472 }
1473
1474 /**
1475  * g_regex_get_match_flags:
1476  * @regex: a #GRegex
1477  *
1478  * Returns the match options that @regex was created with.
1479  *
1480  * Returns: flags from #GRegexMatchFlags
1481  *
1482  * Since: 2.26
1483  */
1484 GRegexMatchFlags
1485 g_regex_get_match_flags (const GRegex *regex)
1486 {
1487   g_return_val_if_fail (regex != NULL, 0);
1488
1489   return regex->match_opts;
1490 }
1491
1492 /**
1493  * g_regex_match_simple:
1494  * @pattern: the regular expression
1495  * @string: the string to scan for matches
1496  * @compile_options: compile options for the regular expression, or 0
1497  * @match_options: match options, or 0
1498  *
1499  * Scans for a match in @string for @pattern.
1500  *
1501  * This function is equivalent to g_regex_match() but it does not
1502  * require to compile the pattern with g_regex_new(), avoiding some
1503  * lines of code when you need just to do a match without extracting
1504  * substrings, capture counts, and so on.
1505  *
1506  * If this function is to be called on the same @pattern more than
1507  * once, it's more efficient to compile the pattern once with
1508  * g_regex_new() and then use g_regex_match().
1509  *
1510  * Returns: %TRUE if the string matched, %FALSE otherwise
1511  *
1512  * Since: 2.14
1513  */
1514 gboolean
1515 g_regex_match_simple (const gchar        *pattern,
1516                       const gchar        *string,
1517                       GRegexCompileFlags  compile_options,
1518                       GRegexMatchFlags    match_options)
1519 {
1520   GRegex *regex;
1521   gboolean result;
1522
1523   regex = g_regex_new (pattern, compile_options, 0, NULL);
1524   if (!regex)
1525     return FALSE;
1526   result = g_regex_match_full (regex, string, -1, 0, match_options, NULL, NULL);
1527   g_regex_unref (regex);
1528   return result;
1529 }
1530
1531 /**
1532  * g_regex_match:
1533  * @regex: a #GRegex structure from g_regex_new()
1534  * @string: the string to scan for matches
1535  * @match_options: match options
1536  * @match_info: (out) (allow-none): pointer to location where to store
1537  *     the #GMatchInfo, or %NULL if you do not need it
1538  *
1539  * Scans for a match in string for the pattern in @regex.
1540  * The @match_options are combined with the match options specified
1541  * when the @regex structure was created, letting you have more
1542  * flexibility in reusing #GRegex structures.
1543  *
1544  * A #GMatchInfo structure, used to get information on the match,
1545  * is stored in @match_info if not %NULL. Note that if @match_info
1546  * is not %NULL then it is created even if the function returns %FALSE,
1547  * i.e. you must free it regardless if regular expression actually matched.
1548  *
1549  * To retrieve all the non-overlapping matches of the pattern in
1550  * string you can use g_match_info_next().
1551  *
1552  * |[
1553  * static void
1554  * print_uppercase_words (const gchar *string)
1555  * {
1556  *   /&ast; Print all uppercase-only words. &ast;/
1557  *   GRegex *regex;
1558  *   GMatchInfo *match_info;
1559  *   &nbsp;
1560  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
1561  *   g_regex_match (regex, string, 0, &amp;match_info);
1562  *   while (g_match_info_matches (match_info))
1563  *     {
1564  *       gchar *word = g_match_info_fetch (match_info, 0);
1565  *       g_print ("Found: %s\n", word);
1566  *       g_free (word);
1567  *       g_match_info_next (match_info, NULL);
1568  *     }
1569  *   g_match_info_free (match_info);
1570  *   g_regex_unref (regex);
1571  * }
1572  * ]|
1573  *
1574  * @string is not copied and is used in #GMatchInfo internally. If
1575  * you use any #GMatchInfo method (except g_match_info_free()) after
1576  * freeing or modifying @string then the behaviour is undefined.
1577  *
1578  * Returns: %TRUE is the string matched, %FALSE otherwise
1579  *
1580  * Since: 2.14
1581  */
1582 gboolean
1583 g_regex_match (const GRegex      *regex,
1584                const gchar       *string,
1585                GRegexMatchFlags   match_options,
1586                GMatchInfo       **match_info)
1587 {
1588   return g_regex_match_full (regex, string, -1, 0, match_options,
1589                              match_info, NULL);
1590 }
1591
1592 /**
1593  * g_regex_match_full:
1594  * @regex: a #GRegex structure from g_regex_new()
1595  * @string: (array length=string_len): the string to scan for matches
1596  * @string_len: the length of @string, or -1 if @string is nul-terminated
1597  * @start_position: starting index of the string to match
1598  * @match_options: match options
1599  * @match_info: (out) (allow-none): pointer to location where to store
1600  *     the #GMatchInfo, or %NULL if you do not need it
1601  * @error: location to store the error occurring, or %NULL to ignore errors
1602  *
1603  * Scans for a match in string for the pattern in @regex.
1604  * The @match_options are combined with the match options specified
1605  * when the @regex structure was created, letting you have more
1606  * flexibility in reusing #GRegex structures.
1607  *
1608  * Setting @start_position differs from just passing over a shortened
1609  * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
1610  * that begins with any kind of lookbehind assertion, such as "\b".
1611  *
1612  * A #GMatchInfo structure, used to get information on the match, is
1613  * stored in @match_info if not %NULL. Note that if @match_info is
1614  * not %NULL then it is created even if the function returns %FALSE,
1615  * i.e. you must free it regardless if regular expression actually
1616  * matched.
1617  *
1618  * @string is not copied and is used in #GMatchInfo internally. If
1619  * you use any #GMatchInfo method (except g_match_info_free()) after
1620  * freeing or modifying @string then the behaviour is undefined.
1621  *
1622  * To retrieve all the non-overlapping matches of the pattern in
1623  * string you can use g_match_info_next().
1624  *
1625  * |[
1626  * static void
1627  * print_uppercase_words (const gchar *string)
1628  * {
1629  *   /&ast; Print all uppercase-only words. &ast;/
1630  *   GRegex *regex;
1631  *   GMatchInfo *match_info;
1632  *   GError *error = NULL;
1633  *   &nbsp;
1634  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
1635  *   g_regex_match_full (regex, string, -1, 0, 0, &amp;match_info, &amp;error);
1636  *   while (g_match_info_matches (match_info))
1637  *     {
1638  *       gchar *word = g_match_info_fetch (match_info, 0);
1639  *       g_print ("Found: %s\n", word);
1640  *       g_free (word);
1641  *       g_match_info_next (match_info, &amp;error);
1642  *     }
1643  *   g_match_info_free (match_info);
1644  *   g_regex_unref (regex);
1645  *   if (error != NULL)
1646  *     {
1647  *       g_printerr ("Error while matching: %s\n", error->message);
1648  *       g_error_free (error);
1649  *     }
1650  * }
1651  * ]|
1652  *
1653  * Returns: %TRUE is the string matched, %FALSE otherwise
1654  *
1655  * Since: 2.14
1656  */
1657 gboolean
1658 g_regex_match_full (const GRegex      *regex,
1659                     const gchar       *string,
1660                     gssize             string_len,
1661                     gint               start_position,
1662                     GRegexMatchFlags   match_options,
1663                     GMatchInfo       **match_info,
1664                     GError           **error)
1665 {
1666   GMatchInfo *info;
1667   gboolean match_ok;
1668
1669   g_return_val_if_fail (regex != NULL, FALSE);
1670   g_return_val_if_fail (string != NULL, FALSE);
1671   g_return_val_if_fail (start_position >= 0, FALSE);
1672   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1673   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, FALSE);
1674
1675   info = match_info_new (regex, string, string_len, start_position,
1676                          match_options, FALSE);
1677   match_ok = g_match_info_next (info, error);
1678   if (match_info != NULL)
1679     *match_info = info;
1680   else
1681     g_match_info_free (info);
1682
1683   return match_ok;
1684 }
1685
1686 /**
1687  * g_regex_match_all:
1688  * @regex: a #GRegex structure from g_regex_new()
1689  * @string: the string to scan for matches
1690  * @match_options: match options
1691  * @match_info: (out) (allow-none): pointer to location where to store
1692  *     the #GMatchInfo, or %NULL if you do not need it
1693  *
1694  * Using the standard algorithm for regular expression matching only
1695  * the longest match in the string is retrieved. This function uses
1696  * a different algorithm so it can retrieve all the possible matches.
1697  * For more documentation see g_regex_match_all_full().
1698  *
1699  * A #GMatchInfo structure, used to get information on the match, is
1700  * stored in @match_info if not %NULL. Note that if @match_info is
1701  * not %NULL then it is created even if the function returns %FALSE,
1702  * i.e. you must free it regardless if regular expression actually
1703  * matched.
1704  *
1705  * @string is not copied and is used in #GMatchInfo internally. If
1706  * you use any #GMatchInfo method (except g_match_info_free()) after
1707  * freeing or modifying @string then the behaviour is undefined.
1708  *
1709  * Returns: %TRUE is the string matched, %FALSE otherwise
1710  *
1711  * Since: 2.14
1712  */
1713 gboolean
1714 g_regex_match_all (const GRegex      *regex,
1715                    const gchar       *string,
1716                    GRegexMatchFlags   match_options,
1717                    GMatchInfo       **match_info)
1718 {
1719   return g_regex_match_all_full (regex, string, -1, 0, match_options,
1720                                  match_info, NULL);
1721 }
1722
1723 /**
1724  * g_regex_match_all_full:
1725  * @regex: a #GRegex structure from g_regex_new()
1726  * @string: (array length=string_len): the string to scan for matches
1727  * @string_len: the length of @string, or -1 if @string is nul-terminated
1728  * @start_position: starting index of the string to match
1729  * @match_options: match options
1730  * @match_info: (out) (allow-none): pointer to location where to store
1731  *     the #GMatchInfo, or %NULL if you do not need it
1732  * @error: location to store the error occurring, or %NULL to ignore errors
1733  *
1734  * Using the standard algorithm for regular expression matching only
1735  * the longest match in the string is retrieved, it is not possible
1736  * to obtain all the available matches. For instance matching
1737  * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;"
1738  * you get "&lt;a&gt; &lt;b&gt; &lt;c&gt;".
1739  *
1740  * This function uses a different algorithm (called DFA, i.e. deterministic
1741  * finite automaton), so it can retrieve all the possible matches, all
1742  * starting at the same point in the string. For instance matching
1743  * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;"
1744  * you would obtain three matches: "&lt;a&gt; &lt;b&gt; &lt;c&gt;",
1745  * "&lt;a&gt; &lt;b&gt;" and "&lt;a&gt;".
1746  *
1747  * The number of matched strings is retrieved using
1748  * g_match_info_get_match_count(). To obtain the matched strings and
1749  * their position you can use, respectively, g_match_info_fetch() and
1750  * g_match_info_fetch_pos(). Note that the strings are returned in
1751  * reverse order of length; that is, the longest matching string is
1752  * given first.
1753  *
1754  * Note that the DFA algorithm is slower than the standard one and it
1755  * is not able to capture substrings, so backreferences do not work.
1756  *
1757  * Setting @start_position differs from just passing over a shortened
1758  * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
1759  * that begins with any kind of lookbehind assertion, such as "\b".
1760  *
1761  * A #GMatchInfo structure, used to get information on the match, is
1762  * stored in @match_info if not %NULL. Note that if @match_info is
1763  * not %NULL then it is created even if the function returns %FALSE,
1764  * i.e. you must free it regardless if regular expression actually
1765  * matched.
1766  *
1767  * @string is not copied and is used in #GMatchInfo internally. If
1768  * you use any #GMatchInfo method (except g_match_info_free()) after
1769  * freeing or modifying @string then the behaviour is undefined.
1770  *
1771  * Returns: %TRUE is the string matched, %FALSE otherwise
1772  *
1773  * Since: 2.14
1774  */
1775 gboolean
1776 g_regex_match_all_full (const GRegex      *regex,
1777                         const gchar       *string,
1778                         gssize             string_len,
1779                         gint               start_position,
1780                         GRegexMatchFlags   match_options,
1781                         GMatchInfo       **match_info,
1782                         GError           **error)
1783 {
1784   GMatchInfo *info;
1785   gboolean done;
1786
1787   g_return_val_if_fail (regex != NULL, FALSE);
1788   g_return_val_if_fail (string != NULL, FALSE);
1789   g_return_val_if_fail (start_position >= 0, FALSE);
1790   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1791   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, FALSE);
1792
1793   info = match_info_new (regex, string, string_len, start_position,
1794                          match_options, TRUE);
1795
1796   done = FALSE;
1797   while (!done)
1798     {
1799       done = TRUE;
1800       info->matches = pcre_dfa_exec (regex->pcre_re, regex->extra,
1801                                      info->string, info->string_len,
1802                                      info->pos,
1803                                      regex->match_opts | match_options,
1804                                      info->offsets, info->n_offsets,
1805                                      info->workspace, info->n_workspace);
1806       if (info->matches == PCRE_ERROR_DFA_WSSIZE)
1807         {
1808           /* info->workspace is too small. */
1809           info->n_workspace *= 2;
1810           info->workspace = g_realloc (info->workspace,
1811                                        info->n_workspace * sizeof (gint));
1812           done = FALSE;
1813         }
1814       else if (info->matches == 0)
1815         {
1816           /* info->offsets is too small. */
1817           info->n_offsets *= 2;
1818           info->offsets = g_realloc (info->offsets,
1819                                      info->n_offsets * sizeof (gint));
1820           done = FALSE;
1821         }
1822       else if (IS_PCRE_ERROR (info->matches))
1823         {
1824           g_set_error (error, G_REGEX_ERROR, G_REGEX_ERROR_MATCH,
1825                        _("Error while matching regular expression %s: %s"),
1826                        regex->pattern, match_error (info->matches));
1827         }
1828     }
1829
1830   /* set info->pos to -1 so that a call to g_match_info_next() fails. */
1831   info->pos = -1;
1832
1833   if (match_info != NULL)
1834     *match_info = info;
1835   else
1836     g_match_info_free (info);
1837
1838   return info->matches >= 0;
1839 }
1840
1841 /**
1842  * g_regex_get_string_number:
1843  * @regex: #GRegex structure
1844  * @name: name of the subexpression
1845  *
1846  * Retrieves the number of the subexpression named @name.
1847  *
1848  * Returns: The number of the subexpression or -1 if @name
1849  *   does not exists
1850  *
1851  * Since: 2.14
1852  */
1853 gint
1854 g_regex_get_string_number (const GRegex *regex,
1855                            const gchar  *name)
1856 {
1857   gint num;
1858
1859   g_return_val_if_fail (regex != NULL, -1);
1860   g_return_val_if_fail (name != NULL, -1);
1861
1862   num = pcre_get_stringnumber (regex->pcre_re, name);
1863   if (num == PCRE_ERROR_NOSUBSTRING)
1864     num = -1;
1865
1866   return num;
1867 }
1868
1869 /**
1870  * g_regex_split_simple:
1871  * @pattern: the regular expression
1872  * @string: the string to scan for matches
1873  * @compile_options: compile options for the regular expression, or 0
1874  * @match_options: match options, or 0
1875  *
1876  * Breaks the string on the pattern, and returns an array of
1877  * the tokens. If the pattern contains capturing parentheses,
1878  * then the text for each of the substrings will also be returned.
1879  * If the pattern does not match anywhere in the string, then the
1880  * whole string is returned as the first token.
1881  *
1882  * This function is equivalent to g_regex_split() but it does
1883  * not require to compile the pattern with g_regex_new(), avoiding
1884  * some lines of code when you need just to do a split without
1885  * extracting substrings, capture counts, and so on.
1886  *
1887  * If this function is to be called on the same @pattern more than
1888  * once, it's more efficient to compile the pattern once with
1889  * g_regex_new() and then use g_regex_split().
1890  *
1891  * As a special case, the result of splitting the empty string ""
1892  * is an empty vector, not a vector containing a single string.
1893  * The reason for this special case is that being able to represent
1894  * a empty vector is typically more useful than consistent handling
1895  * of empty elements. If you do need to represent empty elements,
1896  * you'll need to check for the empty string before calling this
1897  * function.
1898  *
1899  * A pattern that can match empty strings splits @string into
1900  * separate characters wherever it matches the empty string between
1901  * characters. For example splitting "ab c" using as a separator
1902  * "\s*", you will get "a", "b" and "c".
1903  *
1904  * Returns: a %NULL-terminated array of strings. Free it using g_strfreev()
1905  *
1906  * Since: 2.14
1907  **/
1908 gchar **
1909 g_regex_split_simple (const gchar        *pattern,
1910                       const gchar        *string,
1911                       GRegexCompileFlags  compile_options,
1912                       GRegexMatchFlags    match_options)
1913 {
1914   GRegex *regex;
1915   gchar **result;
1916
1917   regex = g_regex_new (pattern, compile_options, 0, NULL);
1918   if (!regex)
1919     return NULL;
1920
1921   result = g_regex_split_full (regex, string, -1, 0, match_options, 0, NULL);
1922   g_regex_unref (regex);
1923   return result;
1924 }
1925
1926 /**
1927  * g_regex_split:
1928  * @regex: a #GRegex structure
1929  * @string: the string to split with the pattern
1930  * @match_options: match time option flags
1931  *
1932  * Breaks the string on the pattern, and returns an array of the tokens.
1933  * If the pattern contains capturing parentheses, then the text for each
1934  * of the substrings will also be returned. If the pattern does not match
1935  * anywhere in the string, then the whole string is returned as the first
1936  * token.
1937  *
1938  * As a special case, the result of splitting the empty string "" is an
1939  * empty vector, not a vector containing a single string. The reason for
1940  * this special case is that being able to represent a empty vector is
1941  * typically more useful than consistent handling of empty elements. If
1942  * you do need to represent empty elements, you'll need to check for the
1943  * empty string before calling this function.
1944  *
1945  * A pattern that can match empty strings splits @string into separate
1946  * characters wherever it matches the empty string between characters.
1947  * For example splitting "ab c" using as a separator "\s*", you will get
1948  * "a", "b" and "c".
1949  *
1950  * Returns: a %NULL-terminated gchar ** array. Free it using g_strfreev()
1951  *
1952  * Since: 2.14
1953  **/
1954 gchar **
1955 g_regex_split (const GRegex     *regex,
1956                const gchar      *string,
1957                GRegexMatchFlags  match_options)
1958 {
1959   return g_regex_split_full (regex, string, -1, 0,
1960                              match_options, 0, NULL);
1961 }
1962
1963 /**
1964  * g_regex_split_full:
1965  * @regex: a #GRegex structure
1966  * @string: (array length=string_len): the string to split with the pattern
1967  * @string_len: the length of @string, or -1 if @string is nul-terminated
1968  * @start_position: starting index of the string to match
1969  * @match_options: match time option flags
1970  * @max_tokens: the maximum number of tokens to split @string into.
1971  *   If this is less than 1, the string is split completely
1972  * @error: return location for a #GError
1973  *
1974  * Breaks the string on the pattern, and returns an array of the tokens.
1975  * If the pattern contains capturing parentheses, then the text for each
1976  * of the substrings will also be returned. If the pattern does not match
1977  * anywhere in the string, then the whole string is returned as the first
1978  * token.
1979  *
1980  * As a special case, the result of splitting the empty string "" is an
1981  * empty vector, not a vector containing a single string. The reason for
1982  * this special case is that being able to represent a empty vector is
1983  * typically more useful than consistent handling of empty elements. If
1984  * you do need to represent empty elements, you'll need to check for the
1985  * empty string before calling this function.
1986  *
1987  * A pattern that can match empty strings splits @string into separate
1988  * characters wherever it matches the empty string between characters.
1989  * For example splitting "ab c" using as a separator "\s*", you will get
1990  * "a", "b" and "c".
1991  *
1992  * Setting @start_position differs from just passing over a shortened
1993  * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
1994  * that begins with any kind of lookbehind assertion, such as "\b".
1995  *
1996  * Returns: a %NULL-terminated gchar ** array. Free it using g_strfreev()
1997  *
1998  * Since: 2.14
1999  **/
2000 gchar **
2001 g_regex_split_full (const GRegex      *regex,
2002                     const gchar       *string,
2003                     gssize             string_len,
2004                     gint               start_position,
2005                     GRegexMatchFlags   match_options,
2006                     gint               max_tokens,
2007                     GError           **error)
2008 {
2009   GError *tmp_error = NULL;
2010   GMatchInfo *match_info;
2011   GList *list, *last;
2012   gint i;
2013   gint token_count;
2014   gboolean match_ok;
2015   /* position of the last separator. */
2016   gint last_separator_end;
2017   /* was the last match 0 bytes long? */
2018   gboolean last_match_is_empty;
2019   /* the returned array of char **s */
2020   gchar **string_list;
2021
2022   g_return_val_if_fail (regex != NULL, NULL);
2023   g_return_val_if_fail (string != NULL, NULL);
2024   g_return_val_if_fail (start_position >= 0, NULL);
2025   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
2026   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
2027
2028   if (max_tokens <= 0)
2029     max_tokens = G_MAXINT;
2030
2031   if (string_len < 0)
2032     string_len = strlen (string);
2033
2034   /* zero-length string */
2035   if (string_len - start_position == 0)
2036     return g_new0 (gchar *, 1);
2037
2038   if (max_tokens == 1)
2039     {
2040       string_list = g_new0 (gchar *, 2);
2041       string_list[0] = g_strndup (&string[start_position],
2042                                   string_len - start_position);
2043       return string_list;
2044     }
2045
2046   list = NULL;
2047   token_count = 0;
2048   last_separator_end = start_position;
2049   last_match_is_empty = FALSE;
2050
2051   match_ok = g_regex_match_full (regex, string, string_len, start_position,
2052                                  match_options, &match_info, &tmp_error);
2053
2054   while (tmp_error == NULL)
2055     {
2056       if (match_ok)
2057         {
2058           last_match_is_empty =
2059                     (match_info->offsets[0] == match_info->offsets[1]);
2060
2061           /* we need to skip empty separators at the same position of the end
2062            * of another separator. e.g. the string is "a b" and the separator
2063            * is " *", so from 1 to 2 we have a match and at position 2 we have
2064            * an empty match. */
2065           if (last_separator_end != match_info->offsets[1])
2066             {
2067               gchar *token;
2068               gint match_count;
2069
2070               token = g_strndup (string + last_separator_end,
2071                                  match_info->offsets[0] - last_separator_end);
2072               list = g_list_prepend (list, token);
2073               token_count++;
2074
2075               /* if there were substrings, these need to be added to
2076                * the list. */
2077               match_count = g_match_info_get_match_count (match_info);
2078               if (match_count > 1)
2079                 {
2080                   for (i = 1; i < match_count; i++)
2081                     list = g_list_prepend (list, g_match_info_fetch (match_info, i));
2082                 }
2083             }
2084         }
2085       else
2086         {
2087           /* if there was no match, copy to end of string. */
2088           if (!last_match_is_empty)
2089             {
2090               gchar *token = g_strndup (string + last_separator_end,
2091                                         match_info->string_len - last_separator_end);
2092               list = g_list_prepend (list, token);
2093             }
2094           /* no more tokens, end the loop. */
2095           break;
2096         }
2097
2098       /* -1 to leave room for the last part. */
2099       if (token_count >= max_tokens - 1)
2100         {
2101           /* we have reached the maximum number of tokens, so we copy
2102            * the remaining part of the string. */
2103           if (last_match_is_empty)
2104             {
2105               /* the last match was empty, so we have moved one char
2106                * after the real position to avoid empty matches at the
2107                * same position. */
2108               match_info->pos = PREV_CHAR (regex, &string[match_info->pos]) - string;
2109             }
2110           /* the if is needed in the case we have terminated the available
2111            * tokens, but we are at the end of the string, so there are no
2112            * characters left to copy. */
2113           if (string_len > match_info->pos)
2114             {
2115               gchar *token = g_strndup (string + match_info->pos,
2116                                         string_len - match_info->pos);
2117               list = g_list_prepend (list, token);
2118             }
2119           /* end the loop. */
2120           break;
2121         }
2122
2123       last_separator_end = match_info->pos;
2124       if (last_match_is_empty)
2125         /* if the last match was empty, g_match_info_next() has moved
2126          * forward to avoid infinite loops, but we still need to copy that
2127          * character. */
2128         last_separator_end = PREV_CHAR (regex, &string[last_separator_end]) - string;
2129
2130       match_ok = g_match_info_next (match_info, &tmp_error);
2131     }
2132   g_match_info_free (match_info);
2133   if (tmp_error != NULL)
2134     {
2135       g_propagate_error (error, tmp_error);
2136       g_list_free_full (list, g_free);
2137       match_info->pos = -1;
2138       return NULL;
2139     }
2140
2141   string_list = g_new (gchar *, g_list_length (list) + 1);
2142   i = 0;
2143   for (last = g_list_last (list); last; last = g_list_previous (last))
2144     string_list[i++] = last->data;
2145   string_list[i] = NULL;
2146   g_list_free (list);
2147
2148   return string_list;
2149 }
2150
2151 enum
2152 {
2153   REPL_TYPE_STRING,
2154   REPL_TYPE_CHARACTER,
2155   REPL_TYPE_SYMBOLIC_REFERENCE,
2156   REPL_TYPE_NUMERIC_REFERENCE,
2157   REPL_TYPE_CHANGE_CASE
2158 };
2159
2160 typedef enum
2161 {
2162   CHANGE_CASE_NONE         = 1 << 0,
2163   CHANGE_CASE_UPPER        = 1 << 1,
2164   CHANGE_CASE_LOWER        = 1 << 2,
2165   CHANGE_CASE_UPPER_SINGLE = 1 << 3,
2166   CHANGE_CASE_LOWER_SINGLE = 1 << 4,
2167   CHANGE_CASE_SINGLE_MASK  = CHANGE_CASE_UPPER_SINGLE | CHANGE_CASE_LOWER_SINGLE,
2168   CHANGE_CASE_LOWER_MASK   = CHANGE_CASE_LOWER | CHANGE_CASE_LOWER_SINGLE,
2169   CHANGE_CASE_UPPER_MASK   = CHANGE_CASE_UPPER | CHANGE_CASE_UPPER_SINGLE
2170 } ChangeCase;
2171
2172 struct _InterpolationData
2173 {
2174   gchar     *text;
2175   gint       type;
2176   gint       num;
2177   gchar      c;
2178   ChangeCase change_case;
2179 };
2180
2181 static void
2182 free_interpolation_data (InterpolationData *data)
2183 {
2184   g_free (data->text);
2185   g_free (data);
2186 }
2187
2188 static const gchar *
2189 expand_escape (const gchar        *replacement,
2190                const gchar        *p,
2191                InterpolationData  *data,
2192                GError            **error)
2193 {
2194   const gchar *q, *r;
2195   gint x, d, h, i;
2196   const gchar *error_detail;
2197   gint base = 0;
2198   GError *tmp_error = NULL;
2199
2200   p++;
2201   switch (*p)
2202     {
2203     case 't':
2204       p++;
2205       data->c = '\t';
2206       data->type = REPL_TYPE_CHARACTER;
2207       break;
2208     case 'n':
2209       p++;
2210       data->c = '\n';
2211       data->type = REPL_TYPE_CHARACTER;
2212       break;
2213     case 'v':
2214       p++;
2215       data->c = '\v';
2216       data->type = REPL_TYPE_CHARACTER;
2217       break;
2218     case 'r':
2219       p++;
2220       data->c = '\r';
2221       data->type = REPL_TYPE_CHARACTER;
2222       break;
2223     case 'f':
2224       p++;
2225       data->c = '\f';
2226       data->type = REPL_TYPE_CHARACTER;
2227       break;
2228     case 'a':
2229       p++;
2230       data->c = '\a';
2231       data->type = REPL_TYPE_CHARACTER;
2232       break;
2233     case 'b':
2234       p++;
2235       data->c = '\b';
2236       data->type = REPL_TYPE_CHARACTER;
2237       break;
2238     case '\\':
2239       p++;
2240       data->c = '\\';
2241       data->type = REPL_TYPE_CHARACTER;
2242       break;
2243     case 'x':
2244       p++;
2245       x = 0;
2246       if (*p == '{')
2247         {
2248           p++;
2249           do
2250             {
2251               h = g_ascii_xdigit_value (*p);
2252               if (h < 0)
2253                 {
2254                   error_detail = _("hexadecimal digit or '}' expected");
2255                   goto error;
2256                 }
2257               x = x * 16 + h;
2258               p++;
2259             }
2260           while (*p != '}');
2261           p++;
2262         }
2263       else
2264         {
2265           for (i = 0; i < 2; i++)
2266             {
2267               h = g_ascii_xdigit_value (*p);
2268               if (h < 0)
2269                 {
2270                   error_detail = _("hexadecimal digit expected");
2271                   goto error;
2272                 }
2273               x = x * 16 + h;
2274               p++;
2275             }
2276         }
2277       data->type = REPL_TYPE_STRING;
2278       data->text = g_new0 (gchar, 8);
2279       g_unichar_to_utf8 (x, data->text);
2280       break;
2281     case 'l':
2282       p++;
2283       data->type = REPL_TYPE_CHANGE_CASE;
2284       data->change_case = CHANGE_CASE_LOWER_SINGLE;
2285       break;
2286     case 'u':
2287       p++;
2288       data->type = REPL_TYPE_CHANGE_CASE;
2289       data->change_case = CHANGE_CASE_UPPER_SINGLE;
2290       break;
2291     case 'L':
2292       p++;
2293       data->type = REPL_TYPE_CHANGE_CASE;
2294       data->change_case = CHANGE_CASE_LOWER;
2295       break;
2296     case 'U':
2297       p++;
2298       data->type = REPL_TYPE_CHANGE_CASE;
2299       data->change_case = CHANGE_CASE_UPPER;
2300       break;
2301     case 'E':
2302       p++;
2303       data->type = REPL_TYPE_CHANGE_CASE;
2304       data->change_case = CHANGE_CASE_NONE;
2305       break;
2306     case 'g':
2307       p++;
2308       if (*p != '<')
2309         {
2310           error_detail = _("missing '<' in symbolic reference");
2311           goto error;
2312         }
2313       q = p + 1;
2314       do
2315         {
2316           p++;
2317           if (!*p)
2318             {
2319               error_detail = _("unfinished symbolic reference");
2320               goto error;
2321             }
2322         }
2323       while (*p != '>');
2324       if (p - q == 0)
2325         {
2326           error_detail = _("zero-length symbolic reference");
2327           goto error;
2328         }
2329       if (g_ascii_isdigit (*q))
2330         {
2331           x = 0;
2332           do
2333             {
2334               h = g_ascii_digit_value (*q);
2335               if (h < 0)
2336                 {
2337                   error_detail = _("digit expected");
2338                   p = q;
2339                   goto error;
2340                 }
2341               x = x * 10 + h;
2342               q++;
2343             }
2344           while (q != p);
2345           data->num = x;
2346           data->type = REPL_TYPE_NUMERIC_REFERENCE;
2347         }
2348       else
2349         {
2350           r = q;
2351           do
2352             {
2353               if (!g_ascii_isalnum (*r))
2354                 {
2355                   error_detail = _("illegal symbolic reference");
2356                   p = r;
2357                   goto error;
2358                 }
2359               r++;
2360             }
2361           while (r != p);
2362           data->text = g_strndup (q, p - q);
2363           data->type = REPL_TYPE_SYMBOLIC_REFERENCE;
2364         }
2365       p++;
2366       break;
2367     case '0':
2368       /* if \0 is followed by a number is an octal number representing a
2369        * character, else it is a numeric reference. */
2370       if (g_ascii_digit_value (*g_utf8_next_char (p)) >= 0)
2371         {
2372           base = 8;
2373           p = g_utf8_next_char (p);
2374         }
2375     case '1':
2376     case '2':
2377     case '3':
2378     case '4':
2379     case '5':
2380     case '6':
2381     case '7':
2382     case '8':
2383     case '9':
2384       x = 0;
2385       d = 0;
2386       for (i = 0; i < 3; i++)
2387         {
2388           h = g_ascii_digit_value (*p);
2389           if (h < 0)
2390             break;
2391           if (h > 7)
2392             {
2393               if (base == 8)
2394                 break;
2395               else
2396                 base = 10;
2397             }
2398           if (i == 2 && base == 10)
2399             break;
2400           x = x * 8 + h;
2401           d = d * 10 + h;
2402           p++;
2403         }
2404       if (base == 8 || i == 3)
2405         {
2406           data->type = REPL_TYPE_STRING;
2407           data->text = g_new0 (gchar, 8);
2408           g_unichar_to_utf8 (x, data->text);
2409         }
2410       else
2411         {
2412           data->type = REPL_TYPE_NUMERIC_REFERENCE;
2413           data->num = d;
2414         }
2415       break;
2416     case 0:
2417       error_detail = _("stray final '\\'");
2418       goto error;
2419       break;
2420     default:
2421       error_detail = _("unknown escape sequence");
2422       goto error;
2423     }
2424
2425   return p;
2426
2427  error:
2428   /* G_GSSIZE_FORMAT doesn't work with gettext, so we use %lu */
2429   tmp_error = g_error_new (G_REGEX_ERROR,
2430                            G_REGEX_ERROR_REPLACE,
2431                            _("Error while parsing replacement "
2432                              "text \"%s\" at char %lu: %s"),
2433                            replacement,
2434                            (gulong)(p - replacement),
2435                            error_detail);
2436   g_propagate_error (error, tmp_error);
2437
2438   return NULL;
2439 }
2440
2441 static GList *
2442 split_replacement (const gchar  *replacement,
2443                    GError      **error)
2444 {
2445   GList *list = NULL;
2446   InterpolationData *data;
2447   const gchar *p, *start;
2448
2449   start = p = replacement;
2450   while (*p)
2451     {
2452       if (*p == '\\')
2453         {
2454           data = g_new0 (InterpolationData, 1);
2455           start = p = expand_escape (replacement, p, data, error);
2456           if (p == NULL)
2457             {
2458               g_list_free_full (list, (GDestroyNotify) free_interpolation_data);
2459               free_interpolation_data (data);
2460
2461               return NULL;
2462             }
2463           list = g_list_prepend (list, data);
2464         }
2465       else
2466         {
2467           p++;
2468           if (*p == '\\' || *p == '\0')
2469             {
2470               if (p - start > 0)
2471                 {
2472                   data = g_new0 (InterpolationData, 1);
2473                   data->text = g_strndup (start, p - start);
2474                   data->type = REPL_TYPE_STRING;
2475                   list = g_list_prepend (list, data);
2476                 }
2477             }
2478         }
2479     }
2480
2481   return g_list_reverse (list);
2482 }
2483
2484 /* Change the case of c based on change_case. */
2485 #define CHANGE_CASE(c, change_case) \
2486         (((change_case) & CHANGE_CASE_LOWER_MASK) ? \
2487                 g_unichar_tolower (c) : \
2488                 g_unichar_toupper (c))
2489
2490 static void
2491 string_append (GString     *string,
2492                const gchar *text,
2493                ChangeCase  *change_case)
2494 {
2495   gunichar c;
2496
2497   if (text[0] == '\0')
2498     return;
2499
2500   if (*change_case == CHANGE_CASE_NONE)
2501     {
2502       g_string_append (string, text);
2503     }
2504   else if (*change_case & CHANGE_CASE_SINGLE_MASK)
2505     {
2506       c = g_utf8_get_char (text);
2507       g_string_append_unichar (string, CHANGE_CASE (c, *change_case));
2508       g_string_append (string, g_utf8_next_char (text));
2509       *change_case = CHANGE_CASE_NONE;
2510     }
2511   else
2512     {
2513       while (*text != '\0')
2514         {
2515           c = g_utf8_get_char (text);
2516           g_string_append_unichar (string, CHANGE_CASE (c, *change_case));
2517           text = g_utf8_next_char (text);
2518         }
2519     }
2520 }
2521
2522 static gboolean
2523 interpolate_replacement (const GMatchInfo *match_info,
2524                          GString          *result,
2525                          gpointer          data)
2526 {
2527   GList *list;
2528   InterpolationData *idata;
2529   gchar *match;
2530   ChangeCase change_case = CHANGE_CASE_NONE;
2531
2532   for (list = data; list; list = list->next)
2533     {
2534       idata = list->data;
2535       switch (idata->type)
2536         {
2537         case REPL_TYPE_STRING:
2538           string_append (result, idata->text, &change_case);
2539           break;
2540         case REPL_TYPE_CHARACTER:
2541           g_string_append_c (result, CHANGE_CASE (idata->c, change_case));
2542           if (change_case & CHANGE_CASE_SINGLE_MASK)
2543             change_case = CHANGE_CASE_NONE;
2544           break;
2545         case REPL_TYPE_NUMERIC_REFERENCE:
2546           match = g_match_info_fetch (match_info, idata->num);
2547           if (match)
2548             {
2549               string_append (result, match, &change_case);
2550               g_free (match);
2551             }
2552           break;
2553         case REPL_TYPE_SYMBOLIC_REFERENCE:
2554           match = g_match_info_fetch_named (match_info, idata->text);
2555           if (match)
2556             {
2557               string_append (result, match, &change_case);
2558               g_free (match);
2559             }
2560           break;
2561         case REPL_TYPE_CHANGE_CASE:
2562           change_case = idata->change_case;
2563           break;
2564         }
2565     }
2566
2567   return FALSE;
2568 }
2569
2570 /* whether actual match_info is needed for replacement, i.e.
2571  * whether there are references
2572  */
2573 static gboolean
2574 interpolation_list_needs_match (GList *list)
2575 {
2576   while (list != NULL)
2577     {
2578       InterpolationData *data = list->data;
2579
2580       if (data->type == REPL_TYPE_SYMBOLIC_REFERENCE ||
2581           data->type == REPL_TYPE_NUMERIC_REFERENCE)
2582         {
2583           return TRUE;
2584         }
2585
2586       list = list->next;
2587     }
2588
2589   return FALSE;
2590 }
2591
2592 /**
2593  * g_regex_replace:
2594  * @regex: a #GRegex structure
2595  * @string: (array length=string_len): the string to perform matches against
2596  * @string_len: the length of @string, or -1 if @string is nul-terminated
2597  * @start_position: starting index of the string to match
2598  * @replacement: text to replace each match with
2599  * @match_options: options for the match
2600  * @error: location to store the error occurring, or %NULL to ignore errors
2601  *
2602  * Replaces all occurrences of the pattern in @regex with the
2603  * replacement text. Backreferences of the form '\number' or
2604  * '\g&lt;number&gt;' in the replacement text are interpolated by the
2605  * number-th captured subexpression of the match, '\g&lt;name&gt;' refers
2606  * to the captured subexpression with the given name. '\0' refers to the
2607  * complete match, but '\0' followed by a number is the octal representation
2608  * of a character. To include a literal '\' in the replacement, write '\\'.
2609  * There are also escapes that changes the case of the following text:
2610  *
2611  * <variablelist>
2612  * <varlistentry><term>\l</term>
2613  * <listitem>
2614  * <para>Convert to lower case the next character</para>
2615  * </listitem>
2616  * </varlistentry>
2617  * <varlistentry><term>\u</term>
2618  * <listitem>
2619  * <para>Convert to upper case the next character</para>
2620  * </listitem>
2621  * </varlistentry>
2622  * <varlistentry><term>\L</term>
2623  * <listitem>
2624  * <para>Convert to lower case till \E</para>
2625  * </listitem>
2626  * </varlistentry>
2627  * <varlistentry><term>\U</term>
2628  * <listitem>
2629  * <para>Convert to upper case till \E</para>
2630  * </listitem>
2631  * </varlistentry>
2632  * <varlistentry><term>\E</term>
2633  * <listitem>
2634  * <para>End case modification</para>
2635  * </listitem>
2636  * </varlistentry>
2637  * </variablelist>
2638  *
2639  * If you do not need to use backreferences use g_regex_replace_literal().
2640  *
2641  * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
2642  * passed to g_regex_new(). If you want to use not UTF-8 encoded stings
2643  * you can use g_regex_replace_literal().
2644  *
2645  * Setting @start_position differs from just passing over a shortened
2646  * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
2647  * begins with any kind of lookbehind assertion, such as "\b".
2648  *
2649  * Returns: a newly allocated string containing the replacements
2650  *
2651  * Since: 2.14
2652  */
2653 gchar *
2654 g_regex_replace (const GRegex      *regex,
2655                  const gchar       *string,
2656                  gssize             string_len,
2657                  gint               start_position,
2658                  const gchar       *replacement,
2659                  GRegexMatchFlags   match_options,
2660                  GError           **error)
2661 {
2662   gchar *result;
2663   GList *list;
2664   GError *tmp_error = NULL;
2665
2666   g_return_val_if_fail (regex != NULL, NULL);
2667   g_return_val_if_fail (string != NULL, NULL);
2668   g_return_val_if_fail (start_position >= 0, NULL);
2669   g_return_val_if_fail (replacement != NULL, NULL);
2670   g_return_val_if_fail (error == NULL || *error == NULL, NULL);
2671   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
2672
2673   list = split_replacement (replacement, &tmp_error);
2674   if (tmp_error != NULL)
2675     {
2676       g_propagate_error (error, tmp_error);
2677       return NULL;
2678     }
2679
2680   result = g_regex_replace_eval (regex,
2681                                  string, string_len, start_position,
2682                                  match_options,
2683                                  interpolate_replacement,
2684                                  (gpointer)list,
2685                                  &tmp_error);
2686   if (tmp_error != NULL)
2687     g_propagate_error (error, tmp_error);
2688
2689   g_list_free_full (list, (GDestroyNotify) free_interpolation_data);
2690
2691   return result;
2692 }
2693
2694 static gboolean
2695 literal_replacement (const GMatchInfo *match_info,
2696                      GString          *result,
2697                      gpointer          data)
2698 {
2699   g_string_append (result, data);
2700   return FALSE;
2701 }
2702
2703 /**
2704  * g_regex_replace_literal:
2705  * @regex: a #GRegex structure
2706  * @string: (array length=string_len): the string to perform matches against
2707  * @string_len: the length of @string, or -1 if @string is nul-terminated
2708  * @start_position: starting index of the string to match
2709  * @replacement: text to replace each match with
2710  * @match_options: options for the match
2711  * @error: location to store the error occurring, or %NULL to ignore errors
2712  *
2713  * Replaces all occurrences of the pattern in @regex with the
2714  * replacement text. @replacement is replaced literally, to
2715  * include backreferences use g_regex_replace().
2716  *
2717  * Setting @start_position differs from just passing over a
2718  * shortened string and setting #G_REGEX_MATCH_NOTBOL in the
2719  * case of a pattern that begins with any kind of lookbehind
2720  * assertion, such as "\b".
2721  *
2722  * Returns: a newly allocated string containing the replacements
2723  *
2724  * Since: 2.14
2725  */
2726 gchar *
2727 g_regex_replace_literal (const GRegex      *regex,
2728                          const gchar       *string,
2729                          gssize             string_len,
2730                          gint               start_position,
2731                          const gchar       *replacement,
2732                          GRegexMatchFlags   match_options,
2733                          GError           **error)
2734 {
2735   g_return_val_if_fail (replacement != NULL, NULL);
2736   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
2737
2738   return g_regex_replace_eval (regex,
2739                                string, string_len, start_position,
2740                                match_options,
2741                                literal_replacement,
2742                                (gpointer)replacement,
2743                                error);
2744 }
2745
2746 /**
2747  * g_regex_replace_eval:
2748  * @regex: a #GRegex structure from g_regex_new()
2749  * @string: (array length=string_len): string to perform matches against
2750  * @string_len: the length of @string, or -1 if @string is nul-terminated
2751  * @start_position: starting index of the string to match
2752  * @match_options: options for the match
2753  * @eval: a function to call for each match
2754  * @user_data: user data to pass to the function
2755  * @error: location to store the error occurring, or %NULL to ignore errors
2756  *
2757  * Replaces occurrences of the pattern in regex with the output of
2758  * @eval for that occurrence.
2759  *
2760  * Setting @start_position differs from just passing over a shortened
2761  * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
2762  * that begins with any kind of lookbehind assertion, such as "\b".
2763  *
2764  * The following example uses g_regex_replace_eval() to replace multiple
2765  * strings at once:
2766  * |[
2767  * static gboolean
2768  * eval_cb (const GMatchInfo *info,
2769  *          GString          *res,
2770  *          gpointer          data)
2771  * {
2772  *   gchar *match;
2773  *   gchar *r;
2774  *
2775  *    match = g_match_info_fetch (info, 0);
2776  *    r = g_hash_table_lookup ((GHashTable *)data, match);
2777  *    g_string_append (res, r);
2778  *    g_free (match);
2779  *
2780  *    return FALSE;
2781  * }
2782  *
2783  * /&ast; ... &ast;/
2784  *
2785  * GRegex *reg;
2786  * GHashTable *h;
2787  * gchar *res;
2788  *
2789  * h = g_hash_table_new (g_str_hash, g_str_equal);
2790  *
2791  * g_hash_table_insert (h, "1", "ONE");
2792  * g_hash_table_insert (h, "2", "TWO");
2793  * g_hash_table_insert (h, "3", "THREE");
2794  * g_hash_table_insert (h, "4", "FOUR");
2795  *
2796  * reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
2797  * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
2798  * g_hash_table_destroy (h);
2799  *
2800  * /&ast; ... &ast;/
2801  * ]|
2802  *
2803  * Returns: a newly allocated string containing the replacements
2804  *
2805  * Since: 2.14
2806  */
2807 gchar *
2808 g_regex_replace_eval (const GRegex        *regex,
2809                       const gchar         *string,
2810                       gssize               string_len,
2811                       gint                 start_position,
2812                       GRegexMatchFlags     match_options,
2813                       GRegexEvalCallback   eval,
2814                       gpointer             user_data,
2815                       GError             **error)
2816 {
2817   GMatchInfo *match_info;
2818   GString *result;
2819   gint str_pos = 0;
2820   gboolean done = FALSE;
2821   GError *tmp_error = NULL;
2822
2823   g_return_val_if_fail (regex != NULL, NULL);
2824   g_return_val_if_fail (string != NULL, NULL);
2825   g_return_val_if_fail (start_position >= 0, NULL);
2826   g_return_val_if_fail (eval != NULL, NULL);
2827   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
2828
2829   if (string_len < 0)
2830     string_len = strlen (string);
2831
2832   result = g_string_sized_new (string_len);
2833
2834   /* run down the string making matches. */
2835   g_regex_match_full (regex, string, string_len, start_position,
2836                       match_options, &match_info, &tmp_error);
2837   while (!done && g_match_info_matches (match_info))
2838     {
2839       g_string_append_len (result,
2840                            string + str_pos,
2841                            match_info->offsets[0] - str_pos);
2842       done = (*eval) (match_info, result, user_data);
2843       str_pos = match_info->offsets[1];
2844       g_match_info_next (match_info, &tmp_error);
2845     }
2846   g_match_info_free (match_info);
2847   if (tmp_error != NULL)
2848     {
2849       g_propagate_error (error, tmp_error);
2850       g_string_free (result, TRUE);
2851       return NULL;
2852     }
2853
2854   g_string_append_len (result, string + str_pos, string_len - str_pos);
2855   return g_string_free (result, FALSE);
2856 }
2857
2858 /**
2859  * g_regex_check_replacement:
2860  * @replacement: the replacement string
2861  * @has_references: (out) (allow-none): location to store information about
2862  *   references in @replacement or %NULL
2863  * @error: location to store error
2864  *
2865  * Checks whether @replacement is a valid replacement string
2866  * (see g_regex_replace()), i.e. that all escape sequences in
2867  * it are valid.
2868  *
2869  * If @has_references is not %NULL then @replacement is checked
2870  * for pattern references. For instance, replacement text 'foo\n'
2871  * does not contain references and may be evaluated without information
2872  * about actual match, but '\0\1' (whole match followed by first
2873  * subpattern) requires valid #GMatchInfo object.
2874  *
2875  * Returns: whether @replacement is a valid replacement string
2876  *
2877  * Since: 2.14
2878  */
2879 gboolean
2880 g_regex_check_replacement (const gchar  *replacement,
2881                            gboolean     *has_references,
2882                            GError      **error)
2883 {
2884   GList *list;
2885   GError *tmp = NULL;
2886
2887   list = split_replacement (replacement, &tmp);
2888
2889   if (tmp)
2890   {
2891     g_propagate_error (error, tmp);
2892     return FALSE;
2893   }
2894
2895   if (has_references)
2896     *has_references = interpolation_list_needs_match (list);
2897
2898   g_list_free_full (list, (GDestroyNotify) free_interpolation_data);
2899
2900   return TRUE;
2901 }
2902
2903 /**
2904  * g_regex_escape_nul:
2905  * @string: the string to escape
2906  * @length: the length of @string
2907  *
2908  * Escapes the nul characters in @string to "\x00".  It can be used
2909  * to compile a regex with embedded nul characters.
2910  *
2911  * For completeness, @length can be -1 for a nul-terminated string.
2912  * In this case the output string will be of course equal to @string.
2913  *
2914  * Returns: a newly-allocated escaped string
2915  *
2916  * Since: 2.30
2917  */
2918 gchar *
2919 g_regex_escape_nul (const gchar *string,
2920                     gint         length)
2921 {
2922   GString *escaped;
2923   const gchar *p, *piece_start, *end;
2924   gint backslashes;
2925
2926   g_return_val_if_fail (string != NULL, NULL);
2927
2928   if (length < 0)
2929     return g_strdup (string);
2930
2931   end = string + length;
2932   p = piece_start = string;
2933   escaped = g_string_sized_new (length + 1);
2934
2935   backslashes = 0;
2936   while (p < end)
2937     {
2938       switch (*p)
2939         {
2940         case '\0':
2941           if (p != piece_start)
2942             {
2943               /* copy the previous piece. */
2944               g_string_append_len (escaped, piece_start, p - piece_start);
2945             }
2946           if ((backslashes & 1) == 0)
2947             g_string_append_c (escaped, '\\');
2948           g_string_append_c (escaped, 'x');
2949           g_string_append_c (escaped, '0');
2950           g_string_append_c (escaped, '0');
2951           piece_start = ++p;
2952           backslashes = 0;
2953           break;
2954         case '\\':
2955           backslashes++;
2956           ++p;
2957           break;
2958         default:
2959           backslashes = 0;
2960           p = g_utf8_next_char (p);
2961           break;
2962         }
2963     }
2964
2965   if (piece_start < end)
2966     g_string_append_len (escaped, piece_start, end - piece_start);
2967
2968   return g_string_free (escaped, FALSE);
2969 }
2970
2971 /**
2972  * g_regex_escape_string:
2973  * @string: (array length=length): the string to escape
2974  * @length: the length of @string, or -1 if @string is nul-terminated
2975  *
2976  * Escapes the special characters used for regular expressions
2977  * in @string, for instance "a.b*c" becomes "a\.b\*c". This
2978  * function is useful to dynamically generate regular expressions.
2979  *
2980  * @string can contain nul characters that are replaced with "\0",
2981  * in this case remember to specify the correct length of @string
2982  * in @length.
2983  *
2984  * Returns: a newly-allocated escaped string
2985  *
2986  * Since: 2.14
2987  */
2988 gchar *
2989 g_regex_escape_string (const gchar *string,
2990                        gint         length)
2991 {
2992   GString *escaped;
2993   const char *p, *piece_start, *end;
2994
2995   g_return_val_if_fail (string != NULL, NULL);
2996
2997   if (length < 0)
2998     length = strlen (string);
2999
3000   end = string + length;
3001   p = piece_start = string;
3002   escaped = g_string_sized_new (length + 1);
3003
3004   while (p < end)
3005     {
3006       switch (*p)
3007         {
3008         case '\0':
3009         case '\\':
3010         case '|':
3011         case '(':
3012         case ')':
3013         case '[':
3014         case ']':
3015         case '{':
3016         case '}':
3017         case '^':
3018         case '$':
3019         case '*':
3020         case '+':
3021         case '?':
3022         case '.':
3023           if (p != piece_start)
3024             /* copy the previous piece. */
3025             g_string_append_len (escaped, piece_start, p - piece_start);
3026           g_string_append_c (escaped, '\\');
3027           if (*p == '\0')
3028             g_string_append_c (escaped, '0');
3029           else
3030             g_string_append_c (escaped, *p);
3031           piece_start = ++p;
3032           break;
3033         default:
3034           p = g_utf8_next_char (p);
3035           break;
3036         }
3037   }
3038
3039   if (piece_start < end)
3040     g_string_append_len (escaped, piece_start, end - piece_start);
3041
3042   return g_string_free (escaped, FALSE);
3043 }