Glob-style pattern matching

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

Functions

Types and Values

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.

[nullable]

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.