mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 03:16:17 +01:00
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.
This commit is contained in:
Matthias Clasen
parent
7c2ae36588
commit
803bae66a3
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
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,
|
||||
|
||||
@ -1,3 +1,9 @@
|
||||
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 < @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 ##### -->
|
||||
|
||||
@ -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 < @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)
|
||||
@ -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 < @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,
|
||||
|
||||
@ -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)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user