patterns.sgml

this is a glib for c language

<!-- ##### SECTION Title ##### -->
Glob-style pattern matching

<!-- ##### SECTION Short_Description ##### -->
matches strings against patterns containing '*' (wildcard) and '?' (joker)

<!-- ##### SECTION Long_Description ##### -->
<para>
The <function>g_pattern_match*</function> functions match a string 
against a pattern containing '*' and '?' wildcards with similar semantics 
as the standard glob() function: '*' matches an arbitrary, possibly empty, 
string, '?' matches an arbitrary character.
</para>
<para>
Note that in contrast to glob(), 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 #GPatternSpec using g_pattern_spec_new() 
and use g_pattern_match_string() instead of g_pattern_match_simple(). This 
avoids the overhead of repeated pattern compilation.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GPatternSpec ##### -->
<para>
A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.
This structure is opaque and its fields cannot be accessed directly.
</para>


<!-- ##### FUNCTION g_pattern_spec_new ##### -->
<para>
Compiles a pattern to a #GPatternSpec.
</para>

@pattern: a zero-terminated UTF-8 encoded string
@Returns: a newly-allocated #GPatternSpec


<!-- ##### FUNCTION g_pattern_spec_free ##### -->
<para>
Frees the memory allocated for the #GPatternSpec.
</para>

@pspec: a #GPatternSpec


<!-- ##### FUNCTION g_pattern_spec_equal ##### -->
<para>
Compares two compiled pattern specs and returns whether they
will match the same set of strings.
</para>

@pspec1: a #GPatternSpec
@pspec2: another #GPatternSpec
@Returns: Whether the compiled patterns are equal


<!-- ##### FUNCTION g_pattern_match ##### -->
<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 
%NULL, this is more efficient if the reversed version of the string to be 
matched is not at hand, as g_pattern_match() 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 g_pattern_match().
</para>
<para>
Note also that the reverse of a UTF-8 encoded string can in general 
<emphasis>not</emphasis> be obtained by g_strreverse(). This works only 
if the string doesn't contain any multibyte characters. GLib offers the 
g_utf8_strreverse() function to reverse UTF-8 encoded strings.
</para>

@pspec: a #GPatternSpec
@string_length: the length of @string (in bytes, i.e. strlen(), 
     <emphasis>not</emphasis> g_utf8_strlen())
@string: the UTF-8 encoded string to match
@string_reversed: the reverse of @string or %NULL
@Returns: %TRUE if @string matches @pspec


<!-- ##### FUNCTION g_pattern_match_string ##### -->
<para>
Matches a string against a compiled pattern. If the string is to be 
matched against more than one pattern, consider using g_pattern_match() 
instead while supplying the reversed string.
</para>

@pspec: a #GPatternSpec
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec


<!-- ##### FUNCTION g_pattern_match_simple ##### -->
<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 g_pattern_spec_new() and call g_pattern_match_string()
repeatedly.
</para>

@pattern: the UTF-8 encoded pattern
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec