luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-03 17:56:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

GPattern: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-30 23:10:34 -05:00
parent 84572f81bf
commit c7000fcfec
3 changed files with 104 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -6,6 +6,7 @@ gvarianttype.sgml
hash_tables.sgml
memory_chunks.sgml
option.sgml
patterns.sgml
random_numbers.sgml
sequence.sgml
shell.sgml

124
docs/reference/glib/tmpl/patterns.sgml
View File

@ -1,124 +0,0 @@
<!-- ##### SECTION Title ##### -->
Glob-style pattern matching
<!-- ##### SECTION Short_Description ##### -->
matches strings against patterns containing '*' (wildcard) and '?' (joker)
<!-- ##### SECTION Long_Description ##### -->
<para>
The <function>g_pattern_match*</function> 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.
</para>
<para>
Note that in contrast to glob(), the '/' character <emphasis>can</emphasis>
be matched by the wildcards, there are no '[...]' character ranges and '*'
and '?' can <emphasis>not</emphasis> be escaped to include them literally
in a pattern.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GPatternSpec ##### -->
<para>
A <structname>GPatternSpec</structname> is the 'compiled' form of a pattern.
This structure is opaque and its fields cannot be accessed directly.
</para>
<!-- ##### FUNCTION g_pattern_spec_new ##### -->
<para>
Compiles a pattern to a #GPatternSpec.
</para>
@pattern: a zero-terminated UTF-8 encoded string
@Returns: a newly-allocated #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_free ##### -->
<para>
Frees the memory allocated for the #GPatternSpec.
</para>
@pspec: a #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_equal ##### -->
<para>
Compares two compiled pattern specs and returns whether they
will match the same set of strings.
</para>
@pspec1: a #GPatternSpec
@pspec2: another #GPatternSpec
@Returns: Whether the compiled patterns are equal
<!-- ##### FUNCTION g_pattern_match ##### -->
<para>
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.
</para>
<para>
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().
</para>
<para>
Note also that the reverse of a UTF-8 encoded string can in general
<emphasis>not</emphasis> 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.
</para>
@pspec: a #GPatternSpec
@string_length: the length of @string (in bytes, i.e. strlen(),
<emphasis>not</emphasis> 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
<!-- ##### FUNCTION g_pattern_match_string ##### -->
<para>
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.
</para>
@pspec: a #GPatternSpec
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec
<!-- ##### FUNCTION g_pattern_match_simple ##### -->
<para>
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.
</para>
@pattern: the UTF-8 encoded pattern
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec

103
glib/gpattern.c
View File

@ -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 <function>g_pattern_match*</function> 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
* <emphasis>can</emphasis> be matched by the wildcards, there are no
* '[...]' character ranges and '*' and '?' can
* <emphasis>not</emphasis> 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 <structname>GPatternSpec</structname> 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(),
* <emphasis>not</emphasis> 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
* <emphasis>not</emphasis> 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)