2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
2001-04-16 Havoc Pennington <hp@redhat.com>
+ * gqsort.c: docs
+
+ * gfileutils.c: docs
+
+ * gwin32.c: docs fixes
+
+ * gconvert.c: docs
+
+ * guniprop.c: docs
+
+ * gutf8.c: docs
+
+2001-04-16 Havoc Pennington <hp@redhat.com>
+
* glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for
glib" so the output looks right
gssize
<SUBSECTION Private>
-gstring
gldouble
GLIB_SIZEOF_VOID_P
GLIB_SIZEOF_LONG
<SUBSECTION Private>
g_io_channel_win32_new_fd
g_io_channel_win32_new_messages
-g_io_channel_win32_new_stream_socket
g_io_channel_win32_poll
g_io_channel_win32_make_pollfd
g_io_channel_win32_get_fd
GHookCheckFunc
GHookMarshaller
GHookCheckMarshaller
-GHookFreeFunc
-G_HOOK_DEFERRED_DESTROY
<SUBSECTION>
g_hook_list_init
GFreeFunc
<SUBSECTION>
-GCompareFuncData
g_qsort_with_data
<SUBSECTION Private>
<!-- ##### FUNCTION g_array_sized_new ##### -->
<para>
-
+Creates a new #GArray with the given size.
</para>
-@zero_terminated:
-@clear:
-@element_size:
-@reserved_size:
-@Returns:
+@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared
+@clear: %TRUE if all bits in the array should be cleared to 0 on allocation
+@element_size: size of each element in the array
+@reserved_size: initial array size (number of elements)
+@Returns: the new #GArray
<!-- ##### MACRO g_array_append_val ##### -->
<!-- ##### FUNCTION g_array_sort ##### -->
<para>
-
+Sorts a #GArray using @compare_func which should be a qsort()-style comparison
+function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
+first arg is greater than second arg).
</para>
-@array:
-@compare_func:
+@array: a #GArray
+@compare_func: comparison function
<!-- ##### FUNCTION g_array_sort_with_data ##### -->
<para>
-
+Like g_array_sort(), but the comparison function receives a user data
+argument.
</para>
-@array:
-@compare_func:
-@user_data:
+@array: a #GArray
+@compare_func: a comparison function
+@user_data: data to pass to @compare_func
<!-- ##### MACRO g_array_index ##### -->
<!-- ##### FUNCTION g_byte_array_sized_new ##### -->
<para>
-
+Creates a new byte array, with the given size.
</para>
-@reserved_size:
-@Returns:
+@reserved_size: initial number of bytes in the array
+@Returns: a new #GByteArray
<!-- ##### FUNCTION g_byte_array_append ##### -->
<!-- ##### FUNCTION g_byte_array_sort ##### -->
<para>
-
+Sorts a byte array, using @compare_func which should be a qsort()-style
+comparison function (returns -1 for first arg is less than second arg, 0 for
+equal, 1 if first arg is greater than second arg).
</para>
-@array:
-@compare_func:
+@array: array to sort
+@compare_func: comparison function
<!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
<para>
-
+Like g_byte_array_sort(), but the comparison function takes a user data argument.
</para>
-@array:
-@compare_func:
-@user_data:
+@array: a #GByteArray
+@compare_func: comparison function
+@user_data: data to pass to @compare_func
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
<para>
-
+Creates a new #GPtrArray with @reserved_size elements.
</para>
-@reserved_size:
-@Returns:
+@reserved_size: Initial number of elements.
+@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_add ##### -->
<!-- ##### FUNCTION g_ptr_array_sort ##### -->
<para>
-
+Sorts the array, using @compare_func which should be a qsort()-style comparison
+function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
+first arg is greater than second arg).
</para>
-@array:
-@compare_func:
+@array: array to sort
+@compare_func: comparison function
<!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
<para>
-
+Like g_ptr_array_sort(), but the comparison function has a user data argument.
</para>
-@array:
-@compare_func:
-@user_data:
+@array: array to sort
+@compare_func: qsort()-style comparison function
+@user_data: data to pass to @compare_func
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
<!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### -->
<para>
-
+Removes an element, without calling its destroy notification function.
</para>
-@datalist:
-@key_id:
-@Returns:
+@datalist: a datalist.
+@key_id: the #GQuark identifying a data element.
+@Returns: the data previously stored at @key_id, or %NULL if none
<!-- ##### MACRO g_datalist_set_data ##### -->
<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### -->
<para>
-
+Removes an element, without calling its destroy notification function.
</para>
-@dataset_location:
-@key_id:
-@Returns:
+@dataset_location: the location identifying the dataset.
+@key_id: the #GQuark ID identifying the data element.
+@Returns: the data previously stored at @key_id, or %NULL if none.
<!-- ##### MACRO g_dataset_set_data ##### -->
<!-- ##### MACRO G_USEC_PER_SEC ##### -->
<para>
-
+Number of microseconds in one second (1 million). This macro is provided for
+code readability.
</para>
<!-- ##### FUNCTION g_usleep ##### -->
<para>
-
+Pauses the program for the given number of microseconds. There are 1 million
+microseconds per second (represented by the #G_USEC_PER_SEC macro). g_usleep()
+may have limited precision, depending on hardware and operating system; don't
+rely on the exact length of the sleep.
</para>
-@microseconds:
+@microseconds: number of microseconds to pause
<!-- ##### STRUCT GDate ##### -->
<!-- ##### FUNCTION g_io_create_watch ##### -->
<para>
-
+Creates a #GSource that's dispatched when @condition is met for the given
+@channel. For example, if condition is #G_IO_IN, the source will be dispatched
+when there's data available for reading. g_io_add_watch() is a simpler
+interface to this same functionality, for the case where you want to add the
+source to the default main loop at the default priority.
</para>
-@channel:
-@condition:
-@Returns:
+@channel: a #GIOChannel to watch
+@condition: conditions to watch for
+@Returns: a new #GSource
<!-- ##### FUNCTION g_io_add_watch ##### -->
<!-- ##### FUNCTION g_list_delete_link ##### -->
<para>
-
+Deletes the node @link from @list.
</para>
-@list:
-@link:
-@Returns:
+@list: a #GList
+@link: node to delete from @list
+@Returns: the new head of @list
<!-- ##### FUNCTION g_list_free ##### -->
<!-- ##### FUNCTION g_list_sort_with_data ##### -->
<para>
-
+Like g_list_sort(), but the comparison function accepts a user data argument.
</para>
-@list:
-@compare_func:
-@user_data:
-@Returns:
+@list: a #GList
+@compare_func: comparison function
+@user_data: user data to pass to comparison function
+@Returns: the new head of @list
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
<!-- ##### FUNCTION g_slist_insert_before ##### -->
<para>
-
+Inserts a node before @sibling containing @data. Returns the new head of the list.
</para>
-@slist:
-@sibling:
-@data:
-@Returns:
+@slist: a #GSList
+@sibling: node to insert @data before
+@data: data to put in the newly-inserted node
+@Returns: new head of the list
<!-- ##### FUNCTION g_slist_insert_sorted ##### -->
<!-- ##### FUNCTION g_slist_delete_link ##### -->
<para>
-
+Deletes a node of @list. Returns the new list head.
</para>
-@list:
-@link:
-@Returns:
+@list: a #GSList
+@link: node to delete
+@Returns: new head of @list
<!-- ##### FUNCTION g_slist_free ##### -->
<!-- ##### FUNCTION g_slist_sort_with_data ##### -->
<para>
-
+Like g_slist_sort(), but the sort function accepts a user data argument.
</para>
-@list:
-@compare_func:
-@user_data:
-@Returns:
+@list: a #GSList
+@compare_func: qsort()-style comparison function
+@user_data: data to pass to comparison function
+@Returns: new head of the list
<!-- ##### FUNCTION g_slist_concat ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
@size bytes of memory. It returns the new address of the memory, which may
-have been moved.
+have been moved. @mem may be %NULL, in which case it's considered to
+have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
</para>
@mem: the memory to reallocate.
-@n_bytes:
+@n_bytes: new size of the memory in bytes
@Returns: the new address of the allocated memory.
<!-- # Unused Parameters # -->
@size: the new size of the allocated memory, in bytes.
<!-- ##### FUNCTION g_try_malloc ##### -->
<para>
-
+Attempts to allocate @n_bytes, and returns %NULL on failure.
+Contrast with g_malloc(), which aborts the program on failure.
</para>
-@n_bytes:
-@Returns:
+@n_bytes: number of bytes to allocate
+@Returns: the allocated memory, or %NULL
<!-- ##### FUNCTION g_try_realloc ##### -->
<para>
-
+Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
+on failure. Contrast with g_realloc(), which aborts the program
+on failure. If @mem is %NULL, behaves the same as g_try_malloc().
</para>
-@mem:
-@n_bytes:
-@Returns:
+@mem: previously-allocated memory, or %NULL
+@n_bytes: number of bytes to allocate
+@Returns: the allocated memory, or %NULL
<!-- ##### FUNCTION g_free ##### -->
<!-- ##### MACRO g_alloca ##### -->
<para>
-
+Allocates @size bytes on the stack; these bytes will be freed when the current
+stack frame is cleaned up.
</para>
-@size:
+@size: number of bytes to allocate
<!-- ##### MACRO g_memmove ##### -->
<!-- ##### STRUCT GMemVTable ##### -->
<para>
-
+A set of functions used to perform memory allocation. The same GMemVTable must
+be used for all allocations in the same program; a call to g_mem_set_vtable(),
+if it exists, should be prior to any use of GLib.
</para>
-@malloc:
-@realloc:
-@free:
-@calloc:
-@try_malloc:
-@try_realloc:
+@malloc: function to use for allocating memory
+@realloc: function to use for reallocating memory
+@free: function to use to free memory
+@calloc: function to use for allocating zero-filled memory
+@try_malloc: function to use for allocating memory without a default error handler
+@try_realloc: function to use for reallocating memory without a default error handler
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
-
+Sets the #GMemVTable to use for memory allocation. You can use this to provide
+custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
+OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free
+functions; GLib can provide default implementations of the others. The malloc
+and realloc implementations should return %NULL on failure, GLib will handle
+error-checking for you. @vtable is copied, so need not persist after this
+function has been called.
</para>
-@vtable:
+@vtable: table of memory allocation routines.
<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
<!-- ##### SECTION Short_Description ##### -->
+Double-ended queue data structure
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### FUNCTION g_strdupv ##### -->
<para>
-
+Copies a %NULL-terminated array of strings. The result consists of a
+%NULL-terminated array, with one malloc block holding the array of strings, and
+each string itself allocated. The simplest way to free the result is with
+g_strfreev() which frees each string in a vector, then the vector itself.
</para>
-@str_array:
-@Returns:
+@str_array: array to copy
+@Returns: a new array
<!-- ##### FUNCTION g_strnfill ##### -->
<!-- ##### FUNCTION g_strlcpy ##### -->
<para>
-
+Portability wrapper that calls strlcpy() on systems which have it, and emulates
+strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
+nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
+the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
+strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
+an even better idea.
</para>
-@dest:
-@src:
-@dest_size:
-@Returns:
+@dest: destination buffer
+@src: source buffer
+@dest_size: length of @dest in bytes
+@Returns: length of @src
<!-- ##### FUNCTION g_strlcat ##### -->
<para>
-
+Portability wrapper that calls strlcat() on systems which have it, and emulates
+strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing
+nul-termination for @dest. The total size of @dest won't exceed
+@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
+strncat(), but for real security g_strconcat() is harder to mess up.
</para>
-@dest:
-@src:
-@dest_size:
-@Returns:
+@dest: destination buffer, already containing one nul-terminated string
+@src: source buffer
+@dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
+@Returns: length of @src plus initial length of string in @dest
<!-- ##### FUNCTION g_strdup_printf ##### -->
<!-- ##### FUNCTION g_strcanon ##### -->
<para>
-
+For each character in @string, if the character is not in @valid_chars,
+replaces the character with @substitutor. Modifies @string in place,
+and return @string itself, not a copy. The return value is to allow
+nesting such as g_strup (g_strcanon (str)).
</para>
-@string:
-@valid_chars:
-@subsitutor:
-@Returns:
+@string: a nul-terminated array of bytes
+@valid_chars: bytes permitted in @string
+@substitutor: replacement character for disallowed bytes
+@Returns: @string
<!-- ##### FUNCTION g_strsplit ##### -->
<!-- ##### FUNCTION g_strconcat ##### -->
<para>
-Concatenates all of the given strings into one long string.
-The returned string should be freed when no longer needed.
+Concatenates all of the given strings into one long string. The returned string
+should be freed when no longer needed. WARNING: THE VARIABLE ARGUMENT LIST MUST
+END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
+random memory junk to your string.
</para>
@string1: The first string to add, which must not be NULL.
<!-- ##### SECTION Long_Description ##### -->
<para>
-A #GString is similar to a standard C string, except that it grows
-automatically as text is appended or inserted.
-</para>
-<para>
-The space allocated for the string is always a power of two, so as the
-string grows it will occupy 2, 4, 8, 16, 32, 64, 128 etc. characters.
+A #GString is similar to a standard C string, except that it grows automatically
+as text is appended or inserted. Also, it stores the length of the string, so
+can be used for binary data with embedded nul bytes.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION g_string_new_len ##### -->
<para>
-
+Creates a new #GString with @len bytes of the @init buffer. Because a length is
+provided, @init need not be nul-terminated, and can contain embedded nul bytes.
</para>
-@init:
-@len:
-@Returns:
+@init: initial contents of string
+@len: length of @init to use
+@Returns: a new #GString
<!-- ##### FUNCTION g_string_sized_new ##### -->
<!-- ##### FUNCTION g_string_append_len ##### -->
<para>
-
+Appends @len bytes of @val to @string. Because @len is provided,
+@val may contain embedded nuls and need not be nul-terminated.
</para>
-@string:
-@val:
-@len:
-@Returns:
+@string: a #GString
+@val: bytes to append
+@len: number of bytes of @val to use
+@Returns: the #GString
<!-- ##### FUNCTION g_string_prepend ##### -->
<!-- ##### FUNCTION g_string_prepend_len ##### -->
<para>
-
+Prepends @len bytes of @val to @string. Because @len is provided,
+@val may contain embedded nuls and need not be nul-terminated.
</para>
-@string:
-@val:
-@len:
-@Returns:
+@string: a #GString
+@val: bytes to prepend
+@len: number of bytes in @val to prepend
+@Returns: the #GString passed in
<!-- ##### FUNCTION g_string_insert ##### -->
<!-- ##### FUNCTION g_string_insert_len ##### -->
<para>
-
+Inserts @len bytes of @val into @string at @pos. Because @len is provided, @val
+ may contain embedded nuls and need not be nul-terminated. If @pos is -1, bytes are inserted at the end of the string.
</para>
-@string:
-@pos:
-@val:
-@len:
-@Returns:
+@string: a #GString
+@pos: position in @string where insertion should happen, or -1 for at the end
+@val: bytes to insert
+@len: number of bytes of @val to insert
+@Returns: the #GString
<!-- ##### FUNCTION g_string_erase ##### -->
<!-- ##### FUNCTION g_string_hash ##### -->
<para>
-
+Creates a hash code for @str; for use with #GHashTable.
</para>
-@str:
-@Returns:
+@str: a string to hash
+@Returns: hash code for @str
<!-- ##### FUNCTION g_string_equal ##### -->
<para>
-
+Compares two strings for equality, returning %TRUE if they are equal.
+For use with #GHashTable.
</para>
-@v:
-@v2:
-@Returns:
+@v: a #GString
+@v2: another #GString
+@Returns: %TRUE if they strings are the same length and contain the same bytes
<!-- ##### SECTION Short_Description ##### -->
+Keep track of elapsed time.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GTimer records a start time, and counts microseconds elapsed since that time.
+This is done somewhat differently on different platforms, and can be tricky to
+get exactly right, so #GTimer provides a portable/convenient interface.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GTimer ##### -->
<para>
-
+Opaque datatype that records a start time.
</para>
<!-- ##### FUNCTION g_timer_new ##### -->
<para>
-
+Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
+called for you).
</para>
-@Returns:
+@Returns: a new #GTimer
<!-- ##### FUNCTION g_timer_start ##### -->
<para>
-
+Marks a start time, so that future calls to g_timer_elapsed() will report the
+time since g_timer_start() was called. g_timer_new() automatically marks the
+start time, so no need to call g_timer_start() immediately after creating the
+timer.
</para>
-@timer:
+@timer: a #GTimer
<!-- ##### FUNCTION g_timer_stop ##### -->
<para>
-
+Marks an end time, so calls to g_timer_elapsed() will return the difference
+between this end time and the start time.
</para>
-@timer:
+@timer: a #GTimer
<!-- ##### FUNCTION g_timer_elapsed ##### -->
<para>
-
+If @timer has been started but not stopped, obtains the time since the timer was
+started. If @timer has been stopped, obtains the elapsed time between the time
+it was started and the time it was stopped. The return value is the number of
+seconds elapsed, and the @microseconds argument allows you to get the number of
+microseconds.
</para>
-@timer:
-@microseconds:
-@Returns:
+@timer: a #GTimer
+@microseconds: return location for microseconds elapsed, or %NULL
+@Returns: seconds elapsed
<!-- ##### FUNCTION g_timer_reset ##### -->
<para>
-
+This function is useless; it's fine to call g_timer_start() on an
+already-started timer to reset the start time, so g_timer_reset() serves no
+purpose.
</para>
-@timer:
+@timer: a #GTimer
<!-- ##### FUNCTION g_timer_destroy ##### -->
<para>
-
+Destroys a timer, freeing associated resources.
</para>
-@timer:
+@timer: a #GTimer to destroy
<!-- ##### FUNCTION g_tree_new ##### -->
<para>
-Creates a new GTree.
+Creates a new #GTree.
</para>
@key_compare_func: the function used to order the nodes in the #GTree.
<!-- ##### FUNCTION g_tree_new_with_data ##### -->
<para>
-
+Creates a new #GTree with a comparison function that accepts user data.
+See g_tree_new() for more details.
</para>
-@key_compare_func:
-@user_data:
-@Returns:
+@key_compare_func: qsort()-style comparison function
+@user_data: data to pass to comparison function
+@Returns: a new #GTree
<!-- ##### FUNCTION g_tree_insert ##### -->
<!-- ##### FUNCTION g_node_copy ##### -->
<para>
-
+Recursively copies a #GNode (but does not deep-copy the data inside the nodes,
+since there's no way for GLib to know how to do that).
</para>
-@node:
-@Returns:
+@node: a #GNode
+@Returns: a new #GNode containing the same data pointers
<!-- ##### FUNCTION g_node_insert ##### -->
#error libiconv not in use but included iconv.h is from libiconv
#endif
+/**
+ * g_iconv_open:
+ * @to_codeset: destination codeset
+ * @from_codeset: source codeset
+ *
+ * Same as the standard UNIX routine iconv_open(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: a "conversion descriptor"
+ **/
GIConv
g_iconv_open (const gchar *to_codeset,
const gchar *from_codeset)
return (GIConv)cd;
}
+/**
+ * g_iconv:
+ * @converter: conversion descriptor from g_iconv_open()
+ * @inbuf: bytes to convert
+ * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
+ * @outbuf: converted output bytes
+ * @outbytes_left: inout parameter, bytes available to fill in @outbuf
+ *
+ * Same as the standard UNIX routine iconv(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: count of non-reversible conversions, or -1 on error
+ **/
size_t
g_iconv (GIConv converter,
gchar **inbuf,
return iconv (cd, inbuf, inbytes_left, outbuf, outbytes_left);
}
+/**
+ * g_iconv_close:
+ * @converter: a conversion descriptor from g_iconv_open()
+ *
+ * Same as the standard UNIX routine iconv_close(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation. Should be called to clean up
+ * the conversion descriptor from iconv_open() when
+ * you are done converting things.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: -1 on error, 0 on success
+ **/
gint
g_iconv_close (GIConv converter)
{
return q;
}
+/**
+ * g_file_error_from_errno:
+ * @err_no: an "errno" value
+ *
+ * Gets a #GFileError constant based on the passed-in errno.
+ * For example, if you pass in EEXIST this function returns
+ * #G_FILE_ERROR_EXIST. Unlike errno values, you can portably
+ * assume that all #GFileError values will exist.
+ *
+ * Normally a #GFileError value goes into a #GError returned
+ * from a function that manipulates files. So you would use
+ * g_file_error_from_errno() when constructing a #GError.
+ *
+ * Return value: #GFileError corresponding to the given errno
+ **/
GFileError
-g_file_error_from_errno (gint en)
+g_file_error_from_errno (gint err_no)
{
- switch (en)
+ switch (err_no)
{
#ifdef EEXIST
case EEXIST:
#error libiconv not in use but included iconv.h is from libiconv
#endif
+/**
+ * g_iconv_open:
+ * @to_codeset: destination codeset
+ * @from_codeset: source codeset
+ *
+ * Same as the standard UNIX routine iconv_open(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: a "conversion descriptor"
+ **/
GIConv
g_iconv_open (const gchar *to_codeset,
const gchar *from_codeset)
return (GIConv)cd;
}
+/**
+ * g_iconv:
+ * @converter: conversion descriptor from g_iconv_open()
+ * @inbuf: bytes to convert
+ * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
+ * @outbuf: converted output bytes
+ * @outbytes_left: inout parameter, bytes available to fill in @outbuf
+ *
+ * Same as the standard UNIX routine iconv(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: count of non-reversible conversions, or -1 on error
+ **/
size_t
g_iconv (GIConv converter,
gchar **inbuf,
return iconv (cd, inbuf, inbytes_left, outbuf, outbytes_left);
}
+/**
+ * g_iconv_close:
+ * @converter: a conversion descriptor from g_iconv_open()
+ *
+ * Same as the standard UNIX routine iconv_close(), but
+ * may be implemented via libiconv on UNIX flavors that lack
+ * a native implementation. Should be called to clean up
+ * the conversion descriptor from iconv_open() when
+ * you are done converting things.
+ *
+ * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * more convenient than the raw iconv wrappers.
+ *
+ * Return value: -1 on error, 0 on success
+ **/
gint
g_iconv_close (GIConv converter)
{
return q;
}
+/**
+ * g_file_error_from_errno:
+ * @err_no: an "errno" value
+ *
+ * Gets a #GFileError constant based on the passed-in errno.
+ * For example, if you pass in EEXIST this function returns
+ * #G_FILE_ERROR_EXIST. Unlike errno values, you can portably
+ * assume that all #GFileError values will exist.
+ *
+ * Normally a #GFileError value goes into a #GError returned
+ * from a function that manipulates files. So you would use
+ * g_file_error_from_errno() when constructing a #GError.
+ *
+ * Return value: #GFileError corresponding to the given errno
+ **/
GFileError
-g_file_error_from_errno (gint en)
+g_file_error_from_errno (gint err_no)
{
- switch (en)
+ switch (err_no)
{
#ifdef EEXIST
case EEXIST:
*
* Modified by the GLib Team and others 1997-2000. See the AUTHORS
* file for a list of people on the GLib Team. See the ChangeLog
- * files for a list of changes. These files are distributed with
- * GLib at ftp://ftp.gtk.org/pub/gtk/. */
+ * files for a list of changes. These files are distributed with GLib
+ * at ftp://ftp.gtk.org/pub/gtk/.
+ */
#include <string.h>
* in this case)!
*/
+/**
+ * g_qsort_with_data:
+ * @pbase: start of array to sort
+ * @total_elems: elements in the array
+ * @size: size of each element
+ * @compare_func: function to compare elements
+ * @user_data: data to pass to @compare_func
+ *
+ * This is just like the standard C qsort() function, but
+ * the comparison routine accepts a user data argument.
+ *
+ **/
void
g_qsort_with_data (gconstpointer pbase,
gint total_elems,
gchar*
g_strcanon (gchar *string,
const gchar *valid_chars,
- gchar subsitutor)
+ gchar substitutor)
{
register gchar *c;
for (c = string; *c; c++)
{
if (!strchr (valid_chars, *c))
- *c = subsitutor;
+ *c = substitutor;
}
return string;
gchar new_delimiter);
gchar* g_strcanon (gchar *string,
const gchar *valid_chars,
- gchar subsitutor);
+ gchar substitutor);
gdouble g_strtod (const gchar *nptr,
gchar **endptr);
G_CONST_RETURN gchar* g_strerror (gint errnum) G_GNUC_CONST;
#define PROP(Char) (((Char) > (G_UNICODE_LAST_CHAR)) ? G_UNICODE_UNASSIGNED : TPROP ((Char) >> 8, (Char) & 0xff))
+/**
+ * g_unichar_break_type:
+ * @c: a Unicode character
+ *
+ * Determines the break type of @c. @c should be a Unicode character
+ * (to derive a character from UTF-8 encoded text, use
+ * g_utf8_get_char()). The break type is used to find word and line
+ * breaks ("text boundaries"), Pango implements the Unicode boundary
+ * resolution alogorithms and normally you would use a function such
+ * as pango_break() instead of caring about break types yourself.
+ *
+ * Return value: break type
+ **/
GUnicodeBreakType
g_unichar_break_type (gunichar c)
{
|| (Type) == G_UNICODE_MODIFIER_LETTER \
|| (Type) == G_UNICODE_OTHER_LETTER)
+/**
+ * g_unichar_isalnum:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is alphanumeric.
+ * Given some UTF-8 text, obtain a character value
+ * with g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is an alphanumeric character
+ **/
gboolean
g_unichar_isalnum (gunichar c)
{
return ISDIGIT (t) || ISALPHA (t);
}
+/**
+ * g_unichar_isalpha:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is alphabetic (i.e. a letter).
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is an alphabetic character
+ **/
gboolean
g_unichar_isalpha (gunichar c)
{
return ISALPHA (t);
}
+
+/**
+ * g_unichar_iscntrl:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a control character.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a control character
+ **/
gboolean
g_unichar_iscntrl (gunichar c)
{
return TYPE (c) == G_UNICODE_CONTROL;
}
+/**
+ * g_unichar_isdigit:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is numeric (i.e. a digit). This
+ * covers ASCII 0-9 and also digits in other languages/scripts. Given
+ * some UTF-8 text, obtain a character value with g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a digit
+ **/
gboolean
g_unichar_isdigit (gunichar c)
{
return TYPE (c) == G_UNICODE_DECIMAL_NUMBER;
}
+
+/**
+ * g_unichar_isgraph:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is printable and not a space
+ * (returns %FALSE for control characters, format characters, and
+ * spaces). g_unichar_isprint() is similar, but returns %TRUE for
+ * spaces. Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is printable unless it's a space
+ **/
gboolean
g_unichar_isgraph (gunichar c)
{
&& t != G_UNICODE_SPACE_SEPARATOR);
}
+/**
+ * g_unichar_islower:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a lowercase letter.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a lowercase letter
+ **/
gboolean
g_unichar_islower (gunichar c)
{
return TYPE (c) == G_UNICODE_LOWERCASE_LETTER;
}
+
+/**
+ * g_unichar_isprint:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is printable.
+ * Unlike g_unichar_isgraph(), returns %TRUE for spaces.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is printable
+ **/
gboolean
g_unichar_isprint (gunichar c)
{
&& t != G_UNICODE_SURROGATE);
}
+/**
+ * g_unichar_ispunct:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is punctuation.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a punctuation character
+ **/
gboolean
g_unichar_ispunct (gunichar c)
{
|| t == G_UNICODE_OPEN_PUNCTUATION);
}
+/**
+ * g_unichar_isspace:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a space, tab, or line separator
+ * (newline, carriage return, etc.). Given some UTF-8 text, obtain a
+ * character value with g_utf8_get_char().
+ *
+ * (Note: don't use this to do word breaking; you have to use
+ * Pango or equivalent to get word breaking right, the algorithm
+ * is fairly complex.)
+ *
+ * Return value: %TRUE if @c is a punctuation character
+ **/
gboolean
g_unichar_isspace (gunichar c)
{
*
* Determines if a character is uppercase.
*
- * Return value:
+ * Return value: %TRUE if @c is an uppercase character.
**/
gboolean
g_unichar_isupper (gunichar c)
*
* Determines if a characters is a hexidecimal digit
*
- * Return value: %TRUE if the character is a hexidecimal digit.
+ * Return value: %TRUE if the character is a hexadecimal digit.
**/
gboolean
g_unichar_isxdigit (gunichar c)
* @c: a unicode character
*
* Determines if a given character is assigned in the Unicode
- * standard
+ * standard.
*
* Return value: %TRUE if the character has an assigned value.
**/
}
/**
- * g_unichar_xdigit_value:
+ * g_unichar_digit_value:
* @c: a unicode character
*
* Determines the numeric value of a character as a decimal
*
* Classifies a unicode character by type.
*
- * Return value: the typ of the character.
+ * Return value: the type of the character.
**/
GUnicodeType
g_unichar_type (gunichar c)
* nul-terminated.
*
* Return value: the length of the string in characters
- */
+ **/
gint
g_utf8_strlen (const gchar *p, gint max)
{
}
+/**
+ * g_utf8_strncpy:
+ * @dest: buffer to fill with characters from @src
+ * @src: UTF-8 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.)
+ *
+ * Return value: @dest
+ **/
gchar *
g_utf8_strncpy (gchar *dest, const gchar *src, size_t n)
{
static int utf8_locale_cache = -1;
static char *utf8_charset_cache = NULL;
+/**
+ * g_get_charset:
+ * @charset: return location for character set name
+ *
+ * Obtains the character set for the current locale; you might use
+ * this character set as an argument to g_convert(), to convert from
+ * the current locale's encoding to some other encoding. (Frequently
+ * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts,
+ * though.)
+ *
+ * The return value is %TRUE if the locale's encoding is UTF-8, in that
+ * case you can perhaps avoid calling g_convert().
+ *
+ * The string returned in @charset is not allocated, and should not be
+ * freed.
+ *
+ * Return value: %TRUE if the returned charset is UTF-8
+ **/
gboolean
g_get_charset (char **charset)
{
* locale from Windows and returns it as a string of the above form
* for use in forming file names etc. The returned string should be
* deallocated with g_free().
+ *
+ * Returns: allocated locale name
*/
gchar *
* or in the thread's language, or the user's language, the system's
* langauge, or US English (see docs for FormatMessage). The returned
* string should be deallocated with g_free().
+ *
+ * Returns: allocated error message
*/
gchar *
g_win32_error_message (gint error)
*
* Modified by the GLib Team and others 1997-2000. See the AUTHORS
* file for a list of people on the GLib Team. See the ChangeLog
- * files for a list of changes. These files are distributed with
- * GLib at ftp://ftp.gtk.org/pub/gtk/. */
+ * files for a list of changes. These files are distributed with GLib
+ * at ftp://ftp.gtk.org/pub/gtk/.
+ */
#include <string.h>
* in this case)!
*/
+/**
+ * g_qsort_with_data:
+ * @pbase: start of array to sort
+ * @total_elems: elements in the array
+ * @size: size of each element
+ * @compare_func: function to compare elements
+ * @user_data: data to pass to @compare_func
+ *
+ * This is just like the standard C qsort() function, but
+ * the comparison routine accepts a user data argument.
+ *
+ **/
void
g_qsort_with_data (gconstpointer pbase,
gint total_elems,
gchar*
g_strcanon (gchar *string,
const gchar *valid_chars,
- gchar subsitutor)
+ gchar substitutor)
{
register gchar *c;
for (c = string; *c; c++)
{
if (!strchr (valid_chars, *c))
- *c = subsitutor;
+ *c = substitutor;
}
return string;
gchar new_delimiter);
gchar* g_strcanon (gchar *string,
const gchar *valid_chars,
- gchar subsitutor);
+ gchar substitutor);
gdouble g_strtod (const gchar *nptr,
gchar **endptr);
G_CONST_RETURN gchar* g_strerror (gint errnum) G_GNUC_CONST;
#define PROP(Char) (((Char) > (G_UNICODE_LAST_CHAR)) ? G_UNICODE_UNASSIGNED : TPROP ((Char) >> 8, (Char) & 0xff))
+/**
+ * g_unichar_break_type:
+ * @c: a Unicode character
+ *
+ * Determines the break type of @c. @c should be a Unicode character
+ * (to derive a character from UTF-8 encoded text, use
+ * g_utf8_get_char()). The break type is used to find word and line
+ * breaks ("text boundaries"), Pango implements the Unicode boundary
+ * resolution alogorithms and normally you would use a function such
+ * as pango_break() instead of caring about break types yourself.
+ *
+ * Return value: break type
+ **/
GUnicodeBreakType
g_unichar_break_type (gunichar c)
{
|| (Type) == G_UNICODE_MODIFIER_LETTER \
|| (Type) == G_UNICODE_OTHER_LETTER)
+/**
+ * g_unichar_isalnum:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is alphanumeric.
+ * Given some UTF-8 text, obtain a character value
+ * with g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is an alphanumeric character
+ **/
gboolean
g_unichar_isalnum (gunichar c)
{
return ISDIGIT (t) || ISALPHA (t);
}
+/**
+ * g_unichar_isalpha:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is alphabetic (i.e. a letter).
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is an alphabetic character
+ **/
gboolean
g_unichar_isalpha (gunichar c)
{
return ISALPHA (t);
}
+
+/**
+ * g_unichar_iscntrl:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a control character.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a control character
+ **/
gboolean
g_unichar_iscntrl (gunichar c)
{
return TYPE (c) == G_UNICODE_CONTROL;
}
+/**
+ * g_unichar_isdigit:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is numeric (i.e. a digit). This
+ * covers ASCII 0-9 and also digits in other languages/scripts. Given
+ * some UTF-8 text, obtain a character value with g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a digit
+ **/
gboolean
g_unichar_isdigit (gunichar c)
{
return TYPE (c) == G_UNICODE_DECIMAL_NUMBER;
}
+
+/**
+ * g_unichar_isgraph:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is printable and not a space
+ * (returns %FALSE for control characters, format characters, and
+ * spaces). g_unichar_isprint() is similar, but returns %TRUE for
+ * spaces. Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is printable unless it's a space
+ **/
gboolean
g_unichar_isgraph (gunichar c)
{
&& t != G_UNICODE_SPACE_SEPARATOR);
}
+/**
+ * g_unichar_islower:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a lowercase letter.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a lowercase letter
+ **/
gboolean
g_unichar_islower (gunichar c)
{
return TYPE (c) == G_UNICODE_LOWERCASE_LETTER;
}
+
+/**
+ * g_unichar_isprint:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is printable.
+ * Unlike g_unichar_isgraph(), returns %TRUE for spaces.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is printable
+ **/
gboolean
g_unichar_isprint (gunichar c)
{
&& t != G_UNICODE_SURROGATE);
}
+/**
+ * g_unichar_ispunct:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is punctuation.
+ * Given some UTF-8 text, obtain a character value with
+ * g_utf8_get_char().
+ *
+ * Return value: %TRUE if @c is a punctuation character
+ **/
gboolean
g_unichar_ispunct (gunichar c)
{
|| t == G_UNICODE_OPEN_PUNCTUATION);
}
+/**
+ * g_unichar_isspace:
+ * @c: a Unicode character
+ *
+ * Determines whether a character is a space, tab, or line separator
+ * (newline, carriage return, etc.). Given some UTF-8 text, obtain a
+ * character value with g_utf8_get_char().
+ *
+ * (Note: don't use this to do word breaking; you have to use
+ * Pango or equivalent to get word breaking right, the algorithm
+ * is fairly complex.)
+ *
+ * Return value: %TRUE if @c is a punctuation character
+ **/
gboolean
g_unichar_isspace (gunichar c)
{
*
* Determines if a character is uppercase.
*
- * Return value:
+ * Return value: %TRUE if @c is an uppercase character.
**/
gboolean
g_unichar_isupper (gunichar c)
*
* Determines if a characters is a hexidecimal digit
*
- * Return value: %TRUE if the character is a hexidecimal digit.
+ * Return value: %TRUE if the character is a hexadecimal digit.
**/
gboolean
g_unichar_isxdigit (gunichar c)
* @c: a unicode character
*
* Determines if a given character is assigned in the Unicode
- * standard
+ * standard.
*
* Return value: %TRUE if the character has an assigned value.
**/
}
/**
- * g_unichar_xdigit_value:
+ * g_unichar_digit_value:
* @c: a unicode character
*
* Determines the numeric value of a character as a decimal
*
* Classifies a unicode character by type.
*
- * Return value: the typ of the character.
+ * Return value: the type of the character.
**/
GUnicodeType
g_unichar_type (gunichar c)
* nul-terminated.
*
* Return value: the length of the string in characters
- */
+ **/
gint
g_utf8_strlen (const gchar *p, gint max)
{
}
+/**
+ * g_utf8_strncpy:
+ * @dest: buffer to fill with characters from @src
+ * @src: UTF-8 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.)
+ *
+ * Return value: @dest
+ **/
gchar *
g_utf8_strncpy (gchar *dest, const gchar *src, size_t n)
{
static int utf8_locale_cache = -1;
static char *utf8_charset_cache = NULL;
+/**
+ * g_get_charset:
+ * @charset: return location for character set name
+ *
+ * Obtains the character set for the current locale; you might use
+ * this character set as an argument to g_convert(), to convert from
+ * the current locale's encoding to some other encoding. (Frequently
+ * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts,
+ * though.)
+ *
+ * The return value is %TRUE if the locale's encoding is UTF-8, in that
+ * case you can perhaps avoid calling g_convert().
+ *
+ * The string returned in @charset is not allocated, and should not be
+ * freed.
+ *
+ * Return value: %TRUE if the returned charset is UTF-8
+ **/
gboolean
g_get_charset (char **charset)
{
* locale from Windows and returns it as a string of the above form
* for use in forming file names etc. The returned string should be
* deallocated with g_free().
+ *
+ * Returns: allocated locale name
*/
gchar *
* or in the thread's language, or the user's language, the system's
* langauge, or US English (see docs for FormatMessage). The returned
* string should be deallocated with g_free().
+ *
+ * Returns: allocated error message
*/
gchar *
g_win32_error_message (gint error)
projects / platform / upstream / glib.git / commitdiff