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

docs on why the deprecated functions are deprecated.

Browse Source 
2001-10-25  Havoc Pennington  <hp@pobox.com>

	* glib/tmpl/string_utils.sgml: docs on why the deprecated
	functions are deprecated.
This commit is contained in:
Havoc Pennington 2001-10-25 14:38:45 +00:00 committed by Havoc Pennington
parent 3c39c8fcd0
commit 0628133a11
2 changed files with 32 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/reference/ChangeLog
View File

@ -1,3 +1,8 @@
2001-10-25 Havoc Pennington <hp@pobox.com>
* glib/tmpl/string_utils.sgml: docs on why the deprecated
functions are deprecated.
2001-10-15 Sven Neumann <sven@gimp.org> 2001-10-15 Sven Neumann <sven@gimp.org>
* glib/tmpl/random_numbers.sgml: fixed typo. * glib/tmpl/random_numbers.sgml: fixed typo.

29
docs/reference/glib/tmpl/string_utils.sgml
View File

@ -509,7 +509,9 @@ possibly non-ASCII character in.
<!-- ##### FUNCTION g_strup ##### --> <!-- ##### FUNCTION g_strup ##### -->
<para> <para>
Converts a string to upper case. Converts a string to upper case. This function is totally broken
for the reasons discussed in the g_strncasecmp() docs -
use g_ascii_strup() or g_utf8_strup() instead.
</para> </para>
@string: the string to convert. @string: the string to convert.
@ -518,7 +520,9 @@ Converts a string to upper case.
<!-- ##### FUNCTION g_strdown ##### --> <!-- ##### FUNCTION g_strdown ##### -->
<para> <para>
Converts a string to lower case. Converts a string to lower case. This function is totally broken for
the reasons discussed in the g_strncasecmp() docs - use
g_ascii_strdown() or g_utf8_strdown() instead.
</para> </para>
@string: the string to convert. @string: the string to convert.
@ -530,6 +534,10 @@ Converts a string to lower case.
A case-insensitive string comparison, corresponding to the standard A case-insensitive string comparison, corresponding to the standard
<function>strcasecmp()</function> function on platforms which support it. <function>strcasecmp()</function> function on platforms which support it.
</para> </para>
<para>
See g_strncasecmp() for a discussion of why this is deprecated and
how to replace it.
</para>
@s1: a string. @s1: a string.
@s2: a string to compare with @s1. @s2: a string to compare with @s1.
@ -544,6 +552,23 @@ A case-insensitive string comparison, corresponding to the standard
It is similar to g_strcasecmp() except it only compares the first @n characters It is similar to g_strcasecmp() except it only compares the first @n characters
of the strings. of the strings.
</para> </para>
<para>
The problem with g_strncasecmp() is that it does the comparison by
calling toupper()/tolower() on each byte. toupper()/tolower() are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an i18n standpoint by operating on
bytes, since characters may be multibyte. Thus g_strncasecmp() is
broken if your string is guaranteed to be ASCII, since it's
locale-sensitive, and it's broken if your string is localized, since
it doesn't work on many encodings at all, including UTF-8, EUC-JP,
etc.
</para>
<para>
There are therefore two replacement functions: g_ascii_strncasecmp(),
which only works on ASCII and is not locale-sensitive, and
g_utf8_casefold(), which is good for case-insensitive sorting of
UTF-8.
</para>
@s1: a string. @s1: a string.
@s2: a string to compare with @s1. @s2: a string to compare with @s1.