From c7000fcfecca109a9f35c8c2e4e56d3a63cf5bd6 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sat, 30 Jan 2010 23:10:34 -0500 Subject: [PATCH] GPattern: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/patterns.sgml | 124 --------------------------------- glib/gpattern.c | 103 +++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 124 deletions(-) delete mode 100644 docs/reference/glib/tmpl/patterns.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index dce5b29..fe832de 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -6,6 +6,7 @@ gvarianttype.sgml hash_tables.sgml memory_chunks.sgml option.sgml +patterns.sgml random_numbers.sgml sequence.sgml shell.sgml diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml deleted file mode 100644 index 8e776c5..0000000 --- a/docs/reference/glib/tmpl/patterns.sgml +++ /dev/null @@ -1,124 +0,0 @@ - -Glob-style pattern matching - - -matches strings against patterns containing '*' (wildcard) and '?' (joker) - - - -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. - - - - - - - - - - - - -A GPatternSpec is the 'compiled' form of a pattern. -This structure is opaque and its fields cannot be accessed directly. - - - - - -Compiles a pattern to a #GPatternSpec. - - -@pattern: a zero-terminated UTF-8 encoded string -@Returns: a newly-allocated #GPatternSpec - - - - -Frees the memory allocated for the #GPatternSpec. - - -@pspec: a #GPatternSpec - - - - -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 - - - - -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 -@Returns: %TRUE if @string matches @pspec - - - - -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 - - - - -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 - - diff --git a/glib/gpattern.c b/glib/gpattern.c index 938083e..33e4aac 100644 --- a/glib/gpattern.c +++ b/glib/gpattern.c @@ -30,6 +30,38 @@ #include "gutils.h" #include "galias.h" +/** + * SECTION: patterns + * @title: Glob-style pattern matching + * @short_description: matches strings against patterns containing '*' + * (wildcard) and '?' (joker) + * + * 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. + **/ + +/** + * GPatternSpec: + * + * A GPatternSpec is the 'compiled' form of a + * pattern. This structure is opaque and its fields cannot be accessed + * directly. + **/ + /* keep enum and structure of gpattern.c and patterntest.c in sync */ typedef enum { @@ -130,6 +162,34 @@ g_pattern_ph_match (const gchar *match_pattern, return *string == 0; } +/** + * g_pattern_match: + * @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 + * @Returns: %TRUE if @string matches @pspec + * + * 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. + **/ gboolean g_pattern_match (GPatternSpec *pspec, guint string_length, @@ -183,6 +243,13 @@ g_pattern_match (GPatternSpec *pspec, } } +/** + * g_pattern_spec_new: + * @pattern: a zero-terminated UTF-8 encoded string + * @Returns: a newly-allocated #GPatternSpec + * + * Compiles a pattern to a #GPatternSpec. + **/ GPatternSpec* g_pattern_spec_new (const gchar *pattern) { @@ -291,6 +358,12 @@ g_pattern_spec_new (const gchar *pattern) return pspec; } +/** + * g_pattern_spec_free: + * @pspec: a #GPatternSpec + * + * Frees the memory allocated for the #GPatternSpec. + **/ void g_pattern_spec_free (GPatternSpec *pspec) { @@ -300,6 +373,15 @@ g_pattern_spec_free (GPatternSpec *pspec) g_free (pspec); } +/** + * g_pattern_spec_equal: + * @pspec1: a #GPatternSpec + * @pspec2: another #GPatternSpec + * @Returns: Whether the compiled patterns are equal + * + * Compares two compiled pattern specs and returns whether they will + * match the same set of strings. + **/ gboolean g_pattern_spec_equal (GPatternSpec *pspec1, GPatternSpec *pspec2) @@ -312,6 +394,16 @@ g_pattern_spec_equal (GPatternSpec *pspec1, strcmp (pspec1->pattern, pspec2->pattern) == 0); } +/** + * g_pattern_match_string: + * @pspec: a #GPatternSpec + * @string: the UTF-8 encoded string to match + * @Returns: %TRUE if @string matches @pspec + * + * 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. + **/ gboolean g_pattern_match_string (GPatternSpec *pspec, const gchar *string) @@ -322,6 +414,17 @@ g_pattern_match_string (GPatternSpec *pspec, return g_pattern_match (pspec, strlen (string), string, NULL); } +/** + * g_pattern_match_simple: + * @pattern: the UTF-8 encoded pattern + * @string: the UTF-8 encoded string to match + * @Returns: %TRUE if @string matches @pspec + * + * 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. + **/ gboolean g_pattern_match_simple (const gchar *pattern, const gchar *string) -- 2.7.4