From 1d174f072bfacee4cefd9308b3ed95030a0e04bc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 10 Nov 2007 02:09:08 +0000 Subject: [PATCH] Add a warning about strlen vs g_utf8_strlen. (#455725, Michael Rasmussen) 2007-11-09 Matthias Clasen * glib/tmpl/patterns.sgml: Add a warning about strlen vs g_utf8_strlen. (#455725, Michael Rasmussen) svn path=/trunk/; revision=5855 --- docs/reference/ChangeLog | 3 ++ docs/reference/glib/tmpl/patterns.sgml | 86 +++++++++++++++++----------------- 2 files changed, 46 insertions(+), 43 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index f2ba34f..cf4685d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,8 @@ 2007-11-09 Matthias Clasen + * 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) diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml index b520bf5..8e776c5 100644 --- a/docs/reference/glib/tmpl/patterns.sgml +++ b/docs/reference/glib/tmpl/patterns.sgml @@ -12,17 +12,16 @@ 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. +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. +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. @@ -45,8 +44,8 @@ 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. +@pattern: a zero-terminated UTF-8 encoded string +@Returns: a newly-allocated #GPatternSpec @@ -54,7 +53,7 @@ Compiles a pattern to a #GPatternSpec. Frees the memory allocated for the #GPatternSpec. -@pspec: a #GPatternSpec. +@pspec: a #GPatternSpec @@ -63,50 +62,51 @@ 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. +@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. +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 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. +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. -@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(), + 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. +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. +@pspec: a #GPatternSpec +@string: the UTF-8 encoded string to match +@Returns: %TRUE if @string matches @pspec @@ -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. -@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 -- 2.7.4