patterns.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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 an
arbitrary, 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, it
is 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 they
will 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 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">g_pattern_match</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">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 to
be 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 compile
the 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>