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

Some further makefile improvement.

Browse Source 
Thu Sep  7 12:35:35 2000  Owen Taylor  <otaylor@redhat.com>

        * Some further makefile improvement.

	* Restore all the docs that mysteriously vanished earlier.
This commit is contained in:
Owen Taylor 2000-09-07 16:36:56 +00:00 committed by Owen Taylor
parent 29b652941c
commit a5c0df554e
43 changed files with 5352 additions and 2047 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/reference/ChangeLog
View File

@ -1,3 +1,9 @@
Thu Sep 7 12:35:35 2000 Owen Taylor <otaylor@redhat.com>
* Some further makefile improvement.
* Restore all the docs that mysteriously vanished earlier.
Wed Sep 6 10:59:45 2000 Owen Taylor <otaylor@redhat.com>
* gobject/Makefile.am glib/Makefile.am: Improve

5
docs/reference/glib/Makefile.am
View File

@ -9,6 +9,9 @@ DOC_MAIN_SGML_FILE=glib-docs.sgml
# The directory containing the source code
DOC_SOURCE_DIR=$(top_srcdir)
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
# Headers to ignore
IGNORE_HFILES= \
gobject \
@ -110,7 +113,7 @@ html:
test -d $(srcdir)/html || mkdir $(srcdir)/html
-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
@echo '-- Fixing Crossreferences'
gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR)
gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIOJNS)
clean-local:
rm -f *~ *.bak *.signals *-unused.txt

10
docs/reference/glib/glib-sections.txt
View File

@ -110,6 +110,13 @@ CLAMP
G_STRUCT_MEMBER
G_STRUCT_MEMBER_P
G_STRUCT_OFFSET
<SUBSECTION Private>
glib_major_version
glib_micro_version
glib_minor_version
glib_interface_age
glib_binary_age
</SECTION>
<SECTION>
@ -466,6 +473,9 @@ G_LOCK_NAME
glib_dummy_decl
GSystemThread
g_thread_error_quark
g_thread_use_default_impl
g_threads_got_initialized
g_thread_functions_for_glib_use
</SECTION>
<SECTION>

43
docs/reference/glib/tmpl/allocators.sgml
View File

@ -2,11 +2,31 @@
Memory Allocators
<!-- ##### SECTION Short_Description ##### -->
allocates chunks of memory for #GList, #GSList and #GNode.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GAllocator is used as an efficient way to allocate small pieces of
memory for use with the #GList, #GSList and #GNode data structures.
It uses a #GMemChunk so elements are allocated in groups, rather than
individually.
</para>
<para>
The #GList, #GSList and #GNode implementations create default #GAllocator
objects, which are probably sufficient for most purposes. These default
allocators use blocks of 128 elements.
</para>
<para>
To use your own #GAllocator, create it with g_allocator_new(). Then
use g_list_push_allocator(), g_slist_push_allocator() or
g_node_push_allocator() before any code which allocates new #GList, #GSList
or #GNode elements respectively. After allocating the new elements, you must
use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator()
to restore the previous allocators.
</para>
<para>
Note that you cannot use the same allocator for #GList, #GSList and #GNode
elements. Each must use separate allocators.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,25 +36,30 @@ Memory Allocators
<!-- ##### STRUCT GAllocator ##### -->
<para>
The #GAllocator struct contains private data. and should only be accessed
using the following functions.
</para>
<!-- ##### FUNCTION g_allocator_new ##### -->
<para>
Creates a new #GAllocator.
</para>
@name:
@n_preallocs:
@Returns:
@name: the name of the #GAllocator. This name is used to set the name of the
#GMemChunk used by the #GAllocator, and is only used for debugging.
@n_preallocs: the number of elements in each block of memory allocated.
Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
@Returns: a new #GAllocator.
<!-- ##### FUNCTION g_allocator_free ##### -->
<para>
Frees all of the memory allocated by the #GAllocator.
</para>
@allocator:
@allocator: a #GAllocator.

205
docs/reference/glib/tmpl/arrays.sgml
View File

@ -2,12 +2,53 @@
Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of arbitrary elements which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
Arrays are similar to standard C arrays, except that they grow automatically
as elements are added.
</para>
<para>
Array elements can be of any size (though all elements of one array are the
same size), and the array can be automatically cleared to '0's and
zero-terminated.
</para>
<para>
To create a new array use g_array_new().
</para>
<para>
To add elements to an array, use g_array_append_val(), g_array_append_vals(),
g_array_prepend_val(), and g_array_prepend_vals().
</para>
<para>
To access an element of an array, use g_array_index().
</para>
<para>
To set the size of an array, use g_array_set_size().
</para>
<para>
To free an array, use g_array_free().
</para>
<example>
<title>Using a GArray to store gint values.</title>
<programlisting>
GArray *garray;
gint i;
/* We create a new array to store gint values.
We don't want it zero-terminated or cleared to 0's. */
garray = g_array_new (FALSE, FALSE, sizeof (gint));
for (i = 0; i < 10000; i++)
g_array_append_val (garray, i);
for (i = 0; i < 10000; i++)
if (g_array_index (garray, gint, i) != i)
g_print ("ERROR: got %d instead of %d\n",
g_array_index (garray, gint, i), i);
g_array_free (garray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,21 +57,24 @@ Arrays
<!-- ##### STRUCT GArray ##### -->
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
</para>
@data:
@len:
@data: a pointer to the element data. The data may be moved as elements are
added to the #GArray.
@len: the number of elements in the #GArray.
<!-- ##### FUNCTION g_array_new ##### -->
<para>
Creates a new #GArray.
</para>
@zero_terminated:
@clear:
@element_size:
@Returns:
@zero_terminated: TRUE if the array should have an extra element at the end
which is set to '0'.
@clear: TRUE if #GArray elements should be automatically cleared to '0'
when they are allocated.
@element_size: the size of each element in bytes.
@Returns: the new #GArray.
<!-- ##### FUNCTION g_array_sized_new ##### -->
@ -47,113 +91,166 @@ Arrays
<!-- ##### MACRO g_array_append_val ##### -->
<para>
Adds the value on to the end of the array.
The array will grow in size automatically if necessary.
</para>
<note>
<para>
g_array_append_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@v:
@a: a #GArray.
@v: the value to append to the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_append_vals ##### -->
<para>
Adds @len elements onto the end of the array.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GArray.
@data: a pointer to the elements to append to the end of the array.
@len: the number of elements to append.
@Returns: the #GArray.
<!-- ##### MACRO g_array_prepend_val ##### -->
<para>
Adds the value on to the start of the array.
The array will grow in size automatically if necessary.
</para>
<para>
This operation is slower than g_array_append_val() since the existing elements
in the array have to be moved to make space for the new element.
</para>
<note>
<para>
g_array_prepend_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@v:
@a: a #GArray.
@v: the value to prepend to the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_prepend_vals ##### -->
<para>
Adds @len elements onto the start of the array.
</para>
<para>
This operation is slower than g_array_append_vals() since the existing elements
in the array have to be moved to make space for the new elements.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GArray.
@data: a pointer to the elements to prepend to the start of the array.
@len: the number of elements to prepend.
@Returns: the #GArray.
<!-- ##### MACRO g_array_insert_val ##### -->
<para>
Inserts an element into an array at the given index.
</para>
<note>
<para>
g_array_insert_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@i:
@v:
@a: a #GArray.
@i: the index to place the element at.
@v: the value to insert into the array.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_insert_vals ##### -->
<para>
Inserts @len elements into a #GArray at the given index.
</para>
@array:
@index:
@data:
@len:
@Returns:
@array: a #GArray.
@index: the index to place the elements at.
@data: a pointer to the elements to insert.
@len: the number of elements to insert.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index ##### -->
<para>
Removes the element at the given index from a #GArray.
The following elements are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GArray.
@index: the index of the element to remove.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index_fast ##### -->
<para>
Removes the element at the given index from a #GArray.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the #GArray. But it is faster than
g_array_remove_index().
</para>
@array:
@index:
@Returns:
@array: a @GArray.
@index: the index of the element to remove.
@Returns: the #GArray.
<!-- ##### MACRO g_array_index ##### -->
<para>
Returns the element of a #GArray at the given index.
The return value is cast to the given type.
<example>
<title>Getting a pointer to an element in a GArray.</title>
<programlisting>
EDayViewEvent *event;
/* This gets a pointer to the 3rd element in the array of EDayViewEvent
structs. */
event = &amp;g_array_index (events, EDayViewEvent, 3);
</programlisting>
</example>
</para>
@a:
@t:
@i:
@a: a #GArray.
@t: the type of the elements.
@i: the index of the element to return.
@Returns: the element of the #GArray at the index given by @i.
<!-- ##### FUNCTION g_array_set_size ##### -->
<para>
Sets the size of the array, expanding it if necessary.
If the array was created with clear set to TRUE, the new elements are set to 0.
</para>
@array:
@length:
@Returns:
@array: a #GArray.
@length: the new size of the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_free ##### -->
<para>
Frees the memory allocated for the #GArray.
If free_segment is TRUE it frees the actual element data as well.
</para>
@array:
@free_segment:
@array: a #GArray.
@free_segment: if TRUE the actual element data is freed as well.
@Returns:

107
docs/reference/glib/tmpl/arrays_byte.sgml
View File

@ -2,12 +2,47 @@
Byte Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of bytes, which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
GByteArray is based on #GArray, to provide arrays of bytes which grow
automatically as elements are added.
</para>
<para>
To create a new #GByteArray use g_byte_array_new().
</para>
<para>
To add elements to a #GByteArray, use g_byte_array_append(), and
g_byte_array_prepend().
</para>
<para>
To set the size of a GByteArray, use g_byte_array_set_size().
</para>
<para>
To free a GByteArray, use g_byte_array_free().
</para>
<example>
<title>Using a GByteArray.</title>
<programlisting>
GByteArray *gbarray;
gint i;
gbarray = g_byte_array_new ();
for (i = 0; i < 10000; i++)
g_byte_array_append (gbarray, (guint8*) "abcd", 4);
for (i = 0; i < 10000; i++)
{
g_assert (gbarray->data[4*i] == 'a');
g_assert (gbarray->data[4*i+1] == 'b');
g_assert (gbarray->data[4*i+2] == 'c');
g_assert (gbarray->data[4*i+3] == 'd');
}
g_byte_array_free (gbarray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,18 +51,19 @@ Byte Arrays
<!-- ##### STRUCT GByteArray ##### -->
<para>
The #GByteArray struct allows access to the public fields of a #GByteArray.
</para>
@data:
@len:
@data: a pointer to the element data. The data may be moved as elements are
added to the #GByteArray.
@len: the number of elements in the #GByteArray.
<!-- ##### FUNCTION g_byte_array_new ##### -->
<para>
Creates a new #GByteArray.
</para>
@Returns:
@Returns: the new #GByteArray.
<!-- ##### FUNCTION g_byte_array_sized_new ##### -->
@ -41,63 +77,70 @@ Byte Arrays
<!-- ##### FUNCTION g_byte_array_append ##### -->
<para>
Adds the given bytes to the end of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_prepend ##### -->
<para>
Adds the given data to the start of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The following bytes are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GByteArray.
@index: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the #GByteArray. But it is faster than
g_byte_array_remove_index().
</para>
@array:
@index:
@Returns:
@array: a #GByteArray.
@index: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
<para>
Sets the size of the #GByteArray, expanding it if necessary.
</para>
@array:
@length:
@Returns:
@array: a #GByteArray.
@length: the new size of the #GByteArray.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
Frees the memory allocated by the #GByteArray.
If free_segment is TRUE it frees the actual byte data.
</para>
@array:
@free_segment:
@array: a #GByteArray.
@free_segment: if TRUE the actual byte data is freed as well.
@Returns:

136
docs/reference/glib/tmpl/arrays_pointer.sgml
View File

@ -2,12 +2,58 @@
Pointer Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of pointers to any type of data, which grow automatically as new
elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
Pointer Arrays are similar to Arrays but are used only for storing pointers.
</para>
<note>
<para>
If you remove elements from the array, elements at the end of the array
are moved into the space previously occupied by the removed element.
This means that you should not rely on the index of particular elements
remaining the same. You should also be careful when deleting elements while
iterating over the array.
</para>
</note>
<para>
To create a pointer array, use g_ptr_array_new().
</para>
<para>
To add elements to a pointer array, use g_ptr_array_add().
</para>
<para>
To remove elements from a pointer array, use g_ptr_array_remove(),
g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
</para>
<para>
To access an element of a pointer array, use g_ptr_array_index().
</para>
<para>
To set the size of a pointer array, use g_ptr_array_set_size().
</para>
<para>
To free a pointer array, use g_ptr_array_free().
</para>
<example>
<title>Using a GPtrArray.</title>
<programlisting>
GPtrArray *gparray;
gchar *string1 = "one", *string2 = "two", *string3 = "three";
gparray = g_ptr_array_new ();
g_ptr_array_add (gparray, (gpointer) string1);
g_ptr_array_add (gparray, (gpointer) string2);
g_ptr_array_add (gparray, (gpointer) string3);
if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
g_print ("ERROR: got %p instead of %p\n",
g_ptr_array_index (gparray, 0), string1);
g_ptr_array_free (gparray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,7 +62,11 @@ Pointer Arrays
<!-- ##### STRUCT GPtrArray ##### -->
<para>
Contains the public fields of a pointer array.
The <structfield>pdata</structfield> field points to the array of pointers,
which may as when the array grows.
The <structfield>len</structfield> field is the number of pointers in the
array.
</para>
@pdata:
@ -24,10 +74,10 @@ Pointer Arrays
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>
Creates a new #GPtrArray.
</para>
@Returns:
@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
@ -41,78 +91,98 @@ Pointer Arrays
<!-- ##### FUNCTION g_ptr_array_add ##### -->
<para>
Adds a pointer to the end of the pointer array.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@array: a #GPtrArray.
@data: the pointer to add.
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The following elements are moved down one place.
</para>
<para>
It returns TRUE if the pointer was removed, or FALSE if the pointer
was not found.
</para>
@array:
@data:
@Returns:
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
<para>
Removes the pointer at the given index from the pointer array.
The following elements are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GPtrArray.
@index: the index of the pointer to remove.
@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
g_ptr_array_remove().
</para>
<para>
It returns TRUE if the pointer was removed, or FALSE if the pointer
was not found.
</para>
@array:
@data:
@Returns:
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: TRUE if the pointer was found in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
<para>
Removes the pointer at the given index from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
g_ptr_array_remove_index().
</para>
@array:
@index:
@Returns:
@array: a #GPtrArray.
@index: the index of the pointer to remove.
@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
<para>
Sets the size of the array, expanding it if necessary.
New elements are set to NULL.
</para>
@array:
@length:
@array: a #GPtrArray.
@length: the new length of the pointer array.
<!-- ##### MACRO g_ptr_array_index ##### -->
<para>
Returns the pointer at the given index of the pointer array.
</para>
@array:
@index:
@array: a #GPtrArray.
@index: the index of the pointer to return.
@Returns: the pointer at the given index.
<!-- ##### FUNCTION g_ptr_array_free ##### -->
<para>
Frees all of the memory allocated for the pointer array.
</para>
@array:
@free_seg:
@array: a #GPtrArray.
@free_seg: if TRUE the actual element data is freed as well.
@Returns:

309
docs/reference/glib/tmpl/byte_order.sgml
View File

@ -2,11 +2,41 @@
Byte Order Macros
<!-- ##### SECTION Short_Description ##### -->
a portable way to convert between different byte orders.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a portable way to determine the host byte order
and to convert values between different byte orders.
</para>
<para>
The byte order is the order in which bytes are stored to create larger
data types such as the #gint and #glong values.
The host byte order is the byte order used on the current machine.
</para>
<para>
Some processors store the most significant bytes (i.e. the bytes that
hold the largest part of the value) first. These are known as big-endian
processors.
</para>
<para>
Other processors (notably the x86 family) store the most significant byte
last. These are known as little-endian processors.
</para>
<para>
Finally, to complicate matters, some other processors store the bytes in
a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
most significant byte is stored first, then the 4th, then the 1st and finally
the 2nd.
</para>
<para>
Obviously there is a problem when these different processors communicate
with each other, for example over networks or by using binary file formats.
This is where these macros come in.
They are typically used to convert values into a byte order
which has been agreed on for use when communicating between different
processors. The Internet uses what is known as 'network byte order'
as the standard byte order (which is in fact the big-endian byte order).
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,437 +46,500 @@ Byte Order Macros
<!-- ##### MACRO G_BYTE_ORDER ##### -->
<para>
The host byte order.
This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
#G_PDP_ENDIAN may be added in future.)
</para>
<!-- ##### MACRO G_LITTLE_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order.
See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO G_BIG_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order.
See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO G_PDP_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order (currently unused).
See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO g_htonl ##### -->
<para>
Converts a 32-bit integer value from host to network byte order.
</para>
@val:
@val: a 32-bit integer value in host byte order.
@Returns: @val converted to network byte order.
<!-- ##### MACRO g_htons ##### -->
<para>
Converts a 16-bit integer value from host to network byte order.
</para>
@val:
@val: a 16-bit integer value in host byte order.
@Returns: @val converted to network byte order.
<!-- ##### MACRO g_ntohl ##### -->
<para>
Converts a 32-bit integer value from network to host byte order.
</para>
@val:
@val: a 32-bit integer value in network byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO g_ntohs ##### -->
<para>
Converts a 16-bit integer value from network to host byte order.
</para>
@val:
@val: a 16-bit integer value in network byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_FROM_BE ##### -->
<para>
Converts a #gint value from big-endian to host byte order.
</para>
@val:
@val: a #gint value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_FROM_LE ##### -->
<para>
Converts a #gint value from little-endian to host byte order.
</para>
@val:
@val: a #gint value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_TO_BE ##### -->
<para>
Converts a #gint value from host byte order to big-endian.
</para>
@val:
@val: a #gint value in host byte order.
@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GINT_TO_LE ##### -->
<para>
Converts a #gint value from host byte order to little-endian.
</para>
@val:
@val: a #gint value in host byte order.
@Returns: @val converted to little-endian byte order.
<!-- ##### MACRO GUINT_FROM_BE ##### -->
<para>
Converts a #guint value from big-endian to host byte order.
</para>
@val:
@val: a #guint value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT_FROM_LE ##### -->
<para>
Converts a #guint value from little-endian to host byte order.
</para>
@val:
@val: a #guint value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT_TO_BE ##### -->
<para>
Converts a #guint value from host byte order to big-endian.
</para>
@val:
@val: a #guint value in host byte order.
@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GUINT_TO_LE ##### -->
<para>
Converts a #guint value from host byte order to little-endian.
</para>
@val:
@val: a #guint value in host byte order.
@Returns: @val converted to little-endian byte order.
<!-- ##### MACRO GLONG_FROM_BE ##### -->
<para>
Converts a #glong value from big-endian to the host byte order.
</para>
@val:
@val: a #glong value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GLONG_FROM_LE ##### -->
<para>
Converts a #glong value from little-endian to host byte order.
</para>
@val:
@val: a #glong value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GLONG_TO_BE ##### -->
<para>
Converts a #glong value from host byte order to big-endian.
</para>
@val:
@val: a #glong value in host byte order.
@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GLONG_TO_LE ##### -->
<para>
Converts a #glong value from host byte order to little-endian.
</para>
@val:
@val: a #glong value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GULONG_FROM_BE ##### -->
<para>
Converts a #gulong value from big-endian to host byte order.
</para>
@val:
@val: a #gulong value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GULONG_FROM_LE ##### -->
<para>
Converts a #gulong value from little-endian to host byte order.
</para>
@val:
@val: a #gulong value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GULONG_TO_BE ##### -->
<para>
Converts a #gulong value from host byte order to big-endian.
</para>
@val:
@val: a #gulong value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GULONG_TO_LE ##### -->
<para>
Converts a #gulong value from host byte order to little-endian.
</para>
@val:
@val: a #gulong value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT16_FROM_BE ##### -->
<para>
Converts a #gint16 value from big-endian to host byte order.
</para>
@val:
@val: a #gint16 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT16_FROM_LE ##### -->
<para>
Converts a #gint16 value from little-endian to host byte order.
</para>
@val:
@val: a #gint16 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT16_TO_BE ##### -->
<para>
Converts a #gint16 value from host byte order to big-endian.
</para>
@val:
@val: a #gint16 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT16_TO_LE ##### -->
<para>
Converts a #gint16 value from host byte order to little-endian.
</para>
@val:
@val: a #gint16 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT16_FROM_BE ##### -->
<para>
Converts a #guint16 value from big-endian to host byte order.
</para>
@val:
@val: a #guint16 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT16_FROM_LE ##### -->
<para>
Converts a #guint16 value from little-endian to host byte order.
</para>
@val:
@val: a #guint16 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT16_TO_BE ##### -->
<para>
Converts a #guint16 value from host byte order to big-endian.
</para>
@val:
@val: a #guint16 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT16_TO_LE ##### -->
<para>
Converts a #guint16 value from host byte order to little-endian.
</para>
@val:
@val: a #guint16 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT32_FROM_BE ##### -->
<para>
Converts a #gint32 value from big-endian to host byte order.
</para>
@val:
@val: a #gint32 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT32_FROM_LE ##### -->
<para>
Converts a #gint32 value from little-endian to host byte order.
</para>
@val:
@val: a #gint32 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT32_TO_BE ##### -->
<para>
Converts a #gint32 value from host byte order to big-endian.
</para>
@val:
@val: a #gint32 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT32_TO_LE ##### -->
<para>
Converts a #gint32 value from host byte order to little-endian.
</para>
@val:
@val: a #gint32 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT32_FROM_BE ##### -->
<para>
Converts a #guint32 value from big-endian to host byte order.
</para>
@val:
@val: a #guint32 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT32_FROM_LE ##### -->
<para>
Converts a #guint32 value from little-endian to host byte order.
</para>
@val:
@val: a #guint32 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT32_TO_BE ##### -->
<para>
Converts a #guint32 value from host byte order to big-endian.
</para>
@val:
@val: a #guint32 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT32_TO_LE ##### -->
<para>
Converts a #guint32 value from host byte order to little-endian.
</para>
@val:
@val: a #guint32 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT64_FROM_BE ##### -->
<para>
Converts a #gint64 value from big-endian to host byte order.
</para>
@val:
@val: a #gint64 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT64_FROM_LE ##### -->
<para>
Converts a #gint64 value from little-endian to host byte order.
</para>
@val:
@val: a #gint64 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT64_TO_BE ##### -->
<para>
Converts a #gint64 value from host byte order to big-endian.
</para>
@val:
@val: a #gint64 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT64_TO_LE ##### -->
<para>
Converts a #gint64 value from host byte order to little-endian.
</para>
@val:
@val: a #gint64 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT64_FROM_BE ##### -->
<para>
Converts a #guint64 value from big-endian to host byte order.
</para>
@val:
@val: a #guint64 value in big-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT64_FROM_LE ##### -->
<para>
Converts a #guint64 value from little-endian to host byte order.
</para>
@val:
@val: a #guint64 value in little-endian byte order.
@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT64_TO_BE ##### -->
<para>
Converts a #guint64 value from host byte order to big-endian.
</para>
@val:
@val: a #guint64 value in host byte order.
@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT64_TO_LE ##### -->
<para>
Converts a #guint64 value from host byte order to little-endian.
</para>
@val:
@val: a #guint64 value in host byte order.
@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT16_SWAP_BE_PDP ##### -->
<para>
Converts a #guint16 value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint16 value in big-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT16_SWAP_LE_BE ##### -->
<para>
Converts a #guint16 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint16 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT16_SWAP_LE_PDP ##### -->
<para>
Converts a #guint16 value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint16 value in little-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_BE_PDP ##### -->
<para>
Converts a #guint32 value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint32 value in big-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_LE_BE ##### -->
<para>
Converts a #guint32 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint32 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_LE_PDP ##### -->
<para>
Converts a #guint32 value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint32 value in little-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT64_SWAP_LE_BE ##### -->
<para>
Converts a #guint64 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>
@val:
@val: a #guint64 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.

114
docs/reference/glib/tmpl/caches.sgml
View File

@ -2,11 +2,23 @@
Caches
<!-- ##### SECTION Short_Description ##### -->
allows sharing of complex data structures to save resources.
<!-- ##### SECTION Long_Description ##### -->
<para>
A #GCache allows sharing of complex data structures, in order to save
system resources.
</para>
<para>
GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
resouces, so a #GCache is used to see if a GtkStyle or GdkGC with the
required properties already exists. If it does, then the existing
GtkStyle or GdkGC is used instead of creating a new one.
</para>
<para>
#GCache uses keys and values.
A #GCache key describes the properties of a particular resource.
A #GCache value is the actual resource.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,47 +28,70 @@ Caches
<!-- ##### STRUCT GCache ##### -->
<para>
The #GCache struct is an opaque data structure containing information about
a #GCache. It should only be accesssed via the following functions.
</para>
<!-- ##### FUNCTION g_cache_new ##### -->
<para>
Creates a new GCache.
</para>
@value_new_func:
@value_destroy_func:
@key_dup_func:
@key_destroy_func:
@hash_key_func:
@hash_value_func:
@key_compare_func:
@Returns:
@value_new_func: a function to create a new object given a key.
This is called by g_cache_insert() if an object with the given key
does not already exist.
@value_destroy_func: a function to destroy an object. It is
called by g_cache_remove() when the object is no longer needed (i.e. its
reference count drops to 0).
@key_dup_func: a function to copy a key. It is called by
g_cache_insert() if the key does not already exist in the GCache.
@key_destroy_func: a function to destroy a key. It is
called by g_cache_remove() when the object is no longer needed (i.e. its
reference count drops to 0).
@hash_key_func: a function to create a hash value from a key.
@hash_value_func: a function to create a hash value from a value.
@key_compare_func: a function to compare two keys. It should return TRUE if
the two keys are equivalent.
@Returns: a new #GCache.
<!-- ##### FUNCTION g_cache_insert ##### -->
<para>
Gets the value corresponding to the given key, creating it if necessary.
It first checks if the value already exists in the #GCache, by using
the @key_compare_func function passed to g_cache_new().
If it does already exist it is returned, and its reference count is increased
by one.
If the value does not currently exist, if is created by calling the
@value_new_func. The key is duplicated by calling
@key_dup_func and the duplicated key and value are inserted
into the #GCache.
</para>
@cache:
@key:
@Returns:
@cache: a #GCache.
@key: a key describing a #GCache object.
@Returns: a pointer to a #GCache value.
<!-- ##### FUNCTION g_cache_remove ##### -->
<para>
Decreases the reference count of the given value.
If it drops to 0 then the value and its corresponding key are destroyed,
using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
</para>
@cache:
@value:
@cache: a #GCache.
@value: the value to remove.
<!-- ##### FUNCTION g_cache_destroy ##### -->
<para>
Frees the memory allocated for the GCache.
</para>
<para>
Note that it does not destroy the keys and values which were contained in the
GCache.
</para>
@cache:
@ -64,47 +99,54 @@ Caches
<!-- ##### FUNCTION g_cache_key_foreach ##### -->
<para>
Calls the given function for each of the keys in the #GCache.
</para>
@cache:
@func:
@user_data:
@cache: a #GCache.
@func: the function to call with each #GCache key.
@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_cache_value_foreach ##### -->
<para>
Calls the given function for each of the values in the #GCache.
</para>
@cache:
@func:
@user_data:
@cache: a #GCache.
@func: the function to call with each #GCache value.
@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GCacheDestroyFunc ##### -->
<para>
Specifies the type of the @value_destroy_func and @key_destroy_func functions
passed to g_cache_new().
The functions are passed a pointer to the #GCache key or #GCache value and
should free any memory and other resources associated with it.
</para>
@value:
@value: the #GCache value to destroy.
<!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
<para>
Specifies the type of the @key_dup_func function passed to g_cache_new().
The function is passed a key (NOT a value as the prototype implies) and
should return a duplicate of the key.
</para>
@value:
@Returns:
@value: the #GCache key to destroy (NOT a #GCache value as it seems).
@Returns: a copy of the #GCache key.
<!-- ##### USER_FUNCTION GCacheNewFunc ##### -->
<para>
Specifies the type of the @value_new_func function passed to g_cache_new().
It is passed a #GCache key and should create the value corresponding to the
key.
</para>
@key:
@Returns:
@key: a #GCache key.
@Returns: a new #GCache value corresponding to the key.

80
docs/reference/glib/tmpl/completion.sgml
View File

@ -2,11 +2,27 @@
Automatic String Completion
<!-- ##### SECTION Short_Description ##### -->
support for automatic completion using a group of target strings.
<!-- ##### SECTION Long_Description ##### -->
<para>
#GCompletion provides support for automatic completion of a string using
any group of target strings. It is typically used for file name completion
as is common in many Unix shells.
</para>
<para>
A #GCompletion is created using g_completion_new().
Target items are added and removed with
g_completion_add_items(), g_completion_remove_items() and
g_completion_clear_items().
A completion attempt is requested with g_completion_complete().
When no longer needed, the #GCompletion is freed with g_completion_free().
</para>
<para>
Items in the completion can be simple strings (e.g. file names),
or pointers to arbitrary data structures. If data structures are used
you must provide a #GCompletionFunc in g_completion_new(),
which retrieves the item's string from the data structure.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +32,15 @@ Automatic String Completion
<!-- ##### STRUCT GCompletion ##### -->
<para>
The data structure used for automatic completion.
<structfield>items</structfield> is the list of target items (strings
or data structures).
<structfield>func</structfield> is the function called to get the string
associated with a target item. It is NULL if the target items are strings.
<structfield>prefix</structfield> is the last prefix passed to
g_completion_complete().
<structfield>cache</structfield> is the list of items which begin with
<structfield>prefix</structfield>.
</para>
@items:
@ -26,64 +50,72 @@ Automatic String Completion
<!-- ##### FUNCTION g_completion_new ##### -->
<para>
Creates a new #GCompletion.
</para>
@func:
@Returns:
@func: the function to be called to return the string representing an item
in the #GCompletion, or NULL if strings are going to be used as the
#GCompletion items.
@Returns: the new #GCompletion.
<!-- ##### USER_FUNCTION GCompletionFunc ##### -->
<para>
Specifies the type of the function passed to g_completion_new().
It should return the string corresponding to the given target item.
This is used when you use data structures as #GCompletion items.
</para>
@Param1:
@Returns:
@Param1: the completion item.
@Returns: the string corresponding to the item.
<!-- ##### FUNCTION g_completion_add_items ##### -->
<para>
Adds items to the #GCompletion.
</para>
@cmp:
@items:
@cmp: the #GCompletion.
@items: the list of items to add.
<!-- ##### FUNCTION g_completion_remove_items ##### -->
<para>
Removes items from a #GCompletion.
</para>
@cmp:
@items:
@cmp: the #GCompletion.
@items: the items to remove.
<!-- ##### FUNCTION g_completion_clear_items ##### -->
<para>
Removes all items from the #GCompletion.
</para>
@cmp:
@cmp: the #GCompletion.
<!-- ##### FUNCTION g_completion_complete ##### -->
<para>
Attempts to complete the string @prefix using the #GCompletion target items.
</para>
@cmp:
@prefix:
@new_prefix:
@Returns:
@cmp: the #GCompletion.
@prefix: the prefix string, typically typed by the user, which is compared
with each of the items.
@new_prefix: if non-NULL, returns the longest prefix which is common to all
items that matched @prefix, or NULL if no items matched @prefix.
This string should be freed when no longer needed.
@Returns: the list of items whose strings begin with @prefix. This should
not be changed.
<!-- ##### FUNCTION g_completion_free ##### -->
<para>
Frees all memory used by the #GCompletion.
</para>
@cmp:
@cmp: the #GCompletion.

134
docs/reference/glib/tmpl/datalist.sgml
View File

@ -2,11 +2,43 @@
Keyed Data Lists
<!-- ##### SECTION Short_Description ##### -->
lists of data elements which are accessible by a string or #GQuark identifier.
<!-- ##### SECTION Long_Description ##### -->
<para>
Keyed data lists provide lists of arbitrary data elements which can be accessed
either with a string or with a #GQuark corresponding to the string.
</para>
<para>
The GQuark methods are quicker, since the strings have to be converted to
GQuarks anyway.
</para>
<para>
Data lists are used in GTK for associating arbitrary data with
GtkObjects, using gtk_object_set_data() and related functions.
</para>
<para>
To create a datalist, use g_datalist_init().
</para>
<para>
To add data elements to a datalist use g_datalist_id_set_data(),
g_datalist_id_set_data_full(), g_datalist_set_data()
and g_datalist_set_data_full().
</para>
<para>
To get data elements from a datalist use g_datalist_id_get_data() and
g_datalist_get_data().
</para>
<para>
To iterate over all data elements in a datalist use g_datalist_foreach().
</para>
<para>
To remove data elements from a datalist use g_datalist_id_remove_data() and
g_datalist_remove_data().
</para>
<para>
To remove all data elements from a datalist, use g_datalist_clear().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,56 +48,66 @@ Keyed Data Lists
<!-- ##### STRUCT GData ##### -->
<para>
The #GData struct is an opaque data structure to represent a
<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_datalist_init ##### -->
<para>
Resets the datalist to NULL.
It does not free any memory or call any destroy functions.
</para>
@datalist:
@datalist: a pointer to a pointer to a datalist.
<!-- ##### MACRO g_datalist_id_set_data ##### -->
<para>
Sets the data corresponding to the given #GQuark id.
Any previous data with the same key is removed, and its
destroy function is called.
</para>
@dl:
@q:
@d:
@dl: a datalist.
@q: the #GQuark to identify the data element.
@d: the data element.
<!-- ##### FUNCTION g_datalist_id_set_data_full ##### -->
<para>
Sets the data corresponding to the given #GQuark id, and the function to
be called when the element is removed from the datalist.
Any previous data with the same key is removed, and its
destroy function is called.
</para>
@datalist:
@key_id:
@data:
@destroy_func:
@datalist: a datalist.
@key_id: the #GQuark to identify the data element.
@data: the data element.
@destroy_func: the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.
<!-- ##### FUNCTION g_datalist_id_get_data ##### -->
<para>
Gets a data element.
</para>
@datalist:
@key_id:
@Returns:
@datalist: a datalist.
@key_id: the #GQuark identifying a data element.
@Returns: the data element, or NULL if it is not found.
<!-- ##### MACRO g_datalist_id_remove_data ##### -->
<para>
Removes an element, using its #GQuark identifier.
</para>
@dl:
@q:
@dl: a datalist.
@q: the #GQuark identifying the data element.
<!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### -->
@ -80,41 +122,48 @@ Keyed Data Lists
<!-- ##### MACRO g_datalist_set_data ##### -->
<para>
Sets the data element corresponding to the given string identifier.
</para>
@dl:
@k:
@d:
@dl: a datalist.
@k: the string to identify the data element.
@d: the data element.
<!-- ##### MACRO g_datalist_set_data_full ##### -->
<para>
Sets the data element corresponding to the given string identifier, and the
function to be called when the data element is removed.
</para>
@dl:
@k:
@d:
@f:
@dl: a datalist.
@k: the string to identify the data element.
@d: the data element.
@f: the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.
<!-- ##### MACRO g_datalist_get_data ##### -->
<para>
Gets a data element, using its string identifer.
This is slower than g_datalist_id_get_data() because the string is first
converted to a #GQuark.
</para>
@dl:
@k:
@dl: a datalist.
@k: the string identifying a data element.
@Returns: the data element, or NULL if it is not found.
<!-- ##### MACRO g_datalist_remove_data ##### -->
<para>
Removes an element using its string identifier.
The data element's destroy function is called if it has been set.
</para>
@dl:
@k:
@dl: a datalist.
@k: the string identifying the data element.
<!-- ##### MACRO g_datalist_remove_no_notify ##### -->
@ -128,19 +177,22 @@ Keyed Data Lists
<!-- ##### FUNCTION g_datalist_foreach ##### -->
<para>
Calls the given function for each data element of the datalist.
The function is called with each data element's #GQuark id and data,
together with the given @user_data parameter.
</para>
@datalist:
@func:
@user_data:
@datalist: a datalist.
@func: the function to call for each data element.
@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_datalist_clear ##### -->
<para>
Frees all the data elements of the datalist.
The data elements' destroy functions are called if they have been set.
</para>
@datalist:
@datalist: a datalist.

146
docs/reference/glib/tmpl/datasets.sgml
View File

@ -2,11 +2,46 @@
Datasets
<!-- ##### SECTION Short_Description ##### -->
associate groups of data elements with particular memory locations.
<!-- ##### SECTION Long_Description ##### -->
<para>
Datasets associate groups of data elements with particular memory locations.
These are useful if you need to associate data with a structure returned
from an external library. Since you cannot modify the structure, you use
its location in memory as the key into a dataset, where you can associate
any number of data elements with it.
</para>
<para>
There are two forms of most of the dataset functions.
The first form uses strings to identify the data elements associated with
a location. The second form uses #GQuark identifiers, which are created
with a call to g_quark_from_string() or g_quark_from_static_string().
The second form is quicker, since it does not require looking up the string
in the hash table of #GQuark identifiers.
</para>
<para>
There is no function to create a dataset. It is automatically created as
soon as you add elements to it.
</para>
<para>
To add data elements to a dataset use g_dataset_id_set_data(),
g_dataset_id_set_data_full(), g_dataset_set_data()
and g_dataset_set_data_full().
</para>
<para>
To get data elements from a dataset use g_dataset_id_get_data() and
g_dataset_get_data().
</para>
<para>
To iterate over all data elements in a dataset use g_dataset_foreach().
</para>
<para>
To remove data elements from a dataset use g_dataset_id_remove_data() and
g_dataset_remove_data().
</para>
<para>
To destroy a dataset, use g_dataset_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,50 +51,61 @@ Datasets
<!-- ##### MACRO g_dataset_id_set_data ##### -->
<para>
Sets the data element associated with the given #GQuark id.
Any previous data with the same key is removed, and its destroy function
is called.
</para>
@l:
@k:
@d:
@l: the location identifying the dataset.
@k: the #GQuark id to identify the data element.
@d: the data element.
<!-- ##### FUNCTION g_dataset_id_set_data_full ##### -->
<para>
Sets the data element associated with the given #GQuark id, and also the
function to call when the data element is destroyed.
Any previous data with the same key is removed, and its
destroy function is called.
</para>
@dataset_location:
@key_id:
@data:
@destroy_func:
@dataset_location: the location identifying the dataset.
@key_id: the #GQuark id to identify the data element.
@data: the data element.
@destroy_func: the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.
<!-- ##### USER_FUNCTION GDestroyNotify ##### -->
<para>
Specifies the type of function which is called when a data element is
destroyed. It is passed the pointer to the data element and should free
any memory and resources allocated for it.
</para>
@data:
@data: the data element.
<!-- ##### FUNCTION g_dataset_id_get_data ##### -->
<para>
Gets the data element corresponding to a #GQuark.
</para>
@dataset_location:
@key_id:
@Returns:
@dataset_location: the location identifying the dataset.
@key_id: the #GQuark id to identify the data element.
@Returns: the data element corresponding to the #GQuark, or NULL if it is
not found.
<!-- ##### MACRO g_dataset_id_remove_data ##### -->
<para>
Removes a data element from a dataset.
The data element's destroy function is called if it has been set.
</para>
@l:
@k:
@l: the location identifying the dataset.
@k: the #GQuark id identifying the data element.
<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### -->
@ -74,41 +120,47 @@ Datasets
<!-- ##### MACRO g_dataset_set_data ##### -->
<para>
Sets the data corresponding to the given string identifier.
</para>
@l:
@k:
@d:
@l: the location identifying the dataset.
@k: the string to identify the data element.
@d: the data element.
<!-- ##### MACRO g_dataset_set_data_full ##### -->
<para>
Sets the data corresponding to the given string identifier, and the function
to call when the data element is destroyed.
</para>
@l:
@k:
@d:
@f:
@l: the location identifying the dataset.
@k: the string to identify the data element.
@d: the data element.
@f: the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.
<!-- ##### MACRO g_dataset_get_data ##### -->
<para>
Gets the data element corresponding to a string.
</para>
@l:
@k:
@l: the location identifying the dataset.
@k: the string identifying the data element.
@Returns: the data element corresponding to the string, or NULL if it is not
found.
<!-- ##### MACRO g_dataset_remove_data ##### -->
<para>
Removes a data element corresponding to a string.
Its destroy function is called if it has been set.
</para>
@l:
@k:
@l: the location identifying the dataset.
@k: the string identifying the data element.
<!-- ##### MACRO g_dataset_remove_no_notify ##### -->
@ -122,29 +174,33 @@ Datasets
<!-- ##### FUNCTION g_dataset_foreach ##### -->
<para>
Calls the given function for each data element which is associated with the
given location.
</para>
@dataset_location:
@func:
@user_data:
@dataset_location: the location identifying the dataset.
@func: the function to call for each data element.
@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GDataForeachFunc ##### -->
<para>
Specifies the type of function passed to g_dataset_foreach().
It is called with each #GQuark id and associated data element,
together with the @user_data parameter supplied to g_dataset_foreach().
</para>
@key_id:
@data:
@user_data:
@key_id: the #GQuark id to identifying the data element.
@data: the data element.
@user_data: user data passed to g_dataset_foreach().
<!-- ##### FUNCTION g_dataset_destroy ##### -->
<para>
Destroys the dataset, freeing all memory allocated, and calling any
destroy functions set for data elements.
</para>
@dataset_location:
@dataset_location: the location identifying the dataset.

554
docs/reference/glib/tmpl/date.sgml
View File

@ -2,16 +2,65 @@
Date and Time Functions
<!-- ##### SECTION Short_Description ##### -->
calendrical calculations and miscellaneous time stuff.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
The #GDate data structure represents a day between January 1, Year 1,
and sometime a few thousand years in the future (right now it will go
to the year 65535 or so, but g_date_set_parse() only parses up to the
year 8000 or so - just count on "a few thousand"). #GDate is meant to
represent everyday dates, not astronomical dates or historical dates
or ISO timestamps or the like. It extrapolates the current Gregorian
calendar forward and backward in time; there is no attempt to change
the calendar to match time periods or locations. #GDate does not store
time information; it represents a <emphasis>day</emphasis>.
</para>
<para>
The #GDate implementation has several nice features; it is only a
64-bit struct, so storing large numbers of dates is very efficient. It
can keep both a Julian and Day-Month-Year representation of the date,
since some calculations are much easier with one representation or the
other. A Julian representation is simply a count of days since some
fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
("Julian" dates in the #GDate API aren't really Julian dates in the
technical sense; technically, Julian dates count from the start of the
Julian period, Jan 1, 4713 BC).
</para>
<para>
#GDate is simple to use. First you need a "blank" date; you can get a
dynamically allocated date from g_date_new(), or you can declare an
automatic variable or array and initialize it to a sane state by
calling g_date_clear(). A cleared date is sane; it's safe to call
g_date_set_dmy() and the other mutator functions to initialize the
value of a cleared date. However, a cleared date is initially
<emphasis>invalid</emphasis>, meaning that it doesn't represent a day
that exists. It is undefined to call any of the date calculation
routines on an invalid date. If you obtain a date from a user or other
unpredictable source, you should check its validity with the
g_date_valid() predicate. g_date_valid() is also used to check for
errors with g_date_set_parse() and other functions that can
fail. Dates can be invalidated by calling g_date_clear() again.
</para>
<para>
<emphasis>It is very important to use the API to access the #GDate
struct.</emphasis> Often only the DMY or only the Julian
representation is valid. Sometimes neither is valid. Use the API.
</para>
<para>
glib doesn't contain any time-manipulation functions; however, there
is a #GTime typedef which is equivalent to time_t, and a #GTimeVal
struct which represents a more precise time (with microseconds). You
can request the current time as a #GTimeVal with g_get_current_time().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<para>
</para>
<!-- ##### MACRO G_USEC_PER_SEC ##### -->
@ -22,16 +71,19 @@ Date and Time Functions
<!-- ##### STRUCT GTimeVal ##### -->
<para>
<para>
Represents a precise time, with seconds and microseconds. Same as the
<structname>struct timeval</structname> returned by the
<function>gettimeofday()</function> UNIX call.
</para>
@tv_sec:
@tv_usec:
<!-- ##### FUNCTION g_get_current_time ##### -->
<para>
<para>
Equivalent to <function>gettimeofday()</function>, but also works on
Win32. Returns the current time.
</para>
@result:
@ -46,8 +98,16 @@ Date and Time Functions
<!-- ##### STRUCT GDate ##### -->
<para>
<para>
Represents a day between January 1, Year 1 and a few thousand years in
the future. None of its members should be accessed directly. If the
<structname>GDate</structname> is obtained from g_date_new(), it will
be safe to mutate but invalid and thus not safe for calendrical computations.
If it's declared on the stack, it will contain garbage so must be
initialized with g_date_clear(). g_date_clear() makes the date invalid
but sane. An invalid date doesn't represent a day, it's "empty." A
date becomes valid after you set it to a Julian day or you set a day,
month, and year.
</para>
@julian_days:
@ -58,14 +118,15 @@ Date and Time Functions
@year:
<!-- ##### TYPEDEF GTime ##### -->
<para>
<para>
Simply a replacement for time_t. Unrelated to GTimer.
</para>
<!-- ##### ENUM GDateDMY ##### -->
<para>
<para>
This enumeration isn't used in the API, but may be useful if you need
to mark a number as a day, month, or year.
</para>
@G_DATE_DAY:
@ -73,14 +134,16 @@ Date and Time Functions
@G_DATE_YEAR:
<!-- ##### TYPEDEF GDateDay ##### -->
<para>
<para>
Integer representing a day of the month; between 1 and
31. #G_DATE_BAD_DAY represents an invalid day of the month.
</para>
<!-- ##### ENUM GDateMonth ##### -->
<para>
<para>
Enumeration representing a month; values are #G_DATE_JANUARY,
#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value.
</para>
@G_DATE_BAD_MONTH:
@ -98,14 +161,17 @@ Date and Time Functions
@G_DATE_DECEMBER:
<!-- ##### TYPEDEF GDateYear ##### -->
<para>
<para>
Integer representing a year; #G_DATE_BAD_YEAR is the invalid
value. The year must be 1 or higher; negative (BC) years are not
allowed. The year is represented with four digits.
</para>
<!-- ##### ENUM GDateWeekday ##### -->
<para>
<para>
Enumeration representing a day of the week; #G_DATE_MONDAY,
#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
</para>
@G_DATE_BAD_WEEKDAY:
@ -118,410 +184,486 @@ Date and Time Functions
@G_DATE_SUNDAY:
<!-- ##### MACRO G_DATE_BAD_DAY ##### -->
<para>
<para>
Represents an invalid #GDateDay.
</para>
<!-- ##### MACRO G_DATE_BAD_JULIAN ##### -->
<para>
<para>
Represents an invalid Julian day number.
</para>
<!-- ##### MACRO G_DATE_BAD_YEAR ##### -->
<para>
<para>
Represents an invalid year.
</para>
<!-- ##### FUNCTION g_date_new ##### -->
<para>
<para>
Allocate a #GDate and initialize it to a sane state. The new date will
be cleared (as if you'd called g_date_clear()) but invalid (it won't
represent an existing day). Free the return value with g_date_free().
</para>
@Returns:
@Returns: The newly-allocated #GDate
<!-- ##### FUNCTION g_date_new_dmy ##### -->
<para>
<para>
Like g_date_new(), but also sets the value of the date. Assuming the
day/month/year triplet you pass in represents an existing day, the
returned date will be valid.
</para>
@day:
@month:
@year:
@Returns:
@day: Day of the month
@month: Month of the year
@year: Year
@Returns: Allocated date initialized with @day, @month, and @year
<!-- ##### FUNCTION g_date_new_julian ##### -->
<para>
<para>
Like g_date_new(), but also sets the value of the date. Assuming the
Julian day number you pass in is valid (greater than 0, less than an
unreasonably large number), the returned date will be valid.
</para>
@julian_day:
@Returns:
@julian_day: Days since January 1, Year 1
@Returns: Allocated date initialized with @julian_day
<!-- ##### FUNCTION g_date_clear ##### -->
<para>
<para>
Initialize one or more #GDate structs to a sane but invalid
state. The cleared dates will not represent an existing date, but will
not contain garbage. Useful to init a date declared on the stack.
Validity can be tested with g_date_valid().
</para>
@date:
@n_dates:
@date: Pointer to one or more dates to clear
@n_dates: Number of dates to clear
<!-- ##### FUNCTION g_date_free ##### -->
<para>
<para>
Free a #GDate returned from g_date_new()
</para>
@date:
@date: Date to free
<!-- ##### FUNCTION g_date_set_day ##### -->
<para>
<para>
Set the day of the month for a #GDate. If the resulting day-month-year
triplet is invalid, the date will be invalid.
</para>
@date:
@day:
@date: Date to set the day for
@day: Day to set
<!-- ##### FUNCTION g_date_set_month ##### -->
<para>
<para>
Set the month of the year for a #GDate. If the resulting
day-month-year triplet is invalid, the date will be invalid.
</para>
@date:
@month:
@date: Date
@month: Month to set
<!-- ##### FUNCTION g_date_set_year ##### -->
<para>
<para>
Set the year for a #GDate. If the resulting day-month-year triplet is
invalid, the date will be invalid.
</para>
@date:
@year:
@date: Date
@year: Year to set
<!-- ##### FUNCTION g_date_set_dmy ##### -->
<para>
<para>
Set the value of a #GDate from a day, month, and year. The DMY triplet
must be valid; if you aren't sure it is, call g_date_valid_dmy() to
check before you set it.
</para>
@date:
@day:
@month:
@y:
@date: Date to set the value of
@day: Day
@month: Month
@y: Year
<!-- ##### FUNCTION g_date_set_julian ##### -->
<para>
<para>
Set the value of a #GDate from a Julian day number.
</para>
@date:
@julian_date:
@date: Date to set
@julian_date: Julian day number (days since January 1, Year 1)
<!-- ##### FUNCTION g_date_set_time ##### -->
<para>
<para>
Set the value of a date from a #GTime (time_t) value. To set the value
of a date to the current day, you could write:
<informalexample><programlisting>
g_date_set_time(date, time(NULL));
</programlisting></informalexample>
</para>
@date:
@time:
@date: Date to update
@time: #GTime value to set
<!-- ##### FUNCTION g_date_set_parse ##### -->
<para>
<para>
Parse a user-inputted string @str, and try to figure out what date it
represents, taking the current locale into account. If the string is
successfully parsed, the date will be valid after the call. Otherwise,
it will be invalid. You should check using g_date_valid() to see
whether the parsing succeeded.
</para>
<para>
This function is not appropriate for file formats and the like; it
isn't very precise, and its exact behavior varies with the
locale. It's intended to be a heuristic routine that guesses what the
user means by a given string (and it does work pretty well in that
capacity).
</para>
@date:
@str:
@date: Date to fill in
@str: String to parse
<!-- ##### FUNCTION g_date_add_days ##### -->
<para>
<para>
Increment a date some number of days. To move forward by weeks, add
weeks*7 days. The date must be valid.
</para>
@date:
@n_days:
@date: The date to increment
@n_days: Number of days to move the date forward
<!-- ##### FUNCTION g_date_subtract_days ##### -->
<para>
<para>
Move a date some number of days into the past. To move by weeks, just
move by weeks*7 days. Date must be valid.
</para>
@date:
@n_days:
@date: Date to decrement
@n_days: Number of days to move
<!-- ##### FUNCTION g_date_add_months ##### -->
<para>
<para>
Increment a date by some number of months. If the day of the month is
greater than 28, this routine may change the day of the month (because
the destination month may not have the current day in it). The date
must be valid.
</para>
@date:
@n_months:
@date: Date to increment
@n_months: Number of months to move forward
<!-- ##### FUNCTION g_date_subtract_months ##### -->
<para>
<para>
Move a date some number of months into the past. If the current day of
the month doesn't exist in the destination month, the day of the month
may change. Date must be valid.
</para>
@date:
@n_months:
@date: Date to decrement
@n_months: Number of months to move
<!-- ##### FUNCTION g_date_add_years ##### -->
<para>
<para>
Increment a date by some number of years. If the date is February 29,
and the destination year is not a leap year, the date will be changed
to February 28. The date must be valid.
</para>
@date:
@n_years:
@date: Date to increment
@n_years: Number of years to move forward
<!-- ##### FUNCTION g_date_subtract_years ##### -->
<para>
<para>
Move a date some number of years into the past. If the current day
doesn't exist in the destination year (i.e. it's February 29 and you
move to a non-leap-year) then the day is changed to February 29. Date
must be valid.
</para>
@date:
@n_years:
@date: Date to decrement
@n_years: Number of years to move
<!-- ##### FUNCTION g_date_compare ##### -->
<para>
<para>
<function>qsort()</function>-style comparsion function for dates. Both
dates must be valid.
</para>
@lhs:
@rhs:
@Returns:
@lhs: First date to compare
@rhs: Second date to compare
@Returns: 0 for equal, less than zero if @lhs is less than @rhs,
greater than zero if @lhs is greater than @rhs
<!-- ##### FUNCTION g_date_day ##### -->
<para>
<para>
Return the day of the month; the #GDate must be valid.
</para>
@date:
@Returns:
@date: Date to extract the day of the month from
@Returns: Day of the month
<!-- ##### FUNCTION g_date_month ##### -->
<para>
<para>
Accessor for the month of the year. Date must be valid.
</para>
@date:
@Returns:
@date: Date to get the month from
@Returns: A #GDateMonth
<!-- ##### FUNCTION g_date_year ##### -->
<para>
<para>
Accessor; returns the year of a #GDate. The date must be valid.
</para>
@date:
@Returns:
@date: Date
@Returns: Year in which the date falls
<!-- ##### FUNCTION g_date_julian ##### -->
<para>
<para>
Accessor, returns the Julian day or "serial number" of the #GDate. The
Julian day is simply the number of days since January 1, Year 1; i.e.,
January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
etc. Date must be valid.
</para>
@date:
@Returns:
@date: Date to extract the Julian day from
@Returns: Julian day
<!-- ##### FUNCTION g_date_weekday ##### -->
<para>
<para>
Returns the day of the week for a #GDate. The date must be valid.
</para>
@date:
@Returns:
@date: Date
@Returns: Day of the week as a #GDateWeekday
<!-- ##### FUNCTION g_date_day_of_year ##### -->
<para>
<para>
Return the day of the year, where Jan 1 is the first day of the
year. Date must be valid.
</para>
@date:
@Returns:
@date: Date to extract day of year from
@Returns: Day of the year
<!-- ##### FUNCTION g_date_days_in_month ##### -->
<para>
<para>
Return the number of days in a month, taking leap years into account.
</para>
@month:
@year:
@Returns:
@month: Month
@year: Year
@Returns: Number of days in @month during the year @year.
<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
<para>
<para>
Returns TRUE if the date is on the first of a month. Date must be valid.
</para>
@date:
@Returns:
@date: Date to check
@Returns: Boolean, if the date is the first of the month
<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
<para>
<para>
Returns TRUE if the date is the last day of the month. Date must be valid.
</para>
@date:
@Returns:
@date: Date to check
@Returns: Boolean, if the date is the last day of the month
<!-- ##### FUNCTION g_date_is_leap_year ##### -->
<para>
<para>
Returns TRUE if the year is a leap year
</para>
@year:
@Returns:
@year: Year to check
@Returns: Boolean, if the year is a leap year
<!-- ##### FUNCTION g_date_monday_week_of_year ##### -->
<para>
<para>
Return the week of the year, where weeks are understood to start on
Monday. If the date is before the first Monday of the year, return
0. Date must be valid.
</para>
@date:
@Returns:
@date: Date to use
@Returns: Week of the year
<!-- ##### FUNCTION g_date_monday_weeks_in_year ##### -->
<para>
<para>
Return the number of weeks in the year, where weeks are taken to start
on Monday. Will be 52 or 53. Date must be valid. (Years always have 52
7-day periods, plus 1 or 2 extra days depending on whether it's a leap
year. This function is basically telling you how many Mondays are in
the year, i.e. there are 53 Mondays if one of the extra days happens
to be a Monday.)
</para>
@year:
@Returns:
@year: Year
@Returns: Number of Mondays in the year
<!-- ##### FUNCTION g_date_sunday_week_of_year ##### -->
<para>
<para>
Week of the year during which this date falls, if weeks are understood
to being on Sunday. Date must be valid. Can return 0 if the day is
before the first Sunday of the year.
</para>
@date:
@Returns:
@date: Date
@Returns: Week number
<!-- ##### FUNCTION g_date_sunday_weeks_in_year ##### -->
<para>
<para>
Return the number of weeks in the year, where weeks are taken to start
on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52
7-day periods, plus 1 or 2 extra days depending on whether it's a leap
year. This function is basically telling you how many Sundays are in
the year, i.e. there are 53 Sundays if one of the extra days happens
to be a Sunday.)
</para>
@year:
@Returns:
@year: Year to count weeks in
@Returns: Number of weeks
<!-- ##### FUNCTION g_date_strftime ##### -->
<para>
<para>
Generate a printed representation of the date, in a locale-specific
way. Works just like the standard C <function>strftime()</function>
function, but only accepts date-related formats; time-related formats
give undefined results. Date must be valid.
</para>
@s:
@slen:
@format:
@date:
@Returns:
@s: Destination buffer
@slen: Max buffer size
@format: Format string
@date: valid #GDate
@Returns: number of characters written to the buffer, or 0 the buffer was too small
<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
<para>
<para>
Fills in the date-related bits of a <structname>struct tm</structname>
using the @date value. Initializes the non-date parts with something
sane but meaningless.
</para>
@date:
@tm:
@date: Date to set the <structname>struct tm</structname> from
@tm: <structname>struct tm</structname> to fill
<!-- ##### FUNCTION g_date_valid ##### -->
<para>
<para>
Returns TRUE if the #GDate represents an existing day. #GDate must not
contain garbage; it should have been initialized with g_date_clear()
if it wasn't allocated by one of the g_date_new() variants.
</para>
@date:
@Returns:
@date: Date to check
@Returns: Whether the date is valid.
<!-- ##### FUNCTION g_date_valid_day ##### -->
<para>
<para>
Returns TRUE if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).
</para>
@day:
@Returns:
@day: Day to check.
@Returns: Boolean, whether the day is valid.
<!-- ##### FUNCTION g_date_valid_month ##### -->
<para>
<para>
Returns TRUE if the month value is valid. The 12 #GDateMonth
enumeration values are the only valid months.
</para>
@month:
@Returns:
@month: Month
@Returns: Boolean, whether the month is valid
<!-- ##### FUNCTION g_date_valid_year ##### -->
<para>
<para>
Returns TRUE if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what GDate will understand.
</para>
@year:
@Returns:
@year: Year
@Returns: Boolean, whether the year is valid.
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
<para>
<para>
Returns TRUE if the day/month/year triplet forms a valid, existing day
in the range of days GDate understands (Year 1 or later, no more than
a few thousand years in the future).
</para>
@day:
@month:
@year:
@Returns:
@day: Day
@month: Month
@year: Year
@Returns: Boolean, whether the date is a valid one
<!-- ##### FUNCTION g_date_valid_julian ##### -->
<para>
<para>
Returns TRUE if the Julian day is valid. Anything greater than zero is basically a
valid Julian, though there is a 32-bit limit.
</para>
@julian_date:
@Returns:
@julian_date: Julian day to check
@Returns: Boolean, whether the Julian day is valid.
<!-- ##### FUNCTION g_date_valid_weekday ##### -->
<para>
<para>
Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
values are the only valid weekdays.
</para>
@weekday:
@Returns:
@weekday: Weekday
@Returns: Boolean, whether the weekday is valid.

56
docs/reference/glib/tmpl/glib-unused.sgml
View File

@ -1,40 +1,82 @@
<!-- ##### MACRO G_GLONG_FORMAT ##### -->
<!-- ##### MACRO lseek ##### -->
<para>
</para>
<!-- ##### MACRO G_GSHORT_FORMAT ##### -->
<!-- ##### USER_FUNCTION GSearchFunc ##### -->
<para>
Specifies the type of function passed to g_tree_search().
</para>
@key: a key from a #GTree.
@data: the data to compare with the key.
@Returns: 0 if the desired key has been found, a negative number if the
desired key comes before @key in the sort order of the #GTree, or a positive
value if the desired key comes after @key.
<!-- ##### MACRO write ##### -->
<para>
</para>
<!-- ##### MACRO G_GUSHORT_FORMAT ##### -->
<!-- ##### MACRO pclose ##### -->
<para>
</para>
<!-- ##### MACRO G_GINT_FORMAT ##### -->
<!-- ##### MACRO g_string ##### -->
<para>
Turns the argument into a string literal by using the '#' stringizing operator.
</para>
@x: text to convert to a literal string.
<!-- ##### MACRO popen ##### -->
<para>
</para>
<!-- ##### MACRO G_GUINT_FORMAT ##### -->
<!-- ##### MACRO access ##### -->
<para>
</para>
<!-- ##### MACRO G_GULONG_FORMAT ##### -->
<!-- ##### MACRO open ##### -->
<para>
</para>
<!-- ##### MACRO G_MICROSEC ##### -->
<!-- ##### MACRO getpid ##### -->
<para>
</para>
<!-- ##### MACRO fdopen ##### -->
<para>
</para>
<!-- ##### MACRO close ##### -->
<para>
</para>
<!-- ##### MACRO getcwd ##### -->
<para>
</para>
<!-- ##### MACRO read ##### -->
<para>
</para>

292
docs/reference/glib/tmpl/hash_tables.sgml
View File

@ -2,11 +2,48 @@
Hash Tables
<!-- ##### SECTION Short_Description ##### -->
associations between keys and values so that given a key the value
can be found quickly.
<!-- ##### SECTION Long_Description ##### -->
<para>
A #GHashTable provides associations between keys and values which
is optimized so that given a key, the associated value can be found
very quickly.
</para>
<para>
Note that neither keys nor values are copied when inserted into the
#GHashTable, so they must exist for the lifetime of the #GHashTable.
This means that the use of static strings is OK, but temporary
strings (i.e. those created in buffers and those returned by GTK widgets)
should be copied with g_strdup() before being inserted.
</para>
<para>
If keys or values are dynamically allocated, you must be careful to ensure
that they are freed when they are removed from the #GHashTable, and also
when they are overwritten by new insertions into the #GHashTable.
It is also not advisable to mix static strings and dynamically-allocated
strings in a #GHashTable, because it then becomes difficult to determine
whether the string should be freed.
</para>
<para>
To create a #GHashTable, use g_hash_table_new().
</para>
<para>
To insert a key and value into a #GHashTable, use g_hash_table_insert().
</para>
<para>
To lookup a value corresponding to a given key, use g_hash_table_lookup()
and g_hash_table_lookup_extended().
</para>
<para>
To remove a key and value, use g_hash_table_remove().
</para>
<para>
To call a function for each key and value pair use g_hash_table_foreach().
</para>
<para>
To destroy a #GHashTable use g_hash_table_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,209 +53,306 @@ Hash Tables
<!-- ##### STRUCT GHashTable ##### -->
<para>
The #GHashTable struct is an opaque data structure to represent a
<link linkend="glib-Hash-Tables">Hash Table</link>.
It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_hash_table_new ##### -->
<para>
Creates a new #GHashTable.
</para>
@hash_func:
@key_compare_func:
@Returns:
@hash_func: a function to create a hash value from a key.
Hash values are used to determine where keys are stored within the
#GHashTable data structure.
The g_direct_hash(), g_int_hash() and g_str_hash() functions are provided for
some common types of keys. If hash_func is NULL, g_direct_hash() is used.
@key_compare_func: a function to compare two keys to see if they are equal.
This is used when looking up keys in the #GHashTable.
The g_direct_equal(), g_int_equal() and g_str_equal() functions are provided
for the most common types of keys. If compare_func is NULL, keys are compared
directly in a similar fashion to g_direct_equal(), but without the overhead
of a function call.
@Returns: a new #GHashTable.
<!-- ##### USER_FUNCTION GHashFunc ##### -->
<para>
Specifies the type of the hash function which is passed to
g_hash_table_new() when a #GHashTable is created.
</para>
<para>
The function is passed a key and should return a guint hash value.
The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
hash functions which can be used when the key is a #gpointer, #gint, and
#gchar* respectively.
</para>
<para>
FIXME: Need more here.
The hash values should be evenly distributed over a fairly large range?
The modulus is taken with the hash table size (a prime number)
to find the 'bucket' to place each key into.
The function should also be very fast, since it is called for each key
lookup.
</para>
@key:
@Returns:
@key: a key.
@Returns: the hash value corresponding to the key.
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
<para>
Specifies the type of a comparison function used to compare two values.
The value which should be returned depends on the context in which the
#GCompareFunc is used.
</para>
<para>
In g_hash_table_new(), g_cache_new(), and g_relation_index() the function
should return TRUE if the two parameters are equal, or FALSE if they are not.
</para>
<para>
In g_list_find_custom() and g_slist_find_custom() the function should return
0 if the two parameters are equal.
</para>
<para>
In g_list_insert_sorted(), g_list_sort(), g_slist_insert_sorted(),
g_slist_sort() and g_tree_new() the function should return a negative integer
if the first value comes before the second, 0 if they are equal, or a positive
integer if the first value comes after the second.
</para>
@a:
@b:
@Returns:
@a: a value.
@b: a value to compare with.
@Returns: TRUE if the two values are equivalent.
<!-- ##### FUNCTION g_hash_table_insert ##### -->
<para>
Inserts a new key and value into a #GHashTable.
If the key already exists in the #GHashTable its current value is replaced
with the new value.
</para>
<note>
<para>
If the keys or values use dynamically allocated memory, then you should
first check if the key already exists in the GHashTable. If it does,
you should free the existing key and/or value before inserting the
new key and value.
</para>
</note>
@hash_table:
@key:
@value:
@hash_table: a #GHashTable.
@key: a key to insert.
@value: the value to associate with the key.
<!-- ##### FUNCTION g_hash_table_size ##### -->
<para>
Returns the number of key/value pairs in a #GHashTable.
</para>
@hash_table:
@Returns:
@hash_table: a #GHashTable.
@Returns: the number of key/value pairs in the #GHashTable.
<!-- ##### FUNCTION g_hash_table_lookup ##### -->
<para>
Looks up a key in the #GHashTable, returning the associated value or NULL
if the key is not found.
</para>
@hash_table:
@key:
@Returns:
@hash_table: a #GHashTable.
@key: the key to look up.
@Returns: the associated value, or NULL if the key is not found.
<!-- ##### FUNCTION g_hash_table_lookup_extended ##### -->
<para>
Looks up a key in the #GHashTable, returning the original key and the
associated value and a gboolean which is TRUE if the key was found.
This is useful if you need to free the memory allocated for the
original key, for example before calling g_hash_table_remove().
</para>
@hash_table:
@lookup_key:
@orig_key:
@value:
@Returns:
@hash_table: a #GHashTable.
@lookup_key: the key to look up.
@orig_key: returns the original key.
@value: returns the value associated with the key.
@Returns: TRUE if the key was found in the #GHashTable.
<!-- ##### FUNCTION g_hash_table_foreach ##### -->
<para>
Calls the given function for each of the key/value pairs in the #GHashTable.
The function is passed the key and value of each pair, and the given
@user_data parameter.
</para>
@hash_table:
@func:
@user_data:
@hash_table: a #GHashTable.
@func: the function to call for each key/value pair.
@user_data: use data to pass to the function.
<!-- ##### USER_FUNCTION GHFunc ##### -->
<para>
Specifies the type of the function passed to g_hash_table_foreach().
It is called with each key/value pair, together with the @user_data parameter
which is passed to g_hash_table_foreach().
</para>
@key:
@value:
@user_data:
@key: a key.
@value: the value corresponding to the key.
@user_data: user data passed to g_hash_table_foreach().
<!-- ##### FUNCTION g_hash_table_remove ##### -->
<para>
Removes a key and its associated value from a #GHashTable.
</para>
<note>
<para>
As with g_hash_table_insert(), you should make sure that any dynamically
allocated values are freed yourself.
</para>
</note>
@hash_table:
@key:
@hash_table: a #GHashTable.
@key: the key to remove.
<!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
<para>
Calls the given function for each key/value pair in the #GHashTable.
If the function returns TRUE, then the key/value pair is removed from the
#GHashTable.
</para>
@hash_table:
@func:
@user_data:
@Returns:
@hash_table: a #GHashTable.
@func: the function to call for each key/value pair.
@user_data: user data to pass to the function.
@Returns: the number of key/value paris removed.
<!-- ##### USER_FUNCTION GHRFunc ##### -->
<para>
Specifies the type of the function passed to g_hash_table_foreach_remove().
It is called with each key/value pair, together with the @user_data parameter
passed to g_hash_table_foreach_remove().
It should return TRUE if the key/value pair should be removed from the
#GHashTable.
</para>
@key:
@value:
@user_data:
@Returns:
@key: a key.
@value: the value associated with the key.
@user_data: user data passed to g_hash_table_remove().
@Returns: TRUE if the key/value pair should be removed from the #GHashTable.
<!-- ##### FUNCTION g_hash_table_freeze ##### -->
<para>
Disable resizing of a #GHashTable.
</para>
<para>
This should be used if you need to make a lot of changes to a #GHashTable
at once, as it reduces the number of times that the #GHashTable is rebuilt.
You should call g_hash_table_thaw() after updating the #GHashTable to
enable resizing again.
</para>
@hash_table:
@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_hash_table_thaw ##### -->
<para>
Enables resizing of a #GHashTable.
</para>
@hash_table:
@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_hash_table_destroy ##### -->
<para>
Destroys the #GHashTable.
</para>
<note>
<para>
If keys and/or values are dynamically allocated, you should free them
first.
</para>
</note>
@hash_table:
@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_direct_equal ##### -->
<para>
Compares two #gpointer arguments and returns TRUE if they are equal.
It can be passed to g_hash_table_new() as the @key_compare_func
parameter, when using pointers as keys in a #GHashTable.
</para>
@v:
@v2:
@Returns:
@v: a key.
@v2: a key to compare with @v.
@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_direct_hash ##### -->
<para>
Converts a gpointer to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter, when
using gpointer values as keys in a #GHashTable.
</para>
@v:
@Returns:
@v: a gpointer key.
@Returns: a hash value corresponding to the key.
<!-- ##### FUNCTION g_int_equal ##### -->
<para>
Compares the two #gint values being pointed to and returns TRUE if they are
equal.
It can be passed to g_hash_table_new() as the @key_compare_func
parameter, when using pointers to integers as keys in a #GHashTable.
</para>
@v:
@v2:
@Returns:
@v: a pointer to a #gint key.
@v2: a pointer to a #gint key to compare with @v.
@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_int_hash ##### -->
<para>
Converts a pointer to a #gint to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter, when
using pointers to gint values as keys in a #GHashTable.
</para>
@v:
@Returns:
@v: a pointer to a #gint key.
@Returns: a hash value corresponding to the key.
<!-- ##### FUNCTION g_str_equal ##### -->
<para>
Compares two strings and returns TRUE if they are equal.
It can be passed to g_hash_table_new() as the @key_compare_func
parameter, when using strings as keys in a #GHashTable.
</para>
@v:
@v2:
@Returns:
@v: a key.
@v2: a key to compare with @v.
@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_str_hash ##### -->
<para>
Converts a string to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter, when
using strings as keys in a #GHashTable.
</para>
@v:
@Returns:
@v: a string key.
@Returns: a hash value corresponding to the key.

322
docs/reference/glib/tmpl/hooks.sgml
View File

@ -2,10 +2,13 @@
Hook Functions
<!-- ##### SECTION Short_Description ##### -->
support for manipulating lists of hook functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GHookList, #GHook and their related functions provide support for
lists of hook functions. Functions can be added and removed from the lists,
and the list of hook functions can be invoked.
</para>
@ -17,6 +20,47 @@ Hook Functions
<!-- ##### STRUCT GHookList ##### -->
<para>
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#guint seq_id;</entry>
<entry>the next free #GHook id.</entry>
</row>
<row>
<entry>#guint hook_size;</entry>
<entry>the size of the #GHookList elements, in bytes.</entry>
</row>
<row>
<entry>#guint is_setup : 1;</entry>
<entry>1 if the #GHookList has been initialized.</entry>
</row>
<row>
<entry>#GHook *hooks;</entry>
<entry>the first #GHook element in the list.</entry>
</row>
<row>
<entry>#GMemChunk *hook_memchunk;</entry>
<entry>the #GMemChunk used for allocating the #GHook elements.</entry>
</row>
<row>
<entry>#GHookFreeFunc hook_free;</entry>
<entry>the function to call to free a #GHook element.</entry>
</row>
<row>
<entry>#GHookFreeFunc hook_destroy;</entry>
<entry>the function to call to destory a #GHook element.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@seq_id:
@ -30,6 +74,51 @@ Hook Functions
<!-- ##### STRUCT GHook ##### -->
<para>
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#gpointer data;</entry>
<entry>.</entry>
</row>
<row>
<entry>#GHook *next;</entry>
<entry>.</entry>
</row>
<row>
<entry>#GHook *prev;</entry>
<entry>.</entry>
</row>
<row>
<entry>#guint ref_count;</entry>
<entry>.</entry>
</row>
<row>
<entry>#guint hook_id;</entry>
<entry>.</entry>
</row>
<row>
<entry>#guint flags;</entry>
<entry>.</entry>
</row>
<row>
<entry>#gpointer data;</entry>
<entry>.</entry>
</row>
<row>
<entry>#GDestroyNotify destroy;</entry>
<entry>.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@data:
@ -95,29 +184,34 @@ Hook Functions
<!-- ##### FUNCTION g_hook_list_init ##### -->
<para>
Initializes a #GHookList.
This must be called before the #GHookList is used.
</para>
@hook_list:
@hook_size:
@hook_list: a #GHookList.
@hook_size: the size of each element in the #GHookList, typically
sizeof (GHook).
<!-- ##### FUNCTION g_hook_list_invoke ##### -->
<para>
Calls all of the #GHook functions in a #GHookList.
</para>
@hook_list:
@may_recurse:
@hook_list: a #GHookList.
@may_recurse: TRUE if functions which are already running (e.g. in another
thread) can be called. If set to FALSE, these are skipped.
<!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
<para>
Calls all of the #GHook functions in a #GHookList.
Any function which returns TRUE is removed from the #GHookList.
</para>
@hook_list:
@may_recurse:
@hook_list: a #GHookList.
@may_recurse: TRUE if functions which are already running (e.g. in another
thread) can be called. If set to FALSE, these are skipped.
<!-- ##### FUNCTION g_hook_list_marshal ##### -->
@ -125,7 +219,7 @@ Hook Functions
</para>
@hook_list:
@hook_list: a #GHookList.
@may_recurse:
@marshaller:
@data:
@ -136,7 +230,7 @@ Hook Functions
</para>
@hook_list:
@hook_list: a #GHookList.
@may_recurse:
@marshaller:
@data:
@ -144,164 +238,183 @@ Hook Functions
<!-- ##### FUNCTION g_hook_list_clear ##### -->
<para>
Removes all the #GHook elements from a #GHookList.
</para>
@hook_list:
@hook_list: a #GHookList.
<!-- ##### FUNCTION g_hook_alloc ##### -->
<para>
Allocates space for a #GHook and initializes it.
</para>
@hook_list:
@Returns:
@hook_list: a #GHookList.
@Returns: a new #GHook.
<!-- ##### MACRO g_hook_append ##### -->
<para>
Appends a #GHook onto the end of a #GHookList.
</para>
@hook_list:
@hook:
@hook_list: a #GHookList.
@hook: the #GHook to add to the end of @hook_list.
<!-- ##### FUNCTION g_hook_prepend ##### -->
<para>
Prepends a #GHook on the start of a #GHookList.
</para>
@hook_list:
@hook:
@hook_list: a #GHookList.
@hook: the #GHook to add to the start of @hook_list.
<!-- ##### FUNCTION g_hook_insert_before ##### -->
<para>
Inserts a #GHook into a #GHookList, before a given #GHook.
</para>
@hook_list:
@sibling:
@hook:
@hook_list: a #GHookList.
@sibling: the #GHook to insert the new #GHook before.
@hook: the #GHook to insert.
<!-- ##### FUNCTION g_hook_insert_sorted ##### -->
<para>
Inserts a #GHook into a #GHookList, sorted by the given function.
</para>
@hook_list:
@hook:
@func:
@hook_list: a #GHookList.
@hook: the #GHook to insert.
@func: the comparison function used to sort the #GHook elements.
<!-- ##### USER_FUNCTION GHookCompareFunc ##### -->
<para>
Defines the type of function used to compare #GHook elements in
g_hook_insert_sorted().
</para>
@new_hook:
@sibling:
@Returns:
@new_hook: the #GHook being inserted.
@sibling: the #GHook to compare with @new_hook.
@Returns: a value <= 0 if @new_hook should be before @sibling.
<!-- ##### FUNCTION g_hook_compare_ids ##### -->
<para>
Compares the ids of two #GHook elements, returning a negative value
if the second id is greater than the first.
</para>
@new_hook:
@sibling:
@Returns:
@new_hook: a #GHook.
@sibling: a #GHook to compare with @new_hook.
@Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook.
<!-- ##### FUNCTION g_hook_get ##### -->
<para>
Returns the #GHook with the given id, or NULL if it is not found.
</para>
@hook_list:
@hook_id:
@Returns:
@hook_list: a #GHookList.
@hook_id: a hook id.
@Returns: the #GHook with the given id, or NULL if it is not found.
<!-- ##### FUNCTION g_hook_find ##### -->
<para>
Finds a #GHook in a #GHookList using the given function to test for a match.
</para>
@hook_list:
@need_valids:
@func:
@data:
@Returns:
@hook_list: a #GHookList.
@need_valids: TRUE if #GHook elements which have been destroyed should be
skipped.
@func: the function to call for each #GHook, which should return TRUE when
the #GHook has been found.
@data: the data passed to @func.
@Returns: the found #GHook or NULL if no matching #GHook is found.
<!-- ##### FUNCTION g_hook_find_data ##### -->
<para>
Finds a #GHook in a #GHookList with the given data.
</para>
@hook_list:
@need_valids:
@data:
@Returns:
@hook_list: a #GHookList.
@need_valids: TRUE if #GHook elements which have been destroyed should be
skipped.
@data: the data to find.
@Returns: the #GHook with the given @data or NULL if no matching
#GHook is found.
<!-- ##### FUNCTION g_hook_find_func ##### -->
<para>
Finds a #GHook in a #GHookList with the given function.
</para>
@hook_list:
@need_valids:
@func:
@Returns:
@hook_list: a #GHookList.
@need_valids: TRUE if #GHook elements which have been destroyed should be
skipped.
@func: the function to find.
@Returns: the #GHook with the given @func or NULL if no matching
#GHook is found.
<!-- ##### USER_FUNCTION GHookFindFunc ##### -->
<para>
Defines the type of the function passed to g_hooK_find_func().
</para>
@hook:
@data:
@Returns:
@hook: a #GHook.
@data: user data passed to g_hook_find_func().
@Returns: TRUE if the required #GHook has been found.
<!-- ##### FUNCTION g_hook_find_func_data ##### -->
<para>
Finds a #GHook in a #GHookList with the given function and data.
</para>
@hook_list:
@need_valids:
@func:
@data:
@Returns:
@hook_list: a #GHookList.
@need_valids: TRUE if #GHook elements which have been destroyed should be
skipped.
@func: the function to find.
@data: the data to find.
@Returns: the #GHook with the given @func and @data or NULL if no matching
#GHook is found.
<!-- ##### FUNCTION g_hook_first_valid ##### -->
<para>
Returns the first #GHook in a #GHookList which has not been destroyed.
The reference count for the #GHook is incremented, so you must call
g_hook_unref() to restore it when no longer needed. (Or call
g_hook_next_valid() if you are stepping through the #GHookList.)
</para>
@hook_list:
@may_be_in_call:
@Returns:
@hook_list: a #GHookList.
@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
thread) are considered valid. If set to FALSE, these are skipped.
@Returns: the first valid #GHook, or NULL if none are valid.
<!-- ##### FUNCTION g_hook_next_valid ##### -->
<para>
Returns the next #GHook in a #GHookList which has not been destroyed.
The reference count for the #GHook is incremented, so you must call
g_hook_unref() to restore it when no longer needed. (Or continue to call
g_hook_next_valid() until NULL is returned.)
</para>
@hook_list:
@hook:
@may_be_in_call:
@Returns:
@hook_list: a #GHookList.
@hook: the current #GHook.
@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
thread) are considered valid. If set to FALSE, these are skipped.
@Returns: the next valid #GHook, or NULL if none are valid.
<!-- ##### ENUM GHookFlagMask ##### -->
@ -322,79 +435,90 @@ Hook Functions
<!-- ##### MACRO G_HOOK_IS_VALID ##### -->
<para>
Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
and it has not been destroyed.
</para>
@hook:
@hook: a #GHook.
@Returns: TRUE if the #GHook is valid.
<!-- ##### MACRO G_HOOK_ACTIVE ##### -->
<para>
Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook
is destroyed.
</para>
@hook:
@hook: a #GHook.
@Returns: TRUE if the #GHook is active.
<!-- ##### MACRO G_HOOK_IN_CALL ##### -->
<para>
Returns TRUE if the #GHook function is currently executing.
</para>
@hook:
@hook: a #GHook.
@Returns: TRUE if the #GHook function is currently executing.
<!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
<para>
Returns TRUE if the #GHook is not in a #GHookList.
</para>
@hook:
@hook: a #GHook.
@Returns: TRUE if the #GHook is not in a #GHookList.
<!-- ##### FUNCTION g_hook_ref ##### -->
<para>
Increments the reference count for a #GHook.
</para>
@hook_list:
@hook:
@hook_list: a #GHookList.
@hook: the #GHook to increment the reference count of.
<!-- ##### FUNCTION g_hook_unref ##### -->
<para>
Decrements the reference count of a #GHook.
If the reference count falls to 0, the #GHook is removed from the #GHookList
and g_hook_free() is called to free it.
</para>
@hook_list:
@hook_list: a #GHookList.
@hook:
<!-- ##### FUNCTION g_hook_free ##### -->
<para>
Calls the #GHookList @hook_free function if it exists, and frees the memory
allocated for the #GHook.
</para>
@hook_list:
@hook:
@hook_list: a #GHookList.
@hook: the #GHook to free.
<!-- ##### FUNCTION g_hook_destroy ##### -->
<para>
Destroys a #GHook, given its ID.
</para>
@hook_list:
@hook_id:
@Returns:
@hook_list: a #GHookList.
@hook_id: a hook ID.
@Returns: TRUE if the #GHook was found in the #GHookList and destroyed.
<!-- ##### FUNCTION g_hook_destroy_link ##### -->
<para>
Removes one #GHook from a #GHookList, calling the @hook_destroy function in
the #GHookList, and the @destroy function of the #GHook, if they exist.
</para>
@hook_list:
@hook:
@hook_list: a #GHookList.
@hook: the #GHook to remove.

237
docs/reference/glib/tmpl/iochannels.sgml
View File

@ -2,21 +2,68 @@
IO Channels
<!-- ##### SECTION Short_Description ##### -->
portable support for using files, pipes and sockets.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GIOChannel data type aims to provide a portable method for using file
descriptors, pipes, and sockets, and integrating them into the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
Currently full support is available on Unix platforms, though support for
Windows is only partially complete.
</para>
<para>
To create a new #GIOChannel on Unix systems use g_io_channel_unix_new().
This works for plain file descriptors, pipes and sockets.
</para>
<para>
Once a #GIOChannel has been created, it can be used in a generic manner
with the functions g_io_channel_read(), g_io_channel_write(),
g_io_channel_seek(), and g_io_channel_close().
</para>
<para>
To add a #GIOChannel to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
you are interested in on the #GIOChannel, and provide a function to be
called whenever these events occur.
</para>
<para>
#GIOChannel instances are created with an initial reference count of 1.
g_io_channel_ref() and g_io_channel_unref() can be used to increment or
decrement the reference count respectively. When the reference count falls
to 0, the #GIOChannel is freed. (Though it isn't closed automatically.)
Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
reference count.
</para>
<para>
GTK+ contains the convenience function gtk_input_add_full()
which creates a #GIOChannel from a file descriptor and adds it to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
The event source can later be removed with gtk_input_remove().
Similar functions can also be found in GDK.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
gdk_input_add_full(), gdk_input_remove()</term>
<listitem><para>
Convenience functions for creating #GIOChannel instances and adding them to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GIOChannel ##### -->
<para>
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
</para>
@channel_flags:
@ -25,40 +72,47 @@ IO Channels
<!-- ##### FUNCTION g_io_channel_unix_new ##### -->
<para>
Creates a new #GIOChannel given a file descriptor.
On Unix systems this works for plain files, pipes, and sockets.
</para>
<para>
The returned #GIOChannel has a reference count of 1.
</para>
@fd:
@Returns:
@fd: a file descriptor.
@Returns: a new #GIOChannel.
<!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
<para>
Returns the file descriptor of the Unix #GIOChannel.
</para>
@channel:
@Returns:
@channel: a #GIOChannel, created with g_io_channel_unix_new().
@Returns: the file descriptor of the #GIOChannel.
<!-- ##### FUNCTION g_io_channel_init ##### -->
<para>
Initializes a #GIOChannel struct. This is called by each of the above functions
when creating a #GIOChannel, and so is not often needed by the application
programmer (unless you are creating a new type of #GIOChannel).
</para>
@channel:
@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_read ##### -->
<para>
Reads data from a #GIOChannel.
</para>
@channel:
@buf:
@count:
@bytes_read:
@Returns:
@channel: a #GIOChannel.
@buf: a buffer to read the data into (which should be at least count bytes
long).
@count: the number of bytes to read from the #GIOChannel.
@bytes_read: returns the number of bytes actually read.
@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### ENUM GIOError ##### -->
@ -73,29 +127,56 @@ IO Channels
<!-- ##### FUNCTION g_io_channel_write ##### -->
<para>
Writes data to a #GIOChannel.
</para>
@channel:
@buf:
@count:
@bytes_written:
@Returns:
@channel: a #GIOChannel.
@buf: the buffer containing the data to write.
@count: the number of bytes to write.
@bytes_written: the number of bytes actually written.
@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### FUNCTION g_io_channel_seek ##### -->
<para>
Sets the current position in the #GIOChannel, similar to the standard system
call <function>fseek()</function>.
</para>
@channel:
@offset:
@type:
@Returns:
@channel: a #GIOChannel.
@offset: an offset, in bytes, which is added to the position specified by
@type.
@type: the position in the file, which can be %G_SEEK_CUR (the current
position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the
file).
@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### ENUM GSeekType ##### -->
<para>
An enumeration specifying the base position for a g_io_channel_seek()
operation.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>G_SEEK_CUR</entry>
<entry>the current position in the file.</entry>
</row>
<row>
<entry>G_SEEK_SET</entry>
<entry>the start of the file.</entry>
</row>
<row>
<entry>G_SEEK_END</entry>
<entry>the end of the file.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@ -105,56 +186,100 @@ IO Channels
<!-- ##### FUNCTION g_io_channel_close ##### -->
<para>
Closes a #GIOChannel.
The #GIOChannel will be freed when its reference count drops to 0.
</para>
@channel:
@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_ref ##### -->
<para>
Increments the reference count of a #GIOChannel.
</para>
@channel:
@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_unref ##### -->
<para>
Decrements the reference count of a #GIOChannel.
</para>
@channel:
@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_add_watch ##### -->
<para>
Adds the #GIOChannel into the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
with the default priority.
</para>
@channel:
@condition:
@func:
@user_data:
@Returns:
@channel: a #GIOChannel.
@condition: the condition to watch for.
@func: the function to call when the condition is satisfied.
@user_data: user data to pass to @func.
@Returns: the event source id.
<!-- ##### FUNCTION g_io_add_watch_full ##### -->
<para>
Adds the #GIOChannel into the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
with the given priority.
</para>
@channel:
@priority:
@condition:
@func:
@user_data:
@notify:
@Returns:
@channel: a #GIOChannel.
@priority: the priority of the #GIOChannel source.
@condition: the condition to watch for.
@func: the function to call when the condition is satisfied.
@user_data: user data to pass to @func.
@notify: the function to call when the source is removed.
@Returns: the event source id.
<!-- ##### ENUM GIOCondition ##### -->
<para>
A bitwise combination representing a condition to watch for on an event
source.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>G_IO_IN</entry>
<entry>There is data to read.</entry>
</row>
<row>
<entry>G_IO_OUT</entry>
<entry>Data can be written (without blocking).</entry>
</row>
<row>
<entry>G_IO_PRI</entry>
<entry>There is urgent data to read.</entry>
</row>
<row>
<entry>G_IO_ERR</entry>
<entry>Error condition.</entry>
</row>
<row>
<entry>G_IO_HUP</entry>
<entry>Hung up (the connection has been broken, usually for pipes and
sockets).</entry>
</row>
<row>
<entry>G_IO_NVAL</entry>
<entry>Invalid request. The file descriptor is not open.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@ -167,18 +292,22 @@ IO Channels
<!-- ##### USER_FUNCTION GIOFunc ##### -->
<para>
Specifies the type of function passed to g_io_add_watch() or
g_io_add_watch_full(), which is called when the requested condition on a
#GIOChannel is satisfied.
</para>
@source:
@condition:
@data:
@Returns:
@source: the #GIOChannel event source.
@condition: the condition which has been satisfied.
@data: user data set in g_io_add_watch() or g_io_add_watch_full().
@Returns: the function should return FALSE if the event source should be
removed.
<!-- ##### STRUCT GIOFuncs ##### -->
<para>
A table of functions used to handle different types of #GIOChannel in a
generic way.
</para>
@io_read:

25
docs/reference/glib/tmpl/limits.sgml
View File

@ -2,11 +2,12 @@
Limits of Basic Types
<!-- ##### SECTION Short_Description ##### -->
portable method of determining the limits of the standard types.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a portable method to determine the limits of some of
the standard integer and floating point types.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,14 +17,14 @@ Limits of Basic Types
<!-- ##### MACRO G_MININT ##### -->
<para>
The minimum value which can be held in a #gint.
</para>
<!-- ##### MACRO G_MAXINT ##### -->
<para>
The maximum value which can be held in a #gint.
</para>
@ -37,14 +38,14 @@ Limits of Basic Types
<!-- ##### MACRO G_MINSHORT ##### -->
<para>
The minimum value which can be held in a #gshort.
</para>
<!-- ##### MACRO G_MAXSHORT ##### -->
<para>
The maximum value which can be held in a #gshort.
</para>
@ -58,14 +59,14 @@ Limits of Basic Types
<!-- ##### MACRO G_MINLONG ##### -->
<para>
The minimum value which can be held in a #glong.
</para>
<!-- ##### MACRO G_MAXLONG ##### -->
<para>
The maximum value which can be held in a #glong.
</para>
@ -79,28 +80,28 @@ Limits of Basic Types
<!-- ##### MACRO G_MINFLOAT ##### -->
<para>
The minimum value which can be held in a #gfloat.
</para>
<!-- ##### MACRO G_MAXFLOAT ##### -->
<para>
The maximum value which can be held in a #gfloat.
</para>
<!-- ##### MACRO G_MINDOUBLE ##### -->
<para>
The minimum value which can be held in a #gdouble.
</para>
<!-- ##### MACRO G_MAXDOUBLE ##### -->
<para>
The maximum value which can be held in a #gdouble.
</para>

320
docs/reference/glib/tmpl/linked_lists_double.sgml
View File

@ -2,11 +2,61 @@
Doubly-Linked Lists
<!-- ##### SECTION Short_Description ##### -->
linked lists containing integer values or pointers to data, with the ability
to iterate over the list in both directions.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GList structure and its associated functions provide a standard
doubly-linked list data structure.
</para>
<para>
Each element in the list contains a piece of data, together with pointers
which link to the previous and next elements in the list.
Using these pointers it is possible to move through the list in both
directions (unlike the
<link linkend="glib-Singly-Linked-lists">Singly-Linked Lists</link>
which only allows movement through the list in the forward direction).
</para>
<para>
The data contained in each element can be either integer values, by using one
of the
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
or simply pointers to any type of data.
</para>
<para>
List elements are allocated in blocks using a #GListAllocator, which is
more efficient than allocating elements individually.
</para>
<para>
Note that most of the #GList functions expect to be passed a pointer to
the first element in the list. The functions which insert elements return
the new start of the list, which may have changed.
</para>
<para>
There is no function to create a #GList. NULL is considered to be the empty
list so you simply set a #GList* to NULL.
</para>
<para>
To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
and g_list_insert_sorted().
</para>
<para>
To remove elements, use g_list_remove().
</para>
<para>
To find elements in the list use g_list_first(), g_list_last(), g_list_next(),
g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and
g_list_find_custom().
</para>
<para>
To find the index of an element use g_list_position() and g_list_index().
</para>
<para>
To call a function for each element in the list use g_list_foreach().
</para>
<para>
To free the entire list, use g_list_free().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +66,12 @@ Doubly-Linked Lists
<!-- ##### STRUCT GList ##### -->
<para>
The #GList struct is used for each element in a doubly-linked list.
The <structfield>data</structfield> field holds the element's data, which can
be a pointer to any kind of data, or any integer value using the
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
The <structfield>next</structfield> and <structfield>prev</structfield>
pointers are the links to the next and previous elements in the list.
</para>
@data:
@ -25,64 +80,103 @@ Doubly-Linked Lists
<!-- ##### FUNCTION g_list_append ##### -->
<para>
Adds a new element on to the end of the list.
</para>
<note>
<para>
The return value is the new start of the list, which may have changed, so
make sure you store the new value.
</para>
</note>
<informalexample><programlisting>
/* Notice that these are initialized to the empty list. */
GList *list = NULL, *number_list = NULL;
@list:
@data:
@Returns:
/* This is a list of strings. */
list = g_list_append (list, "first");
list = g_list_append (list, "second");
/* This is a list of integers. */
number_list = g_list_append (number_list, GINT_TO_POINTER (27));
number_list = g_list_append (number_list, GINT_TO_POINTER (14));
</programlisting></informalexample>
@list: a pointer to a #GList.
@data: the data for the new element.
@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_prepend ##### -->
<para>
Adds a new element on to the start of the list.
</para>
<note>
<para>
The return value is the new start of the list, which may have changed, so
make sure you store the new value.
</para>
</note>
<informalexample><programlisting>
/* Notice that it is initialized to the empty list. */
GList *list = NULL;
list = g_list_prepend (list, "last");
list = g_list_prepend (list, "first");
</programlisting></informalexample>
@list:
@data:
@Returns:
@list: a pointer to a #GList.
@data: the data for the new element.
@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_insert ##### -->
<para>
Inserts a new element into the list at the given position.
</para>
@list:
@data:
@position:
@Returns:
@list: a pointer to a #GList.
@data: the data for the new element.
@position: the position to insert the element. If this is negative, or is
larger than the number of elements in the list, the new element is added on
to the end of the list.
@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_insert_sorted ##### -->
<para>
Inserts a new element into the list, using the given comparison function
to determine its position.
</para>
@list:
@data:
@func:
@Returns:
@list: a pointer to a #GList.
@data: the data for the new element.
@func: the function to compare elements in the list. It should return a
number > 0 if the first parameter comes after the second parameter in
the sort order.
@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_remove ##### -->
<para>
Removes an element from a #GList.
If two elements contain the same data, only the first is removed.
If none of the elements contain the data, the #GList is unchanged.
</para>
@list:
@data:
@Returns:
@list: a #GList.
@data: the data of the element to remove.
@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_remove_link ##### -->
<para>
Removes an element from a #GList, without freeing the element.
The removed element's prev and next links are set to NULL, so that it becomes a
self-contained list with one element.
</para>
@list:
@llink:
@Returns:
@list: a #GList.
@llink: an element in the #GList.
@Returns: the new start of the #GList, without the element.
<!-- ##### FUNCTION g_list_delete_link ##### -->
@ -97,200 +191,234 @@ Doubly-Linked Lists
<!-- ##### FUNCTION g_list_free ##### -->
<para>
Frees all of the memory used by a #GList.
The freed elements are added to the #GListAllocator free list.
</para>
<note>
<para>
If list elements contain dynamically-allocated memory, they should be freed
first.
</para>
</note>
@list:
<!-- ##### FUNCTION g_list_alloc ##### -->
<para>
Allocates space for one #GList element.
It is called by g_list_append(), g_list_prepend(), g_list_insert() and
g_list_insert_sorted() and so is rarely used on its own.
</para>
@Returns:
@Returns: a pointer to the newly-allocated #GList element.
<!-- ##### FUNCTION g_list_free_1 ##### -->
<para>
Frees one #GList element.
It is usually used after g_list_remove_link().
</para>
@list:
@list: a #GList element.
<!-- ##### FUNCTION g_list_length ##### -->
<para>
Gets the number of elements in a #GList.
</para>
@list:
@Returns:
@list: a #GList.
@Returns: the number of elements in the #GList.
<!-- ##### FUNCTION g_list_copy ##### -->
<para>
Copies a #GList.
</para>
<para>
Note that this is a "shallow" copy. If the list elements consist of pointers
to data, the pointers are copied but the actual data isn't.
</para>
@list:
@Returns:
@list: a #GList.
@Returns: a copy of @list.
<!-- ##### FUNCTION g_list_reverse ##### -->
<para>
Reverses a #GList.
It simply switches the next and prev pointers of each element.
</para>
@list:
@Returns:
@list: a #GList.
@Returns: the start of the reversed #GList.
<!-- ##### FUNCTION g_list_sort ##### -->
<para>
Sorts a #GList using the given comparison function.
</para>
@list:
@compare_func:
@Returns:
@list: a #GList.
@compare_func: the comparison function used to sort the #GList. This function
is passed 2 elements of the #GList and should return 0 if they are equal,
a negative value if the first element comes before the second, or a positive
value if the first element comes after the second.
@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_list_concat ##### -->
<para>
Adds the second #GList onto the end of the first #GList.
Note that the elements of the second #GList are not copied.
They are used directly.
</para>
@list1:
@list2:
@Returns:
@list1: a #GList.
@list2: the #GList to add to the end of the first #GList.
@Returns: the start of the new #GList.
<!-- ##### FUNCTION g_list_foreach ##### -->
<para>
Calls a function for each element of a #GList.
</para>
@list:
@func:
@user_data:
@list: a #GList.
@func: the function to call with each element's data.
@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GFunc ##### -->
<para>
Specifies the type of functions passed to g_list_foreach() and
g_slist_foreach().
</para>
@data:
@user_data:
@data: the element's data.
@user_data: user data passed to g_list_foreach() or g_slist_foreach().
<!-- ##### FUNCTION g_list_first ##### -->
<para>
Gets the first element in a #GList.
</para>
@list:
@Returns:
@list: a #GList.
@Returns: the first element in a #GList, or NULL if the #GList has no elements.
<!-- ##### FUNCTION g_list_last ##### -->
<para>
Gets the last element in a #GList.
</para>
@list:
@Returns:
@list: a #GList.
@Returns: the last element in the #GList, or NULL if the #GList has no
elements.
<!-- ##### MACRO g_list_previous ##### -->
<para>
A convenience macro to gets the previous element in a #GList.
</para>
@list:
@list: an element in a #GList.
@Returns: the previous element, or NULL if there are no previous elements.
<!-- ##### MACRO g_list_next ##### -->
<para>
A convenience macro to gets the next element in a #GList.
</para>
@list:
@list: an element in a #GList.
@Returns: the next element, or NULL if there are no more elements.
<!-- ##### FUNCTION g_list_nth ##### -->
<para>
Gets the element at the given position in a #GList.
</para>
@list:
@n:
@Returns:
@list: a #GList.
@n: the position of the element, counting from 0.
@Returns: the element, or NULL if the position is off the end of the #GList.
<!-- ##### FUNCTION g_list_nth_data ##### -->
<para>
Gets the data of the element at the given position.
</para>
@list:
@n:
@Returns:
@list: a #GList.
@n: the position of the element.
@Returns: the element's data, or NULL if the position is off the end of the
#GList.
<!-- ##### FUNCTION g_list_find ##### -->
<para>
Finds the element in a #GList which contains the given data.
</para>
@list:
@data:
@Returns:
@list: a #GList.
@data: the element data to find.
@Returns: the found #GList element, or NULL if it is not found.
<!-- ##### FUNCTION g_list_find_custom ##### -->
<para>
Finds an element in a #GList, using a supplied function to find the desired
element.
It iterates over the list, calling the given function which should return 0
when the desired element is found.
The function takes two #gconstpointer arguments, the #GList element's data
and the given user data.
</para>
@list:
@data:
@func:
@Returns:
@list: a #GList.
@data: user data passed to the function.
@func: the function to call for each element. It should return 0 when the
desired element is found.
@Returns: the found #GList element, or NULL if it is not found.
<!-- ##### FUNCTION g_list_position ##### -->
<para>
Gets the position of the given element in the #GList (starting from 0).
</para>
@list:
@llink:
@Returns:
@list: a #GList.
@llink: an element in the #GList.
@Returns: the position of the element in the #GList, or -1 if the element is
not found.
<!-- ##### FUNCTION g_list_index ##### -->
<para>
Gets the position of the element containing the given data (starting from 0).
</para>
@list:
@data:
@Returns:
@list: a #GList.
@data: the data to find.
@Returns: the index of the element containing the data, or -1 if the data
is not found.
<!-- ##### FUNCTION g_list_push_allocator ##### -->
<para>
Sets the allocator to use to allocate #GList elements.
Use g_list_pop_allocator() to restore the previous allocator.
</para>
@allocator:
@allocator: the #GAllocator to use when allocating #GList elements.
<!-- ##### FUNCTION g_list_pop_allocator ##### -->
<para>
Restores the previous #GAllocator, used when allocating #GList elements.
</para>

297
docs/reference/glib/tmpl/linked_lists_single.sgml
View File

@ -2,11 +2,61 @@
Singly-Linked Lists
<!-- ##### SECTION Short_Description ##### -->
linked lists containing integer values or pointers to data, limited to
iterating over the list in one direction.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GSList structure and its associated functions provide a standard
singly-linked list data structure.
</para>
<para>
Each element in the list contains a piece of data, together with a pointer
which links to the next element in the list.
Using this pointer it is possible to move through the list in one
direction only (unlike the
<link linkend="glib-Doubly-Linked-lists">Doubly-Linked Lists</link>
which allow movement in both directions).
</para>
<para>
The data contained in each element can be either integer values, by using one
of the
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
or simply pointers to any type of data.
</para>
<para>
List elements are allocated in blocks using a #GListAllocator, which is
more efficient than allocating elements individually.
</para>
<para>
Note that most of the #GSList functions expect to be passed a pointer to
the first element in the list. The functions which insert elements return
the new start of the list, which may have changed.
</para>
<para>
There is no function to create a #GSList. NULL is considered to be the empty
list so you simply set a #GSList* to NULL.
</para>
<para>
To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert()
and g_slist_insert_sorted().
</para>
<para>
To remove elements, use g_slist_remove().
</para>
<para>
To find elements in the list use g_slist_last(), g_slist_next(),
g_slist_nth(), g_slist_nth_data(), g_slist_find() and
g_slist_find_custom().
</para>
<para>
To find the index of an element use g_slist_position() and g_slist_index().
</para>
<para>
To call a function for each element in the list use g_slist_foreach().
</para>
<para>
To free the entire list, use g_slist_free().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +66,12 @@ Singly-Linked Lists
<!-- ##### STRUCT GSList ##### -->
<para>
The #GSList struct is used for each element in the singly-linked list.
The <structfield>data</structfield> field holds the element's data, which can
be a pointer to any kind of data, or any integer value using the
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
The <structfield>next</structfield> field contains the link to the next
element in the list.
</para>
@data:
@ -24,41 +79,75 @@ Singly-Linked Lists
<!-- ##### FUNCTION g_slist_alloc ##### -->
<para>
Allocates space for one #GSList element.
It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and
g_slist_insert_sorted() functions and so is rarely used on its own.
</para>
@Returns:
@Returns: a pointer to the newly-allocated #GSList element.
<!-- ##### FUNCTION g_slist_append ##### -->
<para>
Adds a new element on to the end of the list.
</para>
<note>
<para>
The return value is the new start of the list, which may have changed, so
make sure you store the new value.
</para>
</note>
<informalexample><programlisting>
/* Notice that these are initialized to the empty list. */
GSList *list = NULL, *number_list = NULL;
@list:
@data:
@Returns:
/* This is a list of strings. */
list = g_slist_append (list, "first");
list = g_slist_append (list, "second");
/* This is a list of integers. */
number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
</programlisting></informalexample>
@list: a #GSList.
@data: the data for the new element.
@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_prepend ##### -->
<para>
Adds a new element on to the start of the list.
</para>
<note>
<para>
The return value is the new start of the list, which may have changed, so
make sure you store the new value.
</para>
</note>
<informalexample><programlisting>
/* Notice that it is initialized to the empty list. */
GSList *list = NULL;
list = g_slist_prepend (list, "last");
list = g_slist_prepend (list, "first");
</programlisting></informalexample>
@list:
@data:
@Returns:
@list: a #GSList.
@data: the data for the new element.
@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_insert ##### -->
<para>
Inserts a new element into the list at the given position.
</para>
@list:
@data:
@position:
@Returns:
@list: a #GSList.
@data: the data for the new element.
@position: the position to insert the element. If this is negative, or is
larger than the number of elements in the list, the new element is added on
to the end of the list.
@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_insert_before ##### -->
@ -74,33 +163,42 @@ Singly-Linked Lists
<!-- ##### FUNCTION g_slist_insert_sorted ##### -->
<para>
Inserts a new element into the list, using the given comparison function
to determine its position.
</para>
@list:
@data:
@func:
@Returns:
@list: a #GSList.
@data: the data for the new element.
@func: the function to compare elements in the list. It should return a
number > 0 if the first parameter comes after the second parameter in
the sort order.
@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_remove ##### -->
<para>
Removes an element from a #GSList.
If two elements contain the same data, only the first is removed.
If none of the elements contain the data, the #GSList is unchanged.
</para>
@list:
@data:
@Returns:
@list: a #GSList.
@data: the data of the element to remove.
@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_remove_link ##### -->
<para>
Removes an element from a #GSList, without freeing the element.
The removed element's next link is set to NULL, so that it becomes a
self-contained list with one element.
</para>
@list:
@list: a #GSList.
@link:
@Returns:
@Returns: the new start of the #GSList, without the element.
<!-- # Unused Parameters # -->
@llink: an element in the #GSList.
<!-- ##### FUNCTION g_slist_delete_link ##### -->
@ -115,166 +213,189 @@ Singly-Linked Lists
<!-- ##### FUNCTION g_slist_free ##### -->
<para>
Frees all of the memory used by a #GSList.
The freed elements are added to the #GListAllocator free list.
</para>
@list:
@list: a #GSList.
<!-- ##### FUNCTION g_slist_free_1 ##### -->
<para>
Frees one #GSList element.
It is usually used after g_slist_remove_link().
</para>
@list:
@list: a #GSList element.
<!-- ##### FUNCTION g_slist_length ##### -->
<para>
Gets the number of elements in a #GSList.
</para>
@list:
@Returns:
@list: a #GSList.
@Returns: the number of elements in the #GSList.
<!-- ##### FUNCTION g_slist_copy ##### -->
<para>
Copies a #GSList.
</para>
<para>
Note that this is a "shallow" copy. If the list elements consist of pointers
to data, the pointers are copied but the actual data isn't.
</para>
@list:
@Returns:
@list: a #GSList.
@Returns: a copy of @list.
<!-- ##### FUNCTION g_slist_reverse ##### -->
<para>
Reverses a #GSList.
</para>
@list:
@Returns:
@list: a #GSList.
@Returns: the start of the reversed #GSList.
<!-- ##### FUNCTION g_slist_sort ##### -->
<para>
Sorts a #GSList using the given comparison function.
</para>
@list:
@compare_func:
@Returns:
@list: a #GSList.
@compare_func: the comparison function used to sort the #GSList. This function
is passed 2 elements of the #GSList and should return 0 if they are equal,
a negative value if the first element comes before the second, or a positive
value if the first element comes after the second.
@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_slist_concat ##### -->
<para>
Adds the second #GSList onto the end of the first #GSList.
Note that the elements of the second #GSList are not copied.
They are used directly.
</para>
@list1:
@list2:
@Returns:
@list1: a #GSList.
@list2: the #GSList to add to the end of the first #GSList.
@Returns: the start of the new #GSList.
<!-- ##### FUNCTION g_slist_foreach ##### -->
<para>
Calls a function for each element of a #GSList.
</para>
@list:
@func:
@user_data:
@list: a #GSList.
@func: the function to call with each element's data.
@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_slist_last ##### -->
<para>
Gets the last element in a #GSList.
</para>
@list:
@Returns:
@list: a #GSList.
@Returns: the last element in the #GSList, or NULL if the #GSList has no
elements.
<!-- ##### MACRO g_slist_next ##### -->
<para>
A convenience macro to gets the next element in a #GSList.
</para>
@slist:
@slist: an element in a #GSList.
@Returns: the next element, or NULL if there are no more elements.
<!-- ##### FUNCTION g_slist_nth ##### -->
<para>
Gets the element at the given position in a #GSList.
</para>
@list:
@n:
@Returns:
@list: a #GSList.
@n: the position of the element, counting from 0.
@Returns: the element, or NULL if the position is off the end of the #GSList.
<!-- ##### FUNCTION g_slist_nth_data ##### -->
<para>
Gets the data of the element at the given position.
</para>
@list:
@n:
@Returns:
@list: a #GSList.
@n: the position of the element.
@Returns: the element's data, or NULL if the position is off the end of the
#GSList.
<!-- ##### FUNCTION g_slist_find ##### -->
<para>
Finds the element in a #GSList which contains the given data.
</para>
@list:
@data:
@Returns:
@list: a #GSList.
@data: the element data to find.
@Returns: the found #GSList element, or NULL if it is not found.
<!-- ##### FUNCTION g_slist_find_custom ##### -->
<para>
Finds an element in a #GSList, using a supplied function to find the desired
element.
It iterates over the list, calling the given function which should return 0
when the desired element is found.
The function takes two #gconstpointer arguments, the #GSList element's data
and the given user data.
</para>
@list:
@data:
@func:
@Returns:
@list: a #GSList.
@data: user data passed to the function.
@func: the function to call for each element. It should return 0 when the
desired element is found.
@Returns: the found #GSList element, or NULL if it is not found.
<!-- ##### FUNCTION g_slist_position ##### -->
<para>
Gets the position of the given element in the #GSList (starting from 0).
</para>
@list:
@llink:
@Returns:
@list: a #GSList.
@llink: an element in the #GSList.
@Returns: the position of the element in the #GSList, or -1 if the element
is not found.
<!-- ##### FUNCTION g_slist_index ##### -->
<para>
Gets the position of the element containing the given data (starting from 0).
</para>
@list:
@data:
@Returns:
@list: a #GSList.
@data: the data to find.
@Returns: the index of the element containing the data, or -1 if the data
is not found.
<!-- ##### FUNCTION g_slist_push_allocator ##### -->
<para>
Sets the allocator to use to allocate #GSList elements.
Use g_slist_pop_allocator() to restore the previous allocator.
</para>
@allocator:
@allocator: the #GAllocator to use when allocating #GSList elements.
<!-- ##### FUNCTION g_slist_pop_allocator ##### -->
<para>
Restores the previous #GAllocator, used when allocating #GSList elements.
</para>

121
docs/reference/glib/tmpl/macros.sgml
View File

@ -2,11 +2,11 @@
Standard Macros
<!-- ##### SECTION Short_Description ##### -->
commonly-used macros.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a few commonly-used features.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,21 +16,21 @@ Standard Macros
<!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
<para>
The major version number of the GLib library.
</para>
<!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
<para>
The minor version number of the GLib library.
</para>
<!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
<para>
The micro version number of the GLib library.
</para>
@ -58,124 +58,171 @@ Standard Macros
<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
<para>
Checks the version of the GLib library.
It returns TRUE if the GLib library is the same or newer than the given
version.
<example>
<title>Checking the version of the GLib library.</title>
<programlisting>
if (!GLIB_CHECK_VERSION (1, 2, 0))
g_error ("GLib version 1.2.0 or above is needed");
</programlisting>
</example>
</para>
@major:
@minor:
@micro:
@major: the major version number.
@minor: the minor version number.
@micro: the micro version number.
<!-- ##### MACRO G_DIR_SEPARATOR ##### -->
<para>
The directory separator character.
This is '/' on Unix machines and '\' under Windows.
</para>
<!-- ##### MACRO G_DIR_SEPARATOR_S ##### -->
<para>
The directory separator as a string.
This is "/" on Unix machines and "\" under Windows.
</para>
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### -->
<para>
The search path separator character.
This is ':' on Unix machines and ';' under Windows.
</para>
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### -->
<para>
The search path separator as a string.
This is ":" on Unix machines and ";" under Windows.
</para>
<!-- ##### MACRO TRUE ##### -->
<para>
Defines the TRUE value for the #gboolean type.
</para>
<!-- ##### MACRO FALSE ##### -->
<para>
Defines the FALSE value for the #gboolean type.
</para>
<!-- ##### MACRO NULL ##### -->
<para>
Defines the standard NULL pointer.
</para>
<!-- ##### MACRO MIN ##### -->
<para>
Calculates the minimum of @a and @b.
</para>
@a:
@b:
@a: a numeric value.
@b: a numeric value.
@Returns: the minimum of @a and @b.
<!-- ##### MACRO MAX ##### -->
<para>
Calculates the maximum of @a and @b.
</para>
@a:
@b:
@a: a numeric value.
@b: a numeric value.
@Returns: the maximum of @a and @b.
<!-- ##### MACRO ABS ##### -->
<para>
Calculates the absolute value of @a.
The absolute value is simply the number with any negative sign taken away.
</para>
<para>
For example,
<itemizedlist>
<listitem><para>
ABS(-10) is 10.
</para></listitem>
<listitem><para>
ABS(10) is also 10.
</para></listitem>
</itemizedlist>
</para>
@a:
@a: a numeric value.
@Returns: the absolute value of @a.
<!-- ##### MACRO CLAMP ##### -->
<para>
Ensures that @x is between the limits set by @low and @high.
</para>
<para>
For example,
<itemizedlist>
<listitem><para>
CLAMP(5, 10, 15) is 10.
</para></listitem>
<listitem><para>
CLAMP(15, 5, 10) is 10.
</para></listitem>
<listitem><para>
CLAMP(20, 15, 25) is 20.
</para></listitem>
</itemizedlist>
</para>
@x:
@low:
@high:
@x: the value to clamp.
@low: the minimum value allowed.
@high: the maximum value allowed.
@Returns: the value of @x clamped to the range between @low and @high.
<!-- ##### MACRO G_STRUCT_MEMBER ##### -->
<para>
Returns a member of a structure at a given offset, using the given type.
</para>
@member_type:
@struct_p:
@struct_offset:
@member_type: the type of the struct field.
@struct_p: a pointer to a struct.
@struct_offset: the offset of the field from the start of the struct, in bytes.
@Returns: the struct member.
<!-- ##### MACRO G_STRUCT_MEMBER_P ##### -->
<para>
Returns an untyped pointer to a given offset of a struct.
</para>
@struct_p:
@struct_offset:
@struct_p: a pointer to a struct.
@struct_offset: the offset from the start of the struct, in bytes.
@Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
<!-- ##### MACRO G_STRUCT_OFFSET ##### -->
<para>
Returns the offset, in bytes, of a member of a struct.
</para>
@struct_type:
@member:
@struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
@member: a field in the structure, e.g. <structfield>window</structfield>.
@Returns: the offset of @member from the start of @struct_type.

78
docs/reference/glib/tmpl/macros_misc.sgml
View File

@ -2,11 +2,12 @@
Miscellaneous Macros
<!-- ##### SECTION Short_Description ##### -->
specialised macros which are not used often.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide more specialized features which are not needed so often
by application programmers.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,21 +17,24 @@ Miscellaneous Macros
<!-- ##### MACRO G_INLINE_FUNC ##### -->
<para>
Used to declare inline functions. If inline functions are not supported on
the particular platform, the macro evaluates to the empty string.
</para>
<!-- ##### MACRO G_STMT_START ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>
<!-- ##### MACRO G_STMT_END ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>
@ -45,11 +49,11 @@ Miscellaneous Macros
<!-- ##### MACRO G_VA_COPY ##### -->
<para>
Portable way to copy <type>va_list</type> variables.
</para>
@ap1:
@ap2:
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
@ap2: a <type>va_list</type>.
<!-- ##### MACRO G_STRINGIFY ##### -->
@ -62,68 +66,100 @@ Miscellaneous Macros
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
Expands to "__extension__" when GNU C is used as the compiler.
This simply tells GNU C not to warn about the following non-standard code
when compiling with the -pedantic option.
</para>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C const function attribute if the compiler is GNU C.
This enables optimization of the function.
See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
Expands to the GNU C noreturn function attribute if the compiler is GNU C.
It is used for declaring functions which never return.
It enables optimization of the function, and avoids possible compiler
warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
Expands to the GNU C unused function attribute if the compiler is GNU C.
It is used for declaring functions which may never be used.
It avoids possible compiler warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
Expands to the GNU C format function attribute if the compiler is GNU C.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
@format_idx:
@arg_idx:
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
Expands to the GNU C format function attribute if the compiler is GNU C.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>scanf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
@format_idx:
@arg_idx:
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
Expands to the GNU C format_arg function attribute if the compiler is GNU C.
This is used for declaring functions which take a variable number of
parameters, like <function>printf()</function> and
<function>scanf()</function>. See the GNU C documentation for details.
FIXME: I can't find this in my GNU C documentation. Take out?
</para>
@arg_idx:
@arg_idx: the index of the argument.
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C,
or "" if it isn't.
The GNU C __FUNCTION__ variable contains the name of the current function.
See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C,
or "" if it isn't.
The GNU C __PRETTY_FUNCTION__ variable contains the name of the current
function. For a C program this is the same as the __FUNCTION__ variable
but for C++ it also includes extra information such as the class
and function prototype. See the GNU C documentation for details.
</para>

396
docs/reference/glib/tmpl/main.sgml
View File

@ -2,11 +2,47 @@
The Main Event Loop
<!-- ##### SECTION Short_Description ##### -->
manages all available sources of events.
<!-- ##### SECTION Long_Description ##### -->
<para>
The main event loop manages all the available sources of events for GLib
and GTK+ applications. These events can come from any number of different
types of sources such as file descriptors (plain files, pipes or sockets)
and timeouts.
New types of event sources can also be added using g_source_add().
</para>
<para>
Each event source is assigned a priority.
The default priority, #G_PRIORITY_DEFAULT, is 0.
Values less than 0 denote higher priorities.
Values greater than 0 denote lower priorities.
Events from high priority sources
are always processed before events from lower priority sources.
</para>
<para>
Idle functions can also be added, and assigned a priority. These will be
run whenever no events with a higher priority are ready to be processed.
</para>
<para>
The #GMainLoop data type represents a main event loop.
A #GMainLoop is created with g_main_new(). After adding the initial event
sources, g_main_run() is called. This continuously checks for new events
from each of the event sources and dispatches them.
Finally, the processing of an event from one of the sources leads to a call
to g_main_quit() to exit the main loop, and g_main_run() returns.
</para>
<para>
It is possible to create new instances of #GMainLoop recursively.
This is often used in GTK+ applications when showing modal dialog boxes.
However, all event sources are global; they are not tied to a particular
#GMainLoop.
</para>
<para>
GTK+ contains wrappers of many of these functions,
e.g. gtk_main(), gtk_main_quit(), gtk_events_pending(), gtk_idle_add(),
gtk_timeout_add() and gtk_input_add_full().
In a GTK+ application, these wrapper functions should be used instead.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,180 +52,271 @@ The Main Event Loop
<!-- ##### STRUCT GMainLoop ##### -->
<para>
The #GMainLoop struct is an opaque data type representing the main event loop
of a GLib or GTK+ application.
</para>
<!-- ##### FUNCTION g_main_new ##### -->
<para>
Creates a new #GMainLoop.
</para>
@is_running:
@Returns:
@is_running: set to TRUE to indicate that the loop is running. This is not
very important since calling g_main_run() will set this to TRUE anyway.
@Returns: a new #GMainLoop.
<!-- ##### FUNCTION g_main_destroy ##### -->
<para>
Frees the memory allocated for the #GMainLoop.
</para>
@loop:
@loop: a #GMainLoop.
<!-- ##### FUNCTION g_main_run ##### -->
<para>
Runs a main loop until it stops running, which occurs when g_main_quit()
is called.
</para>
@loop:
@loop: a #GMainLoop.
<!-- ##### FUNCTION g_main_is_running ##### -->
<para>
Returns TRUE if the main loop is running.
</para>
@loop:
@Returns:
@loop: a #GMainLoop.
@Returns: TRUE if the main loop is running.
<!-- ##### FUNCTION g_main_pending ##### -->
<para>
Returns TRUE if any events are pending (i.e. ready to be processed).
</para>
@Returns:
@Returns: TRUE if any events are pending.
<!-- ##### FUNCTION g_main_iteration ##### -->
<para>
Runs a single iteration of the main loop.
This will check which event sources are ready to be processed, and will
process the highest priority event sources which are ready.
</para>
@may_block:
@Returns:
@may_block: set to TRUE if it should block (i.e. wait) until an event source
becomes ready. It will return after an event source has been processed.
If set to FALSE it will return immediately if no event source is ready to be
processed.
@Returns: TRUE if more events are pending.
<!-- ##### FUNCTION g_main_quit ##### -->
<para>
Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
it will now return.
</para>
@loop:
@loop: a #GMainLoop.
<!-- ##### MACRO G_PRIORITY_HIGH ##### -->
<para>
Use this for high priority event sources.
It is not used within GLib or GTK+.
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
<para>
Use this for default priority event sources.
In GLib this priority is used when adding timeout functions with
g_timeout_add().
In GDK this priority is used for events from the X Windows server.
</para>
<!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
<para>
Use this for high priority idle functions.
GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and
#G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to
ensure that any pending resizes are processed before any pending redraws,
so that widgets are not redrawn twice unnecessarily.)
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
<para>
Use this for default priority idle functions.
In GLib this priority is used when adding idle functions with g_idle_add().
</para>
<!-- ##### MACRO G_PRIORITY_LOW ##### -->
<para>
Use this for very low priority background tasks.
It is not used within GLib or GTK+.
</para>
<!-- ##### FUNCTION g_timeout_add ##### -->
<para>
Sets a function to be called at regular intervals, with the default priority,
#G_PRIORITY_DEFAULT.
The function is called repeatedly until it returns FALSE, at which point
the timeout is automatically destroyed and the function will not be called
again.
The first call to the function will be at the end of the first @interval.
</para>
<para>
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).
</para>
@interval:
@function:
@data:
@Returns:
@interval: the time between calls to @function, in milliseconds (1/1000ths
of a second.)
@function: the function to call at each interval.
@data: data to pass to @function.
@Returns: the id of the event source.
<!-- ##### FUNCTION g_timeout_add_full ##### -->
<para>
Sets a function to be called at regular intervals, with the given priority.
The function is called repeatedly until it returns FALSE, at which point
the timeout is automatically destroyed and the function will not be called
again.
The @notify function is called when the timeout is destroyed.
The first call to the function will be at the end of the first @interval.
</para>
<para>
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).
</para>
@priority:
@interval:
@function:
@data:
@notify:
@Returns:
@priority: the priority of the function. See #G_PRIORITY_DEFAULT,
#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
#G_PRIORITY_LOW.
@interval: the time between calls to the function, in milliseconds (1/1000ths
of a second.)
@function: the function to call at each interval.
@data: data to pass to @function (and @notify).
@notify: the function to call when the timeout is destroyed, or NULL.
@Returns: the id of event source.
<!-- ##### USER_FUNCTION GSourceFunc ##### -->
<para>
Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
g_idle_add(), and g_idle_add_full().
</para>
@data:
@Returns:
@data: data passed to the function, set when the source was created with one
of the above functions.
@Returns: it should return FALSE if the source should be removed.
<!-- ##### FUNCTION g_idle_add ##### -->
<para>
Adds a function to be called whenever there are no higher priority events
pending. The function is given the default idle priority,
#G_PRIORITY_DEFAULT_IDLE.
If the function returns FALSE it is automatically removed from the list of
event sources and will not be called again.
</para>
@function:
@data:
@Returns:
@function: the function to call.
@data: data to pass to the function.
@Returns: the id of the event source.
<!-- ##### FUNCTION g_idle_add_full ##### -->
<para>
Adds a function to be called whenever there are no higher priority events
pending.
If the function returns FALSE it is automatically removed from the list of
event sources and will not be called again.
</para>
@priority:
@function:
@data:
@destroy:
@Returns:
@priority: the priority of the idle function, which should be somewhere around
#G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
@function: the function to call.
@data: data to pass to the function.
@destroy: the function to call when the timeout is destroyed, or NULL.
@Returns: the id of the event source.
<!-- ##### FUNCTION g_idle_remove_by_data ##### -->
<para>
Removes the idle function with the given data.
</para>
@data:
@Returns:
@data: the data which is passed to the idle function.
@Returns: TRUE if the idle function was found.
<!-- ##### FUNCTION g_main_add_poll ##### -->
<para>
Adds a file descriptor to be polled.
This is usually combined with g_source_add() to add an event source.
The event source's check function will typically test the revents
field in the #GPollFD struct and return TRUE if events need to be processed.
</para>
@fd:
@priority:
@fd: a #GPollFD, which is a file descriptor together with a bitwise
combination of #GIOCondition flags determining which events to poll for.
@priority: the priority of the poll, which should be the same as the priority
used for g_source_add() to ensure that the file descriptor is polled whenever
the results may be needed.
See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
#G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
<!-- ##### STRUCT GPollFD ##### -->
<para>
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#gint fd;</entry>
<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
</row>
<row>
<entry>#gushort events;</entry>
<entry>a bitwise combination of flags from #GIOCondition, specifying which
events should be polled for. Typically for reading from a file descriptor
you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
%G_IO_OUT | %G_IO_ERR.
</entry>
</row>
<row>
<entry>#gushort revents;</entry>
<entry>a bitwise combination of flags from #GIOCondition, returned from the
poll() function to indicate which events occurred.
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@fd:
@ -198,18 +325,25 @@ The Main Event Loop
<!-- ##### FUNCTION g_main_remove_poll ##### -->
<para>
Removes a file descriptor from the list being polled.
</para>
@fd:
@fd: the #GPollFD to remove.
<!-- ##### FUNCTION g_main_set_poll_func ##### -->
<para>
Sets the function to use to handle polling of file descriptors.
It will be used instead of the <function>poll()</function> system call
(or GLib's replacement function, which is used where
<function>poll()</function> isn't available).
</para>
<para>
This function could possibly be used to integrate the GLib event loop
with an external event loop.
</para>
@func:
@func: the function to call to poll all file descriptors.
<!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
@ -222,32 +356,105 @@ The Main Event Loop
<!-- ##### USER_FUNCTION GPollFunc ##### -->
<para>
Specifies the type of function passed to g_main_set_poll_func().
The semantics of the function should match those of the
<function>poll()</function> system call.
</para>
@ufds:
@nfsd:
@timeout:
@Returns:
@ufds: an array of #GPollFD elements.
@nfsd: the number of elements in @ufds.
@timeout: the maximum time to wait for an event of the file descriptors.
@Returns: the number of #GPollFD elements which have events or errors reported,
or -1 if an error occurred.
<!-- ##### FUNCTION g_source_add ##### -->
<para>
Adds an event source to the main loop.
</para>
@priority:
@can_recurse:
@funcs:
@source_data:
@user_data:
@notify:
@Returns:
@priority: the priority of the event source. See #G_PRIORITY_DEFAULT,
#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
#G_PRIORITY_LOW.
@can_recurse: if it is safe to call the source functions recursively.
@funcs: the functions to handle the source.
@source_data: data specific to the type of event source.
@user_data: user data which will be passed to the user function handling the
source.
@notify: the function to call when the source is destroyed.
@Returns: the id of the event source.
<!-- ##### STRUCT GSourceFuncs ##### -->
<para>
The #GSourceFuncs struct contains a table of functions used to handle
event sources in a generic manner.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>prepare</entry>
<entry>
Called before all the file descriptors are polled.
If the source can determine that it is ready here (without waiting for the
results of the poll() call) it should return TRUE.
It can also return a @timeout value which should be the maximum timeout
(in milliseconds) which should be passed to the poll() call.
The actual timeout used will be -1 if all sources returned -1, or it will
be the minimum of all the @timeout values returned which were >= 0.
</entry>
</row>
<row>
<entry>check</entry>
<entry>
Called after all the file descriptors are polled.
The source should return TRUE if it is ready to be processed.
Note that some time may have passed since the previous prepare function was
called, so the source should be checked again here.
</entry>
</row>
<row>
<entry>dispatch</entry>
<entry>
Called to process the event source, after it has returned TRUE in either
its @prepare or its @check function.
</entry>
</row>
<row>
<entry>destroy</entry>
<entry>
Called when the source is destroyed. It will be called with the user data
parameter passed to the g_source_add() and related functions.
</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<para>
For idle sources, the prepare and check functions always return TRUE to
indicate that the source is always ready to be processed.
The prepare function also returns a timeout value of 0 to ensure that the
poll() call doesn't block (since that would be time wasted which could have
been spent running the idle function).
</para>
<para>
For timeout sources, the prepare and check functions both return TRUE if the
timeout interval has expired.
The prepare function also returns a timeout value to ensure that the poll()
call doesn't block too long and miss the next timeout.
</para>
<para>
For file descriptor sources, the prepare function typically returns FALSE,
since it must wait until poll() has been called before it knows whether any
events need to be processed. It sets the returned timeout to -1 to indicate
that it doesn't mind how long the poll() call blocks.
In the check function, it tests the results of the poll() call to see if
the required condition has been met, and returns TRUE if so.
</para>
@prepare:
@ -257,38 +464,55 @@ The Main Event Loop
<!-- ##### FUNCTION g_source_remove ##### -->
<para>
Removes the event source with the given id.
The id is returned when the source is created, either directly with
g_source_add(), or indirectly with g_idle_add(), g_idle_add_full(),
g_timeout_add() and g_timeout_add_full().
</para>
@tag:
@Returns:
@tag: the id of the event source to remove.
@Returns: TRUE if the source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
<para>
Removes the first event source found with the given #GSourceFuncs and user
data.
</para>
<para>
Event sources are sorted with the highest priority first. Sources with equal
priority are stored in the order in which they were added.
</para>
@funcs:
@user_data:
@Returns:
@funcs: the #GSourceFuncs of the source to remove.
@user_data: the user data of the source to remove.
@Returns: TRUE if an event source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
<para>
Removes the first event source found with the given source data.
</para>
<para>
Event sources are sorted with the highest priority first. Sources with equal
priority are stored in the order in which they were added.
</para>
@source_data:
@Returns:
@source_data: the source data, which contains information specific to the
type of source.
@Returns: TRUE if an event source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
<para>
Removes the first event source found with the given user data.
</para>
<para>
Event sources are sorted with the highest priority first. Sources with equal
priority are stored in the order in which they were added.
</para>
@user_data:
@Returns:
@user_data: the user data of the source to remove.
@Returns: TRUE if an event source was found and removed.

111
docs/reference/glib/tmpl/memory.sgml
View File

@ -2,12 +2,18 @@
Memory Allocation
<!-- ##### SECTION Short_Description ##### -->
general memory-handling.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for allocating and freeing memory.
</para>
<note>
<para>
If any call to allocate memory fails, the application is terminated.
This also means that there is no need to check if the call succeeded.
</para>
</note>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,100 +22,135 @@ Memory Allocation
<!-- ##### MACRO g_new ##### -->
<para>
Allocates @count elements of type @type.
The returned pointer is cast to a pointer to the given type.
If @count is 0 it returns NULL.
</para>
@type:
@count:
@type: the type of the elements to allocate.
@count: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- ##### MACRO g_new0 ##### -->
<para>
Allocates @count elements of type @type, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
If @count is 0 it returns NULL.
</para>
@type:
@count:
@type: the type of the elements to allocate.
@count: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- ##### MACRO g_renew ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
@count elements of type @type. It returns the new address of the memory,
which may have been moved.
</para>
@type:
@mem:
@count:
@type: the type of the elements to allocate.
@mem: the currently allocated memory.
@count: the number of elements to allocate.
@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
<!-- ##### FUNCTION g_malloc ##### -->
<para>
Allocates @size bytes of memory.
If @size is 0 it returns NULL.
</para>
@size:
@Returns:
@size: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_malloc0 ##### -->
<para>
Allocates @size bytes of memory, initialized to 0's.
If @size is 0 it returns NULL.
</para>
@size:
@Returns:
@size: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_realloc ##### -->
<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.
</para>
@mem:
@size:
@Returns:
@mem: the memory to reallocate.
@size: the new size of the allocated memory, in bytes.
@Returns: the new address of the allocated memory.
<!-- ##### FUNCTION g_free ##### -->
<para>
Frees the memory pointed to by @mem.
If @mem is NULL it simply returns.
</para>
@mem:
@mem: the memory to free.
<!-- ##### MACRO g_memmove ##### -->
<para>
Copies a block of memory @n bytes long, from @s to @d.
The source and destination areas may overlap.
</para>
<note>
<para>
On architectures where memmove() is not available, this function is implemented
using bcopy(), which may not be able to handle overlapping areas.
</para>
</note>
@d:
@s:
@n:
@d: the destination address to copy the bytes to.
@s: the source address to copy the bytes from.
@n: the number of bytes to copy.
<!-- ##### FUNCTION g_memdup ##### -->
<para>
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
from @mem. If @mem is NULL it returns NULL.
</para>
@mem:
@byte_size:
@Returns:
@mem: the memory to copy.
@byte_size: the number of bytes to copy.
@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem
is NULL.
<!-- ##### FUNCTION g_mem_profile ##### -->
<para>
Outputs a summary of memory usage.
To use this function you must configure glib with the flag
'--enable-mem-profile=yes' before compiling.
</para>
<para>
It outputs the frequency of allocations of different sizes,
the total number of bytes which have been allocated,
the total number of bytes which have been freed,
and the difference between the previous two values, i.e. the number of bytes
still in use.
</para>
<!-- ##### FUNCTION g_mem_check ##### -->
<para>
Checks if the given memory has already been freed. If it has it outputs
a warning message.
To use this function you must configure glib with the flag
'--enable-mem-check=yes' before compiling.
</para>
@mem:
@mem: the memory to check.

231
docs/reference/glib/tmpl/memory_chunks.sgml
View File

@ -2,12 +2,120 @@
Memory Chunks
<!-- ##### SECTION Short_Description ##### -->
efficient way to allocate groups of equal-sized chunks of memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
Memory chunks provide an efficient way to allocate equal-sized pieces of
memory, called atoms. They are used extensively within GLib itself.
For example, the
<link linkend="glib-Doubly-Linked-lists">Doubly Linked Lists</link>
use memory chunks to allocate space for elements of the lists.
</para>
<para>
There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE.
<itemizedlist>
<listitem><para>
#G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never
be freed individually. The memory chunk can only be free in its entirety.
</para></listitem>
<listitem><para>
#G_ALLOC_AND_FREE chunks do allow atoms to be freed individually.
The disadvantage of this is that the memory chunk has to keep track of which
atoms have been freed. This results in more memory being used and a slight
degradation in performance.
</para></listitem>
</itemizedlist>
</para>
<para>
To create a memory chunk use g_mem_chunk_new() or the convenience macro
g_mem_chunk_create().
</para>
<para>
To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(),
or the convenience macros g_chunk_new() or g_chunk_new0().
</para>
<para>
To free an atom use g_mem_chunk_free(), or the convenience macro
g_chunk_free(). (Atoms can only be freed if the memory chunk is created
with the type set to #G_ALLOC_AND_FREE.)
</para>
<para>
To free any blocks of memory which are no longer being used, use
g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().
</para>
<para>
To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset().
</para>
<para>
To destroy a memory chunk, use g_mem_chunk_destroy().
</para>
<para>
To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
</para>
<example>
<title>Using a GMemChunk.</title>
<programlisting>
GMemChunk *mem_chunk;
gchar *mem[10000];
gint i;
/* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding
100 bytes. Note that this means that only 2 atoms fit into each memory
block and so isn't very efficient. */
mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE);
/* Now allocate 10000 atoms. */
for (i = 0; i < 10000; i++)
{
mem[i] = g_chunk_new (gchar, mem_chunk);
/* Fill in the atom memory with some junk. */
for (j = 0; j < 50; j++)
mem[i][j] = i * j;
}
/* Now free all of the atoms. Note that since we are going to destroy the
GMemChunk, this wouldn't normally be used. */
for (i = 0; i < 10000; i++)
{
g_mem_chunk_free (mem_chunk, mem[i]);
}
/* We are finished with the GMemChunk, so we destroy it. */
g_mem_chunk_destroy (mem_chunk);
</programlisting></example>
<example>
<title>Using a GMemChunk with data structures.</title>
<programlisting>
GMemChunk *array_mem_chunk;
GRealArray *array;
/* Create a GMemChunk to hold GRealArray structures, using the
g_mem_chunk_create() convenience macro. We want 1024 atoms in each
memory block, and we want to be able to free individual atoms. */
array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);
/* Allocate one atom, using the g_chunk_new() convenience macro. */
array = g_chunk_new (GRealArray, array_mem_chunk);
/* We can now use array just like a normal pointer to a structure. */
array->data = NULL;
array->len = 0;
array->alloc = 0;
array->zero_terminated = (zero_terminated ? 1 : 0);
array->clear = (clear ? 1 : 0);
array->elt_size = elt_size;
/* We can free the element, so it can be reused. */
g_chunk_free (array, array_mem_chunk);
/* We destroy the GMemChunk when we are finished with it. */
g_mem_chunk_destroy (array_mem_chunk);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
@ -16,143 +124,180 @@ Memory Chunks
<!-- ##### STRUCT GMemChunk ##### -->
<para>
The #GMemChunk struct is an opaque data structure representing a memory
chunk. It should be accessed only through the use of the following functions.
</para>
<!-- ##### MACRO G_ALLOC_AND_FREE ##### -->
<para>
Specifies the type of a #GMemChunk.
Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
will be freed individually.
</para>
<!-- ##### MACRO G_ALLOC_ONLY ##### -->
<para>
Specifies the type of a #GMemChunk.
Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
will never be freed individually.
</para>
<!-- ##### FUNCTION g_mem_chunk_new ##### -->
<para>
Creates a new #GMemChunk.
</para>
@name:
@atom_size:
@area_size:
@type:
@Returns:
@name: a string to identify the #GMemChunk. It is not copied so it
should be valid for the lifetime of the #GMemChunk. It is only used in
g_mem_chunk_print(), which is used for debugging.
@atom_size: the size, in bytes, of each element in the #GMemChunk.
@area_size: the size, in bytes, of each block of memory allocated to contain
the atoms.
@type: the type of the #GMemChunk.
#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
#G_ALLOC_ONLY should be used if atoms will never be freed individually.
#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
but it obviously wastes memory if you no longer need many of the atoms.
@Returns: the new #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_alloc ##### -->
<para>
Allocates an atom of memory from a #GMemChunk.
</para>
@mem_chunk:
@Returns:
@mem_chunk: a #GMemChunk.
@Returns: a pointer to the allocated atom.
<!-- ##### FUNCTION g_mem_chunk_alloc0 ##### -->
<para>
Allocates an atom of memory from a #GMemChunk, setting the memory to 0.
</para>
@mem_chunk:
@Returns:
@mem_chunk: a #GMemChunk.
@Returns: a pointer to the allocated atom.
<!-- ##### FUNCTION g_mem_chunk_free ##### -->
<para>
Frees an atom in a #GMemChunk.
This should only be called if the #GMemChunk was created with
#G_ALLOC_AND_FREE. Otherwise it will simply return.
</para>
@mem_chunk:
@mem:
@mem_chunk: a #GMemChunk.
@mem: a pointer to the atom to free.
<!-- ##### FUNCTION g_mem_chunk_destroy ##### -->
<para>
Frees all of the memory allocated for a #GMemChunk.
</para>
@mem_chunk:
@mem_chunk: a #GMemChunk.
<!-- ##### MACRO g_mem_chunk_create ##### -->
<para>
A convenience macro for creating a new #GMemChunk.
It calls g_mem_chunk_new(), using the given type to create the #GMemChunk
name. The atom size is determined using <function>sizeof()</function>, and the
area size is calculated by multiplying the @pre_alloc parameter with
the atom size.
</para>
@type:
@pre_alloc:
@alloc_type:
@type: the type of the atoms, typically a structure name.
@pre_alloc: the number of atoms to store in each block of memory.
@alloc_type: the type of the #GMemChunk.
#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
#G_ALLOC_ONLY should be used if atoms will never be freed individually.
#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
but it obviously wastes memory if you no longer need many of the atoms.
@Returns: the new #GMemChunk.
<!-- ##### MACRO g_chunk_new ##### -->
<para>
A convenience macro to allocate an atom of memory from a #GMemChunk.
It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
</para>
@type:
@chunk:
@type: the type of the #GMemChunk atoms, typically a structure name.
@chunk: a #GMemChunk.
@Returns: a pointer to the allocated atom, cast to a pointer to @type.
<!-- ##### MACRO g_chunk_new0 ##### -->
<para>
A convenience macro to allocate an atom of memory from a #GMemChunk.
It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
</para>
@type:
@chunk:
@type: the type of the #GMemChunk atoms, typically a structure name.
@chunk: a #GMemChunk.
@Returns: a pointer to the allocated atom, cast to a pointer to @type.
<!-- ##### MACRO g_chunk_free ##### -->
<para>
A convenience macro to free an atom of memory from a #GMemChunk.
It simply switches the arguments and calls g_mem_chunk_free()
It is included simply to complement the other convenience macros, g_chunk_new()
and g_chunk_new0().
</para>
@mem:
@mem_chunk:
@mem: a pointer to the atom to be freed.
@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_reset ##### -->
<para>
Resets a GMemChunk to its initial state.
It frees all of the currently allocated blocks of memory.
</para>
@mem_chunk:
@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_clean ##### -->
<para>
Frees any blocks in a #GMemChunk which are no longer being used.
</para>
@mem_chunk:
@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_blow_chunks ##### -->
<para>
Calls g_mem_chunk_clean() on all #GMemChunk objects.
</para>
<!-- ##### FUNCTION g_mem_chunk_info ##### -->
<para>
Outputs debugging information for all #GMemChunk objects currently in use.
It outputs the number of #GMemChunk objects currently allocated,
and calls g_mem_chunk_print() to output information on each one.
</para>
<!-- ##### FUNCTION g_mem_chunk_print ##### -->
<para>
Outputs debugging information for a #GMemChunk.
It outputs the name of the #GMemChunk (set with g_mem_chunk_new()),
the number of bytes used, and the number of blocks of memory allocated.
</para>
@mem_chunk:
@mem_chunk: a #GMemChunk.

184
docs/reference/glib/tmpl/messages.sgml
View File

@ -2,11 +2,17 @@
Message Logging
<!-- ##### SECTION Short_Description ##### -->
versatile support for logging messages with different levels of importance.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for logging error messages or messages
used for debugging.
</para>
<para>
There are several built-in levels of messages, defined in #GLogLevelFlags.
These can be extended with user-defined levels.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,8 +22,19 @@ Message Logging
<!-- ##### MACRO G_LOG_DOMAIN ##### -->
<para>
Defines the log domain.
For applications, this is typically left as the default NULL (or "") domain.
Libraries should define this so that any messages which they log can
be differentiated from messages from other libraries and application code.
But be careful not to define it in any public header files.
</para>
<para>
For example, GTK uses this in its Makefile.am:
</para>
<informalexample><programlisting>
INCLUDES = \
-DG_LOG_DOMAIN=\"Gtk\"
</programlisting></informalexample>
@ -35,32 +52,33 @@ Message Logging
<!-- ##### MACRO G_LOG_FATAL_MASK ##### -->
<para>
GLib log levels that are considered fatal by default.
</para>
<!-- ##### MACRO G_LOG_LEVEL_USER_SHIFT ##### -->
<para>
Log level shift offset for user defined log levels (0-7 are used by GLib).
</para>
<!-- ##### USER_FUNCTION GLogFunc ##### -->
<para>
Specifies the prototype of log handler functions.
</para>
@log_domain:
@log_level:
@message:
@user_data:
@log_domain: the log domain of the message.
@log_level: the log level of the message (including the fatal and recursion
flags).
@message: the message to process.
@user_data: user data, set in g_log_set_handler().
<!-- ##### ENUM GLogLevelFlags ##### -->
<para>
Flags specifying the level of log messages.
</para>
@G_LOG_FLAG_RECURSION:
@ -75,40 +93,54 @@ Message Logging
<!-- ##### FUNCTION g_log ##### -->
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function>abort()</function>
function is called to terminate the program.
</para>
@log_domain:
@log_level:
@format:
@Varargs:
@log_domain: the log domain, usually #G_LOG_DOMAIN.
@log_level: the log level, either from #GLogLevelFlags or a user-defined level.
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_logv ##### -->
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function>abort()</function>
function is called to terminate the program.
</para>
@log_domain:
@log_level:
@format:
@args:
@log_domain: the log domain.
@log_level: the log level.
@format: the message format. See the <function>printf()</function>
documentation.
@args: the parameters to insert into the format string.
<!-- ##### MACRO g_message ##### -->
<para>
A convenience function/macro to log a normal message.
</para>
@...:
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_warning ##### -->
<para>
A convenience function/macro to log a warning message.
</para>
@...:
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_critical ##### -->
@ -121,103 +153,141 @@ Message Logging
<!-- ##### MACRO g_error ##### -->
<para>
A convenience function/macro to log an error message.
Error messages are always fatal, resulting in a call to
<function>abort()</function> to terminate the application.
</para>
@...:
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### FUNCTION g_log_set_handler ##### -->
<para>
Sets the log handler for a domain and a set of log levels.
To handle fatal and recursive messages the @log_levels parameter
must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
</para>
<para>
Note that since the G_LOG_LEVEL_ERROR log level is always fatal, if you want
to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL.
</para>
@log_domain:
@log_levels:
@log_func:
@user_data:
@Returns:
<example>
<title>Adding a log handler for all warning messages</title>
<programlisting>
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
| G_LOG_FLAG_RECURSIVE, my_log_handler, NULL);
</programlisting>
</example>
@log_domain: the log domain, or NULL for the default "" application domain.
@log_levels: the log levels to apply the log handler for. To handle fatal
and recursive messages as well, combine the log levels with the
G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
@log_func: the log handler function.
@user_data: data passed to the log handler.
@Returns: the id of the new handler.
<!-- ##### FUNCTION g_log_remove_handler ##### -->
<para>
Removes the log handler.
</para>
@log_domain:
@handler_id:
@log_domain: the log domain.
@handler_id: the id of the handler, which was returned in g_log_set_handler().
<!-- ##### FUNCTION g_log_set_always_fatal ##### -->
<para>
Sets the message levels which are always fatal, in any log domain.
When a message with any of these levels is logged the program terminates.
You can only set the levels defined by GLib to be fatal.
%G_LOG_LEVEL_ERROR is always fatal.
</para>
@fatal_mask:
@Returns:
@fatal_mask: the mask containing bits set for each level of error which is
to be fatal.
@Returns: the old fatal mask.
<!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
<para>
Sets the log levels which are fatal in the given domain.
%G_LOG_LEVEL_ERROR is always fatal.
</para>
@log_domain:
@fatal_mask:
@Returns:
@log_domain: the log domain.
@fatal_mask: the new fatal mask.
@Returns: the old fatal mask for the log domain.
<!-- ##### FUNCTION g_log_default_handler ##### -->
<para>
The default log handler.
This is used if no log handler has been set for the particular log domain
and log level combination. It outputs the message to stderr or stdout
and if the log level is fatal it calls <function>abort()</function>.
</para>
<para>
stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and
%G_LOG_LEVEL_WARNING. stdout is used for the rest.
(On the Windows platform, stdout is always used.)
</para>
@log_domain:
@log_level:
@message:
@unused_data:
@log_domain: the log domain of the message.
@log_level: the level of the message.
@message: the message.
@unused_data: data passed from g_log which is unused.
<!-- ##### FUNCTION g_set_error_handler ##### -->
<para>
Sets the function to be called to handle error messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func:
@Returns:
@func: the function to be called to handle error messages.
@Returns: the old error handler.
<!-- ##### USER_FUNCTION GErrorFunc ##### -->
<para>
Specifies the type of function passed to g_set_error_handler().
</para>
@str:
@str: the error message.
<!-- ##### FUNCTION g_set_warning_handler ##### -->
<para>
Sets the function to be called to handle warning messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func:
@Returns:
@func: the function to be called to handle warning messages.
@Returns: the old warning handler.
<!-- ##### USER_FUNCTION GWarningFunc ##### -->
<para>
Specifies the type of function passed to g_set_warning_handler().
</para>
@str:
@str: the warning message.
<!-- ##### FUNCTION g_set_message_handler ##### -->
<para>
Sets the function to be called to handle messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func:
@Returns:
@func: the function to be called to handle normal messages.
@Returns: the old message handler.

146
docs/reference/glib/tmpl/misc_utils.sgml
View File

@ -2,11 +2,11 @@
Miscellaneous Utility Functions
<!-- ##### SECTION Short_Description ##### -->
a selection of portable utility functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
These are portable utility functions.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,103 +16,120 @@ Miscellaneous Utility Functions
<!-- ##### FUNCTION g_get_prgname ##### -->
<para>
Gets the name of the program.
(If you are using GDK or GTK the program name is set in gdk_init(), which
is called by gtk_init(). The program name is found by taking the last
component of argv[0].)
</para>
@Returns:
@Returns: the name of the program.
<!-- ##### FUNCTION g_set_prgname ##### -->
<para>
Sets the name of the program.
</para>
@prgname:
@prgname: the name of the program.
<!-- ##### FUNCTION g_getenv ##### -->
<para>
Returns an environment variable.
On windows systems the returned value is only valid until the next call to
g_getenv().
</para>
@variable:
@Returns:
@variable: the environment variable to get.
@Returns: the value of the environment variable, or NULL if the environment
variable is not found.
<!-- ##### FUNCTION g_get_user_name ##### -->
<para>
Gets the user name of the current user.
</para>
@Returns:
@Returns: the user name of the current user.
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
Gets the real name of the user. This comes from the user's entry in the
passwd file.
</para>
@Returns:
@Returns: the user's real name.
<!-- ##### FUNCTION g_get_home_dir ##### -->
<para>
Gets the current user's home directory.
</para>
@Returns:
@Returns: the current user's home directory.
<!-- ##### FUNCTION g_get_tmp_dir ##### -->
<para>
Gets the directory to use for temporary files.
This is found from inspecting the environment variables TMPDIR, TMP, and TEMP
in that order. If none of those are defined "/tmp" is returned.
</para>
@Returns:
@Returns: the directory to use for temporary files.
<!-- ##### FUNCTION g_get_current_dir ##### -->
<para>
Gets the current directory.
The returned string should be freed when no longer needed.
</para>
@Returns:
@Returns: the current directory.
<!-- ##### FUNCTION g_basename ##### -->
<para>
Gets the name of the file without any leading directory components.
It returns a pointer into the given file name string.
</para>
@file_name:
@Returns:
@file_name: the name of the file.
@Returns: the name of the file without any leading directory components.
<!-- ##### FUNCTION g_dirname ##### -->
<para>
Gets the directory components of a file name.
If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.
</para>
@file_name:
@Returns:
@file_name: the name of the file.
@Returns: the directory components of the file.
<!-- ##### FUNCTION g_path_is_absolute ##### -->
<para>
Returns TRUE if the given @file_name is an absolute file name,
i.e. it contains a full path from the root directory such as '/usr/local'
or 'C:/windows' on windows systems.
</para>
@file_name:
@Returns:
@file_name: a file name.
@Returns: TRUE if @file_name is an absolute path.
<!-- ##### FUNCTION g_path_skip_root ##### -->
<para>
Returns a pointer into @file_name after the root component, i.e. after
the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute
path it returns NULL.
</para>
@file_name:
@Returns:
@file_name: a file name.
@Returns: a pointer into @file_name after the root component.
<!-- ##### FUNCTION g_path_get_dirname ##### -->
@ -153,64 +170,81 @@ Miscellaneous Utility Functions
<!-- ##### FUNCTION g_bit_nth_lsf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit upwards. Bits are numbered from 0 (least significant)
to 31. To start searching from the 0th bit, set @nth_bit to -1.
</para>
@mask:
@nth_bit:
@Returns:
@mask: a #guint32 containing up to 32 bit flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is higher than @nth_bit.
<!-- ##### FUNCTION g_bit_nth_msf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit downwards. Bits are numbered from 0 (least significant)
to 31. To start searching from the 31st bit, set @nth_bit to 32 or -1.
</para>
@mask:
@nth_bit:
@Returns:
@mask: a #guint32 containing up to 32 bit flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is lower than @nth_bit.
<!-- ##### FUNCTION g_bit_storage ##### -->
<para>
Gets the number of bits used to hold @number,
e.g. if @number is 4, 3 bits are needed.
</para>
@number:
@Returns:
@number: a guint.
@Returns: the number of bits used to hold @number.
<!-- ##### FUNCTION g_spaced_primes_closest ##### -->
<para>
Gets the smallest prime number from a built-in array of primes which
is larger than @num. This is used within GLib to calculate the optimum
size of a #GHashTable.
</para>
<para>
The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.
</para>
@num:
@Returns:
@num: a guint.
@Returns: the smallest prime number from a built-in array of primes which is
larger than @num.
<!-- ##### FUNCTION g_atexit ##### -->
<para>
Specifies a function to be called at normal program termination.
</para>
@func:
@func: the function to call on normal program termination.
<!-- ##### FUNCTION g_parse_debug_string ##### -->
<para>
Parses a string containing debugging options separated by ':' into a guint
containing bit flags.
This is used within GDK and GTK to parse the debug options passed on the
command line or through environment variables.
</para>
@string:
@keys:
@nkeys:
@Returns:
@string: a list of debug options separated by ':' or "all" to set all flags.
@keys: pointer to an array of #GDebugKey which associate strings with
bit flags.
@nkeys: the number of #GDebugKey in the array.
@Returns: the combined set of bit flags.
<!-- ##### STRUCT GDebugKey ##### -->
<para>
Associates a string with a bit flag.
Used in g_parse_debug_string().
</para>
@key:
@ -218,14 +252,16 @@ Miscellaneous Utility Functions
<!-- ##### USER_FUNCTION GVoidFunc ##### -->
<para>
Declares a type of function which takes no arguments and has no return value.
It is used to specify the type function passed to g_atexit().
</para>
<!-- ##### USER_FUNCTION GFreeFunc ##### -->
<para>
Declares a type of function which takes an arbitrary data pointer argument
and has no return value. It is not currently used in GLib or GTK+.
</para>
@data:

131
docs/reference/glib/tmpl/modules.sgml
View File

@ -2,11 +2,37 @@
Dynamic Loading of Modules
<!-- ##### SECTION Short_Description ##### -->
portable method for dynamically loading 'plug-ins'.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide a portable way to dynamically load object files
(commonly known as 'plug-ins').
The current implementation supports all systems that provide
an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
shl_load() mechanism, and Windows platforms via DLLs.
</para>
<para>
To use them you must first determine whether dynamic loading
is supported on the platform by calling g_module_supported().
If it is, you can open a module with g_module_open(),
find the module's symbols (e.g. function names) with g_module_symbol(),
and later close the module with g_module_close().
g_module_name() will return the file name of a currently opened module.
</para>
<para>
If any of the above functions fail, the error status can be found with
g_module_error().
</para>
<para>
The gmodule implementation features reference counting for opened modules,
and supports hook functions within a module which are called when the
module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
</para>
<para>
If your module introduces static data to common subsystems in the running
program, e.g. through calling g_quark_from_static_string ("my-module-stuff"),
it must ensure that it is never unloaded, by calling g_module_make_resident().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,41 +42,65 @@ Dynamic Loading of Modules
<!-- ##### STRUCT GModule ##### -->
<para>
The #GModule struct is an opaque data structure to represent a
<link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded Module</link>.
It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_module_supported ##### -->
<para>
Checks if modules are supported on the current platform.
</para>
@Returns:
@Returns: TRUE if modules are supported.
<!-- ##### FUNCTION g_module_build_path ##### -->
<para>
A portable way to build the filename of a module. The platform-specific
prefix and suffix are added to the filename, if needed, and the result is
added to the directory, using the correct separator character.
</para>
<para>
The directory should specify the directory where the module can be found.
It can be NULL or an empty string to indicate that the module is in a standard
operating-system specific directory, though this is not recommended since the
wrong module may be found.
</para>
<para>
For example, calling g_module_build_path() on a Linux system with a directory
of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
On a Windows system, using "\Windows" as the directory it will return
"\Windows\mylibrary.dll".
</para>
@directory:
@module_name:
@Returns:
@directory: the directory where the module is. This can be NULL or the empty
string to indicate that the standard operating system-specific directories
will be used, though that is not recommended.
@module_name: the name of the module.
@Returns: the complete path of the module, including the standard library
prefix and suffix. This should be freed when no longer needed.
<!-- ##### FUNCTION g_module_open ##### -->
<para>
Opens a module.
If the module has already been opened, its reference count is incremented.
</para>
@file_name:
@flags:
@Returns:
@file_name: the name of the file containing the module.
@flags: the flags used for opening the module. Currently this can be 0 or
G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
@Returns: a #GModule on success, or NULL on failure.
<!-- ##### ENUM GModuleFlags ##### -->
<para>
Flags passed to g_module_open().
G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
The default action is to bind all symbols when the module is loaded.
(G_MODULE_BIND_LAZY is not supported on all platforms.)
</para>
@G_MODULE_BIND_LAZY:
@ -58,76 +108,85 @@ Dynamic Loading of Modules
<!-- ##### FUNCTION g_module_symbol ##### -->
<para>
Gets a symbol pointer from a module.
</para>
@module:
@symbol_name:
@symbol:
@Returns:
@module: the module.
@symbol_name: the name of the symbol to find.
@symbol: returns the pointer to the symbol value.
@Returns: TRUE on success.
<!-- ##### FUNCTION g_module_name ##### -->
<para>
Gets the file name from a #GModule.
</para>
@module:
@Returns:
@module: the module.
@Returns: the file name of the module, or "main" if the module is the main
program itself.
<!-- ##### FUNCTION g_module_make_resident ##### -->
<para>
Ensures that a module will never be unloaded.
Any future g_module_close() calls on the module will be ignored.
</para>
@module:
@module: a module to make permanently resident.
<!-- ##### FUNCTION g_module_close ##### -->
<para>
Closes a module.
</para>
@module:
@Returns:
@module: the module to close.
@Returns: TRUE on success.
<!-- ##### FUNCTION g_module_error ##### -->
<para>
Gets a string describing the last module error.
</para>
@Returns:
@Returns: a string describing the last module error.
<!-- ##### USER_FUNCTION GModuleCheckInit ##### -->
<para>
Specifies the type of the module initialization function.
If a module contains a function named g_module_check_init() it is called
automatically when the module is loaded. It is passed the #GModule structure
and should return NULL on success or a string describing the initialization
error.
</para>
@module:
@Returns:
@module: the #GModule corresponding to the module which has just been loaded.
@Returns: NULL on success, or a string describing the initialization error.
<!-- ##### USER_FUNCTION GModuleUnload ##### -->
<para>
Specifies the type of the module function called when it is unloaded.
If a module contains a function named g_module_unload() it is called
automatically when the module is unloaded.
It is passed the #GModule structure.
</para>
@module:
@module: the module about to be unloaded.
<!-- ##### MACRO G_MODULE_EXPORT ##### -->
<para>
Used to declare functions exported by modules.
</para>
<!-- ##### MACRO G_MODULE_IMPORT ##### -->
<para>
Used to declare functions imported from modules.
</para>

63
docs/reference/glib/tmpl/quarks.sgml
View File

@ -2,11 +2,28 @@
Quarks
<!-- ##### SECTION Short_Description ##### -->
a 2-way association between a string and a unique integer identifier.
<!-- ##### SECTION Long_Description ##### -->
<para>
Quarks are associations between strings and integer identifiers.
Given either the string or the #GQuark identifier it is possible to
retrieve the other.
</para>
<para>
Quarks are used for both
<link linkend="glib-datasets">Datasets</link> and
<link linkend="glib-keyed-data-lists">Keyed Data Lists</link>.
</para>
<para>
To create a new quark from a string, use g_quark_from_string() or
g_quark_from_static_string().
</para>
<para>
To find the string corresponding to a given #GQuark, use g_quark_to_string().
</para>
<para>
To find the #GQuark corresponding to a given string, use g_quark_try_string().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,43 +33,59 @@ Quarks
<!-- ##### TYPEDEF GQuark ##### -->
<para>
A GQuark is an integer which uniquely identifies a particular string.
</para>
<!-- ##### FUNCTION g_quark_from_string ##### -->
<para>
Gets the #GQuark identifying the given string.
If the string does not currently have an associated #GQuark, a new
#GQuark is created, using a copy of the string.
</para>
@string:
@Returns:
@string: a string.
@Returns: the #GQuark identifying the string.
<!-- ##### FUNCTION g_quark_from_static_string ##### -->
<para>
Gets the #GQuark identifying the given (static) string.
If the string does not currently have an associated #GQuark, a new
#GQuark is created, linked to the given string.
</para>
<para>
Note that this function is identical to g_quark_from_string() except
that if a new #GQuark is created the string itself is used rather than
a copy. This saves memory, but can only be used if the string will
always exist (if, for example, it is a statically-allocated string).
</para>
@string:
@Returns:
@string: a string.
@Returns: the #GQuark identifying the string.
<!-- ##### FUNCTION g_quark_to_string ##### -->
<para>
Gets the string associated with the given #GQuark.
</para>
@quark:
@Returns:
@quark: a #GQuark.
@Returns: the string associated with the #GQuark.
<!-- ##### FUNCTION g_quark_try_string ##### -->
<para>
Gets the #GQuark associated with the given string, or 0 if the string has
no associated #GQuark.
</para>
<para>
If you want the GQuark to be created if it doesn't already exist, use
g_quark_from_string() or g_quark_from_static_string().
</para>
@string:
@Returns:
@string: a string.
@Returns: the #GQuark associated with the string, or 0 if there is no
#GQuark associated with the string.

155
docs/reference/glib/tmpl/relations.sgml
View File

@ -2,11 +2,53 @@
Relations and Tuples
<!-- ##### SECTION Short_Description ##### -->
tables of data which can be indexed on any number of fields.
<!-- ##### SECTION Long_Description ##### -->
<para>
A #GRelation is a table of data which can be indexed on any number of fields,
rather like simple database tables. A #GRelation contains a number of
records, called tuples. Each record contains a number of fields.
Records are not ordered, so it is not possible to find the record at a
particular index.
</para>
<para>
Note that #GRelation tables are currently limited to 2 fields.
</para>
<para>
To create a GRelation, use g_relation_new().
</para>
<para>
To specify which fields should be indexed, use g_relation_index().
Note that this must be called before any tuples are added to the #GRelation.
</para>
<para>
To add records to a #GRelation use g_relation_insert().
</para>
<para>
To determine if a given record appears in a #GRelation, use
g_relation_exists(). Note that fields are compared directly, so pointers
must point to the exact same position (i.e. different copies of the same
string will not match.)
</para>
<para>
To count the number of records which have a particular value in a given
field, use g_relation_count().
</para>
<para>
To get all the records which have a particular value in a given field,
use g_relation_select(). To access fields of the resulting records,
use g_tuples_index(). To free the resulting records use g_tuples_destroy().
</para>
<para>
To delete all records which have a particular value in a given field,
use g_relation_delete().
</para>
<para>
To destroy the #GRelation, use g_relation_destroy().
</para>
<para>
To help debug #GRelation objects, use g_relation_print().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,121 +58,144 @@ Relations and Tuples
<!-- ##### STRUCT GRelation ##### -->
<para>
The #GRelation struct is an opaque data structure to represent a
<link linkend="glib-Relations-and-Tuples">Relation</link>.
It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_relation_new ##### -->
<para>
Creates a new #GRelation with the given number of fields.
Note that currently the number of fields must be 2.
</para>
@fields:
@Returns:
@fields: the number of fields.
@Returns: a new #GRelation.
<!-- ##### FUNCTION g_relation_index ##### -->
<para>
Creates an index on the given field.
Note that this must be called before any records are added to the #GRelation.
</para>
@relation:
@field:
@hash_func:
@key_compare_func:
@relation: a #GRelation.
@field: the field to index, counting from 0.
@hash_func: a function to produce a hash value from the field data.
@key_compare_func: a function to compare two values of the given field.
<!-- ##### FUNCTION g_relation_insert ##### -->
<para>
Inserts a record into a #GRelation.
</para>
@relation:
@Varargs:
@relation: a #GRelation.
@Varargs: the fields of the record to add. This must match the number of
fields in the #GRelation.
<!-- ##### FUNCTION g_relation_exists ##### -->
<para>
Returns TRUE if a record with the given values exists in a #GRelation.
Note that the values are compared directly, so that, for example, two
copies of the same string will not match.
</para>
@relation:
@Varargs:
@Returns:
@relation: a #GRelation.
@Varargs: the fields of the record to compare. The number must match the
number of fields in the #GRelation.
@Returns: TRUE if a record matches.
<!-- ##### FUNCTION g_relation_count ##### -->
<para>
Returns the number of tuples in a #GRelation that have the given value
in the given field.
</para>
@relation:
@key:
@field:
@Returns:
@relation: a #GRelation.
@key: the value to compare with.
@field: the field of each record to match.
@Returns: the number of matches.
<!-- ##### FUNCTION g_relation_select ##### -->
<para>
Returns all of the tuples which have the given key in the given field.
Use g_tuples_index() to access the returned records.
The returned records should be freed with g_tuples_destroy().
</para>
@relation:
@key:
@field:
@Returns:
@relation: a #GRelation.
@key: the value to compare with.
@field: the field of each record to match.
@Returns: the records (tuples) that matched.
<!-- ##### FUNCTION g_relation_delete ##### -->
<para>
Deletes any records from a GRelation that have the given key value in
the given field.
</para>
@relation:
@key:
@field:
@Returns:
@relation: a #GRelation.
@key: the value to compare with.
@field: the field of each record to match.
@Returns: the number of records deleted.
<!-- ##### FUNCTION g_relation_destroy ##### -->
<para>
Destroys the #GRelation, freeing all memory allocated.
However, it does not free memory allocated for the
tuple data, so you should free that first if appropriate.
</para>
@relation:
@relation: a #GRelation.
<!-- ##### FUNCTION g_relation_print ##### -->
<para>
Outputs information about all records in a #GRelation, as well as the indexes.
It is for debugging.
</para>
@relation:
@relation: a #GRelation.
<!-- ##### STRUCT GTuples ##### -->
<para>
The #GTuples struct is used to return records (or tuples) from the
#GRelation by g_relation_select().
It only contains one public member - the number of records that matched.
To access the matched records, you must use g_tuples_index().
</para>
@len:
<!-- ##### FUNCTION g_tuples_destroy ##### -->
<para>
Frees the records which were returned by g_relation_select().
This should always be called after g_relation_select() when you are
finished with the records.
The records are not removed from the #GRelation.
</para>
@tuples:
@tuples: the tuple data to free.
<!-- ##### FUNCTION g_tuples_index ##### -->
<para>
Gets a field from the records returned by g_relation_select().
It returns the given field of the record at the given index.
The returned value should not be changed.
</para>
@tuples:
@index:
@field:
@Returns:
@tuples: the tuple data, returned by g_relation_select().
@index: the index of the record.
@field: the field to return.
@Returns: the field of the record.

253
docs/reference/glib/tmpl/scanner.sgml
View File

@ -2,11 +2,16 @@
Lexical Scanner
<!-- ##### SECTION Short_Description ##### -->
a general purpose lexical scanner.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GScanner and its associated functions provide a general purpose
lexical scanner.
</para>
<para>
FIXME: really needs an example and more detail, but I don't completely
understand it myself. Look at gtkrc.c for some code using the scanner.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +21,22 @@ Lexical Scanner
<!-- ##### STRUCT GScanner ##### -->
<para>
The data structure representing a lexical scanner.
</para>
<para>
You should set input_name after creating the scanner, since it is used
by the default message handler when displaying warnings and errors.
If you are scanning a file, the file name would be a good choice.
</para>
<para>
The <structfield>user_data</structfield> and
<structfield>derived_data</structfield> fields are not used.
If you need to associate extra data with the scanner you can place them here.
</para>
<para>
If you want to use your own message handler you can set the
<structfield>msg_handler</structfield> field. The type of the message
handler function is declared by #GScannerMsgFunc.
</para>
@user_data:
@ -43,16 +63,50 @@ Lexical Scanner
<!-- ##### FUNCTION g_scanner_new ##### -->
<para>
Creates a new #GScanner.
The @config_templ structure specifies the initial settings of the scanner,
which are copied into the #GScanner <structfield>config</structfield> field.
If you pass NULL then the default settings are used.
(See g_scanner_config_template in gscanner.c for the defaults.)
</para>
@config_templ:
@Returns:
@config_templ: the initial scanner settings.
@Returns: the new #GScanner.
<!-- ##### STRUCT GScannerConfig ##### -->
<para>
Specifies the #GScanner settings.
</para>
<para>
<structfield>cset_skip_characters</structfield> specifies which characters
should be skipped by the scanner (the default is the whitespace characters:
space, tab, carriage-return and line-feed).
</para>
<para>
<structfield>cset_identifier_first</structfield> specifies the characters
which can start identifiers.
(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).
</para>
<para>
<structfield>cset_identifier_nth</structfield> specifies the characters
which can be used in identifiers, after the first character.
The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
#G_CSET_LATINC.
</para>
<para>
<structfield>cpair_comment_single</structfield> specifies the characters
at the start and end of single-line comments. The default is "#\n" which
means that single-line comments start with a '#' and continue until a '\n'
(end of line).
</para>
<para>
<structfield>case_sensitive</structfield> specifies if symbols are
case sensitive.
</para>
<para>
The rest of the fields are flags which turn features on or off.
FIXME: should describe these.
</para>
@cset_skip_characters:
@ -83,11 +137,11 @@ Lexical Scanner
<!-- ##### FUNCTION g_scanner_input_file ##### -->
<para>
Prepares to scan a file.
</para>
@scanner:
@input_fd:
@scanner: a #GScanner.
@input_fd: a file descriptor.
<!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
@ -100,105 +154,122 @@ Lexical Scanner
<!-- ##### FUNCTION g_scanner_stat_mode ##### -->
<para>
Gets the file attributes.
This is the <structfield>st_mode</structfield> field from the
<structname>stat</structname> structure. See the <function>stat()</function>
documentation.
</para>
@filename:
@Returns:
@filename: the file name.
@Returns: the file attributes.
<!-- ##### FUNCTION g_scanner_input_text ##### -->
<para>
Prepares to scan a text buffer.
</para>
@scanner:
@text:
@text_len:
@scanner: a #GScanner.
@text: the text buffer to scan.
@text_len: the length of the text buffer.
<!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
<para>
Gets the next token, without removing it from the input stream.
The token data is placed in the
<structfield>next_token</structfield>,
<structfield>next_value</structfield>,
<structfield>next_line</structfield>, and
<structfield>next_position</structfield> fields of the #GScanner structure.
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the type of the token.
<!-- ##### FUNCTION g_scanner_get_next_token ##### -->
<para>
Gets the next token, removing it from the input stream.
The token data is placed in the
<structfield>token</structfield>,
<structfield>value</structfield>,
<structfield>line</structfield>, and
<structfield>position</structfield> fields of the #GScanner structure.
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the type of the token.
<!-- ##### FUNCTION g_scanner_cur_line ##### -->
<para>
Gets the current line in the input stream (counting from 1).
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the current line.
<!-- ##### FUNCTION g_scanner_cur_position ##### -->
<para>
Gets the current position in the current line (counting from 0).
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the current position on the line.
<!-- ##### FUNCTION g_scanner_cur_token ##### -->
<para>
Gets the current token type.
This is simply the <structfield>token</structfield> field in the #GScanner
structure.
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the current token type.
<!-- ##### FUNCTION g_scanner_cur_value ##### -->
<para>
Gets the current token value.
This is simply the <structfield>value</structfield> field in the #GScanner
structure.
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: the current token value.
<!-- ##### FUNCTION g_scanner_eof ##### -->
<para>
Returns TRUE if the scanner has reached the end of the file or text buffer.
</para>
@scanner:
@Returns:
@scanner: a #GScanner.
@Returns: TRUE if the scanner has reached the end of the file or text buffer.
<!-- ##### FUNCTION g_scanner_set_scope ##### -->
<para>
Sets the current scope.
</para>
@scanner:
@scope_id:
@Returns:
@scanner: a #GScanner.
@scope_id: the new scope id.
@Returns: the old scope id.
<!-- ##### FUNCTION g_scanner_scope_add_symbol ##### -->
<para>
Adds a symbol to the given scope.
</para>
@scanner:
@scope_id:
@symbol:
@value:
@scanner: a #GScanner.
@scope_id: the scope id.
@symbol: the symbol to add.
@value: the value of the symbol.
<!-- ##### FUNCTION g_scanner_scope_foreach_symbol ##### -->
@ -210,6 +281,8 @@ Lexical Scanner
@scope_id:
@func:
@user_data:
<!-- # Unused Parameters # -->
@func_data:
<!-- ##### FUNCTION g_scanner_scope_lookup_symbol ##### -->
@ -261,36 +334,42 @@ Lexical Scanner
<!-- ##### FUNCTION g_scanner_warn ##### -->
<para>
Outputs a warning message, via the #GScanner message handler.
</para>
@scanner:
@format:
@Varargs:
@scanner: a #GScanner.
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_scanner_error ##### -->
<para>
Outputs an error message, via the #GScanner message handler.
</para>
@scanner:
@format:
@Varargs:
@scanner: a #GScanner.
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_scanner_unexp_token ##### -->
<para>
Outputs a message resulting from an unexpected token in the input stream.
FIXME: I don't understand the arguments here.
</para>
@scanner:
@expected_token:
@identifier_spec:
@symbol_spec:
@scanner: a #GScanner.
@expected_token: the expected token.
@identifier_spec: a string describing the expected type of identifier,
or NULL to use the default "identifier" string.
@symbol_spec: a string describing the expected type of identifier,
or NULL to use the default "symbol" string.
@symbol_name:
@message:
@is_error:
@message: a message string to output at the end of the warning/error, or NULL.
@is_error: if TRUE it is output as an error. If False it is output as a
warning.
<!-- ##### USER_FUNCTION GScannerMsgFunc ##### -->
@ -305,15 +384,15 @@ Lexical Scanner
<!-- ##### FUNCTION g_scanner_destroy ##### -->
<para>
Frees all memory used by the #GScanner.
</para>
@scanner:
@scanner: a #GScanner.
<!-- ##### ENUM GTokenType ##### -->
<para>
The possible types of token returned from each g_scanner_get_next_token() call.
</para>
@G_TOKEN_EOF:
@ -323,13 +402,14 @@ Lexical Scanner
<!-- ##### UNION GTokenValue ##### -->
<para>
A union holding the value of the token.
</para>
<!-- ##### ENUM GErrorType ##### -->
<para>
The possible errors, used in the <structfield>v_error</structfield> field
of #GTokenValue, when the token is a G_TOKEN_ERROR.
</para>
@G_ERR_UNKNOWN:
@ -343,14 +423,16 @@ Lexical Scanner
<!-- ##### MACRO G_CSET_a_2_z ##### -->
<para>
The set of lower-case ASCII alphabet characters.
Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO G_CSET_A_2_Z ##### -->
<para>
The set of upper-case ASCII alphabet characters.
Used for specifying valid identifier characters in #GScannerConfig.
</para>
@ -364,44 +446,51 @@ Lexical Scanner
<!-- ##### MACRO G_CSET_LATINC ##### -->
<para>
Part of the set of extended characters in the Latin character sets.
FIXME: lower case?
Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO G_CSET_LATINS ##### -->
<para>
Part of the set of extended characters in the Latin character sets.
FIXME: upper case?
Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO g_scanner_add_symbol ##### -->
<para>
Adds a symbol to the default scope.
Deprecated in favour of g_scanner_scope_add_symbol().
</para>
@scanner:
@symbol:
@value:
@scanner: a #GScanner.
@symbol: the symbol to add.
@value: the value of the symbol.
<!-- ##### MACRO g_scanner_remove_symbol ##### -->
<para>
Removes a symbol from the default scope.
Deprecated in favour of g_scanner_scope_remove_symbol().
</para>
@scanner:
@symbol:
@scanner: a #GScanner.
@symbol: the symbol to remove.
<!-- ##### MACRO g_scanner_foreach_symbol ##### -->
<para>
Calls a function for each symbol in the default scope.
Deprecated in favour of g_scanner_scope_foreach_symbol().
</para>
@scanner:
@func:
@data:
@scanner: a #GScanner.
@func: the function to call with each symbol.
@data: data to pass to the function.

83
docs/reference/glib/tmpl/string_chunks.sgml
View File

@ -2,11 +2,37 @@
String Chunks
<!-- ##### SECTION Short_Description ##### -->
efficient storage of groups of strings.
<!-- ##### SECTION Long_Description ##### -->
<para>
String chunks are used to store groups of strings.
Memory is allocated in blocks, and as strings are added to the #GStringChunk
they are copied into the next free position in a block. When a block is
full a new block is allocated.
</para>
<para>
When storing a large number of strings, string chunks are more efficient
than using g_strdup() since fewer calls to <function>malloc()</function>
are needed, and less memory is wasted in memory allocation overheads.
</para>
<para>
By adding strings with g_string_chunk_insert_const() it is also possible
to remove duplicates.
</para>
<para>
To create a new #GStringChunk use g_string_chunk_new().
</para>
<para>
To add strings to a #GStringChunk use g_string_chunk_insert().
</para>
<para>
To add strings to a #GStringChunk, but without duplicating strings which are
already in the #GStringChunk, use g_string_chunk_insert_const().
</para>
<para>
To free the entire #GStringChunk use g_string_chunk_free().
It is not possible to free individual strings.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,44 +42,69 @@ String Chunks
<!-- ##### STRUCT GStringChunk ##### -->
<para>
An opaque data structure representing String Chunks.
It should only be accessed by using the following functions.
</para>
<!-- ##### FUNCTION g_string_chunk_new ##### -->
<para>
Creates a new #GStringChunk.
</para>
@size:
@Returns:
@size: the default size of the blocks of memory which are allocated to store
the strings. If a particular string is larger than this default size, a larger
block of memory will be allocated for it.
@Returns: a new #GStringChunk.
<!-- ##### FUNCTION g_string_chunk_insert ##### -->
<para>
Adds a copy of @string to the #GStringChunk.
It returns a pointer to the new copy of the string in the #GStringChunk.
The characters in the string can be changed, if necessary, though you
should not change anything after the end of the string.
</para>
<para>
Unlike g_string_chunk_insert_const(), this function does not check for
duplicates. Also strings added with g_string_chunk_insert() will not be
searched by g_string_chunk_insert_const() when looking for duplicates.
</para>
@chunk:
@string:
@Returns:
@chunk: a #GStringChunk.
@string: the string to add.
@Returns: a pointer to the copy of @string within the #GStringChunk.
<!-- ##### FUNCTION g_string_chunk_insert_const ##### -->
<para>
Adds a copy of @string to the #GStringChunk, unless the same string has
already been added to the #GStringChunk with g_string_chunk_insert_const().
</para>
<para>
This function is useful if you need to copy a large number of strings
but do not want to waste space storing duplicates. But you must remember
that there may be several pointers to the same string, and so any changes
made to the strings should be done very carefully.
</para>
<para>
Note that g_string_chunk_insert_const() will not return a pointer to a string
added with g_string_chunk_insert(), even if they do match.
</para>
@chunk:
@string:
@Returns:
@chunk: a #GStringChunk.
@string: the string to add.
@Returns: a pointer to the new or existing copy of @string within the
#GStringChunk.
<!-- ##### FUNCTION g_string_chunk_free ##### -->
<para>
Frees all memory allocated by the #GStringChunk.
After calling g_string_chunk_free() it is not safe to
access any of the strings which were contained within it.
</para>
@chunk:
@chunk: a #GStringChunk.

274
docs/reference/glib/tmpl/string_utils.sgml
View File

@ -2,11 +2,12 @@
String Utility Functions
<!-- ##### SECTION Short_Description ##### -->
various string-related functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,31 +17,37 @@ String Utility Functions
<!-- ##### FUNCTION g_strdup ##### -->
<para>
Duplicates a string.
The returned string should be freed when no longer needed.
</para>
@str:
@Returns:
@str: the string to duplicate.
@Returns: a newly-allocated copy of @str.
<!-- ##### FUNCTION g_strndup ##### -->
<para>
Duplicates the first @n characters of a string, returning a newly-allocated
buffer @n + 1 characters long which will always be null-terminated.
If @str is less than @n characters long the buffer is padded with nulls.
The returned value should be freed when no longer needed.
</para>
@str:
@n:
@Returns:
@str: the string to duplicate part of.
@n: the maximum number of characters to copy from @str.
@Returns: a newly-allocated buffer containing the first @n characters of @str,
null-terminated.
<!-- ##### FUNCTION g_strnfill ##### -->
<para>
Creates a new string @length characters long filled with @fill_char.
The returned string should be freed when no longer needed.
</para>
@length:
@fill_char:
@Returns:
@length: the length of the new string.
@fill_char: the character to fill the string with.
@Returns: a newly-allocated string filled the @fill_char.
<!-- ##### FUNCTION g_strlcpy ##### -->
@ -67,168 +74,223 @@ String Utility Functions
<!-- ##### FUNCTION g_strdup_printf ##### -->
<para>
Similar to the standard C <function>sprintf()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>
@format:
@Varargs:
@Returns:
@format: the standard <function>sprintf()</function> format string.
@Varargs: the parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.
<!-- ##### FUNCTION g_strdup_vprintf ##### -->
<para>
Similar to the standard C <function>vsprintf()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>
@format:
@args:
@Returns:
@format: the standard <function>sprintf()</function> format string.
@args: the list of parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.
<!-- ##### FUNCTION g_snprintf ##### -->
<para>
A safer form of the standard <function>sprintf()</function> function.
The output is guaranteed to not exceed @n characters (including the
terminating NULL character), so it is easy to ensure that a buffer overflow
cannot occur.
</para>
<para>
See also g_strdup_printf().
</para>
<note>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the output
was truncated, and the truncated string may not be NULL-terminated.
</para>
</note>
@string:
@n:
@format:
@Varargs:
@Returns:
@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating null
character).
@format: the format string. See the <function>sprintf()</function>
documentation.
@Varargs: the arguments to insert in the output.
@Returns: the length of the output string.
<!-- ##### FUNCTION g_vsnprintf ##### -->
<para>
A safer form of the standard <function>vsprintf()</function> function.
The output is guaranteed to not exceed @n characters (including the
terminating NULL character), so it is easy to ensure that a buffer overflow
cannot occur.
</para>
<para>
See also g_strdup_vprintf().
</para>
<note>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the output
was truncated, and the truncated string may not be NULL-terminated.
</para>
</note>
@string:
@n:
@format:
@args:
@Returns:
@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating null
character).
@format: the format string. See the <function>sprintf()</function>
documentation.
@args: the list of arguments to insert in the output.
@Returns: the length of the output string.
<!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
<para>
Calculates the maximum space needed to store the output of the
<function>sprintf()</function> function.
</para>
@format:
@args:
@Returns:
@format: the format string. See the <function>printf()</function>
documentation.
@args: the parameters to be inserted into the format string.
@Returns: the maximum space needed to store the formatted string.
<!-- ##### FUNCTION g_strup ##### -->
<para>
Converts a string to upper case.
</para>
@string:
@string: the string to convert.
@Returns:
<!-- ##### FUNCTION g_strdown ##### -->
<para>
Converts a string to lower case.
</para>
@string:
@string: the string to convert.
@Returns:
<!-- ##### FUNCTION g_strcasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strcasecmp()</function> function on platforms which support it.
</para>
@s1:
@s2:
@Returns:
@s1: a string.
@s2: a string to compare with @s1.
@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
value if @s1 > @s2.
<!-- ##### FUNCTION g_strncasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strncasecmp()</function> function on platforms which support it.
It is similar to g_strcasecmp() except it only compares the first @n characters
of the strings.
</para>
@s1:
@s2:
@n:
@Returns:
@s1: a string.
@s2: a string to compare with @s1.
@n: the maximum number of characters to compare.
@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
value if @s1 > @s2.
<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the characters in a string.
For example, g_strreverse ("abcdef") would be "fedcba".
</para>
@string:
@string: the string to reverse.
@Returns:
<!-- ##### FUNCTION g_strtod ##### -->
<para>
Converts a string to a gdouble value.
It calls the standard <function>strtod()</function> function
to handle the conversion, but if the string is not completely converted
it attempts the conversion again in the "C" locale, and returns the best
match.
</para>
@nptr:
@endptr:
@Returns:
@nptr: the string to convert to a numeric value.
@endptr: if non-NULL, it returns the character after the last character used
in the conversion.
@Returns: the gdouble value.
<!-- ##### FUNCTION g_strchug ##### -->
<para>
Removes leading whitespace from a string, by moving the rest of the
characters forward.
</para>
@string:
@Returns:
@string: a string to remove the leading whitespace from.
@Returns: @string.
<!-- ##### FUNCTION g_strchomp ##### -->
<para>
Removes trailing whitespace from a string.
</para>
@string:
@Returns:
@string: a string to remove the trailing whitespace from.
@Returns: @string.
<!-- ##### MACRO g_strstrip ##### -->
<para>
Removes leading and trailing whitespace from a string.
</para>
@string:
@string: a string to remove the leading and trailing whitespace from.
<!-- ##### FUNCTION g_strdelimit ##### -->
<para>
Converts any delimiter characters in @string to @new_delimiter.
Any characters in @string which are found in @delimiters are changed
to the @new_delimiter character.
</para>
@string:
@delimiters:
@new_delimiter:
@string: the string to convert.
@delimiters: a string containing the current delimiters, or NULL to use the
standard delimiters defined in #G_STR_DELIMITERS.
@new_delimiter: the new delimiter character.
@Returns:
<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
The standard delimiters, used in #g_strdelimit.
</para>
<!-- ##### FUNCTION g_strescape ##### -->
<para>
Escapes all backslash characters, '\' in a string, by inserting a second '\'.
</para>
@source:
@exceptions:
@Returns:
@Returns: a newly allocated copy of @string, with all backslash characters
escaped using a second backslash.
<!-- # Unused Parameters # -->
@string: a string to escape the backslashes in.
<!-- ##### FUNCTION g_strcompress ##### -->
@ -253,68 +315,88 @@ String Utility Functions
<!-- ##### FUNCTION g_strsplit ##### -->
<para>
Splits a string into a maximum of @max_tokens pieces, using the given
@delimiter. If @max_tokens is reached, the final string in the returned
string array contains the remainder of @string.
</para>
@string:
@delimiter:
@max_tokens:
@Returns:
@string: a string to split.
@delimiter: a string which specifies the places at which to split the string.
The delimiter is not included in any of the resulting strings, unless
max_tokens is reached.
@max_tokens: the maximum number of strings to split @string into. If this is
less than 1, the string is split completely.
@Returns: a newly-allocated array of strings. Use g_strfreev() to free it.
<!-- ##### FUNCTION g_strfreev ##### -->
<para>
Frees a NULL-terminated array of strings, and the array itself.
</para>
@str_array:
@str_array: a NULL-terminated array of strings to free.
<!-- ##### FUNCTION g_strconcat ##### -->
<para>
Concatenates all of the given strings into one long string.
The returned string should be freed when no longer needed.
</para>
@string1:
@Varargs:
@Returns:
@string1: The first string to add, which must not be NULL.
@Varargs: a NULL-terminated list of strings to append to the string.
@Returns: a newly-allocated string containing all the string arguments.
<!-- ##### FUNCTION g_strjoin ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>
@separator:
@Varargs:
@Returns:
@separator: a string to insert between each of the strings, or NULL.
@Varargs: a NULL-terminated list of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.
<!-- ##### FUNCTION g_strjoinv ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>
@separator:
@str_array:
@Returns:
@separator: a string to insert between each of the strings, or NULL.
@str_array: a NULL-terminated array of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.
<!-- ##### FUNCTION g_strerror ##### -->
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
This function is included since not all platforms support the
<function>strerror()</function> function.
</para>
@errnum:
@Returns:
@errnum: the system error number. See the standard C %errno
documentation.
@Returns: a string describing the error code.
If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
The string can only be used until the next call to g_strerror.
<!-- ##### FUNCTION g_strsignal ##### -->
<para>
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
<function>strsignal()</function> function.
</para>
@signum:
@Returns:
@signum: the signal number. See the <literal>signal</literal>
documentation.
@Returns: a string describing the signal.
If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
The string can only be used until the next call to g_strsignal.

157
docs/reference/glib/tmpl/strings.sgml
View File

@ -2,11 +2,16 @@
Strings
<!-- ##### SECTION Short_Description ##### -->
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.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +21,16 @@ Strings
<!-- ##### STRUCT GString ##### -->
<para>
The #GString struct contains the public fields of a #GString.
The <structfield>str</structfield> field points to the character data.
It may move as text is added.
The <structfield>len</structfield> field contains the length of the string,
not including the terminating null character.
</para>
<para>
The str field is zero-terminated and so can be used as an ordinary C
string. But it may be moved when text is appended or inserted into the
string.
</para>
@str:
@ -24,70 +38,83 @@ Strings
<!-- ##### FUNCTION g_string_new ##### -->
<para>
Creates a new #GString, initialized with the given string.
</para>
@init:
@Returns:
@init: the initial text to copy into the string.
@Returns: the new #GString.
<!-- ##### FUNCTION g_string_sized_new ##### -->
<para>
Creates a new GString, with enough space for @dfl_size characters.
This is useful if you are going to add a lot of text to the string and
don't want it to be reallocated too often.
</para>
@dfl_size:
@Returns:
@dfl_size: the default size of the space allocated to hold the string.
@Returns: the new #GString.
<!-- ##### FUNCTION g_string_assign ##### -->
<para>
Copies the characters from one #GString into another, destroying any previous
contents. It is rather like the standard strcpy() function, except that
you do not have to worry about having enough space to copy the string.
</para>
@string:
@rval:
@Returns:
@rval: the source #GString.
@Returns: the destination #GString.
<!-- # Unused Parameters # -->
@lval: the destination #GString. Its current contents are destroyed.
<!-- ##### FUNCTION g_string_sprintf ##### -->
<para>
Writes a formatted string into a #GString.
This is similar to the standard <function>sprintf()</function> function,
except that the GString buffer automatically expands to contain the results.
The previous contents of the GString are destroyed.
</para>
@string:
@format:
@Varargs:
@string: a #GString.
@format: the string format. See the <function>sprintf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_sprintfa ##### -->
<para>
Appends a formatted string onto the end of a #GString.
This function is is similar to g_string_sprintf() except that
the text is appended to the GString.
</para>
@string:
@format:
@Varargs:
@string: a #GString.
@format: the string format. See the <function>sprintf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_append ##### -->
<para>
Adds a string onto the end of a #GString, expanding it if necessary.
</para>
@string:
@val:
@Returns:
@string: a #GString.
@val: the string to append onto the end of the #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_append_c ##### -->
<para>
Adds a character onto the end of a #GString, expanding it if necessary.
</para>
@string:
@c:
@Returns:
@string: a #GString.
@c: the character to append onto the end of the #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_append_len ##### -->
@ -103,22 +130,22 @@ Strings
<!-- ##### FUNCTION g_string_prepend ##### -->
<para>
Adds a string on to the start of a #GString, expanding it if necessary.
</para>
@string:
@val:
@Returns:
@string: a #GString.
@val: the string to prepend on the start of the #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_prepend_c ##### -->
<para>
Adds a character onto the start of a #GString, expanding it if necessary.
</para>
@string:
@c:
@Returns:
@string: a #GString.
@c: the character to prepend on the start of the #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_prepend_len ##### -->
@ -134,24 +161,24 @@ Strings
<!-- ##### FUNCTION g_string_insert ##### -->
<para>
Inserts a copy of a string into a #GString, expanding it if necessary.
</para>
@string:
@pos:
@val:
@Returns:
@string: a #GString.
@pos: the position to insert the copy of the string.
@val: the string to insert.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_insert_c ##### -->
<para>
Inserts a character into a #GString, expanding it if necessary.
</para>
@string:
@pos:
@c:
@Returns:
@string: a #GString.
@pos: the position to insert the character.
@c: the character to insert.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_insert_len ##### -->
@ -168,51 +195,53 @@ Strings
<!-- ##### FUNCTION g_string_erase ##### -->
<para>
Removes @len characters from a #GString, starting at position @pos.
The rest of the #GString is shifted down to fill the gap.
</para>
@string:
@pos:
@len:
@Returns:
@string: a #GString.
@pos: the position of the characters to remove.
@len: the number of characters to remove.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_truncate ##### -->
<para>
Cuts off the end of the GString, leaving the first @len characters.
</para>
@string:
@len:
@Returns:
@string: a #GString.
@len: the new size of the #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_free ##### -->
<para>
Frees the memory allocated for the #GString.
If free_segment is TRUE it also frees the character data.
</para>
@string:
@free_segment:
@string: a #GString.
@free_segment: if TRUE the actual character data is freed as well.
@Returns:
<!-- ##### FUNCTION g_string_up ##### -->
<para>
Converts a #GString to upper case.
</para>
@string:
@Returns:
@string: a #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_down ##### -->
<para>
Converts a #GString to lower case.
</para>
@string:
@Returns:
@string: a #GString.
@Returns: the #GString.
<!-- ##### FUNCTION g_string_hash ##### -->

740
docs/reference/glib/tmpl/threads.sgml
View File

File diff suppressed because it is too large Load Diff

36
docs/reference/glib/tmpl/timers.sgml
View File

@ -2,11 +2,14 @@
Timers
<!-- ##### SECTION Short_Description ##### -->
functions to time operations.
<!-- ##### SECTION Long_Description ##### -->
<para>
Timers can be used to time operations, in a similar way to a stopwatch.
Call g_timer_new () to create the timer, g_timer_start () to start it,
g_timer_elapsed () to determine the time which has elapsed since the timer
was started, and g_timer_stop () to stop the timer.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,32 +19,32 @@ Timers
<!-- ##### STRUCT GTimer ##### -->
<para>
An opaque data structure which holds the timer information.
</para>
<!-- ##### FUNCTION g_timer_new ##### -->
<para>
Creates a new timer.
</para>
@Returns:
@Returns: the new timer.
<!-- ##### FUNCTION g_timer_start ##### -->
<para>
Starts the timer.
</para>
@timer:
@timer: the timer.
<!-- ##### FUNCTION g_timer_stop ##### -->
<para>
Stops the timer.
</para>
@timer:
@timer: the timer.
<!-- ##### FUNCTION g_timer_elapsed ##### -->
@ -49,24 +52,25 @@ Timers
</para>
@timer:
@microseconds:
@Returns:
@timer: the timer.
@microseconds: if non-NULL, this will be set to the microseconds component
of the elapsed time (it does not include the number of seconds elapsed).
@Returns: the elapsed time in seconds, as a double.
<!-- ##### FUNCTION g_timer_reset ##### -->
<para>
Resets the elapsed time to 0, leaving the timer running.
</para>
@timer:
@timer: the timer.
<!-- ##### FUNCTION g_timer_destroy ##### -->
<para>
Destroys the timer, freeing the memory allocated for it.
</para>
@timer:
@timer: the timer.

169
docs/reference/glib/tmpl/trees-binary.sgml
View File

@ -2,11 +2,36 @@
Balanced Binary Trees
<!-- ##### SECTION Short_Description ##### -->
a sorted collection of key/value pairs optimised for searching
and traversing in order.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GTree structure and its associated functions provide a sorted collection
of key/value pairs optimised for searching and traversing in order.
</para>
<para>
To create a new #GTree use g_tree_new().
</para>
<para>
To insert a key/value pair into a #GTree use g_tree_insert().
</para>
<para>
To lookup the value corresponding to a given key, use g_tree_lookup().
</para>
<para>
To find out the number of nodes in a #GTree, use g_tree_nnodes().
To get the height of a #GTree, use g_tree_height().
</para>
<para>
To traverse a #GTree, calling a function for each node visited in the
traversal, use g_tree_traverse().
</para>
<para>
To remove a key/value pair use g_tree_remove().
</para>
<para>
To destroy a #GTree, use g_tree_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,93 +41,152 @@ Balanced Binary Trees
<!-- ##### STRUCT GTree ##### -->
<para>
The #GTree struct is an opaque data structure representing a
<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
It should be accessed only by using the following functions.
</para>
<!-- ##### FUNCTION g_tree_new ##### -->
<para>
Creates a new GTree.
</para>
@key_compare_func:
@Returns:
@key_compare_func: the function used to order the nodes in the #GTree.
It should return values similar to the standard <function>strcmp()</function>
function -
0 if the two arguments are equal, a negative value if the first argument comes
before the second, or a positive value if the first argument comes after the
second.
@Returns: a new #GTree.
<!-- ##### FUNCTION g_tree_insert ##### -->
<para>
Inserts a key/value pair into a #GTree.
If the given key already exists in the #GTree it is set to the new value.
(If you are using dynamically allocated keys and values you should be careful
to ensure that the old values are freed.)
</para>
<para>
The tree is automatically 'balanced' as new key/value pairs are added,
so that the distance from the root to every leaf is as small as possible.
</para>
@tree:
@key:
@value:
@tree: a #GTree.
@key: the key to insert.
@value: the value corresponding to the key.
<!-- ##### FUNCTION g_tree_nnodes ##### -->
<para>
Gets the number of nodes in a #GTree.
</para>
@tree:
@Returns:
@tree: a #GTree.
@Returns: the number of nodes in the #GTree.
<!-- ##### FUNCTION g_tree_height ##### -->
<para>
Gets the height of a #GTree.
</para>
<para>
If the #GTree contains no nodes, the height is 0.
If the #GTree contains only one root node the height is 1.
If the root node has children the height is 2, etc.
</para>
@tree:
@Returns:
@tree: a #GTree.
@Returns: the height of the #GTree.
<!-- ##### FUNCTION g_tree_lookup ##### -->
<para>
Gets the value corresponding to the given key.
Since a #GTree is automatically balanced as key/value pairs are
added, key lookup is very fast.
</para>
@tree:
@key:
@Returns:
@tree: a #GTree.
@key: the key to look up.
@Returns: the value corresponding to the key.
<!-- ##### FUNCTION g_tree_search ##### -->
<para>
Searches a #GTree using an alternative form of the comparison function.
</para>
<para>
This function is not as useful as it sounds.
It allows you to use a different function for performing the lookup of
a key. However, since the tree is ordered according to the @key_compare_func
function passed to g_tree_new(), the function you pass to g_tree_search() must
return exactly the same value as would be returned by the comparison function,
for each pair of tree nodes, or the search will not work.
</para>
<para>
To search for a specific value, you can use g_tree_traverse().
</para>
@tree:
@search_func:
@data:
@Returns:
@tree: a #GTree.
@search_func: the comparison function used to search the #GTree.
@data: the data passed as the second argument to the @search_func function.
@Returns: the value corresponding to the found key, or NULL if the key is
not found.
<!-- ##### FUNCTION g_tree_traverse ##### -->
<para>
Calls the given function for each node in the GTree.
</para>
@tree:
@traverse_func:
@traverse_type:
@data:
@tree: a #GTree.
@traverse_func: the function to call for each node visited. If this function
returns TRUE, the traversal is stopped.
@traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
%G_PRE_ORDER and %G_POST_ORDER.
@data: user data to pass to the traverse function.
<!-- ##### USER_FUNCTION GTraverseFunc ##### -->
<para>
Specifies the type of function passed to g_tree_traverse().
It is passed the key and value of each node, together with
the @user_data parameter passed to g_tree_traverse().
If the function returns TRUE, the traversal is stopped.
</para>
@key:
@value:
@data:
@Returns:
@key: a key of a #GTree node.
@value: the value corresponding to the key.
@data: user data passed to g_tree_traverse().
@Returns: TRUE to stop the traversal.
<!-- ##### ENUM GTraverseType ##### -->
<para>
Specifies the type of traveral performed by g_tree_traverse(),
g_node_traverse() and g_node_find().
<itemizedlist>
<listitem><para>
%G_PRE_ORDER visits a node, then its children.
</para></listitem>
<listitem><para>
%G_IN_ORDER vists a node's left child first, then the node itself, then its
right child. This is the one to use if you want the output sorted according
to the compare function.
</para></listitem>
<listitem><para>
%G_POST_ORDER visits the node's children, then the node itself.
</para></listitem>
<listitem><para>
%G_LEVEL_ORDER is not implemented for
<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
For <link linkend="glib-N-ary-Trees">N-ary Trees</link>
it calls the function for each child of the node, then it recursively visits
each child.
</para></listitem>
</itemizedlist>
</para>
@G_IN_ORDER:
@ -112,18 +196,21 @@ Balanced Binary Trees
<!-- ##### FUNCTION g_tree_remove ##### -->
<para>
Removes a key/value pair from a #GTree.
If the key or value is dynamically allocated you must remember to free them
yourself.
</para>
@tree:
@key:
@tree: a #GTree.
@key: the key to remove.
<!-- ##### FUNCTION g_tree_destroy ##### -->
<para>
Destroys the #GTree, freeing all of the memory allocated.
But it doesn't free keys or values.
</para>
@tree:
@tree: a #GTree.

367
docs/reference/glib/tmpl/trees-nary.sgml
View File

@ -2,11 +2,46 @@
N-ary Trees
<!-- ##### SECTION Short_Description ##### -->
trees of data with any number of branches.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GNode struct and its associated functions provide a N-ary tree data
structure, where nodes in the tree can contain arbitrary data.
</para>
<para>
To create a new tree use g_node_new().
</para>
<para>
To insert a node into a tree use g_node_insert(), g_node_insert_before(),
g_node_append() and g_node_prepend().
</para>
<para>
To create a new node and insert it into a tree use g_node_insert_data(),
g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data().
</para>
<para>
To reverse the children of a node use g_node_reverse_children().
</para>
<para>
To find a node use g_node_get_root(), g_node_find(), g_node_find_child(),
g_node_child_index(), g_node_child_position(),
g_node_first_child(), g_node_last_child(),
g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(),
g_node_next_sibling() or g_node_last_sibling().
</para>
<para>
To get information about a node or tree use G_NODE_IS_LEAF(),
G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(),
g_node_is_ancestor() or g_node_max_height().
</para>
<para>
To traverse a tree, calling a function for each node visited in the
traversal, use g_node_traverse() or g_node_children_foreach().
</para>
<para>
To remove a node or subtree from a tree use g_node_unlink() or
g_node_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +51,17 @@ N-ary Trees
<!-- ##### STRUCT GNode ##### -->
<para>
The #GNode struct represents one node in a
<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
The <structfield>data</structfield> field contains the actual data of the node.
The <structfield>next</structfield> and <structfield>prev</structfield>
fields point to the node's siblings (a sibling is another #GNode with the
same parent).
The <structfield>parent</structfield> field points to the parent of the #GNode,
or is NULL if the #GNode is the root of the tree.
The <structfield>children</structfield> field points to the first child of the
#GNode. The other children are accessed by using the
<structfield>next</structfield> pointer of each child.
</para>
@data:
@ -27,11 +72,12 @@ N-ary Trees
<!-- ##### FUNCTION g_node_new ##### -->
<para>
Creates a new #GNode containing the given data.
Used to create the first node in a tree.
</para>
@data:
@Returns:
@data: the data of the new node.
@Returns: a new #GNode.
<!-- ##### FUNCTION g_node_copy ##### -->
@ -45,107 +91,135 @@ N-ary Trees
<!-- ##### FUNCTION g_node_insert ##### -->
<para>
Inserts a #GNode beneath the parent at the given position.
</para>
@parent:
@position:
@node:
@Returns:
@parent: the #GNode to place @node under.
@position: the position to place @node at, with respect to its siblings.
If position is -1, @node is inserted as the last child of @parent.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
<!-- ##### FUNCTION g_node_insert_before ##### -->
<para>
Inserts a #GNode beneath the parent before the given sibling.
</para>
@parent:
@sibling:
@node:
@Returns:
@parent: the #GNode to place @node under.
@sibling: the sibling #GNode to place @node before. If sibling is NULL,
the node is inserted as the last child of @parent.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
<!-- ##### MACRO g_node_append ##### -->
<para>
Inserts a #GNode as the last child of the given parent.
</para>
@parent:
@node:
@parent: the #GNode to place the new #GNode under.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
<!-- ##### FUNCTION g_node_prepend ##### -->
<para>
Inserts a #GNode as the first child of the given parent.
</para>
@parent:
@node:
@Returns:
@parent: the #GNode to place the new #GNode under.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
<!-- ##### MACRO g_node_insert_data ##### -->
<para>
Inserts a new #GNode at the given position.
</para>
@parent:
@position:
@data:
@parent: the #GNode to place the new #GNode under.
@position: the position to place the new #GNode at.
If position is -1, the new #GNode is inserted as the last child of @parent.
@data: the data for the new #GNode.
@Returns: the new #GNode.
<!-- ##### MACRO g_node_insert_data_before ##### -->
<para>
Inserts a new #GNode before the given sibling.
</para>
@parent:
@sibling:
@data:
@parent: the #GNode to place the new #GNode under.
@sibling: the sibling #GNode to place the new #GNode before.
@data: the data for the new #GNode.
@Returns: the new #GNode.
<!-- ##### MACRO g_node_append_data ##### -->
<para>
Inserts a new #GNode as the last child of the given parent.
</para>
@parent:
@data:
@parent: the #GNode to place the new #GNode under.
@data: the data for the new #GNode.
@Returns: the new #GNode.
<!-- ##### MACRO g_node_prepend_data ##### -->
<para>
Inserts a new #GNode as the first child of the given parent.
</para>
@parent:
@data:
@parent: the #GNode to place the new #GNode under.
@data: the data for the new #GNode.
@Returns: the new #GNode.
<!-- ##### FUNCTION g_node_reverse_children ##### -->
<para>
Reverses the order of the children of a #GNode.
(It doesn't change the order of the grandchildren.)
</para>
@node:
@node: a #GNode.
<!-- ##### FUNCTION g_node_traverse ##### -->
<para>
Traverses a tree starting at the given root #GNode.
It calls the given function for each node visited.
The traversal can be halted at any point by returning TRUE from @func.
</para>
@root:
@order:
@flags:
@max_depth:
@func:
@data:
@root: the root #GNode of the tree to traverse.
@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER,
%G_POST_ORDER, or %G_LEVEL_ORDER.
@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@max_depth: the maximum depth of the traversal. Nodes below this
depth will not be visited. If max_depth is -1 all nodes in the tree are
visited. If depth is 1, only the root is visited. If depth is 2, the root
and its children are visited. And so on.
@func: the function to call for each visited #GNode.
@data: user data to pass to the function.
<!-- ##### ENUM GTraverseFlags ##### -->
<para>
Specifies which nodes are visited during several of the tree functions,
including g_node_traverse() and g_node_find().
<itemizedlist>
<listitem><para>
%G_TRAVERSE_LEAFS specifies that only leaf nodes should be visited.
</para></listitem>
<listitem><para>
%G_TRAVERSE_NON_LEAFS specifies that only non-leaf nodes should be visited.
</para></listitem>
<listitem><para>
%G_TRAVERSE_ALL specifies that all nodes should be visited.
</para></listitem>
</itemizedlist>
</para>
@G_TRAVERSE_LEAFS:
@ -155,237 +229,274 @@ N-ary Trees
<!-- ##### USER_FUNCTION GNodeTraverseFunc ##### -->
<para>
Specifies the type of function passed to g_node_traverse().
The function is called with each of the nodes visited, together with the
user data passed to g_node_traverse().
If the function returns TRUE, then the traversal is stopped.
</para>
@node:
@data:
@Returns:
@node: a #GNode.
@data: user data passed to g_node_traverse().
@Returns: TRUE to stop the traversal.
<!-- ##### FUNCTION g_node_children_foreach ##### -->
<para>
Calls a function for each of the children of a #GNode.
Note that it doesn't descend beneath the child nodes.
</para>
@node:
@flags:
@func:
@data:
@node: a #GNode.
@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@func: the function to call for each visited node.
@data: user data to pass to the function.
<!-- ##### USER_FUNCTION GNodeForeachFunc ##### -->
<para>
Specifies the type of function passed to g_node_children_foreach().
The function is called with each child node, together with the user data
passed to g_node_children_foreach().
</para>
@node:
@data:
@node: a #GNode.
@data: user data passed to g_node_children_foreach().
<!-- ##### FUNCTION g_node_get_root ##### -->
<para>
Gets the root of a tree.
</para>
@node:
@Returns:
@node: a #GNode.
@Returns: the root of the tree.
<!-- ##### FUNCTION g_node_find ##### -->
<para>
Finds a #GNode in a tree.
</para>
@root:
@order:
@flags:
@data:
@Returns:
@root: the root #GNode of the tree to search.
@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER,
%G_POST_ORDER, or %G_LEVEL_ORDER.
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@data: the data to find.
@Returns: the found #GNode, or NULL if the data is not found.
<!-- ##### FUNCTION g_node_find_child ##### -->
<para>
Finds the first child of a #GNode with the given data.
</para>
@node:
@flags:
@data:
@Returns:
@node: a #GNode.
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@data: the data to find.
@Returns: the found child #GNode, or NULL if the data is not found.
<!-- ##### FUNCTION g_node_child_index ##### -->
<para>
Gets the position of the first child of a #GNode which contains the given data.
</para>
@node:
@data:
@Returns:
@node: a #GNode.
@data: the data to find.
@Returns: the index of the child of @node which contains @data, or -1
if the data is not found.
<!-- ##### FUNCTION g_node_child_position ##### -->
<para>
Gets the position of a #GNode with respect to its siblings.
@child must be a child of @node.
The first child is numbered 0, the second 1, and so on.
</para>
@node:
@child:
@Returns:
@node: a #GNode.
@child: a child of @node.
@Returns: the position of @child with respect to its siblings.
<!-- ##### MACRO g_node_first_child ##### -->
<para>
Gets the first child of a #GNode.
</para>
@node:
@node: a #GNode.
@Returns: the last child of @node, or NULL if @node is NULL or has no children.
<!-- ##### FUNCTION g_node_last_child ##### -->
<para>
Gets the last child of a #GNode.
</para>
@node:
@Returns:
@node: a #GNode (must not be NULL).
@Returns: the last child of @node, or NULL if @node has no children.
<!-- ##### FUNCTION g_node_nth_child ##### -->
<para>
Gets a child of a #GNode, using the given index.
The first child is at index 0. If the index is too big, NULL is returned.
</para>
@node:
@n:
@Returns:
@node: a #GNode.
@n: the index of the desired child.
@Returns: the child of @node at index @n.
<!-- ##### FUNCTION g_node_first_sibling ##### -->
<para>
Gets the first sibling of a #GNode.
This could possibly be the node itself.
</para>
@node:
@Returns:
@node: a #GNode.
@Returns: the first sibling of @node.
<!-- ##### MACRO g_node_next_sibling ##### -->
<para>
Gets the next sibling of a #GNode.
</para>
@node:
@node: a #GNode.
@Returns: the next sibling of @node, or NULL if @node is NULL.
<!-- ##### MACRO g_node_prev_sibling ##### -->
<para>
Gets the previous sibling of a #GNode.
</para>
@node:
@node: a #GNode.
@Returns: the previous sibling of @node, or NULL if @node is NULL.
<!-- ##### FUNCTION g_node_last_sibling ##### -->
<para>
Gets the last sibling of a #GNode.
This could possibly be the node itself.
</para>
@node:
@Returns:
@node: a #GNode.
@Returns: the last sibling of @node.
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
<para>
Returns TRUE if a #GNode is a leaf node.
</para>
@node:
@node: a #GNode.
@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children).
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
<para>
Returns TRUE if a #GNode is the root of a tree.
</para>
@node:
@node: a #GNode.
@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent
or siblings).
<!-- ##### FUNCTION g_node_depth ##### -->
<para>
Gets the depth of a #GNode.
</para>
<para>
If @node is NULL the depth is 0.
The root node has a depth of 1.
For the children of the root node the depth is 2. And so on.
</para>
@node:
@Returns:
@node: a #GNode.
@Returns: the depth of the #GNode.
<!-- ##### FUNCTION g_node_n_nodes ##### -->
<para>
Gets the number of nodes in a tree.
</para>
@root:
@flags:
@Returns:
@root: a #GNode.
@flags: which types of children are to be counted, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@Returns: the number of nodes in the tree.
<!-- ##### FUNCTION g_node_n_children ##### -->
<para>
Gets the number of children of a #GNode.
</para>
@node:
@Returns:
@node: a #GNode.
@Returns: the number of children of @node.
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
<para>
Returns TRUE if @node is an ancestor of @descendant.
This is true if node is the parent of descendant, or if node is the
grandparent of descendant etc.
</para>
@node:
@descendant:
@Returns:
@node: a #GNode.
@descendant: a #GNode.
@Returns: TRUE if @node is an ancestor of @descendant.
<!-- ##### FUNCTION g_node_max_height ##### -->
<para>
Gets the maximum height of all branches beneath a #GNode.
This is the maximum distance from the #GNode to all leaf nodes.
</para>
<para>
If @root is NULL, 0 is returned. If @root has no children, 1 is returned.
If @root has children, 2 is returned. And so on.
</para>
@root:
@Returns:
@root: a #GNode.
@Returns: the maximum height of the tree beneath @root.
<!-- ##### FUNCTION g_node_unlink ##### -->
<para>
Unlinks a #GNode from a tree, resulting in two separate trees.
</para>
@node:
@node: the #GNode to unlink, which becomes the root of a new tree.
<!-- ##### FUNCTION g_node_destroy ##### -->
<para>
Removes the #GNode and its children from the tree, freeing any memory
allocated.
</para>
@root:
@root: the root of the tree/subtree to destroy.
<!-- ##### FUNCTION g_node_push_allocator ##### -->
<para>
Sets the allocator to use to allocate #GNode elements.
Use g_node_pop_allocator() to restore the previous allocator.
</para>
@allocator:
@allocator: the #GAllocator to use when allocating #GNode elements.
<!-- ##### FUNCTION g_node_pop_allocator ##### -->
<para>
Restores the previous #GAllocator, used when allocating #GNode elements.
</para>

50
docs/reference/glib/tmpl/type_conversion.sgml
View File

@ -2,11 +2,37 @@
Type Conversion Macros
<!-- ##### SECTION Short_Description ##### -->
a portable method for storing #gint &amp; #guint values in #gpointer variables.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a portable method of storing #gint and #guint values in
#gpointer variables.
</para>
<para>
Many of the GLib data types are based on storing #gpointer values,
e.g. #GHashTable, #GList, #GSList, #GTree, and #GNode.
By using the type conversion macros described below you can store #gint and
#guint values inside a #gpointer. So you can, for example, create
a hash table of #gint values, or a linked list of #guint values.
</para>
<para>
The type conversion macros are necessary because the size of a #gpointer can
vary across different platforms. So the type conversion has to be done
carefully.
</para>
<para>
Note that the reverse operation, storing #gpointer values in
integer variables, is not supported, since an integer is not guaranteed to
be large enough to store #gpointer values across all platforms.
</para>
<para>
To convert an integer value, a #gint, to a #gpointer, use #GINT_TO_POINTER.
To convert it back to a #gint, use #GPOINTER_TO_INT.
</para>
<para>
To convert an unsigned integer, a #guint, to a #gpointer, use
#GUINT_TO_POINTER. To convert it back to a #guint, use #GPOINTER_TO_UINT.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,33 +42,37 @@ Type Conversion Macros
<!-- ##### MACRO GINT_TO_POINTER ##### -->
<para>
Converts a #gint to a #gpointer.
</para>
@i:
@i: a #gint value.
@Returns: the value converted to a #gpointer.
<!-- ##### MACRO GPOINTER_TO_INT ##### -->
<para>
Converts a #gpointer to a #gint.
</para>
@p:
@p: a #gpointer value.
@Returns: the value converted to a #gint.
<!-- ##### MACRO GUINT_TO_POINTER ##### -->
<para>
Converts a #guint to a #gpointer.
</para>
@u:
@u: a #guint value.
@Returns: the value converted to a #gpointer.
<!-- ##### MACRO GPOINTER_TO_UINT ##### -->
<para>
Converts a #gpointer to a #guint.
</para>
@p:
@p: a #gpointer value.
@Returns: the value converted to a #guint.

101
docs/reference/glib/tmpl/types.sgml
View File

@ -2,10 +2,33 @@
Basic Types
<!-- ##### SECTION Short_Description ##### -->
standard GLib types, defined for ease-of-use and portability.
<!-- ##### SECTION Long_Description ##### -->
<para>
GLib defines a number of commonly used types, which can be divided into
4 groups:
<itemizedlist>
<listitem><para>
New types which are not part of standard C - #gboolean, #gsize, #gssize.
</para></listitem>
<listitem><para>
Integer types which are guaranteed to be the same size across all platforms -
#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64.
</para></listitem>
<listitem><para>
Types which are easier to use than their standard C counterparts -
#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
</para></listitem>
<listitem><para>
Types which correspond exactly to standard C types, but are included
for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
</para></listitem>
</itemizedlist>
</para>
@ -16,154 +39,178 @@ Basic Types
<!-- ##### TYPEDEF gboolean ##### -->
<para>
A standard <type>boolean</type> type.
Variables of this type should only contain the value #TRUE or #FALSE.
</para>
<!-- ##### TYPEDEF gpointer ##### -->
<para>
An untyped pointer.
#gpointer looks better and is easier to use than <type>void*</type>.
</para>
<!-- ##### TYPEDEF gconstpointer ##### -->
<para>
An untyped pointer to constant data.
The data pointed to should not be changed.
</para>
<para>
This is typically used in function prototypes to indicate that the
data pointed to will not be altered by the function.
</para>
<!-- ##### TYPEDEF gchar ##### -->
<para>
Corresponds to the standard C <type>char</type> type.
</para>
<!-- ##### TYPEDEF guchar ##### -->
<para>
Corresponds to the standard C <type>unsigned char</type> type.
</para>
<!-- ##### TYPEDEF gint ##### -->
<para>
Corresponds to the standard C <type>int</type> type.
Values of this type can range from #G_MININT to #G_MAXINT.
</para>
<!-- ##### TYPEDEF guint ##### -->
<para>
Corresponds to the standard C <type>unsigned int</type> type.
</para>
<!-- ##### TYPEDEF gshort ##### -->
<para>
Corresponds to the standard C <type>short</type> type.
Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
</para>
<!-- ##### TYPEDEF gushort ##### -->
<para>
Corresponds to the standard C <type>unsigned short</type> type.
</para>
<!-- ##### TYPEDEF glong ##### -->
<para>
Corresponds to the standard C <type>long</type> type.
Values of this type can range from #G_MINLONG to #G_MAXLONG.
</para>
<!-- ##### TYPEDEF gulong ##### -->
<para>
Corresponds to the standard C <type>unsigned long</type> type.
</para>
<!-- ##### TYPEDEF gint8 ##### -->
<para>
A signed integer guaranteed to be 8 bits on all platforms.
Values of this type can range from -128 to 127.
</para>
<!-- ##### TYPEDEF guint8 ##### -->
<para>
An unsigned integer guaranteed to be 8 bits on all platforms.
Values of this type can range from 0 to 255.
</para>
<!-- ##### TYPEDEF gint16 ##### -->
<para>
A signed integer guaranteed to be 16 bits on all platforms.
Values of this type can range from -32,768 to 32,767.
</para>
<!-- ##### TYPEDEF guint16 ##### -->
<para>
An unsigned integer guaranteed to be 16 bits on all platforms.
Values of this type can range from 0 to 65,535.
</para>
<!-- ##### TYPEDEF gint32 ##### -->
<para>
A signed integer guaranteed to be 32 bits on all platforms.
Values of this type can range from -2,147,483,648 to 2,147,483,647.
</para>
<!-- ##### TYPEDEF guint32 ##### -->
<para>
An unsigned integer guaranteed to be 32 bits on all platforms.
Values of this type can range from 0 to 4,294,967,295.
</para>
<!-- ##### MACRO G_HAVE_GINT64 ##### -->
<para>
This macro is defined if 64-bit signed and unsigned integers are available
on the platform.
</para>
<!-- ##### TYPEDEF gint64 ##### -->
<para>
A signed integer guaranteed to be 64 bits on all platforms on which it is
available (see #G_HAVE_GINT64).
Values of this type can range from -9,223,372,036,854,775,808 to
9,223,372,036,854,775,807.
</para>
<!-- ##### TYPEDEF guint64 ##### -->
<para>
An unsigned integer guaranteed to be 64 bits on all platforms on which it is
available (see #G_HAVE_GINT64).
Values of this type can range from 0 to 18,446,744,073,709,551,615.
</para>
<!-- ##### MACRO G_GINT64_CONSTANT ##### -->
<para>
This macro is used to insert 64-bit integer literals into the source code.
</para>
@val:
@val: a literal integer value, e.g. 0x1d636b02300a7aa7U.
<!-- ##### TYPEDEF gfloat ##### -->
<para>
Corresponds to the standard C <type>float</type> type.
Values of this type can range from #G_MINFLOAT to #G_MAXFLOAT.
</para>
<!-- ##### TYPEDEF gdouble ##### -->
<para>
Corresponds to the standard C <type>double</type> type.
Values of this type can range from #G_MINDOUBLE to #G_MAXDOUBLE.
</para>
<!-- ##### TYPEDEF gsize ##### -->
<para>
An unsigned 32-bit integer intended to represent sizes of data structures.
</para>
<!-- ##### TYPEDEF gssize ##### -->
<para>
A signed 32-bit integer intended to represent sizes of data structures.
</para>

132
docs/reference/glib/tmpl/warnings.sgml
View File

@ -1,12 +1,12 @@
<!-- ##### SECTION Title ##### -->
Warnings and Assertions
Message Output and Debugging Functions
<!-- ##### SECTION Short_Description ##### -->
functions to output messages and help debug applications.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for outputting messages.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,63 +16,94 @@ Warnings and Assertions
<!-- ##### FUNCTION g_print ##### -->
<para>
Outputs a formatted message via the print handler.
The default print handler simply outputs the message to stdout.
</para>
<para>
g_print() should not be used from within libraries for debugging messages,
since it may be redirected by applications to special purpose message
windows or even files.
Instead, libraries should use g_log(), or the convenience functions
g_message(), g_warning() and g_error().
</para>
@format:
@Varargs:
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_print_handler ##### -->
<para>
Sets the print handler.
Any messages passed to g_print() will be output via the new handler.
The default handler simply outputs the message to stdout.
By providing your own handler you can redirect the output, to a GTK
widget or a log file for example.
</para>
@func:
@Returns:
@func: the new print handler.
@Returns: the old print handler.
<!-- ##### USER_FUNCTION GPrintFunc ##### -->
<para>
Specifies the type of the print handler functions.
These are called with the complete formatted string to output.
</para>
@string:
@string: the message to be output.
<!-- ##### FUNCTION g_printerr ##### -->
<para>
Outputs a formatted message via the error message handler.
The default handler simply outputs the message to stderr.
</para>
<para>
g_printerr() should not be used from within libraries. Instead g_log() should
be used, or the convenience functions g_message(), g_warning() and g_error().
</para>
@format:
@Varargs:
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_printerr_handler ##### -->
<para>
Sets the handler for printing error messages.
Any messages passed to g_printerr() will be output via the new handler.
The default handler simply outputs the message to stderr.
By providing your own handler you can redirect the output, to a GTK
widget or a log file for example.
</para>
@func:
@Returns:
@func: the new error message handler.
@Returns: the old error message handler.
<!-- ##### MACRO g_return_if_fail ##### -->
<para>
Returns from the current function if the expression is not true.
If the expression evaluates to FALSE, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</para>
@expr:
@expr: the expression to check.
<!-- ##### MACRO g_return_val_if_fail ##### -->
<para>
Returns from the current function, returning the value @val, if the expression
is not true.
If the expression evaluates to FALSE, a critical message is logged and
@val is returned.
</para>
@expr:
@val:
@expr: the expression to check.
@val: the value to return from the current function if the expression is not
true.
<!-- ##### MACRO g_return_if_reached ##### -->
@ -92,38 +123,79 @@ Warnings and Assertions
<!-- ##### MACRO g_assert ##### -->
<para>
Debugging macro to terminate the application if the assertion fails.
If the assertion fails (i.e. the expression is not true), an error message
is logged and the application is terminated.
</para>
<para>
The macro can be turned off in final releases of code by defining
G_DISABLE_ASSERT when compiling the application.
</para>
@expr:
@expr: the expression to check.
<!-- ##### MACRO g_assert_not_reached ##### -->
<para>
Debugging macro to terminate the application if it is ever reached.
If it is reached, an error message is logged and the application is terminated.
</para>
<para>
The macro can be turned off in final releases of code by defining
G_DISABLE_ASSERT when compiling the application.
</para>
<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed".
This function is intended to be used for debugging use only.
FIXME: How do you set it up?
</para>
<para>
If Exit is selected, the application terminates with a call to
<function>_exit(0)</function>.
</para>
<para>
If Halt is selected, the application enters an infinite loop.
The infinite loop can only be stopped by killing the application,
or by setting glib_on_error_halt to FALSE (possibly via a debugger).
</para>
<para>
If Stack trace is selected, g_on_error_stack_trace() is called. This
invokes gdb, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</para>
<para>
If Proceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
@prg_name:
@prg_name: the program name, needed by gdb for the [S]tack trace option.
If @prg_name is NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
Invokes gdb, which attaches to the current process and shows a stack trace.
Called by g_on_error_query() when the [S]tack trace option is selected.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
@prg_name:
@prg_name: the program name, needed by gdb for the [S]tack trace option.
If @prg_name is NULL, g_get_prgname() is called to get the program name
(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### MACRO G_BREAKPOINT ##### -->
<para>
Inserts a breakpoint instruction into the code (on x86 machines only).
</para>

16
docs/reference/glib/tmpl/windows.sgml
View File

@ -2,11 +2,23 @@
Windows Compatability Functions
<!-- ##### SECTION Short_Description ##### -->
functions to support portability to the Windows environment.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions and macros are provided in the GLib library when compiled
on the Windows platform.
</para>
<para>
Many of the macros simply rename available windows functions
so that they use the same name as the standard Unix functions.
This means that code written for the Unix platform will work without change
under Windows.
</para>
<para>
A few additional constants, types, and functions are also provided,
to provide a common base set of functions across both the Unix and Windows
environments.
</para>
<!-- ##### SECTION See_Also ##### -->

7
docs/reference/gobject/Makefile.am
View File

@ -9,6 +9,9 @@ DOC_MAIN_SGML_FILE=gobject-docs.sgml
# The directory containing the source code (if it contains documentation).
DOC_SOURCE_DIR=$(top_srcdir)/gobject
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=--extra-dir=$(srcdir)/../glib/html
# Headers to ignore
IGNORE_HFILES=
@ -52,7 +55,7 @@ endif
scan:
-(cd $(srcdir) \
&& gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" )
&& gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)")
templates:
cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
@ -65,7 +68,7 @@ html:
test -d $(srcdir)/html || mkdir $(srcdir)/html
-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
@echo '-- Fixing Crossreferences'
gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR)
gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
clean-local:
rm -f *~ *.bak *.signals *-unused.txt