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

docs/reference/ChangeLog

@@ -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)
 

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.
 </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>
-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>
 
 <!-- ##### 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.
+@pattern: a zero-terminated UTF-8 encoded string
-@Returns: a newly-allocated #GPatternSpec.
+@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.
+@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 ##### -->
 <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>
-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>
 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>
 
-@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 ##### -->
 <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>
 
-@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 ##### -->
@@ -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.
+@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