From 4eab875811c415d894626b51818a447adfa1af71 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Mon, 16 Apr 2001 20:05:25 +0000 Subject: [PATCH] docs 2001-04-16 Havoc Pennington * gqsort.c: docs * gfileutils.c: docs * gwin32.c: docs fixes * gconvert.c: docs * guniprop.c: docs * gutf8.c: docs --- ChangeLog | 14 +++ ChangeLog.pre-2-0 | 14 +++ ChangeLog.pre-2-10 | 14 +++ ChangeLog.pre-2-12 | 14 +++ ChangeLog.pre-2-2 | 14 +++ ChangeLog.pre-2-4 | 14 +++ ChangeLog.pre-2-6 | 14 +++ ChangeLog.pre-2-8 | 14 +++ docs/reference/glib/glib-sections.txt | 5 - docs/reference/glib/tmpl/arrays.sgml | 29 ++--- docs/reference/glib/tmpl/arrays_byte.sgml | 22 ++-- docs/reference/glib/tmpl/arrays_pointer.sgml | 22 ++-- docs/reference/glib/tmpl/datalist.sgml | 8 +- docs/reference/glib/tmpl/datasets.sgml | 8 +- docs/reference/glib/tmpl/date.sgml | 10 +- docs/reference/glib/tmpl/iochannels.sgml | 12 +- .../glib/tmpl/linked_lists_double.sgml | 18 +-- .../glib/tmpl/linked_lists_single.sgml | 28 ++--- docs/reference/glib/tmpl/memory.sgml | 53 +++++---- docs/reference/glib/tmpl/queue.sgml | 1 + docs/reference/glib/tmpl/string_utils.sgml | 57 +++++---- docs/reference/glib/tmpl/strings.sgml | 68 +++++------ docs/reference/glib/tmpl/timers.sgml | 46 +++++--- docs/reference/glib/tmpl/trees-binary.sgml | 11 +- docs/reference/glib/tmpl/trees-nary.sgml | 7 +- gconvert.c | 46 ++++++++ gfileutils.c | 19 ++- glib/gconvert.c | 46 ++++++++ glib/gfileutils.c | 19 ++- glib/gqsort.c | 17 ++- glib/gstrfuncs.c | 4 +- glib/gstrfuncs.h | 2 +- glib/gunibreak.c | 13 +++ glib/guniprop.c | 110 +++++++++++++++++- glib/gutf8.c | 33 +++++- glib/gwin32.c | 4 + gqsort.c | 17 ++- gstrfuncs.c | 4 +- gstrfuncs.h | 2 +- gunibreak.c | 13 +++ guniprop.c | 110 +++++++++++++++++- gutf8.c | 33 +++++- gwin32.c | 4 + 43 files changed, 814 insertions(+), 199 deletions(-) diff --git a/ChangeLog b/ChangeLog index 405f4f3c..cc792d17 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 405f4f3c..cc792d17 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,17 @@ +2001-04-16 Havoc Pennington + + * gqsort.c: docs + + * gfileutils.c: docs + + * gwin32.c: docs fixes + + * gconvert.c: docs + + * guniprop.c: docs + + * gutf8.c: docs + 2001-04-16 Havoc Pennington * glib-2.0.m4: put AC_PATH_PROG(pkg-config) before "Checking for diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index d820e171..e28409c1 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -40,7 +40,6 @@ gsize gssize -gstring gldouble GLIB_SIZEOF_VOID_P GLIB_SIZEOF_LONG @@ -617,7 +616,6 @@ GIOFuncs 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 g_hook_list_init @@ -1043,7 +1039,6 @@ GVoidFunc GFreeFunc -GCompareFuncData g_qsort_with_data diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index f4eea22b..2bd14307 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -79,14 +79,14 @@ when they are allocated. - +Creates a new #GArray with the given size. -@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 @@ -211,21 +211,24 @@ g_array_remove_index(). - +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). -@array: -@compare_func: +@array: a #GArray +@compare_func: comparison function - +Like g_array_sort(), but the comparison function receives a user data +argument. -@array: -@compare_func: -@user_data: +@array: a #GArray +@compare_func: a comparison function +@user_data: data to pass to @compare_func diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 9d2fb839..2303e1a8 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. - +Creates a new byte array, with the given size. -@reserved_size: -@Returns: +@reserved_size: initial number of bytes in the array +@Returns: a new #GByteArray @@ -125,21 +125,23 @@ g_byte_array_remove_index(). - +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). -@array: -@compare_func: +@array: array to sort +@compare_func: comparison function - +Like g_byte_array_sort(), but the comparison function takes a user data argument. -@array: -@compare_func: -@user_data: +@array: a #GByteArray +@compare_func: comparison function +@user_data: data to pass to @compare_func diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index f44d90f9..fbe1a3d0 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. - +Creates a new #GPtrArray with @reserved_size elements. -@reserved_size: -@Returns: +@reserved_size: Initial number of elements. +@Returns: the new #GPtrArray. @@ -158,21 +158,23 @@ g_ptr_array_remove_index(). - +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). -@array: -@compare_func: +@array: array to sort +@compare_func: comparison function - +Like g_ptr_array_sort(), but the comparison function has a user data argument. -@array: -@compare_func: -@user_data: +@array: array to sort +@compare_func: qsort()-style comparison function +@user_data: data to pass to @compare_func diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index bef25d17..835ea461 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. - +Removes an element, without calling its destroy notification function. -@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 diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml index c6be2f9c..5631f91c 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. - +Removes an element, without calling its destroy notification function. -@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. diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 60f27af0..2137a148 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(). - +Number of microseconds in one second (1 million). This macro is provided for +code readability. @@ -91,10 +92,13 @@ Win32. Returns the current time. - +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. -@microseconds: +@microseconds: number of microseconds to pause diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index ebfdd05e..6e99a9b4 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. - +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. -@channel: -@condition: -@Returns: +@channel: a #GIOChannel to watch +@condition: conditions to watch for +@Returns: a new #GSource diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index 8812d8a5..fa305ccf 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. - +Deletes the node @link from @list. -@list: -@link: -@Returns: +@list: a #GList +@link: node to delete from @list +@Returns: the new head of @list @@ -270,13 +270,13 @@ value if the first element comes after the second. - +Like g_list_sort(), but the comparison function accepts a user data argument. -@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 diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index 780240fc..b75cb597 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. - +Inserts a node before @sibling containing @data. Returns the new head of the list. -@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 @@ -201,12 +201,12 @@ self-contained list with one element. - +Deletes a node of @list. Returns the new list head. -@list: -@link: -@Returns: +@list: a #GSList +@link: node to delete +@Returns: new head of @list @@ -273,13 +273,13 @@ value if the first element comes after the second. - +Like g_slist_sort(), but the sort function accepts a user data argument. -@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 diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index ba5060a8..79def9ff 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. 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. @mem: the memory to reallocate. -@n_bytes: +@n_bytes: new size of the memory in bytes @Returns: the new address of the allocated memory. @size: the new size of the allocated memory, in bytes. @@ -106,21 +107,24 @@ have been moved. - +Attempts to allocate @n_bytes, and returns %NULL on failure. +Contrast with g_malloc(), which aborts the program on failure. -@n_bytes: -@Returns: +@n_bytes: number of bytes to allocate +@Returns: the allocated memory, or %NULL - +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(). -@mem: -@n_bytes: -@Returns: +@mem: previously-allocated memory, or %NULL +@n_bytes: number of bytes to allocate +@Returns: the allocated memory, or %NULL @@ -134,10 +138,11 @@ If @mem is NULL it simply returns. - +Allocates @size bytes on the stack; these bytes will be freed when the current +stack frame is cleaned up. -@size: +@size: number of bytes to allocate @@ -171,22 +176,30 @@ is NULL. - +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. -@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 - +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. -@vtable: +@vtable: table of memory allocation routines. diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index c178f27f..1f602c66 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/docs/reference/glib/tmpl/queue.sgml @@ -3,6 +3,7 @@ Double-ended Queues +Double-ended queue data structure diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 2bcd04ae..2a87e310 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -41,11 +41,14 @@ null-terminated. - +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. -@str_array: -@Returns: +@str_array: array to copy +@Returns: a new array @@ -71,24 +74,33 @@ The returned string should be freed when no longer needed. - +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. -@dest: -@src: -@dest_size: -@Returns: +@dest: destination buffer +@src: source buffer +@dest_size: length of @dest in bytes +@Returns: length of @src - +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. -@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 @@ -332,13 +344,16 @@ character compressed. - +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)). -@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 @@ -367,8 +382,10 @@ Frees a NULL-terminated array of strings, and the array itself. -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. @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 c096bb71..f6be0043 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. -A #GString is similar to a standard C string, except that it grows -automatically as text is appended or inserted. - - -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. @@ -47,12 +44,13 @@ Creates a new #GString, initialized with the given string. - +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. -@init: -@len: -@Returns: +@init: initial contents of string +@len: length of @init to use +@Returns: a new #GString @@ -129,13 +127,14 @@ Adds a character onto the end of a #GString, expanding it if necessary. - +Appends @len bytes of @val to @string. Because @len is provided, +@val may contain embedded nuls and need not be nul-terminated. -@string: -@val: -@len: -@Returns: +@string: a #GString +@val: bytes to append +@len: number of bytes of @val to use +@Returns: the #GString @@ -160,13 +159,14 @@ Adds a character onto the start of a #GString, expanding it if necessary. - +Prepends @len bytes of @val to @string. Because @len is provided, +@val may contain embedded nuls and need not be nul-terminated. -@string: -@val: -@len: -@Returns: +@string: a #GString +@val: bytes to prepend +@len: number of bytes in @val to prepend +@Returns: the #GString passed in @@ -193,14 +193,15 @@ Inserts a character into a #GString, expanding it if necessary. - +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. -@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 @@ -256,20 +257,21 @@ Converts a #GString to lower case. - +Creates a hash code for @str; for use with #GHashTable. -@str: -@Returns: +@str: a string to hash +@Returns: hash code for @str - +Compares two strings for equality, returning %TRUE if they are equal. +For use with #GHashTable. -@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 0a05d6cc..fed2ad94 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/docs/reference/glib/tmpl/timers.sgml @@ -3,10 +3,13 @@ Timers +Keep track of elapsed time. - +#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. @@ -16,57 +19,68 @@ Timers - +Opaque datatype that records a start time. - +Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly +called for you). -@Returns: +@Returns: a new #GTimer - +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. -@timer: +@timer: a #GTimer - +Marks an end time, so calls to g_timer_elapsed() will return the difference +between this end time and the start time. -@timer: +@timer: a #GTimer - +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. -@timer: -@microseconds: -@Returns: +@timer: a #GTimer +@microseconds: return location for microseconds elapsed, or %NULL +@Returns: seconds elapsed - +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. -@timer: +@timer: a #GTimer - +Destroys a timer, freeing associated resources. -@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 c68e739e..b36bf37a 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. -Creates a new GTree. +Creates a new #GTree. @key_compare_func: the function used to order the nodes in the #GTree. @@ -64,12 +64,13 @@ second. - +Creates a new #GTree with a comparison function that accepts user data. +See g_tree_new() for more details. -@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 diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index 8916fa69..40d2424d 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. - +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). -@node: -@Returns: +@node: a #GNode +@Returns: a new #GNode containing the same data pointers diff --git a/gconvert.c b/gconvert.c index 65a4adaf..035eefae 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 1721fad1..86b33bc0 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 65a4adaf..035eefae 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 1721fad1..86b33bc0 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 c75cca31..a100735a 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 @@ -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 add39aaf..5f12e39b 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 183fecf0..e23973c1 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 6a4b8379..4f329599 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 b1513c1e..6b706b13 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 74d053fe..1e112389 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 1a948180..594fbbe9 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) diff --git a/gqsort.c b/gqsort.c index c75cca31..a100735a 100644 --- a/gqsort.c +++ b/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 @@ -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 add39aaf..5f12e39b 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 183fecf0..e23973c1 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 6a4b8379..4f329599 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 b1513c1e..6b706b13 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) diff --git a/gutf8.c b/gutf8.c index 74d053fe..1e112389 100644 --- a/gutf8.c +++ b/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/gwin32.c b/gwin32.c index 1a948180..594fbbe9 100644 --- a/gwin32.c +++ b/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) -- 2.34.1