Commit 1d174f07 authored by Matthias Clasen's avatar Matthias Clasen Committed by Matthias Clasen

Add a warning about strlen vs g_utf8_strlen. (#455725, Michael Rasmussen)

2007-11-09  Matthias Clasen <mclasen@redhat.com>

        * glib/tmpl/patterns.sgml: Add a warning about strlen vs
        g_utf8_strlen.  (#455725, Michael Rasmussen)



svn path=/trunk/; revision=5855
parent a3c92d93
2007-11-09 Matthias Clasen <mclasen@redhat.com> 2007-11-09 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/patterns.sgml: Add a warning about strlen vs
g_utf8_strlen. (#455725, Michael Rasmussen)
* glib/tmpl/date.sgml: Add a footnote explaining leap years. * glib/tmpl/date.sgml: Add a footnote explaining leap years.
(#491982, Areg Beketovski) (#491982, Areg Beketovski)
......
...@@ -12,17 +12,16 @@ as the standard glob() function: '*' matches an arbitrary, possibly empty, ...@@ -12,17 +12,16 @@ as the standard glob() function: '*' matches an arbitrary, possibly empty,
string, '?' matches an arbitrary character. string, '?' matches an arbitrary character.
</para> </para>
<para> <para>
Note that in contrast to glob(), the '/' character Note that in contrast to glob(), the '/' character <emphasis>can</emphasis>
<emphasis>can</emphasis> be matched by the wildcards, there are no be matched by the wildcards, there are no '[...]' character ranges and '*'
'[...]' character ranges and '*' and '?' can <emphasis>not</emphasis> and '?' can <emphasis>not</emphasis> be escaped to include them literally
be escaped to include them literally in a pattern. in a pattern.
</para> </para>
<para> <para>
When multiple strings must be matched against the same pattern, it When multiple strings must be matched against the same pattern, it is
is better to compile the pattern to a #GPatternSpec using better to compile the pattern to a #GPatternSpec using g_pattern_spec_new()
g_pattern_spec_new() and use g_pattern_match_string() instead of and use g_pattern_match_string() instead of g_pattern_match_simple(). This
g_pattern_match_simple(). This avoids the overhead of repeated avoids the overhead of repeated pattern compilation.
pattern compilation.
</para> </para>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
...@@ -45,8 +44,8 @@ This structure is opaque and its fields cannot be accessed directly. ...@@ -45,8 +44,8 @@ This structure is opaque and its fields cannot be accessed directly.
Compiles a pattern to a #GPatternSpec. Compiles a pattern to a #GPatternSpec.
</para> </para>
@pattern: a zero-terminated UTF-8 encoded string. @pattern: a zero-terminated UTF-8 encoded string
@Returns: a newly-allocated #GPatternSpec. @Returns: a newly-allocated #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_free ##### --> <!-- ##### FUNCTION g_pattern_spec_free ##### -->
...@@ -54,7 +53,7 @@ Compiles a pattern to a #GPatternSpec. ...@@ -54,7 +53,7 @@ Compiles a pattern to a #GPatternSpec.
Frees the memory allocated for the #GPatternSpec. Frees the memory allocated for the #GPatternSpec.
</para> </para>
@pspec: a #GPatternSpec. @pspec: a #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_equal ##### --> <!-- ##### FUNCTION g_pattern_spec_equal ##### -->
...@@ -63,50 +62,51 @@ Compares two compiled pattern specs and returns whether they ...@@ -63,50 +62,51 @@ Compares two compiled pattern specs and returns whether they
will match the same set of strings. will match the same set of strings.
</para> </para>
@pspec1: a #GPatternSpec. @pspec1: a #GPatternSpec
@pspec2: another #GPatternSpec. @pspec2: another #GPatternSpec
@Returns: Whether the compiled patterns are equal. @Returns: Whether the compiled patterns are equal
<!-- ##### FUNCTION g_pattern_match ##### --> <!-- ##### FUNCTION g_pattern_match ##### -->
<para> <para>
Matches a string against a compiled pattern. Passing the correct length of the Matches a string against a compiled pattern. Passing the correct length of
string given is mandatory. The reversed string can be omitted by passing %NULL, the string given is mandatory. The reversed string can be omitted by passing
this is more efficient if the reversed version of the string to be matched is %NULL, this is more efficient if the reversed version of the string to be
not at hand, as g_pattern_match() will only construct it if the compiled pattern matched is not at hand, as g_pattern_match() will only construct it if the
requires reverse matches. compiled pattern requires reverse matches.
</para> </para>
<para> <para>
Note that, if the user code will (possibly) match a string against a multitude Note that, if the user code will (possibly) match a string against a
of patterns containing wildcards, chances are high that some patterns will multitude of patterns containing wildcards, chances are high that some
require a reversed string. In this case, it's more efficient to provide the patterns will require a reversed string. In this case, it's more efficient
reversed string to avoid multiple constructions thereof in the various calls to to provide the reversed string to avoid multiple constructions thereof in
g_pattern_match(). the various calls to g_pattern_match().
</para> </para>
<para> <para>
Note also that the reverse of a UTF-8 encoded string can in general Note also that the reverse of a UTF-8 encoded string can in general
<emphasis>not</emphasis> be obtained by g_strreverse(). <emphasis>not</emphasis> be obtained by g_strreverse(). This works only
This works only if the string doesn't contain any multibyte characters. if the string doesn't contain any multibyte characters. GLib offers the
Glib offers the g_utf8_strreverse() function to reverse UTF-8 encoded strings. g_utf8_strreverse() function to reverse UTF-8 encoded strings.
</para> </para>
@pspec: a #GPatternSpec. @pspec: a #GPatternSpec
@string_length: the length of @string. @string_length: the length of @string (in bytes, i.e. strlen(),
@string: the UTF-8 encoded string to match. <emphasis>not</emphasis> g_utf8_strlen())
@string_reversed: the reverse of @string or %NULL. @string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec. @string_reversed: the reverse of @string or %NULL
@Returns: %TRUE if @string matches @pspec
<!-- ##### FUNCTION g_pattern_match_string ##### --> <!-- ##### FUNCTION g_pattern_match_string ##### -->
<para> <para>
Matches a string against a compiled pattern. If the string is to Matches a string against a compiled pattern. If the string is to be
be matched against more than one pattern, consider using matched against more than one pattern, consider using g_pattern_match()
g_pattern_match() instead while supplying the reversed string. instead while supplying the reversed string.
</para> </para>
@pspec: a #GPatternSpec. @pspec: a #GPatternSpec
@string: the UTF-8 encoded string to match. @string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec. @Returns: %TRUE if @string matches @pspec
<!-- ##### FUNCTION g_pattern_match_simple ##### --> <!-- ##### FUNCTION g_pattern_match_simple ##### -->
...@@ -114,11 +114,11 @@ g_pattern_match() instead while supplying the reversed string. ...@@ -114,11 +114,11 @@ g_pattern_match() instead while supplying the reversed string.
Matches a string against a pattern given as a 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 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() the pattern once with g_pattern_spec_new() and call g_pattern_match_string()
repetively. repeatedly.
</para> </para>
@pattern: the UTF-8 encoded pattern. @pattern: the UTF-8 encoded pattern
@string: the UTF-8 encoded string to match. @string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec. @Returns: %TRUE if @string matches @pspec
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment