| <!-- ##### 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 |
| |
| |