diff options
43 files changed, 814 insertions, 199 deletions
@@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,19 @@ 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 diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 405f4f3c0..cc792d17e 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,19 @@ 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 diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index d820e1718..e28409c1d 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -40,7 +40,6 @@ gsize gssize <SUBSECTION Private> -gstring gldouble GLIB_SIZEOF_VOID_P GLIB_SIZEOF_LONG @@ -617,7 +616,6 @@ GIOFuncs <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 @@ -950,8 +948,6 @@ GHookFunc GHookCheckFunc GHookMarshaller GHookCheckMarshaller -GHookFreeFunc -G_HOOK_DEFERRED_DESTROY <SUBSECTION> g_hook_list_init @@ -1043,7 +1039,6 @@ GVoidFunc GFreeFunc <SUBSECTION> -GCompareFuncData g_qsort_with_data <SUBSECTION Private> diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index f4eea22b3..2bd14307f 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -79,14 +79,14 @@ when they are allocated. <!-- ##### 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 ##### --> @@ -211,21 +211,24 @@ g_array_remove_index(). <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 9d2fb8397..2303e1a8f 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -68,11 +68,11 @@ Creates a new #GByteArray. <!-- ##### 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 ##### --> @@ -125,21 +125,23 @@ g_byte_array_remove_index(). <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index f44d90f9e..fbe1a3d06 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -82,11 +82,11 @@ Creates a new #GPtrArray. <!-- ##### 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 ##### --> @@ -158,21 +158,23 @@ g_ptr_array_remove_index(). <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index bef25d177..835ea4615 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -112,12 +112,12 @@ Removes an element, using its #GQuark identifier. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml index c6be2f9cf..5631f91cc 100644 --- a/docs/reference/glib/tmpl/datasets.sgml +++ b/docs/reference/glib/tmpl/datasets.sgml @@ -110,12 +110,12 @@ The data element's destroy function is called if it has been set. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 60f27af09..2137a1483 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -65,7 +65,8 @@ can request the current time as a #GTimeVal with g_get_current_time(). <!-- ##### MACRO G_USEC_PER_SEC ##### --> <para> - +Number of microseconds in one second (1 million). This macro is provided for +code readability. </para> @@ -91,10 +92,13 @@ Win32. Returns the current time. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index ebfdd05e5..6e99a9b48 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -211,12 +211,16 @@ Decrements the reference count of a #GIOChannel. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index 8812d8a52..fa305ccf7 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -181,12 +181,12 @@ self-contained list with one element. <!-- ##### 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 ##### --> @@ -270,13 +270,13 @@ value if the first element comes after the second. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index 780240fcc..b75cb597f 100644 --- a/docs/reference/glib/tmpl/linked_lists_single.sgml +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -152,13 +152,13 @@ to the end of the list. <!-- ##### 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 ##### --> @@ -201,12 +201,12 @@ self-contained list with one element. <!-- ##### 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 ##### --> @@ -273,13 +273,13 @@ value if the first element comes after the second. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index ba5060a8f..79def9ff7 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -94,11 +94,12 @@ If @size is 0 it returns NULL. <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. @@ -106,21 +107,24 @@ have been moved. <!-- ##### 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 ##### --> @@ -134,10 +138,11 @@ If @mem is NULL it simply returns. <!-- ##### 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 ##### --> @@ -171,22 +176,30 @@ is NULL. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index c178f27fd..1f602c667 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/docs/reference/glib/tmpl/queue.sgml @@ -3,6 +3,7 @@ Double-ended Queues <!-- ##### SECTION Short_Description ##### --> +Double-ended queue data structure <!-- ##### SECTION Long_Description ##### --> <para> diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 2bcd04aef..2a87e3100 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -41,11 +41,14 @@ null-terminated. <!-- ##### 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 ##### --> @@ -71,24 +74,33 @@ The returned string should be freed when no longer needed. <!-- ##### 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 ##### --> @@ -332,13 +344,16 @@ character compressed. <!-- ##### 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 ##### --> @@ -367,8 +382,10 @@ Frees a NULL-terminated array of strings, and the array itself. <!-- ##### 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. diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index c096bb717..f6be0043a 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -6,12 +6,9 @@ text buffers which grow automatically as text is added. <!-- ##### 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 ##### --> @@ -47,12 +44,13 @@ Creates a new #GString, initialized with the given string. <!-- ##### 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 ##### --> @@ -129,13 +127,14 @@ Adds a character onto the end of a #GString, expanding it if necessary. <!-- ##### 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 ##### --> @@ -160,13 +159,14 @@ Adds a character onto the start of a #GString, expanding it if necessary. <!-- ##### 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 ##### --> @@ -193,14 +193,15 @@ Inserts a character into a #GString, expanding it if necessary. <!-- ##### 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 ##### --> @@ -256,20 +257,21 @@ Converts a #GString to lower case. <!-- ##### 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 diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml index 0a05d6cc8..fed2ad94f 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/docs/reference/glib/tmpl/timers.sgml @@ -3,10 +3,13 @@ Timers <!-- ##### 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 ##### --> @@ -16,57 +19,68 @@ Timers <!-- ##### 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 diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index c68e739eb..b36bf37a8 100644 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ b/docs/reference/glib/tmpl/trees-binary.sgml @@ -50,7 +50,7 @@ It should be accessed only by using the following functions. <!-- ##### 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. @@ -64,12 +64,13 @@ second. <!-- ##### 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 ##### --> diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index 8916fa69b..40d2424d9 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -82,11 +82,12 @@ Used to create the first node in a tree. <!-- ##### 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 ##### --> diff --git a/gconvert.c b/gconvert.c index 65a4adafd..035eefaee 100644 --- a/gconvert.c +++ b/gconvert.c @@ -53,6 +53,20 @@ g_convert_error_quark() #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) @@ -62,6 +76,23 @@ g_iconv_open (const gchar *to_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, @@ -74,6 +105,21 @@ g_iconv (GIConv converter, 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) { diff --git a/gfileutils.c b/gfileutils.c index 1721fad12..86b33bc00 100644 --- a/gfileutils.c +++ b/gfileutils.c @@ -117,10 +117,25 @@ g_file_error_quark (void) 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: diff --git a/glib/gconvert.c b/glib/gconvert.c index 65a4adafd..035eefaee 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -53,6 +53,20 @@ g_convert_error_quark() #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) @@ -62,6 +76,23 @@ g_iconv_open (const gchar *to_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, @@ -74,6 +105,21 @@ g_iconv (GIConv converter, 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) { diff --git a/glib/gfileutils.c b/glib/gfileutils.c index 1721fad12..86b33bc00 100644 --- a/glib/gfileutils.c +++ b/glib/gfileutils.c @@ -117,10 +117,25 @@ g_file_error_quark (void) 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: diff --git a/glib/gqsort.c b/glib/gqsort.c index c75cca31a..a100735ac 100644 --- a/glib/gqsort.c +++ b/glib/gqsort.c @@ -28,8 +28,9 @@ * * 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> @@ -92,6 +93,18 @@ stack_node; * 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, diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index add39aaf0..5f12e39b1 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -1112,7 +1112,7 @@ g_strdelimit (gchar *string, gchar* g_strcanon (gchar *string, const gchar *valid_chars, - gchar subsitutor) + gchar substitutor) { register gchar *c; @@ -1122,7 +1122,7 @@ g_strcanon (gchar *string, for (c = string; *c; c++) { if (!strchr (valid_chars, *c)) - *c = subsitutor; + *c = substitutor; } return string; diff --git a/glib/gstrfuncs.h b/glib/gstrfuncs.h index 183fecf0b..e23973c10 100644 --- a/glib/gstrfuncs.h +++ b/glib/gstrfuncs.h @@ -41,7 +41,7 @@ gchar* g_strdelimit (gchar *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; diff --git a/glib/gunibreak.c b/glib/gunibreak.c index 6a4b83795..4f3295993 100644 --- a/glib/gunibreak.c +++ b/glib/gunibreak.c @@ -35,6 +35,19 @@ #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) { diff --git a/glib/guniprop.c b/glib/guniprop.c index b1513c1e4..6b706b136 100644 --- a/glib/guniprop.c +++ b/glib/guniprop.c @@ -50,6 +50,16 @@ || (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) { @@ -57,6 +67,16 @@ 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) { @@ -64,18 +84,52 @@ 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) { @@ -88,12 +142,34 @@ 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) { @@ -105,6 +181,16 @@ 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) { @@ -115,6 +201,20 @@ 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) { @@ -145,7 +245,7 @@ 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) @@ -182,7 +282,7 @@ g_unichar_istitle (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) @@ -198,7 +298,7 @@ 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. **/ @@ -317,7 +417,7 @@ g_unichar_totitle (gunichar c) } /** - * g_unichar_xdigit_value: + * g_unichar_digit_value: * @c: a unicode character * * Determines the numeric value of a character as a decimal @@ -362,7 +462,7 @@ g_unichar_xdigit_value (gunichar c) * * 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) diff --git a/glib/gutf8.c b/glib/gutf8.c index 74d053fe9..1e1123898 100644 --- a/glib/gutf8.c +++ b/glib/gutf8.c @@ -200,7 +200,7 @@ g_utf8_prev_char (const gchar *p) * nul-terminated. * * Return value: the length of the string in characters - */ + **/ gint g_utf8_strlen (const gchar *p, gint max) { @@ -310,6 +310,19 @@ g_utf8_pointer_to_offset (const gchar *str, } +/** + * 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) { @@ -379,6 +392,24 @@ g_utf8_get_charset_internal (char **a) 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) { diff --git a/glib/gwin32.c b/glib/gwin32.c index 1a9481807..594fbbe9a 100644 --- a/glib/gwin32.c +++ b/glib/gwin32.c @@ -545,6 +545,8 @@ g_win32_closedir (DIR *dir) * 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 * @@ -829,6 +831,8 @@ g_win32_getlocale (void) * 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) @@ -28,8 +28,9 @@ * * 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> @@ -92,6 +93,18 @@ stack_node; * 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, diff --git a/gstrfuncs.c b/gstrfuncs.c index add39aaf0..5f12e39b1 100644 --- a/gstrfuncs.c +++ b/gstrfuncs.c @@ -1112,7 +1112,7 @@ g_strdelimit (gchar *string, gchar* g_strcanon (gchar *string, const gchar *valid_chars, - gchar subsitutor) + gchar substitutor) { register gchar *c; @@ -1122,7 +1122,7 @@ g_strcanon (gchar *string, for (c = string; *c; c++) { if (!strchr (valid_chars, *c)) - *c = subsitutor; + *c = substitutor; } return string; diff --git a/gstrfuncs.h b/gstrfuncs.h index 183fecf0b..e23973c10 100644 --- a/gstrfuncs.h +++ b/gstrfuncs.h @@ -41,7 +41,7 @@ gchar* g_strdelimit (gchar *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; diff --git a/gunibreak.c b/gunibreak.c index 6a4b83795..4f3295993 100644 --- a/gunibreak.c +++ b/gunibreak.c @@ -35,6 +35,19 @@ #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) { diff --git a/guniprop.c b/guniprop.c index b1513c1e4..6b706b136 100644 --- a/guniprop.c +++ b/guniprop.c @@ -50,6 +50,16 @@ || (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) { @@ -57,6 +67,16 @@ 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) { @@ -64,18 +84,52 @@ 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) { @@ -88,12 +142,34 @@ 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) { @@ -105,6 +181,16 @@ 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) { @@ -115,6 +201,20 @@ 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) { @@ -145,7 +245,7 @@ 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) @@ -182,7 +282,7 @@ g_unichar_istitle (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) @@ -198,7 +298,7 @@ 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. **/ @@ -317,7 +417,7 @@ g_unichar_totitle (gunichar c) } /** - * g_unichar_xdigit_value: + * g_unichar_digit_value: * @c: a unicode character * * Determines the numeric value of a character as a decimal @@ -362,7 +462,7 @@ g_unichar_xdigit_value (gunichar c) * * 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) @@ -200,7 +200,7 @@ g_utf8_prev_char (const gchar *p) * nul-terminated. * * Return value: the length of the string in characters - */ + **/ gint g_utf8_strlen (const gchar *p, gint max) { @@ -310,6 +310,19 @@ g_utf8_pointer_to_offset (const gchar *str, } +/** + * 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) { @@ -379,6 +392,24 @@ g_utf8_get_charset_internal (char **a) 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) { @@ -545,6 +545,8 @@ g_win32_closedir (DIR *dir) * 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 * @@ -829,6 +831,8 @@ g_win32_getlocale (void) * 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) |