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> functions match a string
  11 against 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 Note that in contrast to <function>glob()</function>, the '/' character
  15 <emphasis>can</emphasis> be matched by the wildcards.
  16 </para>
  17 <para>
  18 There is no way to include literal '*' or '?' characters in a pattern.
  19 </para>
  20 <para>
  21 When multiple string 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 <!-- ##### SECTION See_Also ##### -->
  28 <para>
  29
  30 </para>
  31
  32 <!-- ##### ENUM GMatchType ##### -->
  33 <para>
  34 Enumeration representing different kinds of patterns. This is only used
  35 internally for optimizing the match algorithm.
  36 </para>
  37
  38 @G_MATCH_ALL: a general pattern.
  39 @G_MATCH_ALL_TAIL: a general pattern which contains a fixed part matching
  40 the end of the string.
  41 @G_MATCH_HEAD: a pattern matching every string with a certain prefix.
  42 @G_MATCH_TAIL: a pattern matching every string with a certain suffix.
  43 @G_MATCH_EXACT: a pattern matching exactly one string.
  44 @G_MATCH_LAST:
  45
  46 <!-- ##### STRUCT GPatternSpec ##### -->
  47 <para>
  48 A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.
  49 There should be no need to access its fields.
  50 </para>
  51
  52 @match_type: the #GMatchType of the pattern.
  53 @pattern_length: the length of the pattern.
  54 @pattern: the pattern. Note that this may be different from the @pattern
  55 used to construct this <structname>GPatternSpec</structname>.
  56 @pattern_reversed: the reverse of @pattern.
  57
  58 <!-- ##### FUNCTION g_pattern_spec_new ##### -->
  59 <para>
  60 Compiles a pattern to a #GPatternSpec.
  61 </para>
  62
  63 @pattern: a string.
  64 @Returns: a newly-allocated #GPatternSpec.
  65
  66
  67 <!-- ##### FUNCTION g_pattern_spec_free ##### -->
  68 <para>
  69 Frees the memory allocated for the #GPatternSpec.
  70 </para>
  71
  72 @pspec: a #GPatternSpec.
  73
  74
  75 <!-- ##### FUNCTION g_pattern_match ##### -->
  76 <para>
  77 Matches a string against a compiled pattern.
  78 </para>
  79
  80 @pspec: a #GPatternSpec.
  81 @string_length: the length of @string.
  82 @string: the string to match.
  83 @string_reversed: the reverse of @string.
  84 @Returns: %TRUE if @string matches @pspec.
  85
  86
  87 <!-- ##### FUNCTION g_pattern_match_string ##### -->
  88 <para>
  89 Matches a string against a compiled pattern.
  90 </para>
  91
  92 @pspec: a #GPatternSpec.
  93 @string: the string to match.
  94 @Returns: %TRUE if @string matches @pspec.
  95
  96
  97 <!-- ##### FUNCTION g_pattern_match_simple ##### -->
  98 <para>
  99 Matches a string against a pattern.
 100 </para>
 101
 102 @pattern: the pattern.
 103 @string: the string to match.
 104 @Returns: %TRUE if @string matches @pspec.