ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GMatchInfo&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re39.html" title="&lt;%GLibMarkupParseFlags&gt;">
<link rel="next" href="re41.html" title="&lt;%GLibNormalizeMode&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re39.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re41.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.41"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GMatchInfo&gt;</h2>
<p>&lt;GMatchInfo&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.41.2"></a><h2>Description</h2>
<p>A GMatchInfo is an opaque struct used to return information about
matches.</p>
</div>
<div class="refsect1">
<a name="id-1.1.41.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.41.3.2"></a><h3>expand-references</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:expand-references self string-to-expand))
</pre></div>
<p>Returns a new string containing the text in <em class="parameter"><code>string_to_expand</code></em> with
references and escape sequences expanded. References refer to the last
match done with <em class="parameter"><code>string</code></em> against <em class="parameter"><code>regex</code></em> and have the same syntax used by
<code class="function">g_regex_replace()</code>.
</p>
<p>The <em class="parameter"><code>string_to_expand</code></em> must be UTF-8 encoded even if <span class="type">G_REGEX_RAW</span> was
passed to <code class="function">g_regex_new()</code>.
</p>
<p>The backreferences are extracted from the string passed to the match
function, so you cannot call this function after freeing the string.
</p>
<p><em class="parameter"><code>match_info</code></em> may be <code class="constant">NULL</code> in which case <em class="parameter"><code>string_to_expand</code></em> must not
contain references. For instance "foo\n" does not refer to an actual
pattern and '\n' merely will be replaced with \n character,
while to expand "\0" (whole match) one needs the result of a match.
Use <code class="function">g_regex_check_replacement()</code> to find out whether <em class="parameter"><code>string_to_expand</code></em>
contains references.</p>
<div class="refsect3">
<a name="id-1.1.41.3.2.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>string_to_expand</p></td>
<td class="parameter_description">
<p>the string to expand</p>
<p>Passed as <code class="code">string-to-expand</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.3"></a><h3>fetch</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:fetch self match-num))
</pre></div>
<p>Retrieves the text matching the <em class="parameter"><code>match_num</code></em>'th capturing
parentheses. 0 is the full text of the match, 1 is the first paren
set, 2 the second, and so on.
</p>
<p>If <em class="parameter"><code>match_num</code></em> is a valid sub pattern but it didn't match anything
(e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
string is returned.
</p>
<p>If the match was obtained using the DFA algorithm, that is using
<code class="function">g_regex_match_all()</code> or <code class="function">g_regex_match_all_full()</code>, the retrieved
string is not that of a set of parentheses but that of a matched
substring. Substrings are matched in reverse order of length, so
0 is the longest match.
</p>
<p>The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</p>
<div class="refsect3">
<a name="id-1.1.41.3.3.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p><span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>match_num</p></td>
<td class="parameter_description">
<p>number of the sub expression</p>
<p>Passed as <code class="code">match-num</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.4"></a><h3>fetch-all</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:fetch-all self))
</pre></div>
<p>Bundles up pointers to each of the matching substrings from a match
and stores them in an array of gchar pointers. The first element in
the returned array is the match number 0, i.e. the entire matched
text.
</p>
<p>If a sub pattern didn't match anything (e.g. sub pattern 1, matching
"b" against "(a)?b") then an empty string is inserted.
</p>
<p>If the last match was obtained using the DFA algorithm, that is using
<code class="function">g_regex_match_all()</code> or <code class="function">g_regex_match_all_full()</code>, the retrieved
strings are not that matched by sets of parentheses but that of the
matched substring. Substrings are matched in reverse order of length,
so the first one is the longest match.
</p>
<p>The strings are fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</p>
<div class="refsect3">
<a name="id-1.1.41.3.4.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.5"></a><h3>fetch-named</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:fetch-named self name))
</pre></div>
<p>Retrieves the text matching the capturing parentheses named <em class="parameter"><code>name</code></em>.
</p>
<p>If <em class="parameter"><code>name</code></em> is a valid sub pattern name but it didn't match anything
(e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b")
then an empty string is returned.
</p>
<p>The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</p>
<div class="refsect3">
<a name="id-1.1.41.3.5.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p><span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>name</p></td>
<td class="parameter_description">
<p>name of the subexpression</p>
<p>Passed as <code class="code">name</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.6"></a><h3>fetch-named-pos</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return start-pos end-pos)
  (match-info:fetch-named-pos self name))
</pre></div>
<p>Retrieves the position in bytes of the capturing parentheses named <em class="parameter"><code>name</code></em>.
</p>
<p>If <em class="parameter"><code>name</code></em> is a valid sub pattern name but it didn't match anything
(e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b")
then <em class="parameter"><code>start_pos</code></em> and <em class="parameter"><code>end_pos</code></em> are set to -1 and <code class="constant">TRUE</code> is returned.</p>
<div class="refsect3">
<a name="id-1.1.41.3.6.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p><span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>name</p></td>
<td class="parameter_description">
<p>name of the subexpression</p>
<p>Passed as <code class="code">name</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>start_pos</p></td>
<td class="parameter_description">
<p>pointer to location where to store
    the start position, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">start-pos</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end_pos</p></td>
<td class="parameter_description">
<p>pointer to location where to store
    the end position, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">end-pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.7"></a><h3>fetch-pos</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return start-pos end-pos)
  (match-info:fetch-pos self match-num))
</pre></div>
<p>Retrieves the position in bytes of the <em class="parameter"><code>match_num</code></em>'th capturing
parentheses. 0 is the full text of the match, 1 is the first
paren set, 2 the second, and so on.
</p>
<p>If <em class="parameter"><code>match_num</code></em> is a valid sub pattern but it didn't match anything
(e.g. sub pattern 1, matching "b" against "(a)?b") then <em class="parameter"><code>start_pos</code></em>
and <em class="parameter"><code>end_pos</code></em> are set to -1 and <code class="constant">TRUE</code> is returned.
</p>
<p>If the match was obtained using the DFA algorithm, that is using
<code class="function">g_regex_match_all()</code> or <code class="function">g_regex_match_all_full()</code>, the retrieved
position is not that of a set of parentheses but that of a matched
substring. Substrings are matched in reverse order of length, so
0 is the longest match.</p>
<div class="refsect3">
<a name="id-1.1.41.3.7.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p><span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>match_num</p></td>
<td class="parameter_description">
<p>number of the sub expression</p>
<p>Passed as <code class="code">match-num</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>start_pos</p></td>
<td class="parameter_description">
<p>pointer to location where to store
    the start position, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">start-pos</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>end_pos</p></td>
<td class="parameter_description">
<p>pointer to location where to store
    the end position, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">end-pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.8"></a><h3>free</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (match-info:free self))
</pre></div>
<p>If <em class="parameter"><code>match_info</code></em> is not <code class="constant">NULL</code>, calls <code class="function">g_match_info_unref()</code>; otherwise does
nothing.</p>
<div class="refsect3">
<a name="id-1.1.41.3.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span>, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.9"></a><h3>get-match-count</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:get-match-count self))
</pre></div>
<p>Retrieves the number of matched substrings (including substring 0,
that is the whole matched text), so 1 is returned if the pattern
has no substrings in it and 0 is returned if the match failed.
</p>
<p>If the last match was obtained using the DFA algorithm, that is
using <code class="function">g_regex_match_all()</code> or <code class="function">g_regex_match_all_full()</code>, the retrieved
count is not that of the number of capturing parentheses but that of
the number of matched substrings.</p>
<div class="refsect3">
<a name="id-1.1.41.3.9.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.10"></a><h3>get-regex</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:get-regex self))
</pre></div>
<p>Returns <span class="type">GRegex</span> object used in <em class="parameter"><code>match_info</code></em>. It belongs to Glib
and must not be freed. Use <code class="function">g_regex_ref()</code> if you need to keep it
after you free <em class="parameter"><code>match_info</code></em> object.</p>
<div class="refsect3">
<a name="id-1.1.41.3.10.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.11"></a><h3>get-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:get-string self))
</pre></div>
<p>Returns the string searched with <em class="parameter"><code>match_info</code></em>. This is the
string passed to <code class="function">g_regex_match()</code> or <code class="function">g_regex_replace()</code> so
you may not free it before calling this function.</p>
<div class="refsect3">
<a name="id-1.1.41.3.11.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.12"></a><h3>is-partial-match?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:is-partial-match? self))
</pre></div>
<p>Usually if the string passed to g_regex_match*() matches as far as
it goes, but is too short to match the entire pattern, <code class="constant">FALSE</code> is
returned. There are circumstances where it might be helpful to
distinguish this case from other cases in which there is no match.
</p>
<p>Consider, for example, an application where a human is required to
type in data for a field with specific formatting requirements. An
example might be a date in the form ddmmmyy, defined by the pattern
"^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
If the application sees the user’s keystrokes one by one, and can
check that what has been typed so far is potentially valid, it is
able to raise an error as soon as a mistake is made.
</p>
<p>GRegex supports the concept of partial matching by means of the
<span class="type">G_REGEX_MATCH_PARTIAL_SOFT</span> and <span class="type">G_REGEX_MATCH_PARTIAL_HARD</span> flags.
When they are used, the return code for
<code class="function">g_regex_match()</code> or <code class="function">g_regex_match_full()</code> is, as usual, <code class="constant">TRUE</code>
for a complete match, <code class="constant">FALSE</code> otherwise. But, when these functions
return <code class="constant">FALSE</code>, you can check if the match was partial calling
<code class="function">g_match_info_is_partial_match()</code>.
</p>
<p>The difference between <span class="type">G_REGEX_MATCH_PARTIAL_SOFT</span> and
<span class="type">G_REGEX_MATCH_PARTIAL_HARD</span> is that when a partial match is encountered
with <span class="type">G_REGEX_MATCH_PARTIAL_SOFT</span>, matching continues to search for a
possible complete match, while with <span class="type">G_REGEX_MATCH_PARTIAL_HARD</span> matching
stops at the partial match.
When both <span class="type">G_REGEX_MATCH_PARTIAL_SOFT</span> and <span class="type">G_REGEX_MATCH_PARTIAL_HARD</span>
are set, the latter takes precedence.
</p>
<p>There were formerly some restrictions on the pattern for partial matching.
The restrictions no longer apply.
</p>
<p>See pcrepartial(3) for more information on partial matching.</p>
<div class="refsect3">
<a name="id-1.1.41.3.12.9"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.13"></a><h3>matches?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:matches? self))
</pre></div>
<p>Returns whether the previous match operation succeeded.</p>
<div class="refsect3">
<a name="id-1.1.41.3.13.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.14"></a><h3>next?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:next? self))
</pre></div>
<p>Scans for the next match using the same parameters of the previous
call to <code class="function">g_regex_match_full()</code> or <code class="function">g_regex_match()</code> that returned
<em class="parameter"><code>match_info</code></em>.
</p>
<p>The match is done on the string passed to the match function, so you
cannot free it before calling this function.</p>
<div class="refsect3">
<a name="id-1.1.41.3.14.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span> structure</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.15"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (match-info:ref self))
</pre></div>
<p>Increases reference count of <em class="parameter"><code>match_info</code></em> by 1.</p>
<div class="refsect3">
<a name="id-1.1.41.3.15.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.41.3.16"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (match-info:unref self))
</pre></div>
<p>Decreases reference count of <em class="parameter"><code>match_info</code></em> by 1. When reference count drops
to zero, it frees all the memory associated with the match_info structure.</p>
<div class="refsect3">
<a name="id-1.1.41.3.16.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>match_info</p></td>
<td class="parameter_description">
<p>a <span class="type">GMatchInfo</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>