<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<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>

<refsect1 id="glib-Glob-style-pattern-matching.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GPatternSpec"><returnvalue>GPatternSpec</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-pattern-spec-new">g_pattern_spec_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-pattern-spec-free">g_pattern_spec_free</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-pattern-spec-equal">g_pattern_spec_equal</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-pattern-match">g_pattern_match</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-pattern-match-string">g_pattern_match_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-pattern-match-simple">g_pattern_match_simple</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Glob-style-pattern-matching.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GPatternSpec">GPatternSpec</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Glob-style-pattern-matching.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Glob-style-pattern-matching.description" role="desc">
<title role="desc.title">Description</title>
<para>The g_pattern_match* 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 can be matched by
the wildcards, there are no '[...]' character ranges and '*' and '?'
can not 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.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-pattern-spec-new" role="function">
<title>g_pattern_spec_new&#160;()</title>
<indexterm zone="g-pattern-spec-new"><primary sortas="pattern_spec_new">g_pattern_spec_new</primary></indexterm>
<programlisting language="C"><link linkend="GPatternSpec"><returnvalue>GPatternSpec</returnvalue></link>&#160;*
g_pattern_spec_new (<parameter>const <link linkend="gchar"><type>gchar</type></link> *pattern</parameter>);</programlisting>
<para>Compiles a pattern to a <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.</para>
<refsect3 id="g-pattern-spec-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pattern</para></entry>
<entry role="parameter_description"><para>a zero-terminated UTF-8 encoded string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-pattern-spec-new.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-pattern-spec-free" role="function">
<title>g_pattern_spec_free&#160;()</title>
<indexterm zone="g-pattern-spec-free"><primary sortas="pattern_spec_free">g_pattern_spec_free</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_pattern_spec_free (<parameter><link linkend="GPatternSpec"><type>GPatternSpec</type></link> *pspec</parameter>);</programlisting>
<para>Frees the memory allocated for the <link linkend="GPatternSpec"><type>GPatternSpec</type></link>.</para>
<refsect3 id="g-pattern-spec-free.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pspec</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-pattern-spec-equal" role="function">
<title>g_pattern_spec_equal&#160;()</title>
<indexterm zone="g-pattern-spec-equal"><primary sortas="pattern_spec_equal">g_pattern_spec_equal</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_pattern_spec_equal (<parameter><link linkend="GPatternSpec"><type>GPatternSpec</type></link> *pspec1</parameter>,
                      <parameter><link linkend="GPatternSpec"><type>GPatternSpec</type></link> *pspec2</parameter>);</programlisting>
<para>Compares two compiled pattern specs and returns whether they will
match the same set of strings.</para>
<refsect3 id="g-pattern-spec-equal.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pspec1</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pspec2</para></entry>
<entry role="parameter_description"><para>another <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-pattern-spec-equal.returns" role="returns">
<title>Returns</title>
<para> Whether the compiled patterns are equal</para>
</refsect3></refsect2>
<refsect2 id="g-pattern-match" role="function">
<title>g_pattern_match&#160;()</title>
<indexterm zone="g-pattern-match"><primary sortas="pattern_match">g_pattern_match</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_pattern_match (<parameter><link linkend="GPatternSpec"><type>GPatternSpec</type></link> *pspec</parameter>,
                 <parameter><link linkend="guint"><type>guint</type></link> string_length</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *string_reversed</parameter>);</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
not be obtained by <link linkend="g-strreverse"><function>g_strreverse()</function></link>. This works only if the string
does not 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>
<refsect3 id="g-pattern-match.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pspec</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string_length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>string</parameter>
(in bytes, i.e. <link linkend="strlen"><function>strlen()</function></link>,
not <link linkend="g-utf8-strlen"><function>g_utf8_strlen()</function></link>)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the UTF-8 encoded string to match</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string_reversed</para></entry>
<entry role="parameter_description"><para>the reverse of <parameter>string</parameter>
or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-pattern-match.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>string</parameter>
matches <parameter>pspec</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-pattern-match-string" role="function">
<title>g_pattern_match_string&#160;()</title>
<indexterm zone="g-pattern-match-string"><primary sortas="pattern_match_string">g_pattern_match_string</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_pattern_match_string (<parameter><link linkend="GPatternSpec"><type>GPatternSpec</type></link> *pspec</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>);</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>
<refsect3 id="g-pattern-match-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pspec</para></entry>
<entry role="parameter_description"><para>a <link linkend="GPatternSpec"><type>GPatternSpec</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the UTF-8 encoded string to match</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-pattern-match-string.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>string</parameter>
matches <parameter>pspec</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-pattern-match-simple" role="function">
<title>g_pattern_match_simple&#160;()</title>
<indexterm zone="g-pattern-match-simple"><primary sortas="pattern_match_simple">g_pattern_match_simple</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_pattern_match_simple (<parameter>const <link linkend="gchar"><type>gchar</type></link> *pattern</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>);</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>
<refsect3 id="g-pattern-match-simple.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pattern</para></entry>
<entry role="parameter_description"><para>the UTF-8 encoded pattern</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the UTF-8 encoded string to match</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-pattern-match-simple.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>string</parameter>
matches <parameter>pspec</parameter>
</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="glib-Glob-style-pattern-matching.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GPatternSpec" role="struct">
<title>GPatternSpec</title>
<indexterm zone="GPatternSpec"><primary sortas="PatternSpec">GPatternSpec</primary></indexterm>
<programlisting language="C">typedef struct _GPatternSpec GPatternSpec;</programlisting>
<para>A GPatternSpec struct is the 'compiled' form of a pattern. This
structure is opaque and its fields cannot be accessed directly.</para>
</refsect2>

</refsect1>

</refentry>
