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:
<!-- ##### 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 ##### -->
<!-- ##### 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 < @s2, or a positive
-value if @s1 > @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 < @s2, or a positive
-value if @s1 > @s2.
+@s1:
+@s2:
+@n:
+@Returns:
<!-- ##### FUNCTION g_strreverse ##### -->
<!-- ##### 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 ##### -->
* @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,
* @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,
* 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,
*
* 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)
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)
{
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)
{
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 < @s2,
+ * or a positive value if @s1 > @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)
#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 < @s2,
+ * or a positive value if @s1 > @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,
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)
{
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)
{
* %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>.
**/
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)
{
projects / platform / upstream / glib.git / commitdiff