From a5c0df554e7fb0d05c98bd2ddac893f84b35feba Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Thu, 7 Sep 2000 16:36:56 +0000 Subject: [PATCH] Some further makefile improvement. Thu Sep 7 12:35:35 2000 Owen Taylor * Some further makefile improvement. * Restore all the docs that mysteriously vanished earlier. --- docs/reference/ChangeLog | 6 + docs/reference/glib/Makefile.am | 5 +- docs/reference/glib/glib-sections.txt | 10 + docs/reference/glib/tmpl/allocators.sgml | 43 +- docs/reference/glib/tmpl/arrays.sgml | 207 +++++-- docs/reference/glib/tmpl/arrays_byte.sgml | 107 +++- docs/reference/glib/tmpl/arrays_pointer.sgml | 136 ++++- docs/reference/glib/tmpl/byte_order.sgml | 309 ++++++---- docs/reference/glib/tmpl/caches.sgml | 114 ++-- docs/reference/glib/tmpl/completion.sgml | 80 ++- docs/reference/glib/tmpl/datalist.sgml | 134 +++-- docs/reference/glib/tmpl/datasets.sgml | 146 +++-- docs/reference/glib/tmpl/date.sgml | 558 ++++++++++------- docs/reference/glib/tmpl/glib-unused.sgml | 126 ++-- docs/reference/glib/tmpl/hash_tables.sgml | 292 ++++++--- docs/reference/glib/tmpl/hooks.sgml | 322 +++++++--- docs/reference/glib/tmpl/iochannels.sgml | 239 ++++++-- docs/reference/glib/tmpl/limits.sgml | 25 +- docs/reference/glib/tmpl/linked_lists_double.sgml | 320 +++++++--- docs/reference/glib/tmpl/linked_lists_single.sgml | 297 ++++++--- docs/reference/glib/tmpl/macros.sgml | 121 ++-- docs/reference/glib/tmpl/macros_misc.sgml | 78 ++- docs/reference/glib/tmpl/main.sgml | 398 ++++++++++--- docs/reference/glib/tmpl/memory.sgml | 111 ++-- docs/reference/glib/tmpl/memory_chunks.sgml | 231 +++++-- docs/reference/glib/tmpl/messages.sgml | 184 ++++-- docs/reference/glib/tmpl/misc_utils.sgml | 146 +++-- docs/reference/glib/tmpl/modules.sgml | 131 ++-- docs/reference/glib/tmpl/quarks.sgml | 63 +- docs/reference/glib/tmpl/relations.sgml | 155 +++-- docs/reference/glib/tmpl/scanner.sgml | 253 +++++--- docs/reference/glib/tmpl/string_chunks.sgml | 83 ++- docs/reference/glib/tmpl/string_utils.sgml | 274 ++++++--- docs/reference/glib/tmpl/strings.sgml | 157 +++-- docs/reference/glib/tmpl/threads.sgml | 696 ++++++++++++++++++++-- docs/reference/glib/tmpl/timers.sgml | 36 +- docs/reference/glib/tmpl/trees-binary.sgml | 169 ++++-- docs/reference/glib/tmpl/trees-nary.sgml | 367 ++++++++---- docs/reference/glib/tmpl/type_conversion.sgml | 50 +- docs/reference/glib/tmpl/types.sgml | 101 +++- docs/reference/glib/tmpl/warnings.sgml | 132 +++- docs/reference/glib/tmpl/windows.sgml | 16 +- docs/reference/gobject/Makefile.am | 7 +- 43 files changed, 5370 insertions(+), 2065 deletions(-) rewrite docs/reference/glib/tmpl/glib-unused.sgml (69%) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index ef8c5495d..6e7c13e14 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +Thu Sep 7 12:35:35 2000 Owen Taylor + + * Some further makefile improvement. + + * Restore all the docs that mysteriously vanished earlier. + Wed Sep 6 10:59:45 2000 Owen Taylor * gobject/Makefile.am glib/Makefile.am: Improve diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am index bc9b9e95d..7387ace20 100644 --- a/docs/reference/glib/Makefile.am +++ b/docs/reference/glib/Makefile.am @@ -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 diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 2c80eafd0..c644286df 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -110,6 +110,13 @@ CLAMP G_STRUCT_MEMBER G_STRUCT_MEMBER_P G_STRUCT_OFFSET + + +glib_major_version +glib_micro_version +glib_minor_version +glib_interface_age +glib_binary_age
@@ -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
diff --git a/docs/reference/glib/tmpl/allocators.sgml b/docs/reference/glib/tmpl/allocators.sgml index 7b8807eec..6b12fd27c 100644 --- a/docs/reference/glib/tmpl/allocators.sgml +++ b/docs/reference/glib/tmpl/allocators.sgml @@ -2,11 +2,31 @@ Memory Allocators - +allocates chunks of memory for #GList, #GSList and #GNode. - +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. + + +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. + + +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. + + +Note that you cannot use the same allocator for #GList, #GSList and #GNode +elements. Each must use separate allocators. @@ -16,25 +36,30 @@ Memory Allocators - +The #GAllocator struct contains private data. and should only be accessed +using the following functions. - +Creates a new #GAllocator. -@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. - +Frees all of the memory allocated by the #GAllocator. -@allocator: +@allocator: a #GAllocator. diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index bae144152..bf1f0d155 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -2,12 +2,53 @@ Arrays - +arrays of arbitrary elements which grow automatically as elements are added. - +Arrays are similar to standard C arrays, except that they grow automatically +as elements are added. + + +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. + + +To create a new array use g_array_new(). + + +To add elements to an array, use g_array_append_val(), g_array_append_vals(), +g_array_prepend_val(), and g_array_prepend_vals(). + + +To access an element of an array, use g_array_index(). + + +To set the size of an array, use g_array_set_size(). + +To free an array, use g_array_free(). + + +Using a GArray to store gint values. + + 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); + @@ -16,21 +57,24 @@ Arrays - +Contains the public fields of an Array. -@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. - +Creates a new #GArray. -@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. @@ -47,113 +91,166 @@ Arrays - +Adds the value on to the end of the array. +The array will grow in size automatically if necessary. + + +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. + + -@a: -@v: +@a: a #GArray. +@v: the value to append to the #GArray. +@Returns: the #GArray. - +Adds @len elements onto the end of the array. -@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. - +Adds the value on to the start of the array. +The array will grow in size automatically if necessary. + + +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. + + + +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. + -@a: -@v: +@a: a #GArray. +@v: the value to prepend to the #GArray. +@Returns: the #GArray. - +Adds @len elements onto the start of the array. + + +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. -@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. - +Inserts an element into an array at the given index. + + +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. + + -@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. - +Inserts @len elements into a #GArray at the given index. -@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. - +Removes the element at the given index from a #GArray. +The following elements are moved down one place. -@array: -@index: -@Returns: +@array: a #GArray. +@index: the index of the element to remove. +@Returns: the #GArray. - +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(). -@array: -@index: -@Returns: +@array: a @GArray. +@index: the index of the element to remove. +@Returns: the #GArray. - +Returns the element of a #GArray at the given index. +The return value is cast to the given type. + + +Getting a pointer to an element in a GArray. + + EDayViewEvent *event; + + /* This gets a pointer to the 3rd element in the array of EDayViewEvent + structs. */ + event = &g_array_index (events, EDayViewEvent, 3); + + -@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. - +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. -@array: -@length: -@Returns: +@array: a #GArray. +@length: the new size of the #GArray. +@Returns: the #GArray. - +Frees the memory allocated for the #GArray. +If free_segment is TRUE it frees the actual element data as well. -@array: -@free_segment: +@array: a #GArray. +@free_segment: if TRUE the actual element data is freed as well. @Returns: diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index acdb74550..0a454e63b 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -2,13 +2,48 @@ Byte Arrays - +arrays of bytes, which grow automatically as elements are added. - +GByteArray is based on #GArray, to provide arrays of bytes which grow +automatically as elements are added. + + +To create a new #GByteArray use g_byte_array_new(). + + +To add elements to a #GByteArray, use g_byte_array_append(), and +g_byte_array_prepend(). + + +To set the size of a GByteArray, use g_byte_array_set_size(). + + +To free a GByteArray, use g_byte_array_free(). + +Using a GByteArray. + + 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); + + @@ -16,18 +51,19 @@ Byte Arrays - +The #GByteArray struct allows access to the public fields of a #GByteArray. -@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. - +Creates a new #GByteArray. -@Returns: +@Returns: the new #GByteArray. @@ -41,63 +77,70 @@ Byte Arrays - +Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary. -@array: -@data: -@len: -@Returns: +@array: a #GByteArray. +@data: the byte data to be added. +@len: the number of bytes to add. +@Returns: the #GByteArray. - +Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary. -@array: -@data: -@len: -@Returns: +@array: a #GByteArray. +@data: the byte data to be added. +@len: the number of bytes to add. +@Returns: the #GByteArray. - +Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. -@array: -@index: -@Returns: +@array: a #GByteArray. +@index: the index of the byte to remove. +@Returns: the #GByteArray. - +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(). -@array: -@index: -@Returns: +@array: a #GByteArray. +@index: the index of the byte to remove. +@Returns: the #GByteArray. - +Sets the size of the #GByteArray, expanding it if necessary. -@array: -@length: -@Returns: +@array: a #GByteArray. +@length: the new size of the #GByteArray. +@Returns: the #GByteArray. - +Frees the memory allocated by the #GByteArray. +If free_segment is TRUE it frees the actual byte data. -@array: -@free_segment: +@array: a #GByteArray. +@free_segment: if TRUE the actual byte data is freed as well. @Returns: diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index c969f2eb0..fa6659a32 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -2,12 +2,58 @@ Pointer Arrays - +arrays of pointers to any type of data, which grow automatically as new +elements are added. - +Pointer Arrays are similar to Arrays but are used only for storing pointers. + + + +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. + + + +To create a pointer array, use g_ptr_array_new(). + + +To add elements to a pointer array, use g_ptr_array_add(). + + +To remove elements from a pointer array, use g_ptr_array_remove(), +g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). + +To access an element of a pointer array, use g_ptr_array_index(). + + +To set the size of a pointer array, use g_ptr_array_set_size(). + + +To free a pointer array, use g_ptr_array_free(). + + +Using a GPtrArray. + + 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); + @@ -16,7 +62,11 @@ Pointer Arrays - +Contains the public fields of a pointer array. +The pdata field points to the array of pointers, +which may as when the array grows. +The len field is the number of pointers in the +array. @pdata: @@ -24,10 +74,10 @@ Pointer Arrays - +Creates a new #GPtrArray. -@Returns: +@Returns: the new #GPtrArray. @@ -41,78 +91,98 @@ Pointer Arrays - +Adds a pointer to the end of the pointer array. +The array will grow in size automatically if necessary. -@array: -@data: +@array: a #GPtrArray. +@data: the pointer to add. - +Removes the first occurrence of the given pointer from the pointer array. +The following elements are moved down one place. + + +It returns TRUE if the pointer was removed, or FALSE if the pointer +was not found. -@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. - +Removes the pointer at the given index from the pointer array. +The following elements are moved down one place. -@array: -@index: -@Returns: +@array: a #GPtrArray. +@index: the index of the pointer to remove. +@Returns: the pointer which was removed. - +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(). + + +It returns TRUE if the pointer was removed, or FALSE if the pointer +was not found. -@array: -@data: -@Returns: +@array: a #GPtrArray. +@data: the pointer to remove. +@Returns: TRUE if the pointer was found in the array. - +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(). -@array: -@index: -@Returns: +@array: a #GPtrArray. +@index: the index of the pointer to remove. +@Returns: the pointer which was removed. - +Sets the size of the array, expanding it if necessary. +New elements are set to NULL. -@array: -@length: +@array: a #GPtrArray. +@length: the new length of the pointer array. - +Returns the pointer at the given index of the pointer array. -@array: -@index: +@array: a #GPtrArray. +@index: the index of the pointer to return. +@Returns: the pointer at the given index. - +Frees all of the memory allocated for the pointer array. -@array: -@free_seg: +@array: a #GPtrArray. +@free_seg: if TRUE the actual element data is freed as well. @Returns: diff --git a/docs/reference/glib/tmpl/byte_order.sgml b/docs/reference/glib/tmpl/byte_order.sgml index acd833757..01e931c9a 100644 --- a/docs/reference/glib/tmpl/byte_order.sgml +++ b/docs/reference/glib/tmpl/byte_order.sgml @@ -2,11 +2,41 @@ Byte Order Macros - +a portable way to convert between different byte orders. - +These macros provide a portable way to determine the host byte order +and to convert values between different byte orders. + + +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. + + +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. + + +Other processors (notably the x86 family) store the most significant byte +last. These are known as little-endian processors. + + +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. + + +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). @@ -16,437 +46,500 @@ Byte Order Macros - +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.) - +Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. - +Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. - +Specifies one of the possible types of byte order (currently unused). +See #G_BYTE_ORDER. - +Converts a 32-bit integer value from host to network byte order. -@val: +@val: a 32-bit integer value in host byte order. +@Returns: @val converted to network byte order. - +Converts a 16-bit integer value from host to network byte order. -@val: +@val: a 16-bit integer value in host byte order. +@Returns: @val converted to network byte order. - +Converts a 32-bit integer value from network to host byte order. -@val: +@val: a 32-bit integer value in network byte order. +@Returns: @val converted to host byte order. - +Converts a 16-bit integer value from network to host byte order. -@val: +@val: a 16-bit integer value in network byte order. +@Returns: @val converted to host byte order. - +Converts a #gint value from big-endian to host byte order. -@val: +@val: a #gint value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint value from little-endian to host byte order. -@val: +@val: a #gint value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint value from host byte order to big-endian. -@val: +@val: a #gint value in host byte order. +@Returns: @val converted to big-endian byte order. - +Converts a #gint value from host byte order to little-endian. -@val: +@val: a #gint value in host byte order. +@Returns: @val converted to little-endian byte order. - +Converts a #guint value from big-endian to host byte order. -@val: +@val: a #guint value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint value from little-endian to host byte order. -@val: +@val: a #guint value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint value from host byte order to big-endian. -@val: +@val: a #guint value in host byte order. +@Returns: @val converted to big-endian byte order. - +Converts a #guint value from host byte order to little-endian. -@val: +@val: a #guint value in host byte order. +@Returns: @val converted to little-endian byte order. - +Converts a #glong value from big-endian to the host byte order. -@val: +@val: a #glong value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #glong value from little-endian to host byte order. -@val: +@val: a #glong value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #glong value from host byte order to big-endian. -@val: +@val: a #glong value in host byte order. +@Returns: @val converted to big-endian byte order. - +Converts a #glong value from host byte order to little-endian. -@val: +@val: a #glong value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #gulong value from big-endian to host byte order. -@val: +@val: a #gulong value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gulong value from little-endian to host byte order. -@val: +@val: a #gulong value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gulong value from host byte order to big-endian. -@val: +@val: a #gulong value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #gulong value from host byte order to little-endian. -@val: +@val: a #gulong value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #gint16 value from big-endian to host byte order. -@val: +@val: a #gint16 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint16 value from little-endian to host byte order. -@val: +@val: a #gint16 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint16 value from host byte order to big-endian. -@val: +@val: a #gint16 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #gint16 value from host byte order to little-endian. -@val: +@val: a #gint16 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #guint16 value from big-endian to host byte order. -@val: +@val: a #guint16 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint16 value from little-endian to host byte order. -@val: +@val: a #guint16 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint16 value from host byte order to big-endian. -@val: +@val: a #guint16 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #guint16 value from host byte order to little-endian. -@val: +@val: a #guint16 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #gint32 value from big-endian to host byte order. -@val: +@val: a #gint32 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint32 value from little-endian to host byte order. -@val: +@val: a #gint32 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint32 value from host byte order to big-endian. -@val: +@val: a #gint32 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #gint32 value from host byte order to little-endian. -@val: +@val: a #gint32 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #guint32 value from big-endian to host byte order. -@val: +@val: a #guint32 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint32 value from little-endian to host byte order. -@val: +@val: a #guint32 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint32 value from host byte order to big-endian. -@val: +@val: a #guint32 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #guint32 value from host byte order to little-endian. -@val: +@val: a #guint32 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #gint64 value from big-endian to host byte order. -@val: +@val: a #gint64 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint64 value from little-endian to host byte order. -@val: +@val: a #gint64 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #gint64 value from host byte order to big-endian. -@val: +@val: a #gint64 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #gint64 value from host byte order to little-endian. -@val: +@val: a #gint64 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #guint64 value from big-endian to host byte order. -@val: +@val: a #guint64 value in big-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint64 value from little-endian to host byte order. -@val: +@val: a #guint64 value in little-endian byte order. +@Returns: @val converted to host byte order. - +Converts a #guint64 value from host byte order to big-endian. -@val: +@val: a #guint64 value in host byte order. +@Returns: @val converted to big-endian. - +Converts a #guint64 value from host byte order to little-endian. -@val: +@val: a #guint64 value in host byte order. +@Returns: @val converted to little-endian. - +Converts a #guint16 value between big-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint16 value in big-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint16 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint16 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint16 value between little-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint16 value in little-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint32 value between big-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint32 value in big-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint32 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint32 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint32 value between little-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint32 value in little-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. - +Converts a #guint64 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. -@val: +@val: a #guint64 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index ee51d1f7b..aad81b57a 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -2,11 +2,23 @@ Caches - +allows sharing of complex data structures to save resources. - +A #GCache allows sharing of complex data structures, in order to save +system resources. + + +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. + + +#GCache uses keys and values. +A #GCache key describes the properties of a particular resource. +A #GCache value is the actual resource. @@ -16,47 +28,70 @@ Caches - +The #GCache struct is an opaque data structure containing information about +a #GCache. It should only be accesssed via the following functions. - +Creates a new GCache. -@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. - +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. -@cache: -@key: -@Returns: +@cache: a #GCache. +@key: a key describing a #GCache object. +@Returns: a pointer to a #GCache value. - +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(). -@cache: -@value: +@cache: a #GCache. +@value: the value to remove. - +Frees the memory allocated for the GCache. + + +Note that it does not destroy the keys and values which were contained in the +GCache. @cache: @@ -64,47 +99,54 @@ Caches - +Calls the given function for each of the keys in the #GCache. -@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. - +Calls the given function for each of the values in the #GCache. -@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. - +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. -@value: +@value: the #GCache value to destroy. - +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. -@value: -@Returns: +@value: the #GCache key to destroy (NOT a #GCache value as it seems). +@Returns: a copy of the #GCache key. - +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. -@key: -@Returns: +@key: a #GCache key. +@Returns: a new #GCache value corresponding to the key. diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index 33b8ba99c..6bb768160 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -2,11 +2,27 @@ Automatic String Completion - +support for automatic completion using a group of target strings. - +#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. + + +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(). + + +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. @@ -16,7 +32,15 @@ Automatic String Completion - +The data structure used for automatic completion. +items is the list of target items (strings +or data structures). +func is the function called to get the string +associated with a target item. It is NULL if the target items are strings. +prefix is the last prefix passed to +g_completion_complete(). +cache is the list of items which begin with +prefix. @items: @@ -26,64 +50,72 @@ Automatic String Completion - +Creates a new #GCompletion. -@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. - +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. -@Param1: -@Returns: +@Param1: the completion item. +@Returns: the string corresponding to the item. - +Adds items to the #GCompletion. -@cmp: -@items: +@cmp: the #GCompletion. +@items: the list of items to add. - +Removes items from a #GCompletion. -@cmp: -@items: +@cmp: the #GCompletion. +@items: the items to remove. - +Removes all items from the #GCompletion. -@cmp: +@cmp: the #GCompletion. - +Attempts to complete the string @prefix using the #GCompletion target items. -@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. - +Frees all memory used by the #GCompletion. -@cmp: +@cmp: the #GCompletion. diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index ef17f99f1..bef25d177 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -2,11 +2,43 @@ Keyed Data Lists - +lists of data elements which are accessible by a string or #GQuark identifier. +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. + + +The GQuark methods are quicker, since the strings have to be converted to +GQuarks anyway. + + +Data lists are used in GTK for associating arbitrary data with +GtkObjects, using gtk_object_set_data() and related functions. + + +To create a datalist, use g_datalist_init(). + + +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(). + + +To get data elements from a datalist use g_datalist_id_get_data() and +g_datalist_get_data(). + + +To iterate over all data elements in a datalist use g_datalist_foreach(). + + +To remove data elements from a datalist use g_datalist_id_remove_data() and +g_datalist_remove_data(). + + +To remove all data elements from a datalist, use g_datalist_clear(). @@ -16,56 +48,66 @@ Keyed Data Lists - +The #GData struct is an opaque data structure to represent a +Keyed Data List. +It should only be accessed via the following functions. - +Resets the datalist to NULL. +It does not free any memory or call any destroy functions. -@datalist: +@datalist: a pointer to a pointer to a datalist. - +Sets the data corresponding to the given #GQuark id. +Any previous data with the same key is removed, and its +destroy function is called. -@dl: -@q: -@d: +@dl: a datalist. +@q: the #GQuark to identify the data element. +@d: the data element. - +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. -@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. - +Gets a data element. -@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. - +Removes an element, using its #GQuark identifier. -@dl: -@q: +@dl: a datalist. +@q: the #GQuark identifying the data element. @@ -80,41 +122,48 @@ Keyed Data Lists - +Sets the data element corresponding to the given string identifier. -@dl: -@k: -@d: +@dl: a datalist. +@k: the string to identify the data element. +@d: the data element. - +Sets the data element corresponding to the given string identifier, and the +function to be called when the data element is removed. -@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. - +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. -@dl: -@k: +@dl: a datalist. +@k: the string identifying a data element. +@Returns: the data element, or NULL if it is not found. - +Removes an element using its string identifier. +The data element's destroy function is called if it has been set. -@dl: -@k: +@dl: a datalist. +@k: the string identifying the data element. @@ -128,19 +177,22 @@ Keyed Data Lists - +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. -@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. - +Frees all the data elements of the datalist. +The data elements' destroy functions are called if they have been set. -@datalist: +@datalist: a datalist. diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml index b1105253b..c6be2f9cf 100644 --- a/docs/reference/glib/tmpl/datasets.sgml +++ b/docs/reference/glib/tmpl/datasets.sgml @@ -2,11 +2,46 @@ Datasets - +associate groups of data elements with particular memory locations. - +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. + + +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. + + +There is no function to create a dataset. It is automatically created as +soon as you add elements to it. + + +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(). + + +To get data elements from a dataset use g_dataset_id_get_data() and +g_dataset_get_data(). + + +To iterate over all data elements in a dataset use g_dataset_foreach(). + + +To remove data elements from a dataset use g_dataset_id_remove_data() and +g_dataset_remove_data(). + + +To destroy a dataset, use g_dataset_destroy(). @@ -16,50 +51,61 @@ Datasets - +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. -@l: -@k: -@d: +@l: the location identifying the dataset. +@k: the #GQuark id to identify the data element. +@d: the data element. - +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. -@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. - +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. -@data: +@data: the data element. - +Gets the data element corresponding to a #GQuark. -@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. - +Removes a data element from a dataset. +The data element's destroy function is called if it has been set. -@l: -@k: +@l: the location identifying the dataset. +@k: the #GQuark id identifying the data element. @@ -74,41 +120,47 @@ Datasets - +Sets the data corresponding to the given string identifier. -@l: -@k: -@d: +@l: the location identifying the dataset. +@k: the string to identify the data element. +@d: the data element. - +Sets the data corresponding to the given string identifier, and the function +to call when the data element is destroyed. -@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. - +Gets the data element corresponding to a string. -@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. - +Removes a data element corresponding to a string. +Its destroy function is called if it has been set. -@l: -@k: +@l: the location identifying the dataset. +@k: the string identifying the data element. @@ -122,29 +174,33 @@ Datasets - +Calls the given function for each data element which is associated with the +given location. -@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. - +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(). -@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(). - +Destroys the dataset, freeing all memory allocated, and calling any +destroy functions set for data elements. -@dataset_location: +@dataset_location: the location identifying the dataset. diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index f929872be..ac82029ac 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -2,16 +2,65 @@ Date and Time Functions - +calendrical calculations and miscellaneous time stuff. - - + +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 day. + + + +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). + + + +#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 +invalid, 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. + + + +It is very important to use the API to access the #GDate +struct. Often only the DMY or only the Julian +representation is valid. Sometimes neither is valid. Use the API. + + + +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(). - - + + @@ -22,16 +71,19 @@ Date and Time Functions - - + +Represents a precise time, with seconds and microseconds. Same as the +struct timeval returned by the +gettimeofday() UNIX call. @tv_sec: @tv_usec: - - + +Equivalent to gettimeofday(), but also works on +Win32. Returns the current time. @result: @@ -46,8 +98,16 @@ Date and Time Functions - - + +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 +GDate 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. @julian_days: @@ -58,14 +118,15 @@ Date and Time Functions @year: - - + +Simply a replacement for time_t. Unrelated to GTimer. - - + +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. @G_DATE_DAY: @@ -73,14 +134,16 @@ Date and Time Functions @G_DATE_YEAR: - - + +Integer representing a day of the month; between 1 and +31. #G_DATE_BAD_DAY represents an invalid day of the month. - - + +Enumeration representing a month; values are #G_DATE_JANUARY, +#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value. @G_DATE_BAD_MONTH: @@ -98,14 +161,17 @@ Date and Time Functions @G_DATE_DECEMBER: - - + +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. - - + +Enumeration representing a day of the week; #G_DATE_MONDAY, +#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. @G_DATE_BAD_WEEKDAY: @@ -118,410 +184,486 @@ Date and Time Functions @G_DATE_SUNDAY: - - + +Represents an invalid #GDateDay. - - + +Represents an invalid Julian day number. - - + +Represents an invalid year. - - + +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(). -@Returns: +@Returns: The newly-allocated #GDate - - + +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. -@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 - - + +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. -@julian_day: -@Returns: +@julian_day: Days since January 1, Year 1 +@Returns: Allocated date initialized with @julian_day - - + +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(). -@date: -@n_dates: +@date: Pointer to one or more dates to clear +@n_dates: Number of dates to clear - - + +Free a #GDate returned from g_date_new() -@date: +@date: Date to free - - + +Set the day of the month for a #GDate. If the resulting day-month-year +triplet is invalid, the date will be invalid. -@date: -@day: +@date: Date to set the day for +@day: Day to set - - + +Set the month of the year for a #GDate. If the resulting + day-month-year triplet is invalid, the date will be invalid. -@date: -@month: +@date: Date +@month: Month to set - - + +Set the year for a #GDate. If the resulting day-month-year triplet is + invalid, the date will be invalid. -@date: -@year: +@date: Date +@year: Year to set - - + +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. -@date: -@day: -@month: -@y: +@date: Date to set the value of +@day: Day +@month: Month +@y: Year - - + +Set the value of a #GDate from a Julian day number. -@date: -@julian_date: +@date: Date to set +@julian_date: Julian day number (days since January 1, Year 1) - - + +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: + + g_date_set_time(date, time(NULL)); + -@date: -@time: +@date: Date to update +@time: #GTime value to set - - - - -@date: -@str: + +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. + + + +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). + + +@date: Date to fill in +@str: String to parse - - + +Increment a date some number of days. To move forward by weeks, add +weeks*7 days. The date must be valid. -@date: -@n_days: +@date: The date to increment +@n_days: Number of days to move the date forward - - + +Move a date some number of days into the past. To move by weeks, just +move by weeks*7 days. Date must be valid. -@date: -@n_days: +@date: Date to decrement +@n_days: Number of days to move - - + +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. -@date: -@n_months: +@date: Date to increment +@n_months: Number of months to move forward - - + +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. -@date: -@n_months: +@date: Date to decrement +@n_months: Number of months to move - - + +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. -@date: -@n_years: +@date: Date to increment +@n_years: Number of years to move forward - - + +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. -@date: -@n_years: +@date: Date to decrement +@n_years: Number of years to move - - + +qsort()-style comparsion function for dates. Both +dates must be valid. -@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 - - + +Return the day of the month; the #GDate must be valid. -@date: -@Returns: +@date: Date to extract the day of the month from +@Returns: Day of the month - - + +Accessor for the month of the year. Date must be valid. -@date: -@Returns: +@date: Date to get the month from +@Returns: A #GDateMonth - - + +Accessor; returns the year of a #GDate. The date must be valid. -@date: -@Returns: +@date: Date +@Returns: Year in which the date falls - - + +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. -@date: -@Returns: +@date: Date to extract the Julian day from +@Returns: Julian day - - + +Returns the day of the week for a #GDate. The date must be valid. -@date: -@Returns: +@date: Date +@Returns: Day of the week as a #GDateWeekday - - + +Return the day of the year, where Jan 1 is the first day of the +year. Date must be valid. -@date: -@Returns: +@date: Date to extract day of year from +@Returns: Day of the year - - + +Return the number of days in a month, taking leap years into account. -@month: -@year: -@Returns: +@month: Month +@year: Year +@Returns: Number of days in @month during the year @year. - - + +Returns TRUE if the date is on the first of a month. Date must be valid. -@date: -@Returns: +@date: Date to check +@Returns: Boolean, if the date is the first of the month - - + +Returns TRUE if the date is the last day of the month. Date must be valid. -@date: -@Returns: +@date: Date to check +@Returns: Boolean, if the date is the last day of the month - - + +Returns TRUE if the year is a leap year -@year: -@Returns: +@year: Year to check +@Returns: Boolean, if the year is a leap year - - + +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. -@date: -@Returns: +@date: Date to use +@Returns: Week of the year - - + +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.) -@year: -@Returns: +@year: Year +@Returns: Number of Mondays in the year - - + +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. -@date: -@Returns: +@date: Date +@Returns: Week number - - + +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.) -@year: -@Returns: +@year: Year to count weeks in +@Returns: Number of weeks - - + +Generate a printed representation of the date, in a locale-specific +way. Works just like the standard C strftime() +function, but only accepts date-related formats; time-related formats +give undefined results. Date must be valid. -@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 - - + +Fills in the date-related bits of a struct tm +using the @date value. Initializes the non-date parts with something +sane but meaningless. -@date: -@tm: +@date: Date to set the struct tm from +@tm: struct tm to fill - - + +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. -@date: -@Returns: +@date: Date to check +@Returns: Whether the date is valid. - - + +Returns TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive). -@day: -@Returns: +@day: Day to check. +@Returns: Boolean, whether the day is valid. - - + +Returns TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months. -@month: -@Returns: +@month: Month +@Returns: Boolean, whether the month is valid - - + +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. -@year: -@Returns: +@year: Year +@Returns: Boolean, whether the year is valid. - - + +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). -@day: -@month: -@year: -@Returns: +@day: Day +@month: Month +@year: Year +@Returns: Boolean, whether the date is a valid one - - + +Returns TRUE if the Julian day is valid. Anything greater than zero is basically a +valid Julian, though there is a 32-bit limit. -@julian_date: -@Returns: +@julian_date: Julian day to check +@Returns: Boolean, whether the Julian day is valid. - - + +Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration +values are the only valid weekdays. -@weekday: -@Returns: +@weekday: Weekday +@Returns: Boolean, whether the weekday is valid. diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml dissimilarity index 69% index 380562c2c..bdd048e92 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -1,42 +1,84 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + +Specifies the type of function passed to g_tree_search(). + + +@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. + + + + + + + + + + + + + + + +Turns the argument into a string literal by using the '#' stringizing operator. + + +@x: text to convert to a literal string. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml index 4846b7b96..75ffd0600 100644 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ b/docs/reference/glib/tmpl/hash_tables.sgml @@ -2,11 +2,48 @@ Hash Tables - +associations between keys and values so that given a key the value +can be found quickly. - +A #GHashTable provides associations between keys and values which +is optimized so that given a key, the associated value can be found +very quickly. + + +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. + + +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. + + +To create a #GHashTable, use g_hash_table_new(). + + +To insert a key and value into a #GHashTable, use g_hash_table_insert(). + + +To lookup a value corresponding to a given key, use g_hash_table_lookup() +and g_hash_table_lookup_extended(). + + +To remove a key and value, use g_hash_table_remove(). + + +To call a function for each key and value pair use g_hash_table_foreach(). + + +To destroy a #GHashTable use g_hash_table_destroy(). @@ -16,209 +53,306 @@ Hash Tables - +The #GHashTable struct is an opaque data structure to represent a +Hash Table. +It should only be accessed via the following functions. - +Creates a new #GHashTable. -@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. - +Specifies the type of the hash function which is passed to +g_hash_table_new() when a #GHashTable is created. + + +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. + + +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. -@key: -@Returns: +@key: a key. +@Returns: the hash value corresponding to the key. - +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. + + +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. + + +In g_list_find_custom() and g_slist_find_custom() the function should return +0 if the two parameters are equal. + + +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. -@a: -@b: -@Returns: +@a: a value. +@b: a value to compare with. +@Returns: TRUE if the two values are equivalent. - +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. + + +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. + + -@hash_table: -@key: -@value: +@hash_table: a #GHashTable. +@key: a key to insert. +@value: the value to associate with the key. - +Returns the number of key/value pairs in a #GHashTable. -@hash_table: -@Returns: +@hash_table: a #GHashTable. +@Returns: the number of key/value pairs in the #GHashTable. - +Looks up a key in the #GHashTable, returning the associated value or NULL +if the key is not found. -@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. - +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(). -@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. - +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. -@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. - +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(). -@key: -@value: -@user_data: +@key: a key. +@value: the value corresponding to the key. +@user_data: user data passed to g_hash_table_foreach(). - +Removes a key and its associated value from a #GHashTable. + + +As with g_hash_table_insert(), you should make sure that any dynamically +allocated values are freed yourself. + + -@hash_table: -@key: +@hash_table: a #GHashTable. +@key: the key to remove. - +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. -@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. - +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. -@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. - +Disable resizing of a #GHashTable. + + +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. -@hash_table: +@hash_table: a #GHashTable. - +Enables resizing of a #GHashTable. -@hash_table: +@hash_table: a #GHashTable. - +Destroys the #GHashTable. + + + +If keys and/or values are dynamically allocated, you should free them +first. + -@hash_table: +@hash_table: a #GHashTable. - +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. -@v: -@v2: -@Returns: +@v: a key. +@v2: a key to compare with @v. +@Returns: TRUE if the two keys match. - +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. -@v: -@Returns: +@v: a gpointer key. +@Returns: a hash value corresponding to the key. - +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. -@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. - +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. -@v: -@Returns: +@v: a pointer to a #gint key. +@Returns: a hash value corresponding to the key. - +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. -@v: -@v2: -@Returns: +@v: a key. +@v2: a key to compare with @v. +@Returns: TRUE if the two keys match. - +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. -@v: -@Returns: +@v: a string key. +@Returns: a hash value corresponding to the key. diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml index fecd43c49..47cf06e1f 100644 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -2,10 +2,13 @@ Hook Functions - +support for manipulating lists of hook functions. +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. @@ -17,6 +20,47 @@ Hook Functions + + + + + +#guint seq_id; +the next free #GHook id. + + + +#guint hook_size; +the size of the #GHookList elements, in bytes. + + + +#guint is_setup : 1; +1 if the #GHookList has been initialized. + + + +#GHook *hooks; +the first #GHook element in the list. + + + +#GMemChunk *hook_memchunk; +the #GMemChunk used for allocating the #GHook elements. + + + +#GHookFreeFunc hook_free; +the function to call to free a #GHook element. + + + +#GHookFreeFunc hook_destroy; +the function to call to destory a #GHook element. + + + + @seq_id: @@ -30,6 +74,51 @@ Hook Functions + + + + + +#gpointer data; +. + + + +#GHook *next; +. + + + +#GHook *prev; +. + + + +#guint ref_count; +. + + + +#guint hook_id; +. + + + +#guint flags; +. + + + +#gpointer data; +. + + + +#GDestroyNotify destroy; +. + + + @data: @@ -95,29 +184,34 @@ Hook Functions - +Initializes a #GHookList. +This must be called before the #GHookList is used. -@hook_list: -@hook_size: +@hook_list: a #GHookList. +@hook_size: the size of each element in the #GHookList, typically +sizeof (GHook). - +Calls all of the #GHook functions in a #GHookList. -@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. - +Calls all of the #GHook functions in a #GHookList. +Any function which returns TRUE is removed from the #GHookList. -@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. @@ -125,7 +219,7 @@ Hook Functions -@hook_list: +@hook_list: a #GHookList. @may_recurse: @marshaller: @data: @@ -136,7 +230,7 @@ Hook Functions -@hook_list: +@hook_list: a #GHookList. @may_recurse: @marshaller: @data: @@ -144,164 +238,183 @@ Hook Functions - +Removes all the #GHook elements from a #GHookList. -@hook_list: +@hook_list: a #GHookList. - +Allocates space for a #GHook and initializes it. -@hook_list: -@Returns: +@hook_list: a #GHookList. +@Returns: a new #GHook. - +Appends a #GHook onto the end of a #GHookList. -@hook_list: -@hook: +@hook_list: a #GHookList. +@hook: the #GHook to add to the end of @hook_list. - +Prepends a #GHook on the start of a #GHookList. -@hook_list: -@hook: +@hook_list: a #GHookList. +@hook: the #GHook to add to the start of @hook_list. - +Inserts a #GHook into a #GHookList, before a given #GHook. -@hook_list: -@sibling: -@hook: +@hook_list: a #GHookList. +@sibling: the #GHook to insert the new #GHook before. +@hook: the #GHook to insert. - +Inserts a #GHook into a #GHookList, sorted by the given function. -@hook_list: -@hook: -@func: +@hook_list: a #GHookList. +@hook: the #GHook to insert. +@func: the comparison function used to sort the #GHook elements. - +Defines the type of function used to compare #GHook elements in +g_hook_insert_sorted(). -@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. - +Compares the ids of two #GHook elements, returning a negative value +if the second id is greater than the first. -@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. - +Returns the #GHook with the given id, or NULL if it is not found. -@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. - +Finds a #GHook in a #GHookList using the given function to test for a match. -@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. - +Finds a #GHook in a #GHookList with the given data. -@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. - +Finds a #GHook in a #GHookList with the given function. -@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. - +Defines the type of the function passed to g_hooK_find_func(). -@hook: -@data: -@Returns: +@hook: a #GHook. +@data: user data passed to g_hook_find_func(). +@Returns: TRUE if the required #GHook has been found. - +Finds a #GHook in a #GHookList with the given function and data. -@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. - +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.) -@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. +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.) -@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. @@ -322,79 +435,90 @@ Hook Functions - +Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active +and it has not been destroyed. -@hook: +@hook: a #GHook. +@Returns: TRUE if the #GHook is valid. - +Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook +is destroyed. -@hook: +@hook: a #GHook. +@Returns: TRUE if the #GHook is active. - +Returns TRUE if the #GHook function is currently executing. -@hook: +@hook: a #GHook. +@Returns: TRUE if the #GHook function is currently executing. +Returns TRUE if the #GHook is not in a #GHookList. -@hook: +@hook: a #GHook. +@Returns: TRUE if the #GHook is not in a #GHookList. - +Increments the reference count for a #GHook. -@hook_list: -@hook: +@hook_list: a #GHookList. +@hook: the #GHook to increment the reference count of. - +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. -@hook_list: +@hook_list: a #GHookList. @hook: - +Calls the #GHookList @hook_free function if it exists, and frees the memory +allocated for the #GHook. -@hook_list: -@hook: +@hook_list: a #GHookList. +@hook: the #GHook to free. - +Destroys a #GHook, given its ID. -@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. - +Removes one #GHook from a #GHookList, calling the @hook_destroy function in +the #GHookList, and the @destroy function of the #GHook, if they exist. -@hook_list: -@hook: +@hook_list: a #GHookList. +@hook: the #GHook to remove. diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index fcdbeef72..1c44eb2ce 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -2,21 +2,68 @@ IO Channels - +portable support for using files, pipes and sockets. - +The #GIOChannel data type aims to provide a portable method for using file +descriptors, pipes, and sockets, and integrating them into the +main event loop. +Currently full support is available on Unix platforms, though support for +Windows is only partially complete. + + +To create a new #GIOChannel on Unix systems use g_io_channel_unix_new(). +This works for plain file descriptors, pipes and sockets. + + +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(). + + +To add a #GIOChannel to the +main event loop +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. + + +#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. + + +GTK+ contains the convenience function gtk_input_add_full() +which creates a #GIOChannel from a file descriptor and adds it to the +main event loop. +The event source can later be removed with gtk_input_remove(). +Similar functions can also be found in GDK. - + + + +gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), +gdk_input_add_full(), gdk_input_remove() + +Convenience functions for creating #GIOChannel instances and adding them to the +main event loop. + + + + - +A data structure representing an IO Channel. The fields should be considered +private and should only be accessed with the following functions. @channel_flags: @@ -25,40 +72,47 @@ IO Channels - +Creates a new #GIOChannel given a file descriptor. +On Unix systems this works for plain files, pipes, and sockets. + + +The returned #GIOChannel has a reference count of 1. -@fd: -@Returns: +@fd: a file descriptor. +@Returns: a new #GIOChannel. - +Returns the file descriptor of the Unix #GIOChannel. -@channel: -@Returns: +@channel: a #GIOChannel, created with g_io_channel_unix_new(). +@Returns: the file descriptor of the #GIOChannel. - +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). -@channel: +@channel: a #GIOChannel. - +Reads data from a #GIOChannel. -@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. @@ -73,29 +127,56 @@ IO Channels - +Writes data to a #GIOChannel. -@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. - +Sets the current position in the #GIOChannel, similar to the standard system +call fseek(). -@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. +An enumeration specifying the base position for a g_io_channel_seek() +operation. + + + + + + +G_SEEK_CUR +the current position in the file. + + + +G_SEEK_SET +the start of the file. + + + +G_SEEK_END +the end of the file. + + + @@ -105,56 +186,100 @@ IO Channels - +Closes a #GIOChannel. +The #GIOChannel will be freed when its reference count drops to 0. -@channel: +@channel: a #GIOChannel. - +Increments the reference count of a #GIOChannel. -@channel: +@channel: a #GIOChannel. - +Decrements the reference count of a #GIOChannel. -@channel: +@channel: a #GIOChannel. - +Adds the #GIOChannel into the +main event loop +with the default priority. -@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. - +Adds the #GIOChannel into the +main event loop +with the given priority. -@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. +A bitwise combination representing a condition to watch for on an event +source. + + + + + + +G_IO_IN +There is data to read. + + + +G_IO_OUT +Data can be written (without blocking). + + + +G_IO_PRI +There is urgent data to read. + + + +G_IO_ERR +Error condition. + + + +G_IO_HUP +Hung up (the connection has been broken, usually for pipes and +sockets). + + + +G_IO_NVAL +Invalid request. The file descriptor is not open. + + + @@ -167,18 +292,22 @@ IO Channels - +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. -@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. - +A table of functions used to handle different types of #GIOChannel in a +generic way. @io_read: diff --git a/docs/reference/glib/tmpl/limits.sgml b/docs/reference/glib/tmpl/limits.sgml index 1e73eb045..673fbc5e0 100644 --- a/docs/reference/glib/tmpl/limits.sgml +++ b/docs/reference/glib/tmpl/limits.sgml @@ -2,11 +2,12 @@ Limits of Basic Types - +portable method of determining the limits of the standard types. - +These macros provide a portable method to determine the limits of some of +the standard integer and floating point types. @@ -16,14 +17,14 @@ Limits of Basic Types - +The minimum value which can be held in a #gint. - +The maximum value which can be held in a #gint. @@ -37,14 +38,14 @@ Limits of Basic Types - +The minimum value which can be held in a #gshort. - +The maximum value which can be held in a #gshort. @@ -58,14 +59,14 @@ Limits of Basic Types - +The minimum value which can be held in a #glong. - +The maximum value which can be held in a #glong. @@ -79,28 +80,28 @@ Limits of Basic Types - +The minimum value which can be held in a #gfloat. - +The maximum value which can be held in a #gfloat. - +The minimum value which can be held in a #gdouble. - +The maximum value which can be held in a #gdouble. diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index 7e907188d..e4bf0ada2 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -2,11 +2,61 @@ Doubly-Linked Lists - +linked lists containing integer values or pointers to data, with the ability +to iterate over the list in both directions. - +The #GList structure and its associated functions provide a standard +doubly-linked list data structure. + + +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 +Singly-Linked Lists +which only allows movement through the list in the forward direction). + + +The data contained in each element can be either integer values, by using one +of the +Type Conversion Macros, +or simply pointers to any type of data. + + +List elements are allocated in blocks using a #GListAllocator, which is +more efficient than allocating elements individually. + + +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. + + +There is no function to create a #GList. NULL is considered to be the empty +list so you simply set a #GList* to NULL. + + +To add elements, use g_list_append(), g_list_prepend(), g_list_insert() +and g_list_insert_sorted(). + + +To remove elements, use g_list_remove(). + + +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(). + + +To find the index of an element use g_list_position() and g_list_index(). + + +To call a function for each element in the list use g_list_foreach(). + + +To free the entire list, use g_list_free(). @@ -16,7 +66,12 @@ Doubly-Linked Lists - +The #GList struct is used for each element in a doubly-linked list. +The data field holds the element's data, which can +be a pointer to any kind of data, or any integer value using the +Type Conversion Macros. +The next and prev +pointers are the links to the next and previous elements in the list. @data: @@ -25,64 +80,103 @@ Doubly-Linked Lists - +Adds a new element on to the end of the list. + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + + /* 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)); + + +@list: a pointer to a #GList. +@data: the data for the new element. +@Returns: the new start of the #GList. - +Adds a new element on to the start of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + /* Notice that it is initialized to the empty list. */ + GList *list = NULL; + list = g_list_prepend (list, "last"); + list = g_list_prepend (list, "first"); + -@list: -@data: -@Returns: +@list: a pointer to a #GList. +@data: the data for the new element. +@Returns: the new start of the #GList. - +Inserts a new element into the list at the given position. -@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. - +Inserts a new element into the list, using the given comparison function +to determine its position. -@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. - +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. -@list: -@data: -@Returns: +@list: a #GList. +@data: the data of the element to remove. +@Returns: the new start of the #GList. - +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. -@list: -@llink: -@Returns: +@list: a #GList. +@llink: an element in the #GList. +@Returns: the new start of the #GList, without the element. @@ -97,200 +191,234 @@ Doubly-Linked Lists - +Frees all of the memory used by a #GList. +The freed elements are added to the #GListAllocator free list. + + + +If list elements contain dynamically-allocated memory, they should be freed +first. + @list: - +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. -@Returns: +@Returns: a pointer to the newly-allocated #GList element. - +Frees one #GList element. +It is usually used after g_list_remove_link(). -@list: +@list: a #GList element. - +Gets the number of elements in a #GList. -@list: -@Returns: +@list: a #GList. +@Returns: the number of elements in the #GList. - +Copies a #GList. + + +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. -@list: -@Returns: +@list: a #GList. +@Returns: a copy of @list. - +Reverses a #GList. +It simply switches the next and prev pointers of each element. -@list: -@Returns: +@list: a #GList. +@Returns: the start of the reversed #GList. - +Sorts a #GList using the given comparison function. -@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. - +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. -@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. - +Calls a function for each element of a #GList. -@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. - +Specifies the type of functions passed to g_list_foreach() and +g_slist_foreach(). -@data: -@user_data: +@data: the element's data. +@user_data: user data passed to g_list_foreach() or g_slist_foreach(). - +Gets the first element in a #GList. -@list: -@Returns: +@list: a #GList. +@Returns: the first element in a #GList, or NULL if the #GList has no elements. - +Gets the last element in a #GList. -@list: -@Returns: +@list: a #GList. +@Returns: the last element in the #GList, or NULL if the #GList has no +elements. - +A convenience macro to gets the previous element in a #GList. -@list: +@list: an element in a #GList. +@Returns: the previous element, or NULL if there are no previous elements. - +A convenience macro to gets the next element in a #GList. -@list: +@list: an element in a #GList. +@Returns: the next element, or NULL if there are no more elements. - +Gets the element at the given position in a #GList. -@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. - +Gets the data of the element at the given position. -@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. - +Finds the element in a #GList which contains the given data. -@list: -@data: -@Returns: +@list: a #GList. +@data: the element data to find. +@Returns: the found #GList element, or NULL if it is not found. - +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. -@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. - +Gets the position of the given element in the #GList (starting from 0). -@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. - +Gets the position of the element containing the given data (starting from 0). -@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. - +Sets the allocator to use to allocate #GList elements. +Use g_list_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GList elements. - +Restores the previous #GAllocator, used when allocating #GList elements. diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index dbab524bc..0076ccdc9 100644 --- a/docs/reference/glib/tmpl/linked_lists_single.sgml +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -2,11 +2,61 @@ Singly-Linked Lists - +linked lists containing integer values or pointers to data, limited to +iterating over the list in one direction. - +The #GSList structure and its associated functions provide a standard +singly-linked list data structure. + + +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 +Doubly-Linked Lists +which allow movement in both directions). + + +The data contained in each element can be either integer values, by using one +of the +Type Conversion Macros, +or simply pointers to any type of data. + + +List elements are allocated in blocks using a #GListAllocator, which is +more efficient than allocating elements individually. + + +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. + + +There is no function to create a #GSList. NULL is considered to be the empty +list so you simply set a #GSList* to NULL. + + +To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert() +and g_slist_insert_sorted(). + + +To remove elements, use g_slist_remove(). + + +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(). + + +To find the index of an element use g_slist_position() and g_slist_index(). + + +To call a function for each element in the list use g_slist_foreach(). + + +To free the entire list, use g_slist_free(). @@ -16,7 +66,12 @@ Singly-Linked Lists - +The #GSList struct is used for each element in the singly-linked list. +The data field holds the element's data, which can +be a pointer to any kind of data, or any integer value using the +Type Conversion Macros. +The next field contains the link to the next +element in the list. @data: @@ -24,41 +79,75 @@ Singly-Linked Lists - +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. -@Returns: +@Returns: a pointer to the newly-allocated #GSList element. - +Adds a new element on to the end of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + /* 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)); + + +@list: a #GSList. +@data: the data for the new element. +@Returns: the new start of the #GSList. - +Adds a new element on to the start of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + /* Notice that it is initialized to the empty list. */ + GSList *list = NULL; + list = g_slist_prepend (list, "last"); + list = g_slist_prepend (list, "first"); + -@list: -@data: -@Returns: +@list: a #GSList. +@data: the data for the new element. +@Returns: the new start of the #GSList. - +Inserts a new element into the list at the given position. -@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. @@ -74,33 +163,42 @@ Singly-Linked Lists - +Inserts a new element into the list, using the given comparison function +to determine its position. -@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. - +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. -@list: -@data: -@Returns: +@list: a #GSList. +@data: the data of the element to remove. +@Returns: the new start of the #GSList. - +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. -@list: +@list: a #GSList. @link: -@Returns: +@Returns: the new start of the #GSList, without the element. + +@llink: an element in the #GSList. @@ -115,166 +213,189 @@ Singly-Linked Lists - +Frees all of the memory used by a #GSList. +The freed elements are added to the #GListAllocator free list. -@list: +@list: a #GSList. - +Frees one #GSList element. +It is usually used after g_slist_remove_link(). -@list: +@list: a #GSList element. - +Gets the number of elements in a #GSList. -@list: -@Returns: +@list: a #GSList. +@Returns: the number of elements in the #GSList. - +Copies a #GSList. + + +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. -@list: -@Returns: +@list: a #GSList. +@Returns: a copy of @list. - +Reverses a #GSList. -@list: -@Returns: +@list: a #GSList. +@Returns: the start of the reversed #GSList. - +Sorts a #GSList using the given comparison function. -@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. - +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. -@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. - +Calls a function for each element of a #GSList. -@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. - +Gets the last element in a #GSList. -@list: -@Returns: +@list: a #GSList. +@Returns: the last element in the #GSList, or NULL if the #GSList has no +elements. - +A convenience macro to gets the next element in a #GSList. -@slist: +@slist: an element in a #GSList. +@Returns: the next element, or NULL if there are no more elements. - +Gets the element at the given position in a #GSList. -@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. - +Gets the data of the element at the given position. -@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. - +Finds the element in a #GSList which contains the given data. -@list: -@data: -@Returns: +@list: a #GSList. +@data: the element data to find. +@Returns: the found #GSList element, or NULL if it is not found. - +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. -@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. - +Gets the position of the given element in the #GSList (starting from 0). -@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. - +Gets the position of the element containing the given data (starting from 0). -@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. - +Sets the allocator to use to allocate #GSList elements. +Use g_slist_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GSList elements. - +Restores the previous #GAllocator, used when allocating #GSList elements. diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index c2a4c2fd1..3664e187c 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/docs/reference/glib/tmpl/macros.sgml @@ -2,11 +2,11 @@ Standard Macros - +commonly-used macros. - +These macros provide a few commonly-used features. @@ -16,21 +16,21 @@ Standard Macros - +The major version number of the GLib library. - +The minor version number of the GLib library. - +The micro version number of the GLib library. @@ -58,124 +58,171 @@ Standard Macros +Checks the version of the GLib library. +It returns TRUE if the GLib library is the same or newer than the given +version. + +Checking the version of the GLib library. + + if (!GLIB_CHECK_VERSION (1, 2, 0)) + g_error ("GLib version 1.2.0 or above is needed"); + + -@major: -@minor: -@micro: +@major: the major version number. +@minor: the minor version number. +@micro: the micro version number. - +The directory separator character. +This is '/' on Unix machines and '\' under Windows. - +The directory separator as a string. +This is "/" on Unix machines and "\" under Windows. - +The search path separator character. +This is ':' on Unix machines and ';' under Windows. - +The search path separator as a string. +This is ":" on Unix machines and ";" under Windows. - +Defines the TRUE value for the #gboolean type. - +Defines the FALSE value for the #gboolean type. - +Defines the standard NULL pointer. - +Calculates the minimum of @a and @b. -@a: -@b: +@a: a numeric value. +@b: a numeric value. +@Returns: the minimum of @a and @b. - +Calculates the maximum of @a and @b. -@a: -@b: +@a: a numeric value. +@b: a numeric value. +@Returns: the maximum of @a and @b. - +Calculates the absolute value of @a. +The absolute value is simply the number with any negative sign taken away. + + +For example, + + +ABS(-10) is 10. + + +ABS(10) is also 10. + + -@a: +@a: a numeric value. +@Returns: the absolute value of @a. - +Ensures that @x is between the limits set by @low and @high. + + +For example, + + +CLAMP(5, 10, 15) is 10. + + +CLAMP(15, 5, 10) is 10. + + +CLAMP(20, 15, 25) is 20. + + -@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. - +Returns a member of a structure at a given offset, using the given type. -@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. - +Returns an untyped pointer to a given offset of a struct. -@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. - +Returns the offset, in bytes, of a member of a struct. -@struct_type: -@member: +@struct_type: a structure type, e.g. GtkWidget. +@member: a field in the structure, e.g. window. +@Returns: the offset of @member from the start of @struct_type. diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index 43e4b8b93..c6fbded21 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -2,11 +2,12 @@ Miscellaneous Macros - +specialised macros which are not used often. - +These macros provide more specialized features which are not needed so often +by application programmers. @@ -16,21 +17,24 @@ Miscellaneous Macros - +Used to declare inline functions. If inline functions are not supported on +the particular platform, the macro evaluates to the empty string. - +Used within multi-statement macros so that they can be used in places where +only one statement is expected by the compiler. - +Used within multi-statement macros so that they can be used in places where +only one statement is expected by the compiler. @@ -45,11 +49,11 @@ Miscellaneous Macros - +Portable way to copy va_list variables. -@ap1: -@ap2: +@ap1: the va_list variable to place a copy of @ap2 in. +@ap2: a va_list. @@ -62,68 +66,100 @@ Miscellaneous Macros - +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. - +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. - +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. - +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. - +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 printf(). +It allows the compiler to type-check the arguments passed to the function. +See the GNU C documentation for details. -@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. - +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 scanf(). +It allows the compiler to type-check the arguments passed to the function. +See the GNU C documentation for details. -@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. +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 printf() and +scanf(). See the GNU C documentation for details. +FIXME: I can't find this in my GNU C documentation. Take out? -@arg_idx: +@arg_idx: the index of the argument. - +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. - +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. diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index 212f500ee..0af7652a7 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/docs/reference/glib/tmpl/main.sgml @@ -2,11 +2,47 @@ The Main Event Loop - +manages all available sources of events. - +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(). + + +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. + + +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. + + +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. + + +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. + + +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. @@ -16,180 +52,271 @@ The Main Event Loop - +The #GMainLoop struct is an opaque data type representing the main event loop +of a GLib or GTK+ application. - +Creates a new #GMainLoop. -@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. - +Frees the memory allocated for the #GMainLoop. -@loop: +@loop: a #GMainLoop. - +Runs a main loop until it stops running, which occurs when g_main_quit() +is called. -@loop: +@loop: a #GMainLoop. - +Returns TRUE if the main loop is running. -@loop: -@Returns: +@loop: a #GMainLoop. +@Returns: TRUE if the main loop is running. - +Returns TRUE if any events are pending (i.e. ready to be processed). -@Returns: +@Returns: TRUE if any events are pending. - +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. -@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. - +Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop, +it will now return. -@loop: +@loop: a #GMainLoop. - +Use this for high priority event sources. +It is not used within GLib or GTK+. - +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. - +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.) - +Use this for default priority idle functions. +In GLib this priority is used when adding idle functions with g_idle_add(). - +Use this for very low priority background tasks. +It is not used within GLib or GTK+. - +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. + + +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). -@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. - +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. + + +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). -@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. - +Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(), +g_idle_add(), and g_idle_add_full(). -@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. - +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. -@function: -@data: -@Returns: +@function: the function to call. +@data: data to pass to the function. +@Returns: the id of the event source. - +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. -@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. - +Removes the idle function with the given data. -@data: -@Returns: +@data: the data which is passed to the idle function. +@Returns: TRUE if the idle function was found. - +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. -@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. + + + + + +#gint fd; +the file descriptor to poll (or a HANDLE on Win32 platforms). + + + +#gushort events; +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. + + + + +#gushort revents; +a bitwise combination of flags from #GIOCondition, returned from the +poll() function to indicate which events occurred. + + + + @fd: @@ -198,18 +325,25 @@ The Main Event Loop - +Removes a file descriptor from the list being polled. -@fd: +@fd: the #GPollFD to remove. - +Sets the function to use to handle polling of file descriptors. +It will be used instead of the poll() system call +(or GLib's replacement function, which is used where +poll() isn't available). + + +This function could possibly be used to integrate the GLib event loop +with an external event loop. -@func: +@func: the function to call to poll all file descriptors. @@ -222,32 +356,105 @@ The Main Event Loop - +Specifies the type of function passed to g_main_set_poll_func(). +The semantics of the function should match those of the +poll() system call. -@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. - +Adds an event source to the main loop. -@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. - +The #GSourceFuncs struct contains a table of functions used to handle +event sources in a generic manner. + + + + + + +prepare + +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. + + + + +check + +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. + + + + +dispatch + +Called to process the event source, after it has returned TRUE in either +its @prepare or its @check function. + + + + +destroy + +Called when the source is destroyed. It will be called with the user data +parameter passed to the g_source_add() and related functions. + + + + + + +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). + + +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. + + +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. @prepare: @@ -257,38 +464,55 @@ The Main Event Loop - +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(). -@tag: -@Returns: +@tag: the id of the event source to remove. +@Returns: TRUE if the source was found and removed. - +Removes the first event source found with the given #GSourceFuncs and user +data. + + +Event sources are sorted with the highest priority first. Sources with equal +priority are stored in the order in which they were added. -@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. - +Removes the first event source found with the given source data. + + +Event sources are sorted with the highest priority first. Sources with equal +priority are stored in the order in which they were added. -@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. - +Removes the first event source found with the given user data. + + +Event sources are sorted with the highest priority first. Sources with equal +priority are stored in the order in which they were added. -@user_data: -@Returns: +@user_data: the user data of the source to remove. +@Returns: TRUE if an event source was found and removed. diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index e940bca38..4a6e1b434 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -2,12 +2,18 @@ Memory Allocation - +general memory-handling. - +These functions provide support for allocating and freeing memory. + + +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. + + @@ -16,100 +22,135 @@ Memory Allocation - +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. -@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. - +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. -@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. - +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. -@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. - +Allocates @size bytes of memory. +If @size is 0 it returns NULL. -@size: -@Returns: +@size: the number of bytes to allocate. +@Returns: a pointer to the allocated memory. - +Allocates @size bytes of memory, initialized to 0's. +If @size is 0 it returns NULL. -@size: -@Returns: +@size: the number of bytes to allocate. +@Returns: a pointer to the allocated memory. - +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. -@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. - +Frees the memory pointed to by @mem. +If @mem is NULL it simply returns. -@mem: +@mem: the memory to free. - +Copies a block of memory @n bytes long, from @s to @d. +The source and destination areas may overlap. + + +On architectures where memmove() is not available, this function is implemented +using bcopy(), which may not be able to handle overlapping areas. + + -@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. - +Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is NULL it returns NULL. -@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. - +Outputs a summary of memory usage. +To use this function you must configure glib with the flag +'--enable-mem-profile=yes' before compiling. + + +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. - +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. -@mem: +@mem: the memory to check. diff --git a/docs/reference/glib/tmpl/memory_chunks.sgml b/docs/reference/glib/tmpl/memory_chunks.sgml index 17601e611..2f33963b9 100644 --- a/docs/reference/glib/tmpl/memory_chunks.sgml +++ b/docs/reference/glib/tmpl/memory_chunks.sgml @@ -2,13 +2,121 @@ Memory Chunks - +efficient way to allocate groups of equal-sized chunks of memory. - +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 +Doubly Linked Lists +use memory chunks to allocate space for elements of the lists. + + +There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE. + + +#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. + + +#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. + + + + + +To create a memory chunk use g_mem_chunk_new() or the convenience macro +g_mem_chunk_create(). + + +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(). + + +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.) + + +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(). + + +To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset(). + + +To destroy a memory chunk, use g_mem_chunk_destroy(). + + +To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print(). + +Using a GMemChunk. + + 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); + + + +Using a GMemChunk with data structures. + + 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); + + @@ -16,143 +124,180 @@ Memory Chunks - +The #GMemChunk struct is an opaque data structure representing a memory +chunk. It should be accessed only through the use of the following functions. - +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. - +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. - +Creates a new #GMemChunk. -@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. - +Allocates an atom of memory from a #GMemChunk. -@mem_chunk: -@Returns: +@mem_chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom. - +Allocates an atom of memory from a #GMemChunk, setting the memory to 0. -@mem_chunk: -@Returns: +@mem_chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom. - +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. -@mem_chunk: -@mem: +@mem_chunk: a #GMemChunk. +@mem: a pointer to the atom to free. - +Frees all of the memory allocated for a #GMemChunk. -@mem_chunk: +@mem_chunk: a #GMemChunk. - +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 sizeof(), and the +area size is calculated by multiplying the @pre_alloc parameter with +the atom size. -@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. - +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. -@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. - +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. -@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. - +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(). -@mem: -@mem_chunk: +@mem: a pointer to the atom to be freed. +@mem_chunk: a #GMemChunk. - +Resets a GMemChunk to its initial state. +It frees all of the currently allocated blocks of memory. -@mem_chunk: +@mem_chunk: a #GMemChunk. - +Frees any blocks in a #GMemChunk which are no longer being used. -@mem_chunk: +@mem_chunk: a #GMemChunk. - +Calls g_mem_chunk_clean() on all #GMemChunk objects. - +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. - +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. -@mem_chunk: +@mem_chunk: a #GMemChunk. diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml index d563744f9..13edc578e 100644 --- a/docs/reference/glib/tmpl/messages.sgml +++ b/docs/reference/glib/tmpl/messages.sgml @@ -2,11 +2,17 @@ Message Logging - +versatile support for logging messages with different levels of importance. +These functions provide support for logging error messages or messages +used for debugging. + + +There are several built-in levels of messages, defined in #GLogLevelFlags. +These can be extended with user-defined levels. @@ -16,8 +22,19 @@ Message Logging - +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. + +For example, GTK uses this in its Makefile.am: + + +INCLUDES = \ + -DG_LOG_DOMAIN=\"Gtk\" + @@ -35,32 +52,33 @@ Message Logging - +GLib log levels that are considered fatal by default. - +Log level shift offset for user defined log levels (0-7 are used by GLib). - +Specifies the prototype of log handler functions. -@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(). - +Flags specifying the level of log messages. @G_LOG_FLAG_RECURSION: @@ -75,40 +93,54 @@ Message Logging - +Logs an error or debugging message. +If the log level has been set as fatal, the abort() +function is called to terminate the program. -@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 printf() +documentation. +@Varargs: the parameters to insert into the format string. - +Logs an error or debugging message. +If the log level has been set as fatal, the abort() +function is called to terminate the program. -@log_domain: -@log_level: -@format: -@args: +@log_domain: the log domain. +@log_level: the log level. +@format: the message format. See the printf() +documentation. +@args: the parameters to insert into the format string. - +A convenience function/macro to log a normal message. @...: + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. - +A convenience function/macro to log a warning message. @...: + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. @@ -121,103 +153,141 @@ Message Logging - +A convenience function/macro to log an error message. +Error messages are always fatal, resulting in a call to +abort() to terminate the application. @...: + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. - +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. + + +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. -@log_domain: -@log_levels: -@log_func: -@user_data: -@Returns: + +Adding a log handler for all warning messages + + g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL + | G_LOG_FLAG_RECURSIVE, my_log_handler, NULL); + + + +@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. - +Removes the log handler. -@log_domain: -@handler_id: +@log_domain: the log domain. +@handler_id: the id of the handler, which was returned in g_log_set_handler(). - +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. -@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. - +Sets the log levels which are fatal in the given domain. +%G_LOG_LEVEL_ERROR is always fatal. -@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. - +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 abort(). + + +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.) -@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. - +Sets the function to be called to handle error messages. +This function is deprecated in favour of the new logging facilities. -@func: -@Returns: +@func: the function to be called to handle error messages. +@Returns: the old error handler. - +Specifies the type of function passed to g_set_error_handler(). -@str: +@str: the error message. - +Sets the function to be called to handle warning messages. +This function is deprecated in favour of the new logging facilities. -@func: -@Returns: +@func: the function to be called to handle warning messages. +@Returns: the old warning handler. - +Specifies the type of function passed to g_set_warning_handler(). -@str: +@str: the warning message. - +Sets the function to be called to handle messages. +This function is deprecated in favour of the new logging facilities. -@func: -@Returns: +@func: the function to be called to handle normal messages. +@Returns: the old message handler. diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 932d4a2c8..e9eadd9ca 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -2,11 +2,11 @@ Miscellaneous Utility Functions - +a selection of portable utility functions. - +These are portable utility functions. @@ -16,103 +16,120 @@ Miscellaneous Utility Functions - +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].) -@Returns: +@Returns: the name of the program. - +Sets the name of the program. -@prgname: +@prgname: the name of the program. - +Returns an environment variable. +On windows systems the returned value is only valid until the next call to +g_getenv(). -@variable: -@Returns: +@variable: the environment variable to get. +@Returns: the value of the environment variable, or NULL if the environment +variable is not found. - +Gets the user name of the current user. -@Returns: +@Returns: the user name of the current user. - +Gets the real name of the user. This comes from the user's entry in the +passwd file. -@Returns: +@Returns: the user's real name. - +Gets the current user's home directory. -@Returns: +@Returns: the current user's home directory. - +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. -@Returns: +@Returns: the directory to use for temporary files. - +Gets the current directory. +The returned string should be freed when no longer needed. -@Returns: +@Returns: the current directory. - +Gets the name of the file without any leading directory components. +It returns a pointer into the given file name string. -@file_name: -@Returns: +@file_name: the name of the file. +@Returns: the name of the file without any leading directory components. - +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. -@file_name: -@Returns: +@file_name: the name of the file. +@Returns: the directory components of the file. - +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. -@file_name: -@Returns: +@file_name: a file name. +@Returns: TRUE if @file_name is an absolute path. - +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. -@file_name: -@Returns: +@file_name: a file name. +@Returns: a pointer into @file_name after the root component. @@ -153,64 +170,81 @@ Miscellaneous Utility Functions - +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. -@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. - +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. -@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. - +Gets the number of bits used to hold @number, +e.g. if @number is 4, 3 bits are needed. -@number: -@Returns: +@number: a guint. +@Returns: the number of bits used to hold @number. - +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. + + +The built-in array of primes ranges from 11 to 13845163 such that +each prime is approximately 1.5-2 times the previous prime. -@num: -@Returns: +@num: a guint. +@Returns: the smallest prime number from a built-in array of primes which is +larger than @num. - +Specifies a function to be called at normal program termination. -@func: +@func: the function to call on normal program termination. - +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. -@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. - +Associates a string with a bit flag. +Used in g_parse_debug_string(). @key: @@ -218,14 +252,16 @@ Miscellaneous Utility Functions - +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(). - +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+. @data: diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index 3a6410dba..f3d0ba83e 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -2,11 +2,37 @@ Dynamic Loading of Modules - +portable method for dynamically loading 'plug-ins'. - +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. + + +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. + + +If any of the above functions fail, the error status can be found with +g_module_error(). + + +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). + + +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(). @@ -16,41 +42,65 @@ Dynamic Loading of Modules - +The #GModule struct is an opaque data structure to represent a +Dynamically-Loaded Module. +It should only be accessed via the following functions. - +Checks if modules are supported on the current platform. -@Returns: +@Returns: TRUE if modules are supported. - +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. + + +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. + + +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". -@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. - +Opens a module. +If the module has already been opened, its reference count is incremented. -@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. - +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.) @G_MODULE_BIND_LAZY: @@ -58,76 +108,85 @@ Dynamic Loading of Modules - +Gets a symbol pointer from a module. -@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. - +Gets the file name from a #GModule. -@module: -@Returns: +@module: the module. +@Returns: the file name of the module, or "main" if the module is the main +program itself. - +Ensures that a module will never be unloaded. +Any future g_module_close() calls on the module will be ignored. -@module: +@module: a module to make permanently resident. - +Closes a module. -@module: -@Returns: +@module: the module to close. +@Returns: TRUE on success. - +Gets a string describing the last module error. -@Returns: +@Returns: a string describing the last module error. - +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. -@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. - +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. -@module: +@module: the module about to be unloaded. - +Used to declare functions exported by modules. - +Used to declare functions imported from modules. diff --git a/docs/reference/glib/tmpl/quarks.sgml b/docs/reference/glib/tmpl/quarks.sgml index d6644a0ba..b62e032aa 100644 --- a/docs/reference/glib/tmpl/quarks.sgml +++ b/docs/reference/glib/tmpl/quarks.sgml @@ -2,11 +2,28 @@ Quarks - +a 2-way association between a string and a unique integer identifier. - +Quarks are associations between strings and integer identifiers. +Given either the string or the #GQuark identifier it is possible to +retrieve the other. + + +Quarks are used for both +Datasets and +Keyed Data Lists. + + +To create a new quark from a string, use g_quark_from_string() or +g_quark_from_static_string(). + + +To find the string corresponding to a given #GQuark, use g_quark_to_string(). + + +To find the #GQuark corresponding to a given string, use g_quark_try_string(). @@ -16,43 +33,59 @@ Quarks - +A GQuark is an integer which uniquely identifies a particular string. - +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. -@string: -@Returns: +@string: a string. +@Returns: the #GQuark identifying the string. - +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. + + +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). -@string: -@Returns: +@string: a string. +@Returns: the #GQuark identifying the string. - +Gets the string associated with the given #GQuark. -@quark: -@Returns: +@quark: a #GQuark. +@Returns: the string associated with the #GQuark. - +Gets the #GQuark associated with the given string, or 0 if the string has +no associated #GQuark. + + +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(). -@string: -@Returns: +@string: a string. +@Returns: the #GQuark associated with the string, or 0 if there is no +#GQuark associated with the string. diff --git a/docs/reference/glib/tmpl/relations.sgml b/docs/reference/glib/tmpl/relations.sgml index 9a7a8608a..4c1dd6110 100644 --- a/docs/reference/glib/tmpl/relations.sgml +++ b/docs/reference/glib/tmpl/relations.sgml @@ -2,11 +2,53 @@ Relations and Tuples - +tables of data which can be indexed on any number of fields. - +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. + + +Note that #GRelation tables are currently limited to 2 fields. + + +To create a GRelation, use g_relation_new(). + + +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. + + +To add records to a #GRelation use g_relation_insert(). + + +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.) + + +To count the number of records which have a particular value in a given +field, use g_relation_count(). + + +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(). + + +To delete all records which have a particular value in a given field, +use g_relation_delete(). + + +To destroy the #GRelation, use g_relation_destroy(). + + +To help debug #GRelation objects, use g_relation_print(). @@ -16,121 +58,144 @@ Relations and Tuples - +The #GRelation struct is an opaque data structure to represent a +Relation. +It should only be accessed via the following functions. - +Creates a new #GRelation with the given number of fields. +Note that currently the number of fields must be 2. -@fields: -@Returns: +@fields: the number of fields. +@Returns: a new #GRelation. - +Creates an index on the given field. +Note that this must be called before any records are added to the #GRelation. -@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. - +Inserts a record into a #GRelation. -@relation: -@Varargs: +@relation: a #GRelation. +@Varargs: the fields of the record to add. This must match the number of +fields in the #GRelation. - +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. -@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. - +Returns the number of tuples in a #GRelation that have the given value +in the given field. -@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. - +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(). -@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. - +Deletes any records from a GRelation that have the given key value in +the given field. -@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. - +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. -@relation: +@relation: a #GRelation. - +Outputs information about all records in a #GRelation, as well as the indexes. +It is for debugging. -@relation: +@relation: a #GRelation. - +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(). @len: - +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. -@tuples: +@tuples: the tuple data to free. - +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. -@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. diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml index 496a9416e..2e02cb3a5 100644 --- a/docs/reference/glib/tmpl/scanner.sgml +++ b/docs/reference/glib/tmpl/scanner.sgml @@ -2,11 +2,16 @@ Lexical Scanner - +a general purpose lexical scanner. - +The #GScanner and its associated functions provide a general purpose +lexical scanner. + + +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. @@ -16,7 +21,22 @@ Lexical Scanner - +The data structure representing a lexical scanner. + + +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. + + +The user_data and +derived_data fields are not used. +If you need to associate extra data with the scanner you can place them here. + + +If you want to use your own message handler you can set the +msg_handler field. The type of the message +handler function is declared by #GScannerMsgFunc. @user_data: @@ -43,16 +63,50 @@ Lexical Scanner - +Creates a new #GScanner. +The @config_templ structure specifies the initial settings of the scanner, +which are copied into the #GScanner config field. +If you pass NULL then the default settings are used. +(See g_scanner_config_template in gscanner.c for the defaults.) -@config_templ: -@Returns: +@config_templ: the initial scanner settings. +@Returns: the new #GScanner. - +Specifies the #GScanner settings. + + +cset_skip_characters specifies which characters +should be skipped by the scanner (the default is the whitespace characters: +space, tab, carriage-return and line-feed). + + +cset_identifier_first specifies the characters +which can start identifiers. +(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). + + +cset_identifier_nth 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. + + +cpair_comment_single 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). + + +case_sensitive specifies if symbols are +case sensitive. + + +The rest of the fields are flags which turn features on or off. +FIXME: should describe these. @cset_skip_characters: @@ -83,11 +137,11 @@ Lexical Scanner - +Prepares to scan a file. -@scanner: -@input_fd: +@scanner: a #GScanner. +@input_fd: a file descriptor. @@ -100,105 +154,122 @@ Lexical Scanner - +Gets the file attributes. +This is the st_mode field from the +stat structure. See the stat() +documentation. -@filename: -@Returns: +@filename: the file name. +@Returns: the file attributes. - +Prepares to scan a text buffer. -@scanner: -@text: -@text_len: +@scanner: a #GScanner. +@text: the text buffer to scan. +@text_len: the length of the text buffer. - +Gets the next token, without removing it from the input stream. +The token data is placed in the +next_token, +next_value, +next_line, and +next_position fields of the #GScanner structure. -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the type of the token. - +Gets the next token, removing it from the input stream. +The token data is placed in the +token, +value, +line, and +position fields of the #GScanner structure. -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the type of the token. - +Gets the current line in the input stream (counting from 1). -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the current line. - +Gets the current position in the current line (counting from 0). -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the current position on the line. - +Gets the current token type. +This is simply the token field in the #GScanner +structure. -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the current token type. - +Gets the current token value. +This is simply the value field in the #GScanner +structure. -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: the current token value. - +Returns TRUE if the scanner has reached the end of the file or text buffer. -@scanner: -@Returns: +@scanner: a #GScanner. +@Returns: TRUE if the scanner has reached the end of the file or text buffer. - +Sets the current scope. -@scanner: -@scope_id: -@Returns: +@scanner: a #GScanner. +@scope_id: the new scope id. +@Returns: the old scope id. - +Adds a symbol to the given scope. -@scanner: -@scope_id: -@symbol: -@value: +@scanner: a #GScanner. +@scope_id: the scope id. +@symbol: the symbol to add. +@value: the value of the symbol. @@ -210,6 +281,8 @@ Lexical Scanner @scope_id: @func: @user_data: + +@func_data: @@ -261,36 +334,42 @@ Lexical Scanner - +Outputs a warning message, via the #GScanner message handler. -@scanner: -@format: -@Varargs: +@scanner: a #GScanner. +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. - +Outputs an error message, via the #GScanner message handler. -@scanner: -@format: -@Varargs: +@scanner: a #GScanner. +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. - +Outputs a message resulting from an unexpected token in the input stream. +FIXME: I don't understand the arguments here. -@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. @@ -305,15 +384,15 @@ Lexical Scanner - +Frees all memory used by the #GScanner. -@scanner: +@scanner: a #GScanner. - +The possible types of token returned from each g_scanner_get_next_token() call. @G_TOKEN_EOF: @@ -323,13 +402,14 @@ Lexical Scanner - +A union holding the value of the token. - +The possible errors, used in the v_error field +of #GTokenValue, when the token is a G_TOKEN_ERROR. @G_ERR_UNKNOWN: @@ -343,14 +423,16 @@ Lexical Scanner - +The set of lower-case ASCII alphabet characters. +Used for specifying valid identifier characters in #GScannerConfig. - +The set of upper-case ASCII alphabet characters. +Used for specifying valid identifier characters in #GScannerConfig. @@ -364,44 +446,51 @@ Lexical Scanner - +Part of the set of extended characters in the Latin character sets. +FIXME: lower case? +Used for specifying valid identifier characters in #GScannerConfig. - +Part of the set of extended characters in the Latin character sets. +FIXME: upper case? +Used for specifying valid identifier characters in #GScannerConfig. - +Adds a symbol to the default scope. +Deprecated in favour of g_scanner_scope_add_symbol(). -@scanner: -@symbol: -@value: +@scanner: a #GScanner. +@symbol: the symbol to add. +@value: the value of the symbol. - +Removes a symbol from the default scope. +Deprecated in favour of g_scanner_scope_remove_symbol(). -@scanner: -@symbol: +@scanner: a #GScanner. +@symbol: the symbol to remove. - +Calls a function for each symbol in the default scope. +Deprecated in favour of g_scanner_scope_foreach_symbol(). -@scanner: -@func: -@data: +@scanner: a #GScanner. +@func: the function to call with each symbol. +@data: data to pass to the function. diff --git a/docs/reference/glib/tmpl/string_chunks.sgml b/docs/reference/glib/tmpl/string_chunks.sgml index 43a3364cd..85961aedb 100644 --- a/docs/reference/glib/tmpl/string_chunks.sgml +++ b/docs/reference/glib/tmpl/string_chunks.sgml @@ -2,11 +2,37 @@ String Chunks - +efficient storage of groups of strings. - +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. + + +When storing a large number of strings, string chunks are more efficient +than using g_strdup() since fewer calls to malloc() +are needed, and less memory is wasted in memory allocation overheads. + + +By adding strings with g_string_chunk_insert_const() it is also possible +to remove duplicates. + + +To create a new #GStringChunk use g_string_chunk_new(). + + +To add strings to a #GStringChunk use g_string_chunk_insert(). + + +To add strings to a #GStringChunk, but without duplicating strings which are +already in the #GStringChunk, use g_string_chunk_insert_const(). + + +To free the entire #GStringChunk use g_string_chunk_free(). +It is not possible to free individual strings. @@ -16,44 +42,69 @@ String Chunks - +An opaque data structure representing String Chunks. +It should only be accessed by using the following functions. - +Creates a new #GStringChunk. -@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. - +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. + + +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. -@chunk: -@string: -@Returns: +@chunk: a #GStringChunk. +@string: the string to add. +@Returns: a pointer to the copy of @string within the #GStringChunk. - +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(). + + +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. + + +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. -@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. - +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. -@chunk: +@chunk: a #GStringChunk. diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 655f62fdc..4ec417c30 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -2,11 +2,12 @@ String Utility Functions - +various string-related functions. - +This section describes a number of utility functions for creating, +duplicating, and manipulating strings. @@ -16,31 +17,37 @@ String Utility Functions - +Duplicates a string. +The returned string should be freed when no longer needed. -@str: -@Returns: +@str: the string to duplicate. +@Returns: a newly-allocated copy of @str. - +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. -@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. - +Creates a new string @length characters long filled with @fill_char. +The returned string should be freed when no longer needed. -@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. @@ -67,168 +74,223 @@ String Utility Functions - +Similar to the standard C sprintf() 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. -@format: -@Varargs: -@Returns: +@format: the standard sprintf() format string. +@Varargs: the parameters to insert into the format string. +@Returns: a newly-allocated string holding the result. - +Similar to the standard C vsprintf() 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. -@format: -@args: -@Returns: +@format: the standard sprintf() format string. +@args: the list of parameters to insert into the format string. +@Returns: a newly-allocated string holding the result. - +A safer form of the standard sprintf() 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. + + +See also g_strdup_printf(). + + + +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. + -@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 sprintf() +documentation. +@Varargs: the arguments to insert in the output. +@Returns: the length of the output string. - +A safer form of the standard vsprintf() 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. + + +See also g_strdup_vprintf(). + + +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. + + -@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 sprintf() +documentation. +@args: the list of arguments to insert in the output. +@Returns: the length of the output string. - +Calculates the maximum space needed to store the output of the +sprintf() function. -@format: -@args: -@Returns: +@format: the format string. See the printf() +documentation. +@args: the parameters to be inserted into the format string. +@Returns: the maximum space needed to store the formatted string. - +Converts a string to upper case. -@string: +@string: the string to convert. @Returns: - +Converts a string to lower case. -@string: +@string: the string to convert. @Returns: - +A case-insensitive string comparison, corresponding to the standard +strcasecmp() function on platforms which support it. -@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. - +A case-insensitive string comparison, corresponding to the standard +strncasecmp() function on platforms which support it. +It is similar to g_strcasecmp() except it only compares the first @n characters +of the strings. -@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. - +Reverses all of the characters in a string. +For example, g_strreverse ("abcdef") would be "fedcba". -@string: +@string: the string to reverse. @Returns: - +Converts a string to a gdouble value. +It calls the standard strtod() 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. -@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. - +Removes leading whitespace from a string, by moving the rest of the +characters forward. -@string: -@Returns: +@string: a string to remove the leading whitespace from. +@Returns: @string. - +Removes trailing whitespace from a string. -@string: -@Returns: +@string: a string to remove the trailing whitespace from. +@Returns: @string. - +Removes leading and trailing whitespace from a string. -@string: +@string: a string to remove the leading and trailing whitespace from. - +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. -@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: - +The standard delimiters, used in #g_strdelimit. - +Escapes all backslash characters, '\' in a string, by inserting a second '\'. @source: @exceptions: -@Returns: +@Returns: a newly allocated copy of @string, with all backslash characters +escaped using a second backslash. + +@string: a string to escape the backslashes in. @@ -253,68 +315,88 @@ String Utility Functions - +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. -@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. - +Frees a NULL-terminated array of strings, and the array itself. -@str_array: +@str_array: a NULL-terminated array of strings to free. - +Concatenates all of the given strings into one long string. +The returned string should be freed when no longer needed. -@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. - +Joins a number of strings together to form one long string, with the optional +@separator inserted between each of them. -@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. - +Joins a number of strings together to form one long string, with the optional +@separator inserted between each of them. -@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. - +Returns a string corresponding to the given error code, e.g. "no such process". +This function is included since not all platforms support the +strerror() function. -@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 (<code>)". +The string can only be used until the next call to g_strerror. - +Returns a string describing the given signal, e.g. "Segmentation fault". +This function is included since not all platforms support the +strsignal() function. -@signum: -@Returns: +@signum: the signal number. See the signal +documentation. +@Returns: a string describing the signal. +If the signal is unknown, it returns "unknown signal (<signum>)". +The string can only be used until the next call to g_strsignal. diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index ff7859d7c..0949983b9 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -2,11 +2,16 @@ Strings - +text buffers which grow automatically as text is added. - +A #GString is similar to a standard C string, except that it grows +automatically as text is appended or inserted. + + +The space allocated for the string is always a power of two, so as the +string grows it will occupy 2, 4, 8, 16, 32, 64, 128 etc. characters. @@ -16,7 +21,16 @@ Strings - +The #GString struct contains the public fields of a #GString. +The str field points to the character data. +It may move as text is added. +The len field contains the length of the string, +not including the terminating null character. + + +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. @str: @@ -24,70 +38,83 @@ Strings - +Creates a new #GString, initialized with the given string. -@init: -@Returns: +@init: the initial text to copy into the string. +@Returns: the new #GString. - +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. -@dfl_size: -@Returns: +@dfl_size: the default size of the space allocated to hold the string. +@Returns: the new #GString. - +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. @string: -@rval: -@Returns: +@rval: the source #GString. +@Returns: the destination #GString. + +@lval: the destination #GString. Its current contents are destroyed. - +Writes a formatted string into a #GString. +This is similar to the standard sprintf() function, +except that the GString buffer automatically expands to contain the results. +The previous contents of the GString are destroyed. -@string: -@format: -@Varargs: +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. - +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. -@string: -@format: -@Varargs: +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. - +Adds a string onto the end of a #GString, expanding it if necessary. -@string: -@val: -@Returns: +@string: a #GString. +@val: the string to append onto the end of the #GString. +@Returns: the #GString. - +Adds a character onto the end of a #GString, expanding it if necessary. -@string: -@c: -@Returns: +@string: a #GString. +@c: the character to append onto the end of the #GString. +@Returns: the #GString. @@ -103,22 +130,22 @@ Strings - +Adds a string on to the start of a #GString, expanding it if necessary. -@string: -@val: -@Returns: +@string: a #GString. +@val: the string to prepend on the start of the #GString. +@Returns: the #GString. - +Adds a character onto the start of a #GString, expanding it if necessary. -@string: -@c: -@Returns: +@string: a #GString. +@c: the character to prepend on the start of the #GString. +@Returns: the #GString. @@ -134,24 +161,24 @@ Strings - +Inserts a copy of a string into a #GString, expanding it if necessary. -@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. - +Inserts a character into a #GString, expanding it if necessary. -@string: -@pos: -@c: -@Returns: +@string: a #GString. +@pos: the position to insert the character. +@c: the character to insert. +@Returns: the #GString. @@ -168,51 +195,53 @@ Strings - +Removes @len characters from a #GString, starting at position @pos. +The rest of the #GString is shifted down to fill the gap. -@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. - +Cuts off the end of the GString, leaving the first @len characters. -@string: -@len: -@Returns: +@string: a #GString. +@len: the new size of the #GString. +@Returns: the #GString. - +Frees the memory allocated for the #GString. +If free_segment is TRUE it also frees the character data. -@string: -@free_segment: +@string: a #GString. +@free_segment: if TRUE the actual character data is freed as well. @Returns: - +Converts a #GString to upper case. -@string: -@Returns: +@string: a #GString. +@Returns: the #GString. - +Converts a #GString to lower case. -@string: -@Returns: +@string: a #GString. +@Returns: the #GString. diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 546eed447..68889f4e9 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/docs/reference/glib/tmpl/threads.sgml @@ -1,12 +1,42 @@ + Threads +thread abstraction; including mutexes, conditions and thread private data. + +Threads act almost like processes, but unlike processes all threads of +one process share the same memory. This is good, as it provides easy +communication between the involved threads via this shared memory, and +it is bad, because strange things (so called Heisenbugs) might happen, +when the program is not carefully designed. Especially bad is, that due +to the concurrent nature of threads no assumptions on the order of +execution of different threads can be done unless explictly forced by +the programmer through synchronization primitives. + + +The aim of the thread related functions in GLib is to provide a +portable means for writing multithread safe software. There are +primitives for mutexes to protect the access to portions of memory +(#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are +primitives for condition variables to allow synchronization of threads +(#GCond) and finally there are primitives for thread-private data, +that every thread has a private instance of (#GPrivate, +#GStaticPrivate). + + + +Currently there is only as much thread support included in GLib as is +necessary to make GLib itself multithread safe. Version 1.4 of GLib +will contain full thread support. For now the most portable way to +create threads is to require the macro #G_THREADS_IMPL_POSIX to be +defined and use POSIX threads then. This will work on almost all +platforms (except most notably Solaris and DCE threads.). @@ -15,29 +45,38 @@ Threads - + +This macro is defined, if GLib was compiled with thread support. This +does not necessarily mean, that there is a thread implementation +available, but the infrastructure is in place and once you provide a +thread implementation to g_thread_init(), GLib will be multithread +safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined. - + +This macro is defined, if POSIX style threads are used. - + +This macro is defined, if the SOLARIS thread system is used. - + +This macro is defined, if no thread implementation is used. You can +however provide one to g_thread_init() to make GLib multithread safe. @@ -57,9 +96,20 @@ Threads @G_THREAD_ERROR_AGAIN: + +This function table is used by g_thread_init() to initialize the +thread system. The functions in that table are directly used by their +g_* prepended counterparts, that are described here, e.g. if you call +g_mutex_new() then mutex_new() from the table provided to +g_thread_init() will be called. + + + +This struct should only be used, if you know, what you are doing. + @mutex_new: @mutex_lock: @@ -83,19 +133,81 @@ Threads @thread_self: + + +Before you use a thread related function in GLib, you should +initialize the thread system. This is done by calling +g_thread_init(). Most of the time you will only have to call +g_thread_init(NULL). + + + + +You should only call g_thread_init() with a non-NULL parameter, if you +really know, what you are doing. + + + + + +g_thread_init() must not be called directly or indirectly as a +callback from GLib. + + + +g_thread_init() might only be called once. On the second call +it will abort with an error. If you want to make sure, that the thread +system is initialized, you can do that too: + + + + + +if (!g_thread_supported ()) g_thread_init (NULL); + + + + + +After that line either the thread system is initialized or the program +will abort, if no thread system is available in GLib, i.e. either +#G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined. + + +If no thread system is available and @vtable is NULL or if not all +elements of @vtable are non-NULL, then g_thread_init() will abort. + + + + +To use g_thread_init() in your program, you have to link with the +libraries, that the command "glib-config --libs gthread" outputs. This +is not the case for all the other thread related functions of +GLib. Those can be used without having to link with the thread +libraries. + -@vtable: +@vtable: a function table of type #GThreadFunctions, that provides the +entry points to the thread system to be used. +This function returns, whether the thread system is initialized or +not. + + + +This function is actually a macro. Apart from taking the address of it +you can however use it as if it was a function. + -@Returns: +@Returns: TRUE, if the thread system is initialized. @@ -180,145 +292,368 @@ Threads + + +The #GMutex struct is an opaque data structure to represent a mutex +(mutual exclusion). It can be used to protect data against shared +access. Take for example the following function: + + +A function which will not work in a threaded environment + + int give_me_next_number () + { + static int current_number = 0; + + /* now do a very complicated calculation to calculate the new number, + this might for example be a random number generator */ + current_number = calc_next_number (current_number); + return current_number; + } + + + + + +It is easy to see, that this won't work in a multithreaded +application. There current_number must be protected against shared +access. A first naive implementation would be: + + + + +The wrong way to write a thread-safe function + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + static GMutex * mutex = NULL; + + if (!mutex) + mutex = g_mutex_new (); + g_mutex_lock (mutex); + ret_val = current_number = calc_next_number (current_number); + g_mutex_unlock (mutex); + return ret_val; + } + + + + + +This looks like it would work, but there is a race condition while +constructing the mutex and this code can't work reliable. So please do +not use such constructs in your own programs. One working solution is: + + + + +A correct thread-safe function + + static GMutex *give_me_next_number_mutex = NULL; + + /* this function must be called before any call to give_me_next_number () + it must be called exactly once. */ + void init_give_me_next_number () + { + g_assert (give_me_next_number_mutex == NULL); + give_me_next_number_mutex = g_mutex_new (); + } + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + + g_mutex_lock (give_me_next_number_mutex); + ret_val = current_number = calc_next_number (current_number); + g_mutex_unlock (give_me_next_number_mutex); + return ret_val; + } + + + + +#GStaticMutex provides a simpler and safer way of doing this. + + +A #GMutex should only be accessed via the following functions. + + +All of the g_mutex_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + + +Creates a new #GMutex. + + + +This function will abort, if g_thread_init() has not been called yet. + -@Returns: +@Returns: a new #GMutex. + +Locks the #GMutex. If the #GMutex is already locked by another thread, +the current thread will block until the #GMutex is unlocked by the +other thread. + + +This function can also be used, if g_thread_init() has not yet been +called and will do nothing then. -@mutex: + + +#GMutex is not guaranteed to be recursive, i.e. a thread might block, +if it already has locked the #GMutex. It will deadlock then, of +course. + + + +@mutex: a #GMutex. + +Tries to lock the #GMutex. If the #GMutex is already locked by another +thread, it immediately returns FALSE. Otherwise it locks the #GMutex +and returns TRUE. + + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return TRUE then. -@mutex: -@Returns: +@mutex: a #GMutex. +@Returns: TRUE, if the #GMutex could be locked. - + +Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock() +call, it will be woken and can lock the #GMutex itself. This function +can also be used, if g_thread_init() has not yet been called and will +do nothing then. -@mutex: +@mutex: a #GMutex. - + +Destroys the #GMutex. -@mutex: +@mutex: a #GMutex. + + +A #GStaticMutex works like a #GMutex, but it has one significant +advantage. It doesn't need to be created at run-time like a #GMutex, +but can be defined at compile-time. Here is a shorter, easier and +safer version of our give_me_next_number() example: + + + + +Using GStaticMutex to simplify thread-safe programming + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + static GStaticMutex mutex = G_STATIC_MUTEX_INIT; + + g_static_mutex_lock (&mutex); + ret_val = current_number = calc_next_number (current_number); + g_static_mutex_unlock (&mutex); + return ret_val; + } + + + + +Even though #GStaticMutex is not opaque, it should only be used with +the following functions, as it is defined differently on different +platforms. + +All of the g_static_mutex_* functions can also be used, if +g_thread_init() has not yet. + + +All of the g_static_mutex_* functions are actually macros. Apart from +taking the addresses of them, you can however use them as if they were +functions. + + + + +Every #GStaticMutex must be initialized with this macro, before it can +be used. + + + +Initializing a GStaticMutext + +GStaticMutex my_mutex = G_STATIC_MUTEX_INIT; + + - +works like g_mutex_lock(), but for a #GStaticMutex. -@mutex: +@mutex: a #GStaticMutex. - + +works like g_mutex_trylock(), but for a #GStaticMutex. -@mutex: -@Returns: +@mutex: a #GStaticMutex. +@Returns: TRUE, if the #GStaticMutex could be locked. - + +works like g_mutex_unlock(), but for a #GStaticMutex. -@mutex: +@mutex: a #GStaticMutex. - + +For some operations (like g_cond_wait()) you must have a #GMutex +instead of a #GStaticMutex. This function will return the +corresponding #GMutex for every #GStaticMutex. -@mutex: -@Returns: +@mutex: a #GStaticMutex. +@Returns: the corresponding #GMutex. + + +The G_LOCK_* macros provide a convenient interface to #GStaticMutex +with the advantage that they will expand to nothing in programs +compiled against a thread-disabled GLib, saving code and memory +there. #G_LOCK_DEFINE defines a lock. It can occur, where variable +definitions may occur in programs, i.e. in the first block of a +function or outside of functions. The @name parameter will be mangled +to get the name of the #GStaticMutex. This means, that you can use +names of existing variables as the parameter, e.g. the name of the +variable you intent to protect with the lock. Look at our +give_me_next_number() example using the G_LOCK_* macros: + + + +Using the G_LOCK_* convenience macros + +G_LOCK_DEFINE (current_number); +int give_me_next_number () + { + static int current_number = 0; + int ret_val; + + G_LOCK (current_number); + ret_val = current_number = calc_next_number (current_number); + G_UNLOCK (current_number); + return ret_val; + } + + -@name: +@name: the name of the lock. - + +This works like #G_LOCK_DEFINE, but it creates a static object. -@name: +@name: the name of the lock. - + +This declares a lock, that is defined with #G_LOCK_DEFINE in another module. -@name: +@name: the name of the lock. - + +works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE. -@name: +@name: the name of the lock. - + +works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE. -@name: +@name: the name of the lock. +@Returns: TRUE, if the lock could be locked. - + +works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE. -@name: +@name: the name of the lock. @@ -458,117 +793,347 @@ Threads + + +The #GCond struct is an opaque data structure to represent a +condition. A #GCond is an object, that threads can block on, if they +find a certain condition to be false. If other threads change the +state of this condition they can signal the #GCond, such that the +waiting thread is woken up. + + + + +Using GCond to block a thread until a condition is satisfied + +GCond* data_cond = NULL; /* Must be initialized somewhere */ +GMutex* data_mutex = NULL; /* Must be initialized somewhere */ +gpointer current_data = NULL; + +void push_data (gpointer data) +{ + g_mutex_lock (data_mutex); + current_data = data; + g_cond_signal (data_cond); + g_mutex_unlock (data_mutex); +} + +gpointer pop_data () +{ + gpointer data; + + g_mutex_lock (data_mutex); + while (!current_data) + g_cond_wait (data_cond, data_mutex); + data = current_data; + current_data = NULL; + g_mutex_unlock (data_mutex); + return data; +} + + + + + +Whenever a thread calls pop_data() now, it will wait until +current_data is non-NULL, i.e. until some other thread has called +push_data(). + + + +It is important to use the g_cond_wait() and g_cond_timed_wait() +functions only inside a loop, which checks for the condition to be +true as it is not guaranteed that the waiting thread will find it +fulfilled, even if the signaling thread left the condition +in that state. This is because another thread can have altered the +condition, before the waiting thread got the chance to be woken up, +even if the condition itself is protected by a #GMutex, like above. + + + +A #GCond should only be accessed via the following functions. + + +All of the g_cond_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + - + +Creates a new #GCond. This function will abort, if g_thread_init() +has not been called yet. -@Returns: +@Returns: a new #GCond. +If threads are waiting for @cond, exactly one of them is woken up. It +is good practice to hold the same lock as the waiting thread, while +calling this function, though not required. + + +This function can also be used, if g_thread_init() has +not yet been called and will do nothing then. -@cond: +@cond: a #GCond. + +If threads are waiting for @cond, all of them are woken up. It is good +practice to lock the same mutex as the waiting threads, while calling +this function, though not required. + + +This function can also be used, if g_thread_init() has +not yet been called and will do nothing then. -@cond: +@cond: a #GCond. + +Waits until this thread is woken up on the #GCond. The #GMutex is +unlocked before falling asleep and locked again before resuming. + + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return then. -@cond: -@mutex: +@cond: a #GCond. +@mutex: the #GMutex, that is currently locked. + +Waits until this thread is woken up on the #GCond, but not longer than +until the time, that is specified by @abs_time. The #GMutex is +unlocked before falling asleep and locked again before resuming. + + +If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait(). -@cond: -@mutex: -@abs_time: -@Returns: + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return TRUE then. + + +@cond: a #GCond. +@mutex: the #GMutex, that is currently locked. +@abs_time: a #GTimeVal, determining the final time. +@Returns: TRUE, if the thread is woken up in time. - + +Destroys the #GCond. -@cond: +@cond: a #GCond. +The #GPrivate struct is an opaque data structure to represent a thread +private data key. Threads can thereby obtain and set a pointer, which +is private to the current thread. Take our give_me_next_number() +example from above. Now we don't want current_number to be shared +between the threads, but to be private to each thread. This can be +done as follows: + + +Using GPrivate for per-thread data + + GPrivate* current_number_key = NULL; /* Must be initialized somewhere */ + /* with g_private_new (g_free); */ + + int give_me_next_number () + { + int *current_number = g_private_get (current_number_key); + + if (!current_number) + { + current_number = g_new (int,1); + *current_number = 0; + g_private_set (current_number_key, current_number); + } + *current_number = calc_next_number (*current_number); + return *current_number; + } + + + + + +Here the pointer belonging to the key current_number_key is read. If +it is NULL, it has not been set yet. Then get memory for an integer +value, assign this memory to the pointer and write the pointer +back. Now we have an integer value, that is private to the current +thread. + + + +The #GPrivate struct should only be accessed via the following functions. + + + +All of the g_private_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + +Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer +to a destructor function. Whenever a thread ends and the corresponding +pointer keyed to this instance of #GPrivate is non-NULL, the +destructor is called with this pointer as the argument. + + + +The @destructor is working quite differently from @notify in +g_static_private_set(). + + + + +A #GPrivate can not be destroyed. Reuse it instead, if you can to +avoid shortage. + -@destructor: + + +This function will abort, if g_thread_init() has not been called yet. + + + +@destructor: a function to handle the data keyed to #GPrivate, when a +thread ends. @Returns: + +Returns the pointer keyed to @private_key for the current thread. This +pointer is NULL, when g_private_set() hasn't been called for the +current @private_key and thread yet. + + +This function can also be used, if g_thread_init() has not yet been +called and will return the value of @private_key casted to #gpointer then. -@private_key: -@Returns: +@private_key: a #GPrivate. +@Returns: the corresponding pointer. + +Sets the pointer keyed to @private_key for the current thread. + + +This function can also be used, if g_thread_init() has not yet been +called and will set @private_key to @data casted to #GPrivate* then. -@private_key: -@data: +@private_key: a #GPrivate. +@data: the new pointer. + +@value: + +A #GStaticPrivate works almost like a #GPrivate, but it has one +significant advantage. It doesn't need to be created at run-time like +a #GPrivate, but can be defined at compile-time. This is similar to +the difference between #GMutex and #GStaticMutex. Now look at our +give_me_next_number() example with #GStaticPrivate: + + + +Using GStaticPrivate for per-thread data + + int give_me_next_number () + { + static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; + int *current_number = g_static_private_get (&current_number_key); + + if (!current_number) + { + current_number = g_new (int,1); + *current_number = 0; + g_static_private_set (&current_number_key, current_number, g_free); + } + *current_number = calc_next_number (*current_number); + return *current_number; + } + + @index: +Every #GStaticPrivate must be initialized with this macro, before it can +be used. + + + + +GStaticPrivate my_private = G_STATIC_PRIVATE_INIT; + + +Works like g_private_get() only for a #GStaticPrivate. + + +This function also works, if g_thread_init() has not yet been called. -@private_key: -@Returns: +@private_key: a #GStaticPrivate. +@Returns: the corresponding pointer. @@ -583,12 +1148,29 @@ Threads +Sets the pointer keyed to @private_key for the current thread and the +function @notify to be called with that pointer (NULL or non-NULL), +whenever the pointer is set again or whenever the current thread ends. + + +This function also works, if g_thread_init() has not yet been +called. If g_thread_init() is called later, the @data keyed to +@private_key will be inherited only by the main thread, i.e. the one that +called g_thread_init(). -@private_key: -@data: -@notify: + + +The @notify is working quite differently from @destructor in +g_private_new(). + + + +@private_key: a #GStaticPrivate. +@data: the new pointer. +@notify: a function to be called with the pointer, whenever the +current thread ends or sets this pointer again. diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml index 0a05d6cc8..87cba3791 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/docs/reference/glib/tmpl/timers.sgml @@ -2,11 +2,14 @@ Timers - +functions to time operations. - +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. @@ -16,32 +19,32 @@ Timers - +An opaque data structure which holds the timer information. - +Creates a new timer. -@Returns: +@Returns: the new timer. - +Starts the timer. -@timer: +@timer: the timer. - +Stops the timer. -@timer: +@timer: the timer. @@ -49,24 +52,25 @@ Timers -@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. - +Resets the elapsed time to 0, leaving the timer running. -@timer: +@timer: the timer. - +Destroys the timer, freeing the memory allocated for it. -@timer: +@timer: the timer. diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index c19ab9342..104c66ae2 100644 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ b/docs/reference/glib/tmpl/trees-binary.sgml @@ -2,11 +2,36 @@ Balanced Binary Trees - +a sorted collection of key/value pairs optimised for searching +and traversing in order. - +The #GTree structure and its associated functions provide a sorted collection +of key/value pairs optimised for searching and traversing in order. + + +To create a new #GTree use g_tree_new(). + + +To insert a key/value pair into a #GTree use g_tree_insert(). + + +To lookup the value corresponding to a given key, use g_tree_lookup(). + + +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(). + + +To traverse a #GTree, calling a function for each node visited in the +traversal, use g_tree_traverse(). + + +To remove a key/value pair use g_tree_remove(). + + +To destroy a #GTree, use g_tree_destroy(). @@ -16,93 +41,152 @@ Balanced Binary Trees - +The #GTree struct is an opaque data structure representing a +Balanced Binary Tree. +It should be accessed only by using the following functions. - +Creates a new GTree. -@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 strcmp() +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. - +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.) + + +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. -@tree: -@key: -@value: +@tree: a #GTree. +@key: the key to insert. +@value: the value corresponding to the key. - +Gets the number of nodes in a #GTree. -@tree: -@Returns: +@tree: a #GTree. +@Returns: the number of nodes in the #GTree. - +Gets the height of a #GTree. + + +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. -@tree: -@Returns: +@tree: a #GTree. +@Returns: the height of the #GTree. - +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. -@tree: -@key: -@Returns: +@tree: a #GTree. +@key: the key to look up. +@Returns: the value corresponding to the key. - +Searches a #GTree using an alternative form of the comparison function. + + +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. + + +To search for a specific value, you can use g_tree_traverse(). -@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. - +Calls the given function for each node in the GTree. -@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. - +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. -@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. - +Specifies the type of traveral performed by g_tree_traverse(), +g_node_traverse() and g_node_find(). + + +%G_PRE_ORDER visits a node, then its children. + + +%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. + + +%G_POST_ORDER visits the node's children, then the node itself. + + +%G_LEVEL_ORDER is not implemented for +Balanced Binary Trees. +For N-ary Trees +it calls the function for each child of the node, then it recursively visits +each child. + + @G_IN_ORDER: @@ -112,18 +196,21 @@ Balanced Binary Trees - +Removes a key/value pair from a #GTree. +If the key or value is dynamically allocated you must remember to free them +yourself. -@tree: -@key: +@tree: a #GTree. +@key: the key to remove. - +Destroys the #GTree, freeing all of the memory allocated. +But it doesn't free keys or values. -@tree: +@tree: a #GTree. diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index c994ac61c..2019c861b 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -2,11 +2,46 @@ N-ary Trees - +trees of data with any number of branches. - +The #GNode struct and its associated functions provide a N-ary tree data +structure, where nodes in the tree can contain arbitrary data. + + +To create a new tree use g_node_new(). + + +To insert a node into a tree use g_node_insert(), g_node_insert_before(), +g_node_append() and g_node_prepend(). + + +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(). + + +To reverse the children of a node use g_node_reverse_children(). + + +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(). + + +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(). + + +To traverse a tree, calling a function for each node visited in the +traversal, use g_node_traverse() or g_node_children_foreach(). + + +To remove a node or subtree from a tree use g_node_unlink() or +g_node_destroy(). @@ -16,7 +51,17 @@ N-ary Trees - +The #GNode struct represents one node in a +N-ary Tree. +The data field contains the actual data of the node. +The next and prev +fields point to the node's siblings (a sibling is another #GNode with the +same parent). +The parent field points to the parent of the #GNode, +or is NULL if the #GNode is the root of the tree. +The children field points to the first child of the +#GNode. The other children are accessed by using the +next pointer of each child. @data: @@ -27,11 +72,12 @@ N-ary Trees - +Creates a new #GNode containing the given data. +Used to create the first node in a tree. -@data: -@Returns: +@data: the data of the new node. +@Returns: a new #GNode. @@ -45,107 +91,135 @@ N-ary Trees - +Inserts a #GNode beneath the parent at the given position. -@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. - +Inserts a #GNode beneath the parent before the given sibling. -@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. - +Inserts a #GNode as the last child of the given parent. -@parent: -@node: +@parent: the #GNode to place the new #GNode under. +@node: the #GNode to insert. +@Returns: the inserted #GNode. - +Inserts a #GNode as the first child of the given parent. -@parent: -@node: -@Returns: +@parent: the #GNode to place the new #GNode under. +@node: the #GNode to insert. +@Returns: the inserted #GNode. - +Inserts a new #GNode at the given position. -@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. - +Inserts a new #GNode before the given sibling. -@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. - +Inserts a new #GNode as the last child of the given parent. -@parent: -@data: +@parent: the #GNode to place the new #GNode under. +@data: the data for the new #GNode. +@Returns: the new #GNode. - +Inserts a new #GNode as the first child of the given parent. -@parent: -@data: +@parent: the #GNode to place the new #GNode under. +@data: the data for the new #GNode. +@Returns: the new #GNode. - +Reverses the order of the children of a #GNode. +(It doesn't change the order of the grandchildren.) -@node: +@node: a #GNode. - +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. -@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. - +Specifies which nodes are visited during several of the tree functions, +including g_node_traverse() and g_node_find(). + + +%G_TRAVERSE_LEAFS specifies that only leaf nodes should be visited. + + +%G_TRAVERSE_NON_LEAFS specifies that only non-leaf nodes should be visited. + + +%G_TRAVERSE_ALL specifies that all nodes should be visited. + + @G_TRAVERSE_LEAFS: @@ -155,237 +229,274 @@ N-ary Trees - +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. -@node: -@data: -@Returns: +@node: a #GNode. +@data: user data passed to g_node_traverse(). +@Returns: TRUE to stop the traversal. - +Calls a function for each of the children of a #GNode. +Note that it doesn't descend beneath the child nodes. -@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. - +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(). -@node: -@data: +@node: a #GNode. +@data: user data passed to g_node_children_foreach(). - +Gets the root of a tree. -@node: -@Returns: +@node: a #GNode. +@Returns: the root of the tree. - +Finds a #GNode in a tree. -@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. - +Finds the first child of a #GNode with the given data. -@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. - +Gets the position of the first child of a #GNode which contains the given data. -@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. - +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. -@node: -@child: -@Returns: +@node: a #GNode. +@child: a child of @node. +@Returns: the position of @child with respect to its siblings. - +Gets the first child of a #GNode. -@node: +@node: a #GNode. +@Returns: the last child of @node, or NULL if @node is NULL or has no children. - +Gets the last child of a #GNode. -@node: -@Returns: +@node: a #GNode (must not be NULL). +@Returns: the last child of @node, or NULL if @node has no children. - +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. -@node: -@n: -@Returns: +@node: a #GNode. +@n: the index of the desired child. +@Returns: the child of @node at index @n. - +Gets the first sibling of a #GNode. +This could possibly be the node itself. -@node: -@Returns: +@node: a #GNode. +@Returns: the first sibling of @node. - +Gets the next sibling of a #GNode. -@node: +@node: a #GNode. +@Returns: the next sibling of @node, or NULL if @node is NULL. - +Gets the previous sibling of a #GNode. -@node: +@node: a #GNode. +@Returns: the previous sibling of @node, or NULL if @node is NULL. - +Gets the last sibling of a #GNode. +This could possibly be the node itself. -@node: -@Returns: +@node: a #GNode. +@Returns: the last sibling of @node. - +Returns TRUE if a #GNode is a leaf node. -@node: +@node: a #GNode. +@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children). - +Returns TRUE if a #GNode is the root of a tree. -@node: +@node: a #GNode. +@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent +or siblings). - +Gets the depth of a #GNode. + + +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. -@node: -@Returns: +@node: a #GNode. +@Returns: the depth of the #GNode. - +Gets the number of nodes in a tree. -@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. - +Gets the number of children of a #GNode. -@node: -@Returns: +@node: a #GNode. +@Returns: the number of children of @node. - +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. -@node: -@descendant: -@Returns: +@node: a #GNode. +@descendant: a #GNode. +@Returns: TRUE if @node is an ancestor of @descendant. - +Gets the maximum height of all branches beneath a #GNode. +This is the maximum distance from the #GNode to all leaf nodes. + + +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. -@root: -@Returns: +@root: a #GNode. +@Returns: the maximum height of the tree beneath @root. - +Unlinks a #GNode from a tree, resulting in two separate trees. -@node: +@node: the #GNode to unlink, which becomes the root of a new tree. - +Removes the #GNode and its children from the tree, freeing any memory +allocated. -@root: +@root: the root of the tree/subtree to destroy. - +Sets the allocator to use to allocate #GNode elements. +Use g_node_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GNode elements. - +Restores the previous #GAllocator, used when allocating #GNode elements. diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml index dd4adec70..45138be50 100644 --- a/docs/reference/glib/tmpl/type_conversion.sgml +++ b/docs/reference/glib/tmpl/type_conversion.sgml @@ -2,11 +2,37 @@ Type Conversion Macros - +a portable method for storing #gint & #guint values in #gpointer variables. - +These macros provide a portable method of storing #gint and #guint values in +#gpointer variables. + + +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. + + +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. + + +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. + + +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. + + +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. @@ -16,33 +42,37 @@ Type Conversion Macros - +Converts a #gint to a #gpointer. -@i: +@i: a #gint value. +@Returns: the value converted to a #gpointer. - +Converts a #gpointer to a #gint. -@p: +@p: a #gpointer value. +@Returns: the value converted to a #gint. - +Converts a #guint to a #gpointer. -@u: +@u: a #guint value. +@Returns: the value converted to a #gpointer. - +Converts a #gpointer to a #guint. -@p: +@p: a #gpointer value. +@Returns: the value converted to a #guint. diff --git a/docs/reference/glib/tmpl/types.sgml b/docs/reference/glib/tmpl/types.sgml index 92f5b5471..b3d63a401 100644 --- a/docs/reference/glib/tmpl/types.sgml +++ b/docs/reference/glib/tmpl/types.sgml @@ -2,10 +2,33 @@ Basic Types - +standard GLib types, defined for ease-of-use and portability. +GLib defines a number of commonly used types, which can be divided into +4 groups: + + + +New types which are not part of standard C - #gboolean, #gsize, #gssize. + + + +Integer types which are guaranteed to be the same size across all platforms - +#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64. + + + +Types which are easier to use than their standard C counterparts - +#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. + + + +Types which correspond exactly to standard C types, but are included +for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble. + + @@ -16,154 +39,178 @@ Basic Types - +A standard boolean type. +Variables of this type should only contain the value #TRUE or #FALSE. - +An untyped pointer. +#gpointer looks better and is easier to use than void*. - +An untyped pointer to constant data. +The data pointed to should not be changed. + + +This is typically used in function prototypes to indicate that the +data pointed to will not be altered by the function. - +Corresponds to the standard C char type. - +Corresponds to the standard C unsigned char type. - +Corresponds to the standard C int type. +Values of this type can range from #G_MININT to #G_MAXINT. - +Corresponds to the standard C unsigned int type. - +Corresponds to the standard C short type. +Values of this type can range from #G_MINSHORT to #G_MAXSHORT. - +Corresponds to the standard C unsigned short type. - +Corresponds to the standard C long type. +Values of this type can range from #G_MINLONG to #G_MAXLONG. - +Corresponds to the standard C unsigned long type. - +A signed integer guaranteed to be 8 bits on all platforms. +Values of this type can range from -128 to 127. - +An unsigned integer guaranteed to be 8 bits on all platforms. +Values of this type can range from 0 to 255. - +A signed integer guaranteed to be 16 bits on all platforms. +Values of this type can range from -32,768 to 32,767. - +An unsigned integer guaranteed to be 16 bits on all platforms. +Values of this type can range from 0 to 65,535. - +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. - +An unsigned integer guaranteed to be 32 bits on all platforms. +Values of this type can range from 0 to 4,294,967,295. - +This macro is defined if 64-bit signed and unsigned integers are available +on the platform. - +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. - +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. - +This macro is used to insert 64-bit integer literals into the source code. -@val: +@val: a literal integer value, e.g. 0x1d636b02300a7aa7U. - +Corresponds to the standard C float type. +Values of this type can range from #G_MINFLOAT to #G_MAXFLOAT. - +Corresponds to the standard C double type. +Values of this type can range from #G_MINDOUBLE to #G_MAXDOUBLE. - +An unsigned 32-bit integer intended to represent sizes of data structures. - +A signed 32-bit integer intended to represent sizes of data structures. diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index 451d3290d..edd9ab2b3 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -1,12 +1,12 @@ -Warnings and Assertions +Message Output and Debugging Functions - +functions to output messages and help debug applications. - +These functions provide support for outputting messages. @@ -16,63 +16,94 @@ Warnings and Assertions - +Outputs a formatted message via the print handler. +The default print handler simply outputs the message to stdout. + + +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(). -@format: -@Varargs: +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. - +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. -@func: -@Returns: +@func: the new print handler. +@Returns: the old print handler. - +Specifies the type of the print handler functions. +These are called with the complete formatted string to output. -@string: +@string: the message to be output. - +Outputs a formatted message via the error message handler. +The default handler simply outputs the message to stderr. + + +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(). -@format: -@Varargs: +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. - +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. -@func: -@Returns: +@func: the new error message handler. +@Returns: the old error message handler. - +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. -@expr: +@expr: the expression to check. - +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. -@expr: -@val: +@expr: the expression to check. +@val: the value to return from the current function if the expression is not +true. @@ -92,38 +123,79 @@ Warnings and Assertions - +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. + + +The macro can be turned off in final releases of code by defining +G_DISABLE_ASSERT when compiling the application. -@expr: +@expr: the expression to check. - +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. + + +The macro can be turned off in final releases of code by defining +G_DISABLE_ASSERT when compiling the application. - +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? + + +If Exit is selected, the application terminates with a call to +_exit(0). + + +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). + + +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. + + +If Proceed is selected, the function returns. + + +This function may cause different actions on non-unix platforms. -@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). - +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. + + +This function may cause different actions on non-unix platforms. -@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). - +Inserts a breakpoint instruction into the code (on x86 machines only). diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml index e07c6a839..e4118b87b 100644 --- a/docs/reference/glib/tmpl/windows.sgml +++ b/docs/reference/glib/tmpl/windows.sgml @@ -2,11 +2,23 @@ Windows Compatability Functions - +functions to support portability to the Windows environment. - +These functions and macros are provided in the GLib library when compiled +on the Windows platform. + + +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. + + +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. diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am index 532774d23..3e4d9c9c4 100644 --- a/docs/reference/gobject/Makefile.am +++ b/docs/reference/gobject/Makefile.am @@ -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 -- 2.11.4.GIT