Glob-style pattern matching

## Glob-style pattern matching 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_utf8_strreverse()` function to reverse UTF-8 encoded strings.

`pspec` : | a GPatternSpec
`string_length` : | the length of `string` (in bytes, i.e. `strlen()`, not `g_utf8_strlen()`)
`string` : | the UTF-8 encoded string to match
`string_reversed` : | the reverse of `string` or `NULL`. [allow-none]
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()` repeatedly.

`pattern` : | the UTF-8 encoded pattern
`string` : | the UTF-8 encoded string to match
Returns : | `TRUE` if `string` matches `pspec`