docs/reference/glib/html/glib-Glob-style-pattern-matching.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Glob-style pattern matching</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-Commandline-option-parser.html" title="Commandline option parser">
  10 <link rel="next" href="glib-Perl-compatible-regular-expressions.html" title="Perl-compatible regular expressions">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="chapter" href="glib.html" title="GLib Overview">
  14 <link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
  15 <link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
  16 <link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
  17 <link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
  18 <link rel="chapter" href="tools.html" title="GLib Tools">
  19 <link rel="index" href="api-index-full.html" title="Index">
  20 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  21 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  22 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  23 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  24 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  25 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  26 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  27 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  28 <link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
  29 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  30 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  31 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  32 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  33 </head>
  34 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  35 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  36 <tr valign="middle">
  37 <td><a accesskey="p" href="glib-Commandline-option-parser.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  38 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  39 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  40 <th width="100%" align="center">GLib Reference Manual</th>
  41 <td><a accesskey="n" href="glib-Perl-compatible-regular-expressions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  42 </tr>
  43 <tr><td colspan="5" class="shortcuts">
  44 <a href="#glib-Glob-style-pattern-matching.synopsis" class="shortcut">Top</a>
  45                    |
  46                   <a href="#glib-Glob-style-pattern-matching.description" class="shortcut">Description</a>
  47 </td></tr>
  48 </table>
  49 <div class="refentry" title="Glob-style pattern matching">
  50 <a name="glib-Glob-style-pattern-matching"></a><div class="titlepage"></div>
  51 <div class="refnamediv"><table width="100%"><tr>
  52 <td valign="top">
  53 <h2><span class="refentrytitle"><a name="glib-Glob-style-pattern-matching.top_of_page"></a>Glob-style pattern matching</span></h2>
  54 <p>Glob-style pattern matching — matches strings against patterns containing '*'
  55                     (wildcard) and '?' (joker)</p>
  56 </td>
  57 <td valign="top" align="right"></td>
  58 </tr></table></div>
  59 <div class="refsynopsisdiv" title="Synopsis">
  60 <a name="glib-Glob-style-pattern-matching.synopsis"></a><h2>Synopsis</h2>
  61 <pre class="synopsis">
  62 #include &lt;glib.h&gt;
  63
  64                     <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec">GPatternSpec</a>;
  65 <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a>*       <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-spec-new" title="g_pattern_spec_new ()">g_pattern_spec_new</a>                  (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *pattern);
  66 <span class="returnvalue">void</span>                <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-spec-free" title="g_pattern_spec_free ()">g_pattern_spec_free</a>                 (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec);
  67 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-spec-equal" title="g_pattern_spec_equal ()">g_pattern_spec_equal</a>                (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec1,
  68                                                          <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec2);
  69 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match" title="g_pattern_match ()">g_pattern_match</a>                     (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec,
  70                                                          <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a> string_length,
  71                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string,
  72                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string_reversed);
  73 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match-string" title="g_pattern_match_string ()">g_pattern_match_string</a>              (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec,
  74                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);
  75 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match-simple" title="g_pattern_match_simple ()">g_pattern_match_simple</a>              (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *pattern,
  76                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);
  77 </pre>
  78 </div>
  79 <div class="refsect1" title="Description">
  80 <a name="glib-Glob-style-pattern-matching.description"></a><h2>Description</h2>
  81 <p>
  82 The <code class="function">g_pattern_match*</code> functions match a string
  83 against a pattern containing '*' and '?' wildcards with similar
  84 semantics as the standard <code class="function">glob()</code> function: '*' matches an arbitrary,
  85 possibly empty, string, '?' matches an arbitrary character.
  86 </p>
  87 <p>
  88 Note that in contrast to <code class="function">glob()</code>, the '/' character
  89 <span class="emphasis"><em>can</em></span> be matched by the wildcards, there are no
  90 '[...]' character ranges and '*' and '?' can
  91 <span class="emphasis"><em>not</em></span> be escaped to include them literally in a
  92 pattern.
  93 </p>
  94 <p>
  95 When multiple strings must be matched against the same pattern, it
  96 is better to compile the pattern to a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a> using
  97 <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-spec-new" title="g_pattern_spec_new ()"><code class="function">g_pattern_spec_new()</code></a> and use <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match-string" title="g_pattern_match_string ()"><code class="function">g_pattern_match_string()</code></a> instead of
  98 <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match-simple" title="g_pattern_match_simple ()"><code class="function">g_pattern_match_simple()</code></a>. This avoids the overhead of repeated
  99 pattern compilation.</p>
 100 </div>
 101 <div class="refsect1" title="Details">
 102 <a name="glib-Glob-style-pattern-matching.details"></a><h2>Details</h2>
 103 <div class="refsect2" title="GPatternSpec">
 104 <a name="GPatternSpec"></a><h3>GPatternSpec</h3>
 105 <pre class="programlisting">typedef struct _GPatternSpec GPatternSpec;</pre>
 106 <p>
 107 A <span class="structname">GPatternSpec</span> is the 'compiled' form of a
 108 pattern. This structure is opaque and its fields cannot be accessed
 109 directly.</p>
 110 </div>
 111 <hr>
 112 <div class="refsect2" title="g_pattern_spec_new ()">
 113 <a name="g-pattern-spec-new"></a><h3>g_pattern_spec_new ()</h3>
 114 <pre class="programlisting"><a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a>*       g_pattern_spec_new                  (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *pattern);</pre>
 115 <p>
 116 Compiles a pattern to a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>.</p>
 117 <div class="variablelist"><table border="0">
 118 <col align="left" valign="top">
 119 <tbody>
 120 <tr>
 121 <td><p><span class="term"><em class="parameter"><code>pattern</code></em> :</span></p></td>
 122 <td> a zero-terminated UTF-8 encoded string
 123 </td>
 124 </tr>
 125 <tr>
 126 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 127 <td> a newly-allocated <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 128 </td>
 129 </tr>
 130 </tbody>
 131 </table></div>
 132 </div>
 133 <hr>
 134 <div class="refsect2" title="g_pattern_spec_free ()">
 135 <a name="g-pattern-spec-free"></a><h3>g_pattern_spec_free ()</h3>
 136 <pre class="programlisting"><span class="returnvalue">void</span>                g_pattern_spec_free                 (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec);</pre>
 137 <p>
 138 Frees the memory allocated for the <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>.</p>
 139 <div class="variablelist"><table border="0">
 140 <col align="left" valign="top">
 141 <tbody><tr>
 142 <td><p><span class="term"><em class="parameter"><code>pspec</code></em> :</span></p></td>
 143 <td> a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 144 </td>
 145 </tr></tbody>
 146 </table></div>
 147 </div>
 148 <hr>
 149 <div class="refsect2" title="g_pattern_spec_equal ()">
 150 <a name="g-pattern-spec-equal"></a><h3>g_pattern_spec_equal ()</h3>
 151 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_pattern_spec_equal                (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec1,
 152                                                          <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec2);</pre>
 153 <p>
 154 Compares two compiled pattern specs and returns whether they will
 155 match the same set of strings.</p>
 156 <div class="variablelist"><table border="0">
 157 <col align="left" valign="top">
 158 <tbody>
 159 <tr>
 160 <td><p><span class="term"><em class="parameter"><code>pspec1</code></em> :</span></p></td>
 161 <td> a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 162 </td>
 163 </tr>
 164 <tr>
 165 <td><p><span class="term"><em class="parameter"><code>pspec2</code></em> :</span></p></td>
 166 <td> another <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 167 </td>
 168 </tr>
 169 <tr>
 170 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 171 <td> Whether the compiled patterns are equal
 172 </td>
 173 </tr>
 174 </tbody>
 175 </table></div>
 176 </div>
 177 <hr>
 178 <div class="refsect2" title="g_pattern_match ()">
 179 <a name="g-pattern-match"></a><h3>g_pattern_match ()</h3>
 180 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_pattern_match                     (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec,
 181                                                          <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a> string_length,
 182                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string,
 183                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string_reversed);</pre>
 184 <p>
 185 Matches a string against a compiled pattern. Passing the correct
 186 length of the string given is mandatory. The reversed string can be
 187 omitted by passing <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, this is more efficient if the reversed
 188 version of the string to be matched is not at hand, as
 189 <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match" title="g_pattern_match ()"><code class="function">g_pattern_match()</code></a> will only construct it if the compiled pattern
 190 requires reverse matches.
 191 </p>
 192 <p>
 193 Note that, if the user code will (possibly) match a string against a
 194 multitude of patterns containing wildcards, chances are high that
 195 some patterns will require a reversed string. In this case, it's
 196 more efficient to provide the reversed string to avoid multiple
 197 constructions thereof in the various calls to <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match" title="g_pattern_match ()"><code class="function">g_pattern_match()</code></a>.
 198 </p>
 199 <p>
 200 Note also that the reverse of a UTF-8 encoded string can in general
 201 <span class="emphasis"><em>not</em></span> be obtained by <a class="link" href="glib-String-Utility-Functions.html#g-strreverse" title="g_strreverse ()"><code class="function">g_strreverse()</code></a>. This works
 202 only if the string doesn't contain any multibyte characters. GLib
 203 offers the <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strreverse" title="g_utf8_strreverse ()"><code class="function">g_utf8_strreverse()</code></a> function to reverse UTF-8 encoded
 204 strings.</p>
 205 <div class="variablelist"><table border="0">
 206 <col align="left" valign="top">
 207 <tbody>
 208 <tr>
 209 <td><p><span class="term"><em class="parameter"><code>pspec</code></em> :</span></p></td>
 210 <td> a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 211 </td>
 212 </tr>
 213 <tr>
 214 <td><p><span class="term"><em class="parameter"><code>string_length</code></em> :</span></p></td>
 215 <td> the length of <em class="parameter"><code>string</code></em> (in bytes, i.e. <code class="function">strlen()</code>,
 216                 <span class="emphasis"><em>not</em></span> <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strlen" title="g_utf8_strlen ()"><code class="function">g_utf8_strlen()</code></a>)
 217 </td>
 218 </tr>
 219 <tr>
 220 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 221 <td> the UTF-8 encoded string to match
 222 </td>
 223 </tr>
 224 <tr>
 225 <td><p><span class="term"><em class="parameter"><code>string_reversed</code></em> :</span></p></td>
 226 <td> the reverse of <em class="parameter"><code>string</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 227 </td>
 228 </tr>
 229 <tr>
 230 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 231 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>string</code></em> matches <em class="parameter"><code>pspec</code></em>
 232 </td>
 233 </tr>
 234 </tbody>
 235 </table></div>
 236 </div>
 237 <hr>
 238 <div class="refsect2" title="g_pattern_match_string ()">
 239 <a name="g-pattern-match-string"></a><h3>g_pattern_match_string ()</h3>
 240 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_pattern_match_string              (<a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="returnvalue">GPatternSpec</span></a> *pspec,
 241                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);</pre>
 242 <p>
 243 Matches a string against a compiled pattern. If the string is to be
 244 matched against more than one pattern, consider using
 245 <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match" title="g_pattern_match ()"><code class="function">g_pattern_match()</code></a> instead while supplying the reversed string.</p>
 246 <div class="variablelist"><table border="0">
 247 <col align="left" valign="top">
 248 <tbody>
 249 <tr>
 250 <td><p><span class="term"><em class="parameter"><code>pspec</code></em> :</span></p></td>
 251 <td> a <a class="link" href="glib-Glob-style-pattern-matching.html#GPatternSpec" title="GPatternSpec"><span class="type">GPatternSpec</span></a>
 252 </td>
 253 </tr>
 254 <tr>
 255 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 256 <td> the UTF-8 encoded string to match
 257 </td>
 258 </tr>
 259 <tr>
 260 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 261 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>string</code></em> matches <em class="parameter"><code>pspec</code></em>
 262 </td>
 263 </tr>
 264 </tbody>
 265 </table></div>
 266 </div>
 267 <hr>
 268 <div class="refsect2" title="g_pattern_match_simple ()">
 269 <a name="g-pattern-match-simple"></a><h3>g_pattern_match_simple ()</h3>
 270 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_pattern_match_simple              (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *pattern,
 271                                                          const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *string);</pre>
 272 <p>
 273 Matches a string against a pattern given as a string. If this
 274 function is to be called in a loop, it's more efficient to compile
 275 the pattern once with <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-spec-new" title="g_pattern_spec_new ()"><code class="function">g_pattern_spec_new()</code></a> and call
 276 <a class="link" href="glib-Glob-style-pattern-matching.html#g-pattern-match-string" title="g_pattern_match_string ()"><code class="function">g_pattern_match_string()</code></a> repeatedly.</p>
 277 <div class="variablelist"><table border="0">
 278 <col align="left" valign="top">
 279 <tbody>
 280 <tr>
 281 <td><p><span class="term"><em class="parameter"><code>pattern</code></em> :</span></p></td>
 282 <td> the UTF-8 encoded pattern
 283 </td>
 284 </tr>
 285 <tr>
 286 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 287 <td> the UTF-8 encoded string to match
 288 </td>
 289 </tr>
 290 <tr>
 291 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 292 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>string</code></em> matches <em class="parameter"><code>pspec</code></em>
 293 </td>
 294 </tr>
 295 </tbody>
 296 </table></div>
 297 </div>
 298 </div>
 299 </div>
 300 <div class="footer">
 301 <hr>
 302           Generated by GTK-Doc V1.13</div>
 303 </body>
 304 </html>