docs/reference/glib/tmpl/patterns.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Glob-style pattern matching
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 Matches strings against patterns containing '*' and '?' wildcards.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 The <function>g_pattern_match*</function> match a string against
  11 a pattern containing '*' and '?' wildcards with similar semantics
  12 as the standard <function>glob()</function> function: '*' matches an
  13 arbitrary, possibly empty, string, '?' matches an arbitrary character.
  14 </para>
  15 <para>
  16 There is no way to include literal '*' or '?' characters in a pattern.
  17 </para>
  18 <para>
  19 When multiple string must be matched against the same pattern, it
  20 is better to compile the pattern to a #GPatternSpec using
  21 g_pattern_spec_new() and use g_pattern_match_string() instead of
  22 g_pattern_match_simple().  This avoids the overhead of repeated
  23 pattern compilation.
  24 </para>
  25 <!-- ##### SECTION See_Also ##### -->
  26 <para>
  27
  28 </para>
  29
  30 <!-- ##### ENUM GMatchType ##### -->
  31 <para>
  32 Enumeration representing different kinds of patterns. This is only used
  33 internally for optimizing the match algorithm.
  34 </para>
  35
  36 @G_MATCH_ALL: a general pattern.
  37 @G_MATCH_ALL_TAIL: a general pattern which contains a fixed part matching
  38 the end of the string.
  39 @G_MATCH_HEAD: a pattern matching every string with a certain prefix.
  40 @G_MATCH_TAIL: a pattern matching every string with a certain suffix.
  41 @G_MATCH_EXACT: a pattern matching exactly one string.
  42 @G_MATCH_LAST:
  43
  44 <!-- ##### STRUCT GPatternSpec ##### -->
  45 <para>
  46 A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.
  47 There should be no need to access its fields.
  48 </para>
  49
  50 @match_type: the #GMatchType of the pattern.
  51 @pattern_length: the length of the pattern.
  52 @pattern: the pattern. Note that this may be different from the @pattern
  53 used to construct this <structname>GPatternSpec</structname>.
  54 @pattern_reversed: the reverse of @pattern.
  55
  56 <!-- ##### FUNCTION g_pattern_spec_new ##### -->
  57 <para>
  58 Compiles a pattern to a #GPatternSpec.
  59 </para>
  60
  61 @pattern: a string.
  62 @Returns: a newly-allocated #GPatternSpec.
  63
  64
  65 <!-- ##### FUNCTION g_pattern_spec_free ##### -->
  66 <para>
  67 Frees the memory allocated for the #GPatternSpec.
  68 </para>
  69
  70 @pspec: a #GPatternSpec.
  71
  72
  73 <!-- ##### FUNCTION g_pattern_match ##### -->
  74 <para>
  75 Matches a string against a compiled pattern.
  76 </para>
  77
  78 @pspec: a #GPatternSpec.
  79 @string_length: the length of @string.
  80 @string: the string to match.
  81 @string_reversed: the reverse of @string.
  82 @Returns: %TRUE if @string matches @pspec.
  83
  84
  85 <!-- ##### FUNCTION g_pattern_match_string ##### -->
  86 <para>
  87 Matches a string against a compiled pattern.
  88 </para>
  89
  90 @pspec: a #GPatternSpec.
  91 @string: the string to match.
  92 @Returns: %TRUE if @string matches @pspec.
  93
  94
  95 <!-- ##### FUNCTION g_pattern_match_simple ##### -->
  96 <para>
  97 Matches a string against a pattern.
  98 </para>
  99
 100 @pattern: the pattern.
 101 @string: the string to match.
 102 @Returns: %TRUE if @string matches @pspec.