<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 <glib.h>
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);
<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>
<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"><function>glob()</function></link></function> function: '*' matches an
arbitrary, possibly empty, string, '?' matches an arbitrary character.
</para>
<para>
Note that in contrast to <function><link linkend="glob"><function>glob()</function></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, 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>
<title>Details</title>
<refsect2>
<title><anchor id="GPatternSpec"/>struct GPatternSpec</title>
<indexterm><primary>GPatternSpec</primary></indexterm><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>
<indexterm><primary>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> :</term>
<listitem><simpara>a zero-terminated UTF-8 encoded string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pattern-spec-free"/>g_pattern_spec_free ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pattern-spec-equal"/>g_pattern_spec_equal ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pspec2</parameter> :</term>
<listitem><simpara>another <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>Whether the compiled patterns are equal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pattern-match"/>g_pattern_match ()</title>
<indexterm><primary>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 <literal>NULL</literal>,
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 <function><link linkend="g-strreverse"><function>g_strreverse()</function></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><variablelist role="params">
<varlistentry><term><parameter>pspec</parameter> :</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string_length</parameter> :</term>
<listitem><simpara>the length of <parameter>string</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the UTF-8 encoded string to match.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string_reversed</parameter> :</term>
<listitem><simpara>the reverse of <parameter>string</parameter> or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pattern-match-string"/>g_pattern_match_string ()</title>
<indexterm><primary>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> :</term>
<listitem><simpara>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the UTF-8 encoded string to match.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-pattern-match-simple"/>g_pattern_match_simple ()</title>
<indexterm><primary>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>
repetively.
</para><variablelist role="params">
<varlistentry><term><parameter>pattern</parameter> :</term>
<listitem><simpara>the UTF-8 encoded pattern.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the UTF-8 encoded string to match.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>string</parameter> matches <parameter>pspec</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>