Commit a5c0df55 authored by Owen Taylor's avatar Owen Taylor Committed by Owen Taylor

Some further makefile improvement.

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

        * Some further makefile improvement.

	* Restore all the docs that mysteriously vanished earlier.
parent 29b65294
Thu Sep 7 12:35:35 2000 Owen Taylor <otaylor@redhat.com>
* Some further makefile improvement.
* Restore all the docs that mysteriously vanished earlier.
Wed Sep 6 10:59:45 2000 Owen Taylor <otaylor@redhat.com>
* gobject/Makefile.am glib/Makefile.am: Improve
......
......@@ -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
......
......@@ -110,6 +110,13 @@ CLAMP
G_STRUCT_MEMBER
G_STRUCT_MEMBER_P
G_STRUCT_OFFSET
<SUBSECTION Private>
glib_major_version
glib_micro_version
glib_minor_version
glib_interface_age
glib_binary_age
</SECTION>
<SECTION>
......@@ -466,6 +473,9 @@ G_LOCK_NAME
glib_dummy_decl
GSystemThread
g_thread_error_quark
g_thread_use_default_impl
g_threads_got_initialized
g_thread_functions_for_glib_use
</SECTION>
<SECTION>
......
......@@ -2,11 +2,31 @@
Memory Allocators
<!-- ##### SECTION Short_Description ##### -->
allocates chunks of memory for #GList, #GSList and #GNode.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GAllocator is used as an efficient way to allocate small pieces of
memory for use with the #GList, #GSList and #GNode data structures.
It uses a #GMemChunk so elements are allocated in groups, rather than
individually.
</para>
<para>
The #GList, #GSList and #GNode implementations create default #GAllocator
objects, which are probably sufficient for most purposes. These default
allocators use blocks of 128 elements.
</para>
<para>
To use your own #GAllocator, create it with g_allocator_new(). Then
use g_list_push_allocator(), g_slist_push_allocator() or
g_node_push_allocator() before any code which allocates new #GList, #GSList
or #GNode elements respectively. After allocating the new elements, you must
use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator()
to restore the previous allocators.
</para>
<para>
Note that you cannot use the same allocator for #GList, #GSList and #GNode
elements. Each must use separate allocators.
</para>
<!-- ##### SECTION See_Also ##### -->
......@@ -16,25 +36,30 @@ Memory Allocators
<!-- ##### STRUCT GAllocator ##### -->
<para>
The #GAllocator struct contains private data. and should only be accessed
using the following functions.
</para>
<!-- ##### FUNCTION g_allocator_new ##### -->
<para>
Creates a new #GAllocator.
</para>
@name:
@n_preallocs:
@Returns:
@name: the name of the #GAllocator. This name is used to set the name of the
#GMemChunk used by the #GAllocator, and is only used for debugging.
@n_preallocs: the number of elements in each block of memory allocated.
Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
@Returns: a new #GAllocator.
<!-- ##### FUNCTION g_allocator_free ##### -->
<para>
Frees all of the memory allocated by the #GAllocator.
</para>
@allocator:
@allocator: a #GAllocator.
......@@ -2,12 +2,53 @@
Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of arbitrary elements which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
Arrays are similar to standard C arrays, except that they grow automatically
as elements are added.
</para>
<para>
Array elements can be of any size (though all elements of one array are the
same size), and the array can be automatically cleared to '0's and
zero-terminated.
</para>
<para>
To create a new array use g_array_new().
</para>
<para>
To add elements to an array, use g_array_append_val(), g_array_append_vals(),
g_array_prepend_val(), and g_array_prepend_vals().
</para>
<para>
To access an element of an array, use g_array_index().
</para>
<para>
To set the size of an array, use g_array_set_size().
</para>
<para>
To free an array, use g_array_free().
</para>
<example>
<title>Using a GArray to store gint values.</title>
<programlisting>
GArray *garray;
gint i;
/* We create a new array to store gint values.
We don't want it zero-terminated or cleared to 0's. */
garray = g_array_new (FALSE, FALSE, sizeof (gint));
for (i = 0; i < 10000; i++)
g_array_append_val (garray, i);
for (i = 0; i < 10000; i++)
if (g_array_index (garray, gint, i) != i)
g_print ("ERROR: got %d instead of %d\n",
g_array_index (garray, gint, i), i);
g_array_free (garray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
......@@ -16,21 +57,24 @@ Arrays
<!-- ##### STRUCT GArray ##### -->
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
</para>
@data:
@len:
@data: a pointer to the element data. The data may be moved as elements are
added to the #GArray.
@len: the number of elements in the #GArray.
<!-- ##### FUNCTION g_array_new ##### -->
<para>
Creates a new #GArray.
</para>
@zero_terminated:
@clear:
@element_size:
@Returns:
@zero_terminated: TRUE if the array should have an extra element at the end
which is set to '0'.
@clear: TRUE if #GArray elements should be automatically cleared to '0'
when they are allocated.
@element_size: the size of each element in bytes.
@Returns: the new #GArray.
<!-- ##### FUNCTION g_array_sized_new ##### -->
......@@ -47,113 +91,166 @@ Arrays
<!-- ##### MACRO g_array_append_val ##### -->
<para>
Adds the value on to the end of the array.
The array will grow in size automatically if necessary.
</para>
<note>
<para>
g_array_append_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@v:
@a: a #GArray.
@v: the value to append to the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_append_vals ##### -->
<para>
Adds @len elements onto the end of the array.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GArray.
@data: a pointer to the elements to append to the end of the array.
@len: the number of elements to append.
@Returns: the #GArray.
<!-- ##### MACRO g_array_prepend_val ##### -->
<para>
Adds the value on to the start of the array.
The array will grow in size automatically if necessary.
</para>
<para>
This operation is slower than g_array_append_val() since the existing elements
in the array have to be moved to make space for the new element.
</para>
<note>
<para>
g_array_prepend_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@v:
@a: a #GArray.
@v: the value to prepend to the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_prepend_vals ##### -->
<para>
Adds @len elements onto the start of the array.
</para>
<para>
This operation is slower than g_array_append_vals() since the existing elements
in the array have to be moved to make space for the new elements.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GArray.
@data: a pointer to the elements to prepend to the start of the array.
@len: the number of elements to prepend.
@Returns: the #GArray.
<!-- ##### MACRO g_array_insert_val ##### -->
<para>
Inserts an element into an array at the given index.
</para>
<note>
<para>
g_array_insert_val() is a macro which uses a reference to the value
parameter @v. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note>
@a:
@i:
@v:
@a: a #GArray.
@i: the index to place the element at.
@v: the value to insert into the array.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_insert_vals ##### -->
<para>
Inserts @len elements into a #GArray at the given index.
</para>
@array:
@index:
@data:
@len:
@Returns:
@array: a #GArray.
@index: the index to place the elements at.
@data: a pointer to the elements to insert.
@len: the number of elements to insert.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index ##### -->
<para>
Removes the element at the given index from a #GArray.
The following elements are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GArray.
@index: the index of the element to remove.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index_fast ##### -->
<para>
Removes the element at the given index from a #GArray.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the #GArray. But it is faster than
g_array_remove_index().
</para>
@array:
@index:
@Returns:
@array: a @GArray.
@index: the index of the element to remove.
@Returns: the #GArray.
<!-- ##### MACRO g_array_index ##### -->
<para>
Returns the element of a #GArray at the given index.
The return value is cast to the given type.
<example>
<title>Getting a pointer to an element in a GArray.</title>
<programlisting>
EDayViewEvent *event;
/* This gets a pointer to the 3rd element in the array of EDayViewEvent
structs. */
event = &amp;g_array_index (events, EDayViewEvent, 3);
</programlisting>
</example>
</para>
@a:
@t:
@i:
@a: a #GArray.
@t: the type of the elements.
@i: the index of the element to return.
@Returns: the element of the #GArray at the index given by @i.
<!-- ##### FUNCTION g_array_set_size ##### -->
<para>
Sets the size of the array, expanding it if necessary.
If the array was created with clear set to TRUE, the new elements are set to 0.
</para>
@array:
@length:
@Returns:
@array: a #GArray.
@length: the new size of the #GArray.
@Returns: the #GArray.
<!-- ##### FUNCTION g_array_free ##### -->
<para>
Frees the memory allocated for the #GArray.
If free_segment is TRUE it frees the actual element data as well.
</para>
@array:
@free_segment:
@array: a #GArray.
@free_segment: if TRUE the actual element data is freed as well.
@Returns:
......@@ -2,13 +2,48 @@
Byte Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of bytes, which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
GByteArray is based on #GArray, to provide arrays of bytes which grow
automatically as elements are added.
</para>
<para>
To create a new #GByteArray use g_byte_array_new().
</para>
<para>
To add elements to a #GByteArray, use g_byte_array_append(), and
g_byte_array_prepend().
</para>
<para>
To set the size of a GByteArray, use g_byte_array_set_size().
</para>
<para>
To free a GByteArray, use g_byte_array_free().
</para>
<example>
<title>Using a GByteArray.</title>
<programlisting>
GByteArray *gbarray;
gint i;
gbarray = g_byte_array_new ();
for (i = 0; i < 10000; i++)
g_byte_array_append (gbarray, (guint8*) "abcd", 4);
for (i = 0; i < 10000; i++)
{
g_assert (gbarray->data[4*i] == 'a');
g_assert (gbarray->data[4*i+1] == 'b');
g_assert (gbarray->data[4*i+2] == 'c');
g_assert (gbarray->data[4*i+3] == 'd');
}
g_byte_array_free (gbarray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
......@@ -16,18 +51,19 @@ Byte Arrays
<!-- ##### STRUCT GByteArray ##### -->
<para>
The #GByteArray struct allows access to the public fields of a #GByteArray.
</para>
@data:
@len:
@data: a pointer to the element data. The data may be moved as elements are
added to the #GByteArray.
@len: the number of elements in the #GByteArray.
<!-- ##### FUNCTION g_byte_array_new ##### -->
<para>
Creates a new #GByteArray.
</para>
@Returns:
@Returns: the new #GByteArray.
<!-- ##### FUNCTION g_byte_array_sized_new ##### -->
......@@ -41,63 +77,70 @@ Byte Arrays
<!-- ##### FUNCTION g_byte_array_append ##### -->
<para>
Adds the given bytes to the end of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_prepend ##### -->
<para>
Adds the given data to the start of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@len:
@Returns:
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The following bytes are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GByteArray.
@index: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the #GByteArray. But it is faster than
g_byte_array_remove_index().
</para>
@array:
@index:
@Returns:
@array: a #GByteArray.
@index: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
<para>
Sets the size of the #GByteArray, expanding it if necessary.
</para>
@array:
@length:
@Returns:
@array: a #GByteArray.
@length: the new size of the #GByteArray.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
Frees the memory allocated by the #GByteArray.
If free_segment is TRUE it frees the actual byte data.
</para>
@array:
@free_segment:
@array: a #GByteArray.
@free_segment: if TRUE the actual byte data is freed as well.
@Returns:
......@@ -2,12 +2,58 @@
Pointer Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of pointers to any type of data, which grow automatically as new
elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
Pointer Arrays are similar to Arrays but are used only for storing pointers.
</para>
<note>
<para>
If you remove elements from the array, elements at the end of the array
are moved into the space previously occupied by the removed element.
This means that you should not rely on the index of particular elements
remaining the same. You should also be careful when deleting elements while
iterating over the array.
</para>
</note>
<para>
To create a pointer array, use g_ptr_array_new().
</para>
<para>
To add elements to a pointer array, use g_ptr_array_add().
</para>
<para>
To remove elements from a pointer array, use g_ptr_array_remove(),
g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
</para>
<para>
To access an element of a pointer array, use g_ptr_array_index().
</para>
<para>
To set the size of a pointer array, use g_ptr_array_set_size().
</para>
<para>
To free a pointer array, use g_ptr_array_free().
</para>
<example>
<title>Using a GPtrArray.</title>
<programlisting>
GPtrArray *gparray;
gchar *string1 = "one", *string2 = "two", *string3 = "three";
gparray = g_ptr_array_new ();
g_ptr_array_add (gparray, (gpointer) string1);
g_ptr_array_add (gparray, (gpointer) string2);
g_ptr_array_add (gparray, (gpointer) string3);
if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
g_print ("ERROR: got %p instead of %p\n",
g_ptr_array_index (gparray, 0), string1);
g_ptr_array_free (gparray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
......@@ -16,7 +62,11 @@ Pointer Arrays
<!-- ##### STRUCT GPtrArray ##### -->
<para>
Contains the public fields of a pointer array.
The <structfield>pdata</structfield> field points to the array of pointers,
which may as when the array grows.
The <structfield>len</structfield> field is the number of pointers in the
array.
</para>
@pdata:
......@@ -24,10 +74,10 @@ Pointer Arrays
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>
Creates a new #GPtrArray.
</para>
@Returns:
@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
......@@ -41,78 +91,98 @@ Pointer Arrays
<!-- ##### FUNCTION g_ptr_array_add ##### -->
<para>
Adds a pointer to the end of the pointer array.
The array will grow in size automatically if necessary.
</para>
@array:
@data:
@array: a #GPtrArray.
@data: the pointer to add.
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The following elements are moved down one place.
</para>
<para>
It returns TRUE if the pointer was removed, or FALSE if the pointer
was not found.
</para>
@array:
@data:
@Returns:
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
<para>
Removes the pointer at the given index from the pointer array.
The following elements are moved down one place.
</para>
@array:
@index:
@Returns:
@array: a #GPtrArray.
@index: the index of the pointer to remove.
@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
g_ptr_array_remove().
</para>
<para>
It returns TRUE if the pointer was removed, or FALSE if the pointer
was not found.
</para>
@array:
@data:
@Returns:
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: TRUE if the pointer was found in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
<para>
Removes the pointer at the given index from the pointer array.