## Glob-style pattern matching

Glob-style pattern matching — matches strings against patterns containing '*' (wildcard) and '?' (joker)

## Functions

GPatternSpec * | g_pattern_spec_new ()
void | g_pattern_spec_free ()
gboolean | g_pattern_spec_equal ()
gboolean | g_pattern_match ()
gboolean | g_pattern_match_string ()
gboolean | g_pattern_match_simple ()

## Types and Values

| GPatternSpec

## Includes

    #include <glib.h>

## 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.

## Functions

### g_pattern_spec_new ()

    GPatternSpec *
    g_pattern_spec_new (const gchar *pattern);

Compiles a pattern to a GPatternSpec.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 does not contain any multibyte characters. GLib offers the `g_utf8_strreverse()` function to reverse UTF-8 encoded strings.

#### Parameters

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.

#### Parameters

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.

#### Parameters

pattern | the UTF-8 encoded pattern |
string | the UTF-8 encoded string to match |

#### Returns

`TRUE` if `string` matches `pspec`

## Types and Values

### GPatternSpec

    typedef struct _GPatternSpec GPatternSpec;

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