<refentry id="glib-Glob-style-pattern-matching"><refmeta><refentrytitle>Glob-style pattern matching</refentrytitle><manvolnum>3</manvolnum><refmiscinfo>GLIB Library</refmiscinfo></refmeta><refnamediv><refname>Glob-style pattern matching</refname><refpurpose>matches strings against patterns containing '*' (wildcard) and '?' (joker).</refpurpose></refnamediv><refsynopsisdiv><title>Synopsis</title><synopsis>#include &lt;glib.h&gt;struct      <link linkend="GPatternSpec">GPatternSpec</link>;<link linkend="GPatternSpec">GPatternSpec</link>* <link linkend="g-pattern-spec-new">g_pattern_spec_new</link>            (const <link linkend="gchar">gchar</link> *pattern);void        <link linkend="g-pattern-spec-free">g_pattern_spec_free</link>             (<link linkend="GPatternSpec">GPatternSpec</link> *pspec);<link linkend="gboolean">gboolean</link>    <link linkend="g-pattern-spec-equal">g_pattern_spec_equal</link>            (<link linkend="GPatternSpec">GPatternSpec</link> *pspec1,                                             <link linkend="GPatternSpec">GPatternSpec</link> *pspec2);<link linkend="gboolean">gboolean</link>    <link linkend="g-pattern-match">g_pattern_match</link>                 (<link linkend="GPatternSpec">GPatternSpec</link> *pspec,                                             <link linkend="guint">guint</link> string_length,                                             const <link linkend="gchar">gchar</link> *string,                                             const <link linkend="gchar">gchar</link> *string_reversed);<link linkend="gboolean">gboolean</link>    <link linkend="g-pattern-match-string">g_pattern_match_string</link>          (<link linkend="GPatternSpec">GPatternSpec</link> *pspec,                                             const <link linkend="gchar">gchar</link> *string);<link linkend="gboolean">gboolean</link>    <link linkend="g-pattern-match-simple">g_pattern_match_simple</link>          (const <link linkend="gchar">gchar</link> *pattern,                                             const <link linkend="gchar">gchar</link> *string);</synopsis></refsynopsisdiv><refsect1><title>Description</title><para>The <function>g_pattern_match*</function> functions match a string against a pattern containing '*' and '?' wildcards with similar semantics as the standard <function><link linkend="glob">glob</link>()</function> function: '*' matches anarbitrary, possibly empty, string, '?' matches an arbitrary character.</para><para>Note that in contrast to <function><link linkend="glob">glob</link>()</function>, the '/' character<emphasis>can</emphasis> be matched by the wildcards, there are no'[...]' character ranges and '*' and '?' can <emphasis>not</emphasis>be escaped to include them literally in a pattern. </para><para>When multiple strings must be matched against the same pattern, itis better to compile the pattern to a <link linkend="GPatternSpec">GPatternSpec</link> using <link linkend="g-pattern-spec-new">g_pattern_spec_new</link>() and use <link linkend="g-pattern-match-string">g_pattern_match_string</link>() instead of <link linkend="g-pattern-match-simple">g_pattern_match_simple</link>().  This avoids the overhead of repeated pattern compilation.</para></refsect1><refsect1><title>Details</title><refsect2><title><anchor id="GPatternSpec">struct GPatternSpec</title><programlisting>struct GPatternSpec;</programlisting><para>A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.This structure is opaque and its fields cannot be accessed directly.</para></refsect2><refsect2><title><anchor id="g-pattern-spec-new">g_pattern_spec_new ()</title><programlisting><link linkend="GPatternSpec">GPatternSpec</link>* g_pattern_spec_new            (const <link linkend="gchar">gchar</link> *pattern);</programlisting><para>Compiles a pattern to a <link linkend="GPatternSpec">GPatternSpec</link>.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pattern</parameter>&nbsp;:</entry><entry>a zero-terminated UTF-8 encoded string.</entry></row><row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="g-pattern-spec-free">g_pattern_spec_free ()</title><programlisting>void        g_pattern_spec_free             (<link linkend="GPatternSpec">GPatternSpec</link> *pspec);</programlisting><para>Frees the memory allocated for the <link linkend="GPatternSpec">GPatternSpec</link>.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry><entry>a <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="g-pattern-spec-equal">g_pattern_spec_equal ()</title><programlisting><link linkend="gboolean">gboolean</link>    g_pattern_spec_equal            (<link linkend="GPatternSpec">GPatternSpec</link> *pspec1,                                             <link linkend="GPatternSpec">GPatternSpec</link> *pspec2);</programlisting><para>Compares two compiled pattern specs and returns whether theywill match the same set of strings.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pspec1</parameter>&nbsp;:</entry><entry>a <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row><row><entry align="right"><parameter>pspec2</parameter>&nbsp;:</entry><entry>another <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row><row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>Whether the compiled patterns are equal.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="g-pattern-match">g_pattern_match ()</title><programlisting><link linkend="gboolean">gboolean</link>    g_pattern_match                 (<link linkend="GPatternSpec">GPatternSpec</link> *pspec,                                             <link linkend="guint">guint</link> string_length,                                             const <link linkend="gchar">gchar</link> *string,                                             const <link linkend="gchar">gchar</link> *string_reversed);</programlisting><para>Matches a string against a compiled pattern. Passing the correct length of thestring given is mandatory. The reversed string can be omitted by passing <literal>NULL</literal>,this is more efficient if the reversed version of the string to be matched isnot at hand, as <link linkend="g-pattern-match">g_pattern_match</link>() will only construct it if the compiled patternrequires reverse matches.</para><para>Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that some patterns will require a reversed string. In this case, it's more efficient to provide the reversed string to avoid multiple constructions thereof in the various calls to<link linkend="g-pattern-match">g_pattern_match</link>().</para><para>Note also that the reverse of a UTF-8 encoded string can in general <emphasis>not</emphasis> be obtained by <function><link linkend="g-strreverse">g_strreverse</link>()</function>.This works only if the string doesn't contain any multibyte characters.Glib doesn't currently offer a function to reverse UTF-8 encoded strings.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry><entry>a <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row><row><entry align="right"><parameter>string_length</parameter>&nbsp;:</entry><entry>the length of <parameter>string</parameter>.</entry></row><row><entry align="right"><parameter>string</parameter>&nbsp;:</entry><entry>the UTF-8 encoded string to match.</entry></row><row><entry align="right"><parameter>string_reversed</parameter>&nbsp;:</entry><entry>the reverse of <parameter>string</parameter> or <literal>NULL</literal>.</entry></row><row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="g-pattern-match-string">g_pattern_match_string ()</title><programlisting><link linkend="gboolean">gboolean</link>    g_pattern_match_string          (<link linkend="GPatternSpec">GPatternSpec</link> *pspec,                                             const <link linkend="gchar">gchar</link> *string);</programlisting><para>Matches a string against a compiled pattern. If the string is tobe matched against more than one pattern, consider using<link linkend="g-pattern-match">g_pattern_match</link>() instead while supplying the reversed string.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry><entry>a <link linkend="GPatternSpec">GPatternSpec</link>.</entry></row><row><entry align="right"><parameter>string</parameter>&nbsp;:</entry><entry>the UTF-8 encoded string to match.</entry></row><row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title><anchor id="g-pattern-match-simple">g_pattern_match_simple ()</title><programlisting><link linkend="gboolean">gboolean</link>    g_pattern_match_simple          (const <link linkend="gchar">gchar</link> *pattern,                                             const <link linkend="gchar">gchar</link> *string);</programlisting><para>Matches a string against a pattern given as a string.If this function is to be called in a loop, it's more efficient to compilethe pattern once with <link linkend="g-pattern-spec-new">g_pattern_spec_new</link>() and call <link linkend="g-pattern-match-string">g_pattern_match_string</link>()repetively.</para><informaltable pgwide="1" frame="none" role="params"><tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"><tbody><row><entry align="right"><parameter>pattern</parameter>&nbsp;:</entry><entry>the UTF-8 encoded pattern.</entry></row><row><entry align="right"><parameter>string</parameter>&nbsp;:</entry><entry>the UTF-8 encoded string to match.</entry></row><row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.</entry></row></tbody></tgroup></informaltable></refsect2></refsect1></refentry>