luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 07:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: don't use the type tag

Browse Source 
Just avoid explicit docbook markup.
This commit is contained in:
Matthias Clasen 2014-01-31 05:58:17 -05:00
parent 3d42934b71
commit fc04275a00
8 changed files with 203 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
gio/gcredentials.c
View File

@ -53,21 +53,19 @@
* #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
* g_unix_connection_receive_credentials() for details.
*
* On Linux, the native credential type is a <type>struct ucred</type>
* - see the
* <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
* man page for details. This corresponds to
* On Linux, the native credential type is a struct ucred - see the
* unix(7) man page for details. This corresponds to
* %G_CREDENTIALS_TYPE_LINUX_UCRED.
*
* On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
* credential type is a <type>struct cmsgcred</type>. This corresponds
* credential type is a struct cmsgcred. This corresponds
* to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
*
* On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
* On OpenBSD, the native credential type is a struct sockpeercred.
* This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
*
* On Solaris (including OpenSolaris and its derivatives), the native
* credential type is a <type>ucred_t</type>. This corresponds to
* credential type is a ucred_t. This corresponds to
* %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
*/

4
gio/ginetsocketaddress.c
View File

@ -44,8 +44,8 @@
/**
* GInetSocketAddress:
*
* An IPv4 or IPv6 socket address, corresponding to a <type>struct
* sockaddr_in</type> or <type>struct sockaddr_in6</type>.
* An IPv4 or IPv6 socket address, corresponding to a struct
* sockaddr_in or struct sockaddr_in6.
*/
struct _GInetSocketAddressPrivate

38
gio/gsocketaddress.c
View File

@ -47,16 +47,15 @@
* for socket communication
* @include: gio/gio.h
*
* #GSocketAddress is the equivalent of <type>struct sockaddr</type>
* in the BSD sockets API. This is an abstract class; use
* #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
* for UNIX domain sockets.
* #GSocketAddress is the equivalent of struct sockaddr in the BSD
* sockets API. This is an abstract class; use #GInetSocketAddress
* for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
*/
/**
* GSocketAddress:
*
* A socket endpoint address, corresponding to <type>struct sockaddr</type>
* A socket endpoint address, corresponding to struct sockaddr
* or one of its subtypes.
*/
@ -80,7 +79,7 @@ G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GSocketAddress, g_socket_address, G_TYPE_OBJEC
*
* Gets the socket family type of @address.
*
* Returns: the socket family type of @address.
* Returns: the socket family type of @address
*
* Since: 2.22
*/
@ -143,11 +142,11 @@ g_socket_address_init (GSocketAddress *address)
* g_socket_address_get_native_size:
* @address: a #GSocketAddress
*
* Gets the size of @address's native <type>struct sockaddr</type>.
* Gets the size of @address's native struct sockaddr.
* You can use this to allocate memory to pass to
* g_socket_address_to_native().
*
* Returns: the size of the native <type>struct sockaddr</type> that
* Returns: the size of the native struct sockaddr that
* @address represents
*
* Since: 2.22
@ -164,17 +163,16 @@ g_socket_address_get_native_size (GSocketAddress *address)
* g_socket_address_to_native:
* @address: a #GSocketAddress
* @dest: a pointer to a memory location that will contain the native
* <type>struct sockaddr</type>.
* struct sockaddr
* @destlen: the size of @dest. Must be at least as large as
* g_socket_address_get_native_size().
* @error: #GError for error reporting, or %NULL to ignore.
* g_socket_address_get_native_size()
* @error: #GError for error reporting, or %NULL to ignore
*
* Converts a #GSocketAddress to a native <type>struct
* sockaddr</type>, which can be passed to low-level functions like
* connect() or bind().
* Converts a #GSocketAddress to a native struct sockaddr, which can
* be passed to low-level functions like connect() or bind().
*
* If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
* returned. If the address type is not known on the system
* If not enough space is available, a %G_IO_ERROR_NO_SPACE error
* is returned. If the address type is not known on the system
* then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
*
* Returns: %TRUE if @dest was filled in, %FALSE on error
@ -194,14 +192,14 @@ g_socket_address_to_native (GSocketAddress *address,
/**
* g_socket_address_new_from_native:
* @native: a pointer to a <type>struct sockaddr</type>
* @native: a pointer to a struct sockaddr
* @len: the size of the memory location pointed to by @native
*
* Creates a #GSocketAddress subclass corresponding to the native
* <type>struct sockaddr</type> @native.
* struct sockaddr @native.
*
* Returns: a new #GSocketAddress if @native could successfully be converted,
* otherwise %NULL.
* Returns: a new #GSocketAddress if @native could successfully
* be converted, otherwise %NULL
*
* Since: 2.22
*/

2
gio/gunixsocketaddress.c
View File

@ -55,7 +55,7 @@
* GUnixSocketAddress:
*
* A UNIX-domain (local) socket address, corresponding to a
* <type>struct sockaddr_un</type>.
* struct sockaddr_un.
*/
enum

46
glib/docs.c
View File

@ -64,8 +64,7 @@
* gpointer:
*
* An untyped pointer.
* #gpointer looks better and is easier to use
* than <type>void*</type>.
* #gpointer looks better and is easier to use than void*.
*/
/**
@ -81,19 +80,19 @@
/**
* gchar:
*
* Corresponds to the standard C <type>char</type> type.
* Corresponds to the standard C char type.
*/
/**
* guchar:
*
* Corresponds to the standard C <type>unsigned char</type> type.
* Corresponds to the standard C unsigned char type.
*/
/**
* gint:
*
* Corresponds to the standard C <type>int</type> type.
* Corresponds to the standard C int type.
* Values of this type can range from #G_MININT to #G_MAXINT.
*/
@ -112,7 +111,7 @@
/**
* guint:
*
* Corresponds to the standard C <type>unsigned int</type> type.
* Corresponds to the standard C unsigned int type.
* Values of this type can range from 0 to #G_MAXUINT.
*/
@ -125,7 +124,7 @@
/**
* gshort:
*
* Corresponds to the standard C <type>short</type> type.
* Corresponds to the standard C short type.
* Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
*/
@ -144,7 +143,7 @@
/**
* gushort:
*
* Corresponds to the standard C <type>unsigned short</type> type.
* Corresponds to the standard C unsigned short type.
* Values of this type can range from 0 to #G_MAXUSHORT.
*/
@ -157,7 +156,7 @@
/**
* glong:
*
* Corresponds to the standard C <type>long</type> type.
* Corresponds to the standard C long type.
* Values of this type can range from #G_MINLONG to #G_MAXLONG.
*/
@ -176,7 +175,7 @@
/**
* gulong:
*
* Corresponds to the standard C <type>unsigned long</type> type.
* Corresponds to the standard C unsigned long type.
* Values of this type can range from 0 to #G_MAXULONG.
*/
@ -491,7 +490,7 @@
/**
* gfloat:
*
* Corresponds to the standard C <type>float</type> type.
* Corresponds to the standard C float type.
* Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
*/
@ -513,7 +512,7 @@
/**
* gdouble:
*
* Corresponds to the standard C <type>double</type> type.
* Corresponds to the standard C double type.
* Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
*/
@ -536,7 +535,7 @@
* gsize:
*
* An unsigned integer type of the result of the sizeof operator,
* corresponding to the <type>size_t</type> type defined in C99.
* corresponding to the size_t type defined in C99.
* This type is wide enough to hold the numeric value of a pointer,
* so it is usually 32bit wide on a 32bit platform and 64bit wide
* on a 64bit platform. Values of this type can range from 0 to
@ -577,7 +576,7 @@
* gssize:
*
* A signed variant of #gsize, corresponding to the
* <type>ssize_t</type> defined on most platforms.
* ssize_t defined on most platforms.
* Values of this type can range from #G_MINSSIZE
* to #G_MAXSSIZE.
*
@ -614,7 +613,7 @@
* goffset:
*
* A signed integer type that is used for file offsets,
* corresponding to the C99 type <type>off64_t</type>.
* corresponding to the C99 type off64_t.
* Values of this type can range from #G_MINOFFSET to
* #G_MAXOFFSET.
*
@ -670,7 +669,7 @@
/**
* gintptr:
*
* Corresponds to the C99 type <type>intptr_t</type>,
* Corresponds to the C99 type intptr_t,
* a signed integer type that can hold any pointer.
*
* To print or scan values of this type, use
@ -701,7 +700,7 @@
/**
* guintptr:
*
* Corresponds to the C99 type <type>uintptr_t</type>,
* Corresponds to the C99 type uintptr_t,
* an unsigned integer type that can hold any pointer.
*
* To print or scan values of this type, use
@ -1772,15 +1771,14 @@
/**
* G_VA_COPY:
* @ap1: the <type>va_list</type> variable to place a copy of @ap2 in
* @ap2: a <type>va_list</type>
* @ap1: the va_list variable to place a copy of @ap2 in
* @ap2: a va_list
*
* Portable way to copy <type>va_list</type> variables.
* Portable way to copy va_list variables.
*
* In order to use this function, you must include
* <filename>string.h</filename> yourself, because this macro may
* use memmove() and GLib does not include <filename>string.h</filename>
* for you.
* In order to use this function, you must include string.h yourself,
* because this macro may use memmove() and GLib does not include
* string.h for you.
*/
/**

2
glib/gdate.c
View File

@ -1281,7 +1281,7 @@ g_date_set_parse (GDate *d,
/**
* g_date_set_time_t:
* @date: a #GDate
* @timet: <type>time_t</type> value to set
* @timet: time_t value to set
*
* Sets the value of a date to the date corresponding to a time
* specified as a time_t. The time to date conversion is done using

66
glib/gstrfuncs.c
View File

@ -99,9 +99,9 @@
* Unlike the standard C library isalnum() function, this only
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphanumeric character
*/
@ -115,9 +115,9 @@
* Unlike the standard C library isalpha() function, this only
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphabetic character
*/
@ -131,9 +131,9 @@
* Unlike the standard C library iscntrl() function, this only
* recognizes standard ASCII control characters and ignores the
* locale, returning %FALSE for all non-ASCII characters. Also,
* unlike the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
* unlike the standard library function, this takes a char, not
* an int, so don't call it on %EOF, but no need to cast to #guchar
* before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII control character.
*/
@ -145,9 +145,8 @@
* Determines whether a character is digit (0-9).
*
* Unlike the standard C library isdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
* on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
* non-ASCII character in.
* a char, not an int, so don't call it on %EOF, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII digit.
*/
@ -161,9 +160,9 @@
* Unlike the standard C library isgraph() function, this only
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character other than space.
*/
@ -177,10 +176,9 @@
* Unlike the standard C library islower() function, this only
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to worry about casting to #guchar before passing a possibly
* non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to worry about casting
* to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII lower case letter
*/
@ -194,9 +192,9 @@
* Unlike the standard C library isprint() function, this only
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character.
*/
@ -210,9 +208,9 @@
* Unlike the standard C library ispunct() function, this only
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII punctuation character.
*/
@ -226,9 +224,9 @@
* Unlike the standard C library isspace() function, this only
* recognizes standard ASCII white-space and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to cast to #guchar before
* passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII white-space character
*/
@ -242,10 +240,9 @@
* Unlike the standard C library isupper() function, this only
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
* not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* worry about casting to #guchar before passing a possibly non-ASCII
* character in.
* the standard library function, this takes a char, not an int,
* so don't call it on %EOF, but no need to worry about casting
* to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII upper case letter
*/
@ -257,9 +254,8 @@
* Determines whether a character is a hexadecimal-digit character.
*
* Unlike the standard C library isxdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
* on <literal>EOF</literal>, but no need to cast to #guchar before passing a
* possibly non-ASCII character in.
* a char, not an int, so don't call it on %EOF, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
*/

259
glib/gutf8.c
View File

@ -139,7 +139,7 @@ const gchar * const g_utf8_skip = utf8_skip_data;
* it starts with an appropriate byte.
*
* Return value: a pointer to the found character or %NULL.
**/
*/
gchar *
g_utf8_find_prev_char (const char *str,
const char *p)
@ -156,7 +156,7 @@ g_utf8_find_prev_char (const char *str,
* g_utf8_find_next_char:
* @p: a pointer to a position within a UTF-8 encoded string
* @end: a pointer to the byte following the end of the string,
* or %NULL to indicate that the string is nul-terminated.
* or %NULL to indicate that the string is nul-terminated
*
* Finds the start of the next UTF-8 character in the string after @p.
*
@ -165,7 +165,7 @@ g_utf8_find_prev_char (const char *str,
* it starts with an appropriate byte.
*
* Return value: a pointer to the found character or %NULL
**/
*/
gchar *
g_utf8_find_next_char (const gchar *p,
const gchar *end)
@ -193,8 +193,8 @@ g_utf8_find_next_char (const gchar *p,
* it starts with an appropriate byte. If @p might be the first
* character of the string, you must use g_utf8_find_prev_char() instead.
*
* Return value: a pointer to the found character.
**/
* Return value: a pointer to the found character
*/
gchar *
g_utf8_prev_char (const gchar *p)
{
@ -205,7 +205,7 @@ g_utf8_prev_char (const gchar *p)
return (gchar *)p;
}
}
/**
* g_utf8_strlen:
* @p: pointer to the start of a UTF-8 encoded string
@ -220,7 +220,7 @@ g_utf8_prev_char (const gchar *p)
* middle of a character, the last (partial) character is not counted.
*
* Return value: the length of the string in characters
**/
*/
glong
g_utf8_strlen (const gchar *p,
gssize max)
@ -267,8 +267,7 @@ g_utf8_strlen (const gchar *p,
* @end_pos: another character offset within @str
*
* Copies a substring out of a UTF-8 encoded string.
* The substring will contain @end_pos - @start_pos
* characters.
* The substring will contain @end_pos - @start_pos characters.
*
* Returns: a newly allocated copy of the requested
* substring. Free with g_free() when no longer needed.
@ -297,13 +296,14 @@ g_utf8_substring (const gchar *str,
* @p: a pointer to Unicode character encoded as UTF-8
*
* Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
* If @p does not point to a valid UTF-8 encoded character, results are
* undefined. If you are not sure that the bytes are complete
*
* If @p does not point to a valid UTF-8 encoded character, results
* are undefined. If you are not sure that the bytes are complete
* valid Unicode characters, you should use g_utf8_get_char_validated()
* instead.
*
* Return value: the resulting character
**/
*/
gunichar
g_utf8_get_char (const gchar *p)
{
@ -332,17 +332,14 @@ g_utf8_get_char (const gchar *p)
* instead of forwards if @offset is in the last fourth of the string,
* since moving forward is about 3 times faster than moving backward.
*
* <note><para>
* This function doesn't abort when reaching the end of @str. Therefore
* you should be sure that @offset is within string boundaries before
* calling that function. Call g_utf8_strlen() when unsure.
*
* Note that this function doesn't abort when reaching the end of @str.
* Therefore you should be sure that @offset is within string boundaries
* before calling that function. Call g_utf8_strlen() when unsure.
* This limitation exists as this function is called frequently during
* text rendering and therefore has to be as fast as possible.
* </para></note>
*
* Return value: the resulting pointer
**/
*/
gchar *
g_utf8_offset_to_pointer (const gchar *str,
glong offset)
@ -386,7 +383,7 @@ g_utf8_offset_to_pointer (const gchar *str,
* a negative offset in this case.
*
* Return value: the resulting character offset
**/
*/
glong
g_utf8_pointer_to_offset (const gchar *str,
const gchar *pos)
@ -413,14 +410,13 @@ g_utf8_pointer_to_offset (const gchar *str,
* @src: UTF-8 encoded string
* @n: character count
*
* Like the standard C strncpy() function, but
* copies a given number of characters instead of a given number of
* bytes. The @src string must be valid UTF-8 encoded text.
* (Use g_utf8_validate() on all text before trying to use UTF-8
* utility functions with it.)
* Like the standard C strncpy() function, but copies a given number
* of characters instead of a given number of bytes. The @src string
* must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
* text before trying to use UTF-8 utility functions with it.)
*
* Return value: @dest
**/
*/
gchar *
g_utf8_strncpy (gchar *dest,
const gchar *src,
@ -449,7 +445,7 @@ g_utf8_strncpy (gchar *dest,
* Converts a single character to UTF-8.
*
* Return value: number of bytes written
**/
*/
int
g_unichar_to_utf8 (gunichar c,
gchar *outbuf)
@ -514,9 +510,9 @@ g_unichar_to_utf8 (gunichar c,
* If @len is -1, allow unbounded search.
*
* Return value: %NULL if the string does not contain the character,
* otherwise, a pointer to the start of the leftmost occurrence of
* the character in the string.
**/
* otherwise, a pointer to the start of the leftmost occurrence
* of the character in the string.
*/
gchar *
g_utf8_strchr (const char *p,
gssize len,
@ -542,9 +538,9 @@ g_utf8_strchr (const char *p,
* If @len is -1, allow unbounded search.
*
* Return value: %NULL if the string does not contain the character,
* otherwise, a pointer to the start of the rightmost occurrence of the
* character in the string.
**/
* otherwise, a pointer to the start of the rightmost occurrence
* of the character in the string.
*/
gchar *
g_utf8_strrchr (const char *p,
gssize len,
@ -651,7 +647,7 @@ g_utf8_get_char_extended (const gchar *p,
* g_utf8_get_char_validated:
* @p: a pointer to Unicode character encoded as UTF-8
* @max_len: the maximum number of bytes to read, or -1, for no maximum or
* if @p is nul-terminated
* if @p is nul-terminated
*
* Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
* This function checks for incomplete characters, for invalid characters
@ -659,14 +655,14 @@ g_utf8_get_char_extended (const gchar *p,
* overlong encodings of valid characters.
*
* Return value: the resulting character. If @p points to a partial
* sequence at the end of a string that could begin a valid
* character (or if @max_len is zero), returns (gunichar)-2;
* otherwise, if @p does not point to a valid UTF-8 encoded
* Unicode character, returns (gunichar)-1.
**/
* sequence at the end of a string that could begin a valid
* character (or if @max_len is zero), returns (gunichar)-2;
* otherwise, if @p does not point to a valid UTF-8 encoded
* Unicode character, returns (gunichar)-1.
*/
gunichar
g_utf8_get_char_validated (const gchar *p,
gssize max_len)
g_utf8_get_char_validated (const gchar *p,
gssize max_len)
{
gunichar result;
@ -687,9 +683,9 @@ g_utf8_get_char_validated (const gchar *p,
* g_utf8_to_ucs4_fast:
* @str: a UTF-8 encoded string
* @len: the maximum length of @str to use, in bytes. If @len < 0,
* then the string is nul-terminated.
* @items_written: (allow-none): location to store the number of characters in the
* result, or %NULL.
* then the string is nul-terminated.
* @items_written: (allow-none): location to store the number of
* characters in the result, or %NULL.
*
* Convert a string from UTF-8 to a 32-bit fixed width
* representation as UCS-4, assuming valid UTF-8 input.
@ -698,8 +694,8 @@ g_utf8_get_char_validated (const gchar *p,
* will be added to the string after the converted text.
*
* Return value: a pointer to a newly allocated UCS-4 string.
* This value must be freed with g_free().
**/
* This value must be freed with g_free().
*/
gunichar *
g_utf8_to_ucs4_fast (const gchar *str,
glong len,
@ -750,7 +746,8 @@ g_utf8_to_ucs4_fast (const gchar *str,
/* It's an out-of-sequence 10xxxxxxx byte.
* Rather than making an ugly hash of this and the next byte
* and overrunning the buffer, it's more useful to treat it
* with a replacement character */
* with a replacement character
*/
result[i] = 0xfffd;
continue;
}
@ -790,28 +787,27 @@ try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error)
* g_utf8_to_ucs4:
* @str: a UTF-8 encoded string
* @len: the maximum length of @str to use, in bytes. If @len < 0,
* then the string is nul-terminated.
* then the string is nul-terminated.
* @items_read: (allow-none): location to store number of bytes read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @items_written: (allow-none): location to store number of characters written or %NULL.
* The value here stored does not include the trailing 0
* character.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @items_written: (allow-none): location to store number of characters
* written or %NULL. The value here stored does not include the
* trailing 0 character.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
*
* Convert a string from UTF-8 to a 32-bit fixed width
* representation as UCS-4. A trailing 0 character will be added to the
* string after the converted text.
*
* Return value: a pointer to a newly allocated UCS-4 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set.
**/
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set.
*/
gunichar *
g_utf8_to_ucs4 (const gchar *str,
glong len,
@ -876,11 +872,12 @@ g_utf8_to_ucs4 (const gchar *str,
* g_ucs4_to_utf8:
* @str: a UCS-4 encoded string
* @len: the maximum length (number of characters) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of characters read, or %NULL.
* @items_written: (allow-none): location to store number of bytes written or %NULL.
* The value here stored does not include the trailing 0
* byte.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of characters
* read, or %NULL.
* @items_written: (allow-none): location to store number of bytes
* written or %NULL. The value here stored does not include the
* trailing 0 byte.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
@ -889,12 +886,10 @@ g_utf8_to_ucs4 (const gchar *str,
* to UTF-8. The result will be terminated with a 0 byte.
*
* Return value: a pointer to a newly allocated UTF-8 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set. In that case, @items_read will be
* set to the position of the first invalid input
* character.
**/
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set. In that case, @items_read
* will be set to the position of the first invalid input character.
*/
gchar *
g_ucs4_to_utf8 (const gunichar *str,
glong len,
@ -950,19 +945,17 @@ g_ucs4_to_utf8 (const gunichar *str,
/**
* g_utf16_to_utf8:
* @str: a UTF-16 encoded string
* @len: the maximum length (number of <type>gunichar2</type>) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of words read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @items_written: (allow-none): location to store number of bytes written, or %NULL.
* The value stored here does not include the trailing
* 0 byte.
* @len: the maximum length (number of #gunichar2) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of words read,
* or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial character. If
* an error occurs then the index of the invalid input is stored here.
* @items_written: (allow-none): location to store number of bytes written,
* or %NULL. The value stored here does not include the trailing 0 byte.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
*
* Convert a string from UTF-16 to UTF-8. The result will be
* terminated with a 0 byte.
@ -979,9 +972,8 @@ g_ucs4_to_utf8 (const gunichar *str,
* things unpaired surrogates.
*
* Return value: a pointer to a newly allocated UTF-8 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set.
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set.
**/
gchar *
g_utf16_to_utf8 (const gunichar2 *str,
@ -990,8 +982,8 @@ g_utf16_to_utf8 (const gunichar2 *str,
glong *items_written,
GError **error)
{
/* This function and g_utf16_to_ucs4 are almost exactly identical - The lines that differ
* are marked.
/* This function and g_utf16_to_ucs4 are almost exactly identical -
* The lines that differ are marked.
*/
const gunichar2 *in;
gchar *out;
@ -1107,28 +1099,26 @@ g_utf16_to_utf8 (const gunichar2 *str,
/**
* g_utf16_to_ucs4:
* @str: a UTF-16 encoded string
* @len: the maximum length (number of <type>gunichar2</type>) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of words read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @items_written: (allow-none): location to store number of characters written, or %NULL.
* The value stored here does not include the trailing
* 0 character.
* @len: the maximum length (number of #gunichar2) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of words read,
* or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial character. If
* an error occurs then the index of the invalid input is stored here.
* @items_written: (allow-none): location to store number of characters
* written, or %NULL. The value stored here does not include the trailing
* 0 character.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
*
* Convert a string from UTF-16 to UCS-4. The result will be
* nul-terminated.
*
* Return value: a pointer to a newly allocated UCS-4 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set.
**/
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set.
*/
gunichar *
g_utf16_to_ucs4 (const gunichar2 *str,
glong len,
@ -1248,27 +1238,25 @@ g_utf16_to_ucs4 (const gunichar2 *str,
* g_utf8_to_utf16:
* @str: a UTF-8 encoded string
* @len: the maximum length (number of bytes) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of bytes read, or %NULL.
* If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial
* character. If an error occurs then the index of the
* invalid input is stored here.
* @items_written: (allow-none): location to store number of <type>gunichar2</type> written,
* or %NULL.
* The value stored here does not include the trailing 0.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of bytes read,
* or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
* returned in case @str contains a trailing partial character. If
* an error occurs then the index of the invalid input is stored here.
* @items_written: (allow-none): location to store number of #gunichar2
* written, or %NULL. The value stored here does not include the
* trailing 0.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
*
* Convert a string from UTF-8 to UTF-16. A 0 character will be
* added to the result after the converted text.
*
* Return value: a pointer to a newly allocated UTF-16 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set.
**/
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set.
*/
gunichar2 *
g_utf8_to_utf16 (const gchar *str,
glong len,
@ -1367,25 +1355,24 @@ g_utf8_to_utf16 (const gchar *str,
* g_ucs4_to_utf16:
* @str: a UCS-4 encoded string
* @len: the maximum length (number of characters) of @str to use.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of bytes read, or %NULL.
* If an error occurs then the index of the invalid input
* is stored here.
* @items_written: (allow-none): location to store number of <type>gunichar2</type>
* written, or %NULL. The value stored here does not
* include the trailing 0.
* If @len < 0, then the string is nul-terminated.
* @items_read: (allow-none): location to store number of bytes read,
* or %NULL. If an error occurs then the index of the invalid input
* is stored here.
* @items_written: (allow-none): location to store number of #gunichar2
* written, or %NULL. The value stored here does not include the
* trailing 0.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
* errors. Any of the errors in #GConvertError other than
* %G_CONVERT_ERROR_NO_CONVERSION may occur.
*
* Convert a string from UCS-4 to UTF-16. A 0 character will be
* added to the result after the converted text.
*
* Return value: a pointer to a newly allocated UTF-16 string.
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
* @error set.
**/
* This value must be freed with g_free(). If an error occurs,
* %NULL will be returned and @error set.
*/
gunichar2 *
g_ucs4_to_utf16 (const gunichar *str,
glong len,
@ -1631,7 +1618,7 @@ fast_validate_len (const char *str,
* with g_utf8_validate() before doing anything else with it.
*
* Return value: %TRUE if the text was valid UTF-8
**/
*/
gboolean
g_utf8_validate (const char *str,
gssize max_len,
@ -1675,7 +1662,7 @@ g_unichar_validate (gunichar ch)
* g_utf8_strreverse:
* @str: a UTF-8 encoded string
* @len: the maximum length of @str to use, in bytes. If @len < 0,
* then the string is nul-terminated.
* then the string is nul-terminated.
*
* Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
* (Use g_utf8_validate() on all text before trying to use UTF-8
@ -1691,7 +1678,7 @@ g_unichar_validate (gunichar ch)
* newly-allocated memory, which should be freed with g_free() when
* no longer needed.
*
* Returns: a newly-allocated string which is the reverse of @str.
* Returns: a newly-allocated string which is the reverse of @str
*
* Since: 2.2
*/