Glob-style pattern matching
3
GLIB Library

# Glob-style pattern matching

matches strings against patterns containing '*' (wildcard) and '?' (joker).

## Synopsis

    #include <glib.h>

                        GPatternSpec;
    GPatternSpec*       g_pattern_spec_new                  (const gchar *pattern);
    void                g_pattern_spec_free                 (GPatternSpec *pspec);
    gboolean            g_pattern_spec_equal                (GPatternSpec *pspec1,
                                                             GPatternSpec *pspec2);
    gboolean            g_pattern_match                     (GPatternSpec *pspec,
                                                             guint string_length,
                                                             const gchar *string,
                                                             const gchar *string_reversed);
    gboolean            g_pattern_match_string              (GPatternSpec *pspec,
                                                             const gchar *string);
    gboolean            g_pattern_match_simple              (const gchar *pattern,
                                                             const gchar *string);

## Description

The `g_pattern_match*` 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.

Note that in contrast to `glob()`, the '/' character can be matched by the wildcards, there are no '[...]' character ranges and '*' and '?' can not be escaped to include them literally in a pattern.

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.

## Details

### GPatternSpec

    typedef struct _GPatternSpec GPatternSpec;

A GPatternSpec is the 'compiled' form of a pattern. This structure is opaque and its fields cannot be accessed directly.

### g_pattern_spec_new ()

    GPatternSpec*       g_pattern_spec_new                  (const gchar *pattern);

Compiles a pattern to a GPatternSpec.

`pattern` :

  a zero-terminated UTF-8 encoded string.

Returns :

  a newly-allocated GPatternSpec.

### g_pattern_spec_free ()

    void                g_pattern_spec_free                 (GPatternSpec *pspec);

Frees the memory allocated for the GPatternSpec.

`pspec` :

  a GPatternSpec.

### g_pattern_spec_equal ()

    gboolean            g_pattern_spec_equal                (GPatternSpec *pspec1,
                                                             GPatternSpec *pspec2);

Compares two compiled pattern specs and returns whether they will match the same set of strings.

`pspec1` :

  a GPatternSpec.

`pspec2` :

  another GPatternSpec.

Returns :

  Whether the compiled patterns are equal.

### g_pattern_match ()

    gboolean            g_pattern_match                     (GPatternSpec *pspec,
                                                             guint string_length,
                                                             const gchar *string,
                                                             const gchar *string_reversed);

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.

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()`.

Note also that the reverse of a UTF-8 encoded string can in general not be obtained by `g_strreverse()`. This works only if the string doesn't contain any multibyte characters. Glib offers the `g_utf_strreverse()` function to reverse UTF-8 encoded strings.

`pspec` :

  a GPatternSpec.

`string_length` :

  the length of `string`.

`string` :

  the UTF-8 encoded string to match.

`string_reversed` :

  the reverse of `string` or `NULL`.

Returns :

  `TRUE` if `string` matches `pspec`.

### g_pattern_match_string ()

    gboolean            g_pattern_match_string              (GPatternSpec *pspec,
                                                             const gchar *string);

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.

`pspec` :

  a GPatternSpec.

`string` :

  the UTF-8 encoded string to match.

Returns :

  `TRUE` if `string` matches `pspec`.

### g_pattern_match_simple ()

    gboolean            g_pattern_match_simple              (const gchar *pattern,
                                                             const gchar *string);

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()` repetively.

`pattern` :

  the UTF-8 encoded pattern.

`string` :

  the UTF-8 encoded string to match.

Returns :

  `TRUE` if `string` matches `pspec`.