| <!-- ##### 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_utf_strreverse() function to reverse UTF-8 encoded strings. |
| </para> |
| |
| @pspec: a #GPatternSpec. |
| @string_length: the length of @string. |
| @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() |
| repetively. |
| </para> |
| |
| @pattern: the UTF-8 encoded pattern. |
| @string: the UTF-8 encoded string to match. |
| @Returns: %TRUE if @string matches @pspec. |
| |
| |