Commit 803bae66 authored by Matthias Clasen's avatar Matthias Clasen

Move some docs inline, and add deprecation information. To see the list of

	* glib/gutils.c:
	* glib/gtree.c:
	* glib/gstring.c:
	* glib/gstrfuncs.c:
	* glib/giochannel.c: Move some docs inline, and add deprecation
	information. To see the list of affected functions, grep for
	"Deprecated:".

	* glib/tmpl/strings.sgml:
	* glib/tmpl/string_utils.sgml:
	* glib/tmpl/misc_utils.sgml: Move some docs inline.
parent 7c2ae365
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/gutils.c:
* glib/gtree.c:
* glib/gstring.c:
* glib/gstrfuncs.c:
* glib/giochannel.c: Move some docs inline, and add deprecation
information. To see the list of affected functions, grep for
"Deprecated:".
* configure.in: Fix the definitions around printf: either we use
system printf in which case HAVE_VASPRINTF, HAVE_C99_VSNPRINTF and
HAVE_UNIX98_PRINTF have already been determined by earlier tests,
......
2002-11-28 Matthias Clasen <maclas@gmx.de>
* glib/tmpl/strings.sgml:
* glib/tmpl/string_utils.sgml:
* glib/tmpl/misc_utils.sgml: Move some docs inline.
2002-11-23 Matthias Clasen <maclas@gmx.de>
* gobject/tmpl/gclosure.sgml:
......
......@@ -93,19 +93,10 @@ The returned string should be freed when no longer needed.
<!-- ##### FUNCTION g_basename ##### -->
<para>
This function is deprecated and will be removed in the next major
release of GLib. Use g_path_get_basename() instead.
</para>
<para>
Gets the name of the file without any leading
directory components. It returns a pointer into the given file name
string.
</para>
@file_name: the name of the file.
@Returns: the name of the file without any leading directory components.
@file_name:
@Returns:
<!-- ##### MACRO g_dirname ##### -->
......
......@@ -571,73 +571,37 @@ possibly non-ASCII character in.
<!-- ##### FUNCTION g_strup ##### -->
<para>
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>
@string: the string to convert.
@string:
@Returns:
<!-- ##### FUNCTION g_strdown ##### -->
<para>
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>
@string: the string to convert.
@string:
@Returns:
<!-- ##### FUNCTION g_strcasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strcasecmp()</function> function on platforms which support it.
</para>
<para>
See g_strncasecmp() for a discussion of why this is deprecated and
how to replace it.
</para>
@s1: a string.
@s2: a string to compare with @s1.
@Returns: 0 if the strings match, a negative value if @s1 &lt; @s2, or a positive
value if @s1 &gt; @s2.
@s1:
@s2:
@Returns:
<!-- ##### FUNCTION g_strncasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strncasecmp()</function> function on platforms which support it.
It is similar to g_strcasecmp() except it only compares the first @n characters
of the strings.
</para>
<para>
The problem with g_strncasecmp() is that it does the comparison by
calling <function>toupper()</function>/<function>tolower()</function>
on each byte. <function>toupper()</function>/<function>tolower()</function> 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.
@s2: a string to compare with @s1.
@n: the maximum number of characters to compare.
@Returns: 0 if the strings match, a negative value if @s1 &lt; @s2, or a positive
value if @s1 &gt; @s2.
@s1:
@s2:
@n:
@Returns:
<!-- ##### FUNCTION g_strreverse ##### -->
......
......@@ -313,20 +313,18 @@ If @free_segment is %TRUE it also frees the character data.
<!-- ##### FUNCTION g_string_up ##### -->
<para>
Converts a #GString to upper case.
</para>
@string: a #GString.
@Returns: the #GString.
@string:
@Returns:
<!-- ##### FUNCTION g_string_down ##### -->
<para>
Converts a #GString to lower case.
</para>
@string: a #GString.
@Returns: the #GString.
@string:
@Returns:
<!-- ##### FUNCTION g_string_hash ##### -->
......
......@@ -160,10 +160,11 @@ g_io_error_get_from_g_error (GIOStatus status,
* @count: the number of bytes to read from the #GIOChannel.
* @bytes_read: returns the number of bytes actually read.
*
* Reads data from a #GIOChannel. This function is deprecated. New code should
* use g_io_channel_read_chars() instead.
* Reads data from a #GIOChannel.
*
* Return value: %G_IO_ERROR_NONE if the operation was successful.
*
* Deprecated: Use g_io_channel_read_chars() instead.
**/
GIOError
g_io_channel_read (GIOChannel *channel,
......@@ -195,10 +196,11 @@ g_io_channel_read (GIOChannel *channel,
* @count: the number of bytes to write.
* @bytes_written: the number of bytes actually written.
*
* Writes data to a #GIOChannel. This function is deprecated. New code should
* use g_io_channel_write_chars() instead.
* Writes data to a #GIOChannel.
*
* Return value: %G_IO_ERROR_NONE if the operation was successful.
*
* Deprecated: Use g_io_channel_write_chars() instead.
**/
GIOError
g_io_channel_write (GIOChannel *channel,
......@@ -232,10 +234,11 @@ g_io_channel_write (GIOChannel *channel,
* file).
*
* Sets the current position in the #GIOChannel, similar to the standard library
* function <function>fseek()</function>. This function is deprecated. New
* code should use g_io_channel_seek_position() instead.
* function <function>fseek()</function>.
*
* Return value: %G_IO_ERROR_NONE if the operation was successful.
*
* Deprecated: Use g_io_channel_seek_position() instead.
**/
GIOError
g_io_channel_seek (GIOChannel *channel,
......@@ -296,9 +299,9 @@ g_io_channel_seek (GIOChannel *channel,
*
* Close an IO channel. Any pending data to be written will be
* flushed, ignoring errors. The channel will not be freed until the
* last reference is dropped using g_io_channel_unref(). This
* function is deprecated: you should use g_io_channel_shutdown()
* instead.
* last reference is dropped using g_io_channel_unref().
*
* Deprecated: Use g_io_channel_shutdown() instead.
**/
void
g_io_channel_close (GIOChannel *channel)
......
......@@ -1529,6 +1529,18 @@ g_ascii_strup (const gchar *str,
return result;
}
/**
* g_strdown:
* @string: the string to convert.
*
* Converts a string to lower case.
*
* Return value: the string
*
* Deprecated: This function is totally broken for the reasons discussed in
* the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
* instead.
**/
gchar*
g_strdown (gchar *string)
{
......@@ -1548,6 +1560,17 @@ g_strdown (gchar *string)
return (gchar *) string;
}
/**
* g_strup:
* @string: the string to convert.
*
* Converts a string to upper case.
*
* Return value: the string
*
* Deprecated: This function is totally broken for the reasons discussed in
* the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
**/
gchar*
g_strup (gchar *string)
{
......@@ -1764,6 +1787,20 @@ g_ascii_strncasecmp (const gchar *s1,
return 0;
}
/**
* g_strcasecmp:
* @s1: a string.
* @s2: a string to compare with @s1.
*
* A case-insensitive string comparison, corresponding to the standard
* strcasecmp() function on platforms which support it.
*
* Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
*
* Deprecated: See g_strncasecmp() for a discussion of why this function is
* deprecated and how to replace it.
**/
gint
g_strcasecmp (const gchar *s1,
const gchar *s2)
......@@ -1795,6 +1832,33 @@ g_strcasecmp (const gchar *s1,
#endif
}
/**
* g_strncasecmp:
* @s1: a string.
* @s2: a string to compare with @s1.
* @n: the maximum number of characters to compare.
*
* A case-insensitive string comparison, corresponding to the standard
* strncasecmp() function on platforms which support it.
* It is similar to g_strcasecmp() except it only compares the first @n
* characters of the strings.
*
* Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
* or a positive value if @s1 &gt; @s2.
*
* Deprecated: The problem with g_strncasecmp() is that it does the
* comparison by calling toupper()/tolower(). These functions 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.
* 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.
**/
gint
g_strncasecmp (const gchar *s1,
const gchar *s2,
......
......@@ -669,6 +669,18 @@ g_string_ascii_up (GString *string)
return string;
}
/**
* g_string_down:
* @string: a #GString
*
* Converts a #GString to lowercase.
*
* Returns: the #GString.
*
* Deprecated: This function uses the locale-specific tolower() function,
* which is almost never the right thing. Use g_string_ascii_down() or
* g_utf8_strdown() instead.
*/
GString*
g_string_down (GString *string)
{
......@@ -690,6 +702,18 @@ g_string_down (GString *string)
return string;
}
/**
* g_string_up:
* @string: a #GString
*
* Converts a #GString to uppercase.
*
* Return value: the #GString
*
* Deprecated: This function uses the locale-specific toupper() function,
* which is almost never the right thing. Use g_string_ascii_up() or
* g_utf8_strup() instead.
**/
GString*
g_string_up (GString *string)
{
......
......@@ -471,9 +471,10 @@ g_tree_foreach (GTree *tree,
* %G_PRE_ORDER and %G_POST_ORDER.
* @user_data: user data to pass to the function.
*
* Calls the given function for each node in the #GTree. This function is
* deprecated, since the order of a balanced tree is somewhat arbitrary.
* If you just want to visit all nodes in sorted order, use g_tree_foreach()
* Calls the given function for each node in the #GTree.
*
* Deprecated: The order of a balanced tree is somewhat arbitrary. If you
* just want to visit all nodes in sorted order, use g_tree_foreach()
* instead. If you really need to visit nodes in a different order, consider
* using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
**/
......
......@@ -383,6 +383,17 @@ g_parse_debug_string (const gchar *string,
return result;
}
/**
* g_basename:
* @file_name: the name of the file.
*
* Gets the name of the file without any leading directory components.
* It returns a pointer into the given file name string.
*
* Return value: the name of the file without any leading directory components.
*
* Deprecated: Use g_path_get_basename() instead.
**/
G_CONST_RETURN gchar*
g_basename (const gchar *file_name)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment