Commit 4eab8758 authored by Havoc Pennington's avatar Havoc Pennington Committed by Havoc Pennington

docs

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
parent cc395641
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
......
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
......
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
......
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
......
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
......
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
......
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
......
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
......
......@@ -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>
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -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 ##### -->
......
......@@ -3,6 +3,7 @@ Double-ended Queues
<!-- ##### SECTION Short_Description ##### -->
Double-ended queue data structure
<!-- ##### SECTION Long_Description ##### -->
<para>
......
......@@ -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.
......
......@@ -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.