← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/glib2.0/jaunty-updates

« back to all changes in this revision

Viewing changes to docs/reference/glib/html/glib-Perl-compatible-regular-expressions.html

  • Committer: Bazaar Package Importer
  • Author(s): Sebastian Dröge
  • Date: 2009-03-14 10:53:26 UTC
  • mfrom: (1.2.44 upstream) (3.2.27 jaunty)
  • Revision ID: james.westby@ubuntu.com-20090314105326-6oo6zwt0xmc2jor2
Tags: 2.20.0-1
* New upstream stable release.
* Upload to unstable, remove check-dist include.
  This won't block any transitions because of symbol files.
* debian/libglib2.0-0.symbols,
  debian/rules:
  + Update for the API changes.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/html/glib-Perl-compatible-regular-expressions.html
3
3
<head>
4
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>Perl-compatible regular expressions</title>
6
 
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
 
6
<meta name="generator" content="DocBook XSL Stylesheets V1.74.2">
7
7
<link rel="home" href="index.html" title="GLib Reference Manual">
8
8
<link rel="up" href="glib-utilities.html" title="GLib Utilities">
9
9
<link rel="prev" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching">
27
27
<link rel="index" href="ix09.html" title="Index of new symbols in 2.14">
28
28
<link rel="index" href="ix10.html" title="Index of new symbols in 2.16">
29
29
<link rel="index" href="ix11.html" title="Index of new symbols in 2.18">
 
30
<link rel="index" href="ix12.html" title="Index of new symbols in 2.20">
30
31
</head>
31
32
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
32
33
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
824
825
</tr>
825
826
<tr>
826
827
<td><p><span class="term"><em class="parameter"><code>compile_options</code></em> :</span></p></td>
827
 
<td> compile options for the regular expression
 
828
<td> compile options for the regular expression, or 0 
828
829
</td>
829
830
</tr>
830
831
<tr>
831
832
<td><p><span class="term"><em class="parameter"><code>match_options</code></em> :</span></p></td>
832
 
<td> match options for the regular expression
 
833
<td> match options for the regular expression, or 0
833
834
</td>
834
835
</tr>
835
836
<tr>
1083
1084
</tr>
1084
1085
<tr>
1085
1086
<td><p><span class="term"><em class="parameter"><code>compile_options</code></em> :</span></p></td>
1086
 
<td> compile options for the regular expression
 
1087
<td> compile options for the regular expression, or 0
1087
1088
</td>
1088
1089
</tr>
1089
1090
<tr>
1090
1091
<td><p><span class="term"><em class="parameter"><code>match_options</code></em> :</span></p></td>
1091
 
<td> match options
 
1092
<td> match options, or 0
1092
1093
</td>
1093
1094
</tr>
1094
1095
<tr>
1095
1096
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1096
 
<td> <a class="link" href="glib-Standard-Macros.html#TRUE--CAPS" title="TRUE"><code class="literal">TRUE</code></a> is the string matched, <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a> otherwise
 
1097
<td> <a class="link" href="glib-Standard-Macros.html#TRUE--CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the string matched, <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a> otherwise
1097
1098
 
1098
1099
</td>
1099
1100
</tr>
1149
1150
</pre></div>
1150
1151
<p>
1151
1152
</p>
 
1153
<p>
 
1154
<em class="parameter"><code>string</code></em> is not copied and is used in <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> internally. If 
 
1155
you use any <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> method (except <a class="link" href="glib-Perl-compatible-regular-expressions.html#g-match-info-free" title="g_match_info_free ()"><code class="function">g_match_info_free()</code></a>) after 
 
1156
freeing or modifying <em class="parameter"><code>string</code></em> then the behaviour is undefined.</p>
 
1157
<p>
 
1158
</p>
1152
1159
<div class="variablelist"><table border="0">
1153
1160
<col align="left" valign="top">
1154
1161
<tbody>
1318
1325
stored in <em class="parameter"><code>match_info</code></em> if not <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a>. Note that if <em class="parameter"><code>match_info</code></em> is 
1319
1326
not <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> then it is created even if the function returns <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a>, 
1320
1327
i.e. you must free it regardless if regular expression actually 
1321
 
matched.</p>
 
1328
matched.
 
1329
</p>
 
1330
<p>
 
1331
<em class="parameter"><code>string</code></em> is not copied and is used in <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> internally. If 
 
1332
you use any <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> method (except <a class="link" href="glib-Perl-compatible-regular-expressions.html#g-match-info-free" title="g_match_info_free ()"><code class="function">g_match_info_free()</code></a>) after 
 
1333
freeing or modifying <em class="parameter"><code>string</code></em> then the behaviour is undefined.</p>
1322
1334
<p>
1323
1335
</p>
1324
1336
<div class="variablelist"><table border="0">
1402
1414
stored in <em class="parameter"><code>match_info</code></em> if not <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a>. Note that if <em class="parameter"><code>match_info</code></em> is 
1403
1415
not <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> then it is created even if the function returns <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a>, 
1404
1416
i.e. you must free it regardless if regular expression actually 
1405
 
matched.</p>
 
1417
matched.
 
1418
</p>
 
1419
<p>
 
1420
<em class="parameter"><code>string</code></em> is not copied and is used in <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> internally. If 
 
1421
you use any <a class="link" href="glib-Perl-compatible-regular-expressions.html#GMatchInfo" title="GMatchInfo"><span class="type">GMatchInfo</span></a> method (except <a class="link" href="glib-Perl-compatible-regular-expressions.html#g-match-info-free" title="g_match_info_free ()"><code class="function">g_match_info_free()</code></a>) after 
 
1422
freeing or modifying <em class="parameter"><code>string</code></em> then the behaviour is undefined.</p>
1406
1423
<p>
1407
1424
</p>
1408
1425
<div class="variablelist"><table border="0">
1510
1527
</tr>
1511
1528
<tr>
1512
1529
<td><p><span class="term"><em class="parameter"><code>compile_options</code></em> :</span></p></td>
1513
 
<td> compile options for the regular expression
 
1530
<td> compile options for the regular expression, or 0
1514
1531
</td>
1515
1532
</tr>
1516
1533
<tr>
1517
1534
<td><p><span class="term"><em class="parameter"><code>match_options</code></em> :</span></p></td>
1518
 
<td> match options
 
1535
<td> match options, or 0
1519
1536
</td>
1520
1537
</tr>
1521
1538
<tr>
1522
1539
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1523
 
<td> a <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated gchar ** array. Free it using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>
 
1540
<td> a <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings. Free it using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>
1524
1541
 
1525
1542
</td>
1526
1543
</tr>
1681
1698
                                                         <a class="link" href="glib-Perl-compatible-regular-expressions.html#GRegexMatchFlags" title="enum GRegexMatchFlags">GRegexMatchFlags</a> match_options,
1682
1699
                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **error);</pre>
1683
1700
<p>
1684
 
Replaces all occurances of the pattern in <em class="parameter"><code>regex</code></em> with the
 
1701
Replaces all occurrences of the pattern in <em class="parameter"><code>regex</code></em> with the
1685
1702
replacement text. Backreferences of the form '\number' or 
1686
1703
'\g&lt;number&gt;' in the replacement text are interpolated by the 
1687
1704
number-th captured subexpression of the match, '\g&lt;name&gt;' refers 
1792
1809
                                                         <a class="link" href="glib-Perl-compatible-regular-expressions.html#GRegexMatchFlags" title="enum GRegexMatchFlags">GRegexMatchFlags</a> match_options,
1793
1810
                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **error);</pre>
1794
1811
<p>
1795
 
Replaces all occurances of the pattern in <em class="parameter"><code>regex</code></em> with the
 
1812
Replaces all occurrences of the pattern in <em class="parameter"><code>regex</code></em> with the
1796
1813
replacement text. <em class="parameter"><code>replacement</code></em> is replaced literally, to
1797
1814
include backreferences use <a class="link" href="glib-Perl-compatible-regular-expressions.html#g-regex-replace" title="g_regex_replace ()"><code class="function">g_regex_replace()</code></a>.
1798
1815
</p>
1863
1880
                                                         <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer">gpointer</a> user_data,
1864
1881
                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **error);</pre>
1865
1882
<p>
1866
 
Replaces occurances of the pattern in regex with the output of 
1867
 
<em class="parameter"><code>eval</code></em> for that occurance.
 
1883
Replaces occurrences of the pattern in regex with the output of 
 
1884
<em class="parameter"><code>eval</code></em> for that occurrence.
1868
1885
</p>
1869
1886
<p>
1870
1887
Setting <em class="parameter"><code>start_position</code></em> differs from just passing over a shortened 
1871
1888
string and setting <a class="link" href="glib-Perl-compatible-regular-expressions.html#G-REGEX-MATCH-NOTBOL--CAPS"><span class="type">G_REGEX_MATCH_NOTBOL</span></a> in the case of a pattern 
1872
 
that begins with any kind of lookbehind assertion, such as "\b".</p>
 
1889
that begins with any kind of lookbehind assertion, such as "\b".
 
1890
</p>
 
1891
<p>
 
1892
The following example uses <a class="link" href="glib-Perl-compatible-regular-expressions.html#g-regex-replace-eval" title="g_regex_replace_eval ()"><code class="function">g_regex_replace_eval()</code></a> to replace multiple
 
1893
strings at once:
 
1894
</p>
 
1895
<div class="informalexample"><pre class="programlisting">
 
1896
static gboolean 
 
1897
eval_cb (const GMatchInfo *info,          
 
1898
         GString          *res,
 
1899
         gpointer          data)
 
1900
{
 
1901
  gchar *match;
 
1902
  gchar *r;
 
1903
 
 
1904
   match = g_match_info_fetch (info, 0);
 
1905
   r = g_hash_table_lookup ((GHashTable *)data, match);
 
1906
   g_string_append (res, r);
 
1907
   g_free (match);
 
1908
 
 
1909
   return FALSE;
 
1910
}
 
1911
 
 
1912
/* ... */
 
1913
 
 
1914
GRegex *reg;
 
1915
GHashTable *h;
 
1916
gchar *res;
 
1917
 
 
1918
h = g_hash_table_new (g_str_hash, g_str_equal);
 
1919
 
 
1920
g_hash_table_insert (h, "1", "ONE");
 
1921
g_hash_table_insert (h, "2", "TWO");
 
1922
g_hash_table_insert (h, "3", "THREE");
 
1923
g_hash_table_insert (h, "4", "FOUR");
 
1924
 
 
1925
reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
 
1926
res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
 
1927
g_hash_table_destroy (h);
 
1928
 
 
1929
/* ... */
 
1930
</pre></div>
1873
1931
<p>
1874
1932
</p>
1875
1933
<div class="variablelist"><table border="0">
2334
2392
                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> *start_pos,
2335
2393
                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> *end_pos);</pre>
2336
2394
<p>
2337
 
Retrieves the position of the <em class="parameter"><code>match_num</code></em>'th capturing 
 
2395
Retrieves the position in bytes of the <em class="parameter"><code>match_num</code></em>'th capturing 
2338
2396
parentheses. 0 is the full text of the match, 1 is the first 
2339
2397
paren set, 2 the second, and so on.
2340
2398
</p>
2436
2494
                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> *start_pos,
2437
2495
                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> *end_pos);</pre>
2438
2496
<p>
2439
 
Retrieves the position of the capturing parentheses named <em class="parameter"><code>name</code></em>.
 
2497
Retrieves the position in bytes of the capturing parentheses named <em class="parameter"><code>name</code></em>.
2440
2498
</p>
2441
2499
<p>
2442
2500
If <em class="parameter"><code>name</code></em> is a valid sub pattern name but it didn't match anything