1<!-- ##### SECTION Title ##### --> 2Glob-style pattern matching 3 4<!-- ##### SECTION Short_Description ##### --> 5matches strings against patterns containing '*' (wildcard) and '?' (joker) 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9The <function>g_pattern_match*</function> functions match a string 10against a pattern containing '*' and '?' wildcards with similar semantics 11as the standard glob() function: '*' matches an arbitrary, possibly empty, 12string, '?' matches an arbitrary character. 13</para> 14<para> 15Note that in contrast to glob(), the '/' character <emphasis>can</emphasis> 16be matched by the wildcards, there are no '[...]' character ranges and '*' 17and '?' can <emphasis>not</emphasis> be escaped to include them literally 18in a pattern. 19</para> 20<para> 21When multiple strings must be matched against the same pattern, it is 22better to compile the pattern to a #GPatternSpec using g_pattern_spec_new() 23and use g_pattern_match_string() instead of g_pattern_match_simple(). This 24avoids the overhead of repeated pattern compilation. 25</para> 26 27<!-- ##### SECTION See_Also ##### --> 28<para> 29 30</para> 31 32<!-- ##### SECTION Stability_Level ##### --> 33 34 35<!-- ##### STRUCT GPatternSpec ##### --> 36<para> 37A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern. 38This structure is opaque and its fields cannot be accessed directly. 39</para> 40 41 42<!-- ##### FUNCTION g_pattern_spec_new ##### --> 43<para> 44Compiles a pattern to a #GPatternSpec. 45</para> 46 47@pattern: a zero-terminated UTF-8 encoded string 48@Returns: a newly-allocated #GPatternSpec 49 50 51<!-- ##### FUNCTION g_pattern_spec_free ##### --> 52<para> 53Frees the memory allocated for the #GPatternSpec. 54</para> 55 56@pspec: a #GPatternSpec 57 58 59<!-- ##### FUNCTION g_pattern_spec_equal ##### --> 60<para> 61Compares two compiled pattern specs and returns whether they 62will match the same set of strings. 63</para> 64 65@pspec1: a #GPatternSpec 66@pspec2: another #GPatternSpec 67@Returns: Whether the compiled patterns are equal 68 69 70<!-- ##### FUNCTION g_pattern_match ##### --> 71<para> 72Matches a string against a compiled pattern. Passing the correct length of 73the string given is mandatory. The reversed string can be omitted by passing 74%NULL, this is more efficient if the reversed version of the string to be 75matched is not at hand, as g_pattern_match() will only construct it if the 76compiled pattern requires reverse matches. 77</para> 78<para> 79Note that, if the user code will (possibly) match a string against a 80multitude of patterns containing wildcards, chances are high that some 81patterns will require a reversed string. In this case, it's more efficient 82to provide the reversed string to avoid multiple constructions thereof in 83the various calls to g_pattern_match(). 84</para> 85<para> 86Note also that the reverse of a UTF-8 encoded string can in general 87<emphasis>not</emphasis> be obtained by g_strreverse(). This works only 88if the string doesn't contain any multibyte characters. GLib offers the 89g_utf8_strreverse() function to reverse UTF-8 encoded strings. 90</para> 91 92@pspec: a #GPatternSpec 93@string_length: the length of @string (in bytes, i.e. strlen(), 94 <emphasis>not</emphasis> g_utf8_strlen()) 95@string: the UTF-8 encoded string to match 96@string_reversed: the reverse of @string or %NULL 97@Returns: %TRUE if @string matches @pspec 98 99 100<!-- ##### FUNCTION g_pattern_match_string ##### --> 101<para> 102Matches a string against a compiled pattern. If the string is to be 103matched against more than one pattern, consider using g_pattern_match() 104instead while supplying the reversed string. 105</para> 106 107@pspec: a #GPatternSpec 108@string: the UTF-8 encoded string to match 109@Returns: %TRUE if @string matches @pspec 110 111 112<!-- ##### FUNCTION g_pattern_match_simple ##### --> 113<para> 114Matches a string against a pattern given as a string. 115If this function is to be called in a loop, it's more efficient to compile 116the pattern once with g_pattern_spec_new() and call g_pattern_match_string() 117repeatedly. 118</para> 119 120@pattern: the UTF-8 encoded pattern 121@string: the UTF-8 encoded string to match 122@Returns: %TRUE if @string matches @pspec 123 124 125