<refentry id="glib-Glob-style-pattern-matching">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Glob-style-pattern-matching.top_of_page">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 id="glib-Glob-style-pattern-matching.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <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);
<link linkend="void">void</link>                <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 id="glib-Glob-style-pattern-matching.description" role="desc">
<title role="desc.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 <link linkend="glob"><function>glob()</function></link> function: '*' matches an arbitrary, possibly empty,
string, '?' matches an arbitrary character.
</para>
<para>
Note that in contrast to <link linkend="glob"><function>glob()</function></link>, 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, it is
better to compile the pattern to a <link linkend="GPatternSpec"><type>GPatternSpec</type></link> using <link linkend="g-pattern-spec-new"><function>g_pattern_spec_new()</function></link>
and use <link linkend="g-pattern-match-string"><function>g_pattern_match_string()</function></link> instead of <link linkend="g-pattern-match-simple"><function>g_pattern_match_simple()</function></link>. This
avoids the overhead of repeated pattern compilation.
</para>
</refsect1>

<refsect1 id="glib-Glob-style-pattern-matching.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GPatternSpec" role="struct">
<title>GPatternSpec</title>
<indexterm zone="GPatternSpec"><primary sortas="PatternSpec">GPatternSpec</primary></indexterm><programlisting>typedef struct _GPatternSpec 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 id="g-pattern-spec-new" role="function">
<title>g_pattern_spec_new ()</title>
<indexterm zone="g-pattern-spec-new"><primary sortas="pattern_spec_new">g_pattern_spec_new</primary></indexterm><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"><type>GPatternSpec</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>a zero-terminated UTF-8 encoded string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pattern-spec-free" role="function">
<title>g_pattern_spec_free ()</title>
<indexterm zone="g-pattern-spec-free"><primary sortas="pattern_spec_free">g_pattern_spec_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_pattern_spec_free                 (<link linkend="GPatternSpec">GPatternSpec</link> *pspec);</programlisting>
<para>
Frees the memory allocated for the <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>pspec</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pattern-spec-equal" role="function">
<title>g_pattern_spec_equal ()</title>
<indexterm zone="g-pattern-spec-equal"><primary sortas="pattern_spec_equal">g_pattern_spec_equal</primary></indexterm><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 they
will match the same set of strings.
</para><variablelist role="params">
<varlistentry><term><parameter>pspec1</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec2</parameter>&#160;:</term>
<listitem><simpara>another <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Whether the compiled patterns are equal
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pattern-match" role="function">
<title>g_pattern_match ()</title>
<indexterm zone="g-pattern-match"><primary sortas="pattern_match">g_pattern_match</primary></indexterm><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
the string given is mandatory. The reversed string can be omitted by passing
<link linkend="NULL--CAPS"><literal>NULL</literal></link>, this is more efficient if the reversed version of the string to be
matched is not at hand, as <link linkend="g-pattern-match"><function>g_pattern_match()</function></link> will only construct it if the
compiled pattern requires 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"><function>g_pattern_match()</function></link>.
</para>
<para>
Note also that the reverse of a UTF-8 encoded string can in general
<emphasis>not</emphasis> be obtained by <link linkend="g-strreverse"><function>g_strreverse()</function></link>. This works only
if the string doesn't contain any multibyte characters. GLib offers the
<link linkend="g-utf8-strreverse"><function>g_utf8_strreverse()</function></link> function to reverse UTF-8 encoded strings.
</para><variablelist role="params">
<varlistentry><term><parameter>pspec</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string_length</parameter>&#160;:</term>
<listitem><simpara>the length of <parameter>string</parameter> (in bytes, i.e. <link linkend="strlen"><function>strlen()</function></link>, 
     <emphasis>not</emphasis> <link linkend="g-utf8-strlen"><function>g_utf8_strlen()</function></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the UTF-8 encoded string to match
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string_reversed</parameter>&#160;:</term>
<listitem><simpara>the reverse of <parameter>string</parameter> or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>string</parameter> matches <parameter>pspec</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pattern-match-string" role="function">
<title>g_pattern_match_string ()</title>
<indexterm zone="g-pattern-match-string"><primary sortas="pattern_match_string">g_pattern_match_string</primary></indexterm><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 to be
matched against more than one pattern, consider using <link linkend="g-pattern-match"><function>g_pattern_match()</function></link>
instead while supplying the reversed string.
</para><variablelist role="params">
<varlistentry><term><parameter>pspec</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the UTF-8 encoded string to match
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>string</parameter> matches <parameter>pspec</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-pattern-match-simple" role="function">
<title>g_pattern_match_simple ()</title>
<indexterm zone="g-pattern-match-simple"><primary sortas="pattern_match_simple">g_pattern_match_simple</primary></indexterm><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 compile
the pattern once with <link linkend="g-pattern-spec-new"><function>g_pattern_spec_new()</function></link> and call <link linkend="g-pattern-match-string"><function>g_pattern_match_string()</function></link>
repeatedly.
</para><variablelist role="params">
<varlistentry><term><parameter>pattern</parameter>&#160;:</term>
<listitem><simpara>the UTF-8 encoded pattern
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the UTF-8 encoded string to match
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>string</parameter> matches <parameter>pspec</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
