docs/reference/glib/tmpl/patterns.sgml

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