luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-05 00:46:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Matthias Clasen 2007-11-10 02:09:08 +00:00 committed by Matthias Clasen
parent a3c92d9305
commit 1d174f072b
2 changed files with 46 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/ChangeLog
View File

@ -1,5 +1,8 @@
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.
(#491982, Areg Beketovski)

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

@ -12,17 +12,16 @@ 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.
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.
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 ##### -->
@ -45,8 +44,8 @@ This structure is opaque and its fields cannot be accessed directly.
Compiles a pattern to a #GPatternSpec.
</para>
@pattern: a zero-terminated UTF-8 encoded string.
@Returns: a newly-allocated #GPatternSpec.
@pattern: a zero-terminated UTF-8 encoded string
@Returns: a newly-allocated #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_free ##### -->
@ -54,7 +53,7 @@ Compiles a pattern to a #GPatternSpec.
Frees the memory allocated for the #GPatternSpec.
</para>
@pspec: a #GPatternSpec.
@pspec: a #GPatternSpec
<!-- ##### FUNCTION g_pattern_spec_equal ##### -->
@ -63,50 +62,51 @@ 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.
@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.
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().
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.
<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.
@string: the UTF-8 encoded string to match.
@string_reversed: the reverse of @string or %NULL.
@Returns: %TRUE if @string matches @pspec.
@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.
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.
@pspec: a #GPatternSpec
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec
<!-- ##### FUNCTION g_pattern_match_simple ##### -->
@ -114,11 +114,11 @@ g_pattern_match() instead while supplying the reversed 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()
repetively.
repeatedly.
</para>
@pattern: the UTF-8 encoded pattern.
@string: the UTF-8 encoded string to match.
@Returns: %TRUE if @string matches @pspec.
@pattern: the UTF-8 encoded pattern
@string: the UTF-8 encoded string to match
@Returns: %TRUE if @string matches @pspec