Add warning to doc comment that these functions should not be used on

2005-09-16  Tor Lillqvist  <tml@novell.com>

	* glib/gstrfuncs.c (g_ascii_strcasecmp, g_ascii_strncasecmp): Add
	warning to doc comment that these functions should not be used on
	encodings like CP932.

diff --git a/ChangeLog b/ChangeLog
index fe23d0c..bf439e4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-09-16  Tor Lillqvist  <tml@novell.com>
+
+       * glib/gstrfuncs.c (g_ascii_strcasecmp, g_ascii_strncasecmp): Add
+       warning to doc comment that these functions should not be used on
+       encodings like CP932.
+
 2005-09-14  Matthias Clasen  <mclasen@redhat.com>
 
        * tests/keyfile-test.c: Add a test for grup names of length 1.

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index fe23d0c..bf439e4 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,9 @@
+2005-09-16  Tor Lillqvist  <tml@novell.com>
+
+       * glib/gstrfuncs.c (g_ascii_strcasecmp, g_ascii_strncasecmp): Add
+       warning to doc comment that these functions should not be used on
+       encodings like CP932.
+
 2005-09-14  Matthias Clasen  <mclasen@redhat.com>
 
        * tests/keyfile-test.c: Add a test for grup names of length 1.

diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index fe23d0c..bf439e4 100644 (file)
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,3 +1,9 @@
+2005-09-16  Tor Lillqvist  <tml@novell.com>
+
+       * glib/gstrfuncs.c (g_ascii_strcasecmp, g_ascii_strncasecmp): Add
+       warning to doc comment that these functions should not be used on
+       encodings like CP932.
+
 2005-09-14  Matthias Clasen  <mclasen@redhat.com>
 
        * tests/keyfile-test.c: Add a test for grup names of length 1.

diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 3574f97..321c110 100644 (file)
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -1735,8 +1735,16 @@ g_ascii_xdigit_value (gchar c)
  *
  * Unlike the BSD strcasecmp() function, this only recognizes standard
  * ASCII letters and ignores the locale, treating all non-ASCII
- * characters as if they are not letters.
- * 
+ * bytes as if they are not letters.
+ *
+ * This function should be used only on strings that are known to be
+ * in encodings where the bytes corresponding to ASCII letters always
+ * represent themselves. This includes UTF-8 and the ISO-8859-*
+ * charsets, but not for instance double-byte encodings like the
+ * Windows Codepage 932, where the trailing bytes of double-byte
+ * characters include all ASCII letters. If you compare two CP932
+ * strings using this function, you will get false matches.
+ *
  * Return value: an integer less than, equal to, or greater than
  *               zero if @s1 is found, respectively, to be less than,
  *               to match, or to be greater than @s2.
@@ -1775,6 +1783,10 @@ g_ascii_strcasecmp (const gchar *s1,
  * ASCII letters and ignores the locale, treating all non-ASCII
  * characters as if they are not letters.
  * 
+ * The same warning as in g_ascii_strcasecmp() applies: Use this
+ * function only on strings known to be in encodings where bytes
+ * corresponding to ASCII letters always represent themselves.
+ *
  * Return value: an integer less than, equal to, or greater than zero
  *               if the first @n bytes of @s1 is found, respectively,
  *               to be less than, to match, or to be greater than the