mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-04 10:16:17 +01:00
glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml
glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml, glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml, glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml: Markup fixes and a few additions.
This commit is contained in:
Matthias Clasen
parent
d398a176e1
commit
abf9f5f8f8
@ -1,3 +1,12 @@
|
||||
2001-09-30 Matthias Clasen <matthiasc@poet.de>
|
||||
|
||||
* glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml
|
||||
glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml,
|
||||
glib/tmpl/datalist.sgml, glib/tmpl/date.sgml,
|
||||
glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml,
|
||||
glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml:
|
||||
Markup fixes and a few additions.
|
||||
|
||||
2001-09-27 Matthias Clasen <matthiasc@poet.de>
|
||||
|
||||
* glib/tmpl/macros.sgml, glib/tmpl/macros_misc.sgml,
|
||||
|
||||
@ -69,9 +69,9 @@ added to the #GArray.
|
||||
Creates a new #GArray.
|
||||
</para>
|
||||
|
||||
@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'
|
||||
@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.
|
||||
@ -85,11 +85,11 @@ add many elements to the array. Note however that the size of the
|
||||
array is still 0.
|
||||
</para>
|
||||
|
||||
@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared
|
||||
@clear: %TRUE if all bits in the array should be cleared to 0 on allocation
|
||||
@element_size: size of each element in the array
|
||||
@reserved_size: number of elements preallocated
|
||||
@Returns: the new #GArray
|
||||
@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared.
|
||||
@clear: %TRUE if all bits in the array should be cleared to 0 on allocation.
|
||||
@element_size: size of each element in the array.
|
||||
@reserved_size: number of elements preallocated.
|
||||
@Returns: the new #GArray.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_array_append_val ##### -->
|
||||
@ -214,13 +214,13 @@ g_array_remove_index().
|
||||
|
||||
<!-- ##### FUNCTION g_array_sort ##### -->
|
||||
<para>
|
||||
Sorts a #GArray using @compare_func which should be a qsort()-style comparison
|
||||
Sorts a #GArray using @compare_func which should be a <function>qsort()</function>-style comparison
|
||||
function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
|
||||
first arg is greater than second arg).
|
||||
</para>
|
||||
|
||||
@array: a #GArray
|
||||
@compare_func: comparison function
|
||||
@array: a #GArray.
|
||||
@compare_func: comparison function.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_array_sort_with_data ##### -->
|
||||
@ -229,9 +229,9 @@ Like g_array_sort(), but the comparison function receives a user data
|
||||
argument.
|
||||
</para>
|
||||
|
||||
@array: a #GArray
|
||||
@compare_func: a comparison function
|
||||
@user_data: data to pass to @compare_func
|
||||
@array: a #GArray.
|
||||
@compare_func: comparison function.
|
||||
@user_data: data to pass to @compare_func.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_array_index ##### -->
|
||||
@ -260,7 +260,7 @@ The return value is cast to the given type.
|
||||
<!-- ##### 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.
|
||||
If the array was created with @clear set to %TRUE, the new elements are set to 0.
|
||||
</para>
|
||||
|
||||
@array: a #GArray.
|
||||
@ -271,11 +271,10 @@ If the array was created with clear set to TRUE, the new elements are set to 0.
|
||||
<!-- ##### 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.
|
||||
If @free_segment is %TRUE it frees the actual element data as well.
|
||||
</para>
|
||||
|
||||
@array: a #GArray.
|
||||
@free_segment: if TRUE the actual element data is freed as well.
|
||||
@Returns:
|
||||
@free_segment: if %TRUE the actual element data is freed as well.
|
||||
|
||||
|
||||
|
||||
@ -73,8 +73,8 @@ avoids frequent reallocation, if you are going to add many bytes to
|
||||
the array. Note however that the size of the array is still 0.
|
||||
</para>
|
||||
|
||||
@reserved_size: number of bytes preallocated
|
||||
@Returns: the new #GByteArray
|
||||
@reserved_size: number of bytes preallocated.
|
||||
@Returns: the new #GByteArray.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_byte_array_append ##### -->
|
||||
@ -127,13 +127,13 @@ g_byte_array_remove_index().
|
||||
|
||||
<!-- ##### FUNCTION g_byte_array_sort ##### -->
|
||||
<para>
|
||||
Sorts a byte array, using @compare_func which should be a qsort()-style
|
||||
Sorts a byte array, using @compare_func which should be a <function>qsort()</function>-style
|
||||
comparison function (returns -1 for first arg is less than second arg, 0 for
|
||||
equal, 1 if first arg is greater than second arg).
|
||||
</para>
|
||||
|
||||
@array: array to sort
|
||||
@compare_func: comparison function
|
||||
@array: a #GByteArray.
|
||||
@compare_func: comparison function.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
|
||||
@ -141,9 +141,9 @@ equal, 1 if first arg is greater than second arg).
|
||||
Like g_byte_array_sort(), but the comparison function takes a user data argument.
|
||||
</para>
|
||||
|
||||
@array: a #GByteArray
|
||||
@compare_func: comparison function
|
||||
@user_data: data to pass to @compare_func
|
||||
@array: a #GByteArray.
|
||||
@compare_func: comparison function.
|
||||
@user_data: data to pass to @compare_func.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
|
||||
@ -159,11 +159,10 @@ Sets the size of the #GByteArray, expanding it if necessary.
|
||||
<!-- ##### FUNCTION g_byte_array_free ##### -->
|
||||
<para>
|
||||
Frees the memory allocated by the #GByteArray.
|
||||
If free_segment is TRUE it frees the actual byte data.
|
||||
If free_segment is %TRUE it frees the actual byte data.
|
||||
</para>
|
||||
|
||||
@array: a #GByteArray.
|
||||
@free_segment: if TRUE the actual byte data is freed as well.
|
||||
@Returns:
|
||||
@free_segment: if %TRUE the actual byte data is freed as well.
|
||||
|
||||
|
||||
|
||||
@ -108,13 +108,13 @@ 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
|
||||
It returns %TRUE if the pointer was removed, or %FALSE if the pointer
|
||||
was not found.
|
||||
</para>
|
||||
|
||||
@array: a #GPtrArray.
|
||||
@data: the pointer to remove.
|
||||
@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
|
||||
@Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found
|
||||
in the array.
|
||||
|
||||
|
||||
@ -137,13 +137,13 @@ 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
|
||||
It returns %TRUE if the pointer was removed, or %FALSE if the pointer
|
||||
was not found.
|
||||
</para>
|
||||
|
||||
@array: a #GPtrArray.
|
||||
@data: the pointer to remove.
|
||||
@Returns: TRUE if the pointer was found in the array.
|
||||
@Returns: %TRUE if the pointer was found in the array.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
|
||||
@ -161,13 +161,13 @@ g_ptr_array_remove_index().
|
||||
|
||||
<!-- ##### FUNCTION g_ptr_array_sort ##### -->
|
||||
<para>
|
||||
Sorts the array, using @compare_func which should be a qsort()-style comparison
|
||||
Sorts the array, using @compare_func which should be a <function>qsort()</function>-style comparison
|
||||
function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
|
||||
first arg is greater than second arg).
|
||||
</para>
|
||||
|
||||
@array: array to sort
|
||||
@compare_func: comparison function
|
||||
@array: a #GPtrArray.
|
||||
@compare_func: comparison function.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
|
||||
@ -175,15 +175,15 @@ first arg is greater than second arg).
|
||||
Like g_ptr_array_sort(), but the comparison function has a user data argument.
|
||||
</para>
|
||||
|
||||
@array: array to sort
|
||||
@compare_func: qsort()-style comparison function
|
||||
@user_data: data to pass to @compare_func
|
||||
@array: a #GPtrArray.
|
||||
@compare_func: comparison function.
|
||||
@user_data: data to pass to @compare_func.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
|
||||
<para>
|
||||
Sets the size of the array, expanding it if necessary.
|
||||
New elements are set to NULL.
|
||||
New elements are set to %NULL.
|
||||
</para>
|
||||
|
||||
@array: a #GPtrArray.
|
||||
@ -206,7 +206,6 @@ Frees all of the memory allocated for the pointer array.
|
||||
</para>
|
||||
|
||||
@array: a #GPtrArray.
|
||||
@free_seg: if TRUE the actual element data is freed as well.
|
||||
@Returns:
|
||||
@free_seg: if %TRUE the actual element data is freed as well.
|
||||
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
Caches
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
allows sharing of complex data structures to save resources.
|
||||
caches allow sharing of complex data structures to save resources.
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
@ -35,7 +35,7 @@ a #GCache. It should only be accesssed via the following functions.
|
||||
|
||||
<!-- ##### FUNCTION g_cache_new ##### -->
|
||||
<para>
|
||||
Creates a new GCache.
|
||||
Creates a new #GCache.
|
||||
</para>
|
||||
|
||||
@value_new_func: a function to create a new object given a key.
|
||||
@ -45,17 +45,15 @@ does not already exist.
|
||||
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.
|
||||
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_equal_func: a function to compare two keys. It should return TRUE if
|
||||
@key_equal_func: a function to compare two keys. It should return %TRUE if
|
||||
the two keys are equivalent.
|
||||
@Returns: a new #GCache.
|
||||
<!-- # Unused Parameters # -->
|
||||
@key_compare_func:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cache_insert ##### -->
|
||||
@ -96,7 +94,7 @@ Note that it does not destroy the keys and values which were contained in the
|
||||
GCache.
|
||||
</para>
|
||||
|
||||
@cache:
|
||||
@cache: a #GCache.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cache_key_foreach ##### -->
|
||||
@ -133,11 +131,11 @@ should free any memory and other resources associated with it.
|
||||
<!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of the @key_dup_func function passed to g_cache_new().
|
||||
The function is passed a key (NOT a value as the prototype implies) and
|
||||
The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
|
||||
should return a duplicate of the key.
|
||||
</para>
|
||||
|
||||
@value: the #GCache key to destroy (NOT a #GCache value as it seems).
|
||||
@value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
|
||||
@Returns: a copy of the #GCache key.
|
||||
|
||||
|
||||
|
||||
@ -10,8 +10,8 @@ Keyed data lists provide lists of arbitrary data elements which can be accessed
|
||||
either with a string or with a #GQuark corresponding to the string.
|
||||
</para>
|
||||
<para>
|
||||
The GQuark methods are quicker, since the strings have to be converted to
|
||||
GQuarks anyway.
|
||||
The #GQuark methods are quicker, since the strings have to be converted to
|
||||
#GQuarks anyway.
|
||||
</para>
|
||||
<para>
|
||||
Data lists are used in GTK for associating arbitrary data with
|
||||
@ -56,7 +56,7 @@ It should only be accessed via the following functions.
|
||||
|
||||
<!-- ##### FUNCTION g_datalist_init ##### -->
|
||||
<para>
|
||||
Resets the datalist to NULL.
|
||||
Resets the datalist to %NULL.
|
||||
It does not free any memory or call any destroy functions.
|
||||
</para>
|
||||
|
||||
@ -98,7 +98,7 @@ Gets a data element.
|
||||
|
||||
@datalist: a datalist.
|
||||
@key_id: the #GQuark identifying a data element.
|
||||
@Returns: the data element, or NULL if it is not found.
|
||||
@Returns: the data element, or %NULL if it is not found.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_datalist_id_remove_data ##### -->
|
||||
@ -117,7 +117,7 @@ Removes an element, without calling its destroy notification function.
|
||||
|
||||
@datalist: a datalist.
|
||||
@key_id: the #GQuark identifying a data element.
|
||||
@Returns: the data previously stored at @key_id, or %NULL if none
|
||||
@Returns: the data previously stored at @key_id, or %NULL if none.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_datalist_set_data ##### -->
|
||||
@ -153,7 +153,7 @@ converted to a #GQuark.
|
||||
|
||||
@dl: a datalist.
|
||||
@k: the string identifying a data element.
|
||||
@Returns: the data element, or NULL if it is not found.
|
||||
@Returns: the data element, or %NULL if it is not found.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_datalist_remove_data ##### -->
|
||||
|
||||
@ -94,7 +94,7 @@ Gets the data element corresponding to a #GQuark.
|
||||
|
||||
@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
|
||||
@Returns: the data element corresponding to the #GQuark, or %NULL if it is
|
||||
not found.
|
||||
|
||||
|
||||
@ -149,7 +149,7 @@ Gets the data element corresponding to a string.
|
||||
|
||||
@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
|
||||
@Returns: the data element corresponding to the string, or %NULL if it is not
|
||||
found.
|
||||
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -87,7 +87,7 @@ Specifies the type of the hash function which is passed to
|
||||
g_hash_table_new() when a #GHashTable is created.
|
||||
</para>
|
||||
<para>
|
||||
The function is passed a key and should return a guint hash value.
|
||||
The 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.
|
||||
@ -108,13 +108,13 @@ lookup.
|
||||
<!-- ##### USER_FUNCTION GEqualFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of a function used to test two values for
|
||||
equality. The function should return TRUE if both values are equal and
|
||||
FALSE otherwise.
|
||||
equality. The function should return %TRUE if both values are equal and
|
||||
%FALSE otherwise.
|
||||
</para>
|
||||
|
||||
@a: a value.
|
||||
@b: a value to compare with.
|
||||
@Returns: TRUE if @a = @b; FALSE otherwise.
|
||||
@Returns: %TRUE if @a = @b; %FALSE otherwise.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_hash_table_insert ##### -->
|
||||
@ -237,14 +237,14 @@ which is passed to g_hash_table_foreach().
|
||||
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
|
||||
It should return %TRUE if the key/value pair should be removed from the
|
||||
#GHashTable.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
@Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_hash_table_freeze ##### -->
|
||||
@ -275,14 +275,14 @@ This function is deprecated and will be removed in the next major
|
||||
|
||||
<!-- ##### FUNCTION g_direct_equal ##### -->
|
||||
<para>
|
||||
Compares two #gpointer arguments and returns TRUE if they are equal.
|
||||
Compares two #gpointer arguments and returns %TRUE if they are equal.
|
||||
It can be passed to g_hash_table_new() as the @key_equal_func
|
||||
parameter, when using pointers as keys in a #GHashTable.
|
||||
</para>
|
||||
|
||||
@v: a key.
|
||||
@v2: a key to compare with @v.
|
||||
@Returns: TRUE if the two keys match.
|
||||
@Returns: %TRUE if the two keys match.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_direct_hash ##### -->
|
||||
@ -298,7 +298,7 @@ using gpointer values as keys in a #GHashTable.
|
||||
|
||||
<!-- ##### FUNCTION g_int_equal ##### -->
|
||||
<para>
|
||||
Compares the two #gint values being pointed to and returns TRUE if they are
|
||||
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_equal_func
|
||||
parameter, when using pointers to integers as keys in a #GHashTable.
|
||||
@ -306,14 +306,14 @@ parameter, when using pointers to integers as keys in a #GHashTable.
|
||||
|
||||
@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.
|
||||
@Returns: %TRUE if the two keys match.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_int_hash ##### -->
|
||||
<para>
|
||||
Converts a pointer to a #gint to a hash value.
|
||||
It can be passed to g_hash_table_new() as the @hash_func parameter, when
|
||||
using pointers to gint values as keys in a #GHashTable.
|
||||
using pointers to #gint values as keys in a #GHashTable.
|
||||
</para>
|
||||
|
||||
@v: a pointer to a #gint key.
|
||||
@ -322,14 +322,14 @@ using pointers to gint values as keys in a #GHashTable.
|
||||
|
||||
<!-- ##### FUNCTION g_str_equal ##### -->
|
||||
<para>
|
||||
Compares two strings and returns TRUE if they are equal.
|
||||
Compares two strings and returns %TRUE if they are equal.
|
||||
It can be passed to g_hash_table_new() as the @key_equal_func
|
||||
parameter, when using strings as keys in a #GHashTable.
|
||||
</para>
|
||||
|
||||
@v: a key.
|
||||
@v2: a key to compare with @v.
|
||||
@Returns: TRUE if the two keys match.
|
||||
@Returns: %TRUE if the two keys match.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_str_hash ##### -->
|
||||
|
||||
@ -22,87 +22,72 @@ This also means that there is no need to check if the call succeeded.
|
||||
|
||||
<!-- ##### MACRO g_new ##### -->
|
||||
<para>
|
||||
Allocates @count elements of type @type.
|
||||
Allocates @n_structs elements of type @struct_type.
|
||||
The returned pointer is cast to a pointer to the given type.
|
||||
If @count is 0 it returns NULL.
|
||||
If @count is 0 it returns %NULL.
|
||||
</para>
|
||||
|
||||
@struct_type:
|
||||
@n_structs:
|
||||
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
|
||||
<!-- # Unused Parameters # -->
|
||||
@type: the type of the elements to allocate.
|
||||
@count: the number of elements to allocate.
|
||||
@struct_type: the type of the elements to allocate.
|
||||
@n_structs: the number of elements to allocate.
|
||||
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_new0 ##### -->
|
||||
<para>
|
||||
Allocates @count elements of type @type, initialized to 0's.
|
||||
Allocates @n_structs elements of type @struct_type, initialized to 0's.
|
||||
The returned pointer is cast to a pointer to the given type.
|
||||
If @count is 0 it returns NULL.
|
||||
If @count is 0 it returns %NULL.
|
||||
</para>
|
||||
|
||||
@struct_type:
|
||||
@n_structs:
|
||||
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
|
||||
<!-- # Unused Parameters # -->
|
||||
@type: the type of the elements to allocate.
|
||||
@count: the number of elements to allocate.
|
||||
@struct_type: the type of the elements to allocate.
|
||||
@n_structs: the number of elements to allocate.
|
||||
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_renew ##### -->
|
||||
<para>
|
||||
Reallocates the memory pointed to by @mem, so that it now has space for
|
||||
@count elements of type @type. It returns the new address of the memory,
|
||||
which may have been moved.
|
||||
@n_struct elements of type @struct_type. It returns the new address of
|
||||
the memory, which may have been moved.
|
||||
</para>
|
||||
|
||||
@struct_type:
|
||||
@struct_type: the type of the elements to allocate.
|
||||
@mem: the currently allocated memory.
|
||||
@n_structs:
|
||||
@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
|
||||
<!-- # Unused Parameters # -->
|
||||
@type: the type of the elements to allocate.
|
||||
@count: the number of elements to allocate.
|
||||
@n_structs: the number of elements to allocate.
|
||||
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_malloc ##### -->
|
||||
<para>
|
||||
Allocates @size bytes of memory.
|
||||
If @size is 0 it returns NULL.
|
||||
Allocates @n_bytes bytes of memory.
|
||||
If @n_bytes is 0 it returns %NULL.
|
||||
</para>
|
||||
|
||||
@n_bytes:
|
||||
@n_bytes: the number of bytes to allocate.
|
||||
@Returns: a pointer to the allocated memory.
|
||||
<!-- # Unused Parameters # -->
|
||||
@size: the number of bytes to allocate.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_malloc0 ##### -->
|
||||
<para>
|
||||
Allocates @size bytes of memory, initialized to 0's.
|
||||
If @size is 0 it returns NULL.
|
||||
Allocates @n_bytes bytes of memory, initialized to 0's.
|
||||
If @n_bytes is 0 it returns %NULL.
|
||||
</para>
|
||||
|
||||
@n_bytes:
|
||||
@n_bytes: the number of bytes to allocate.
|
||||
@Returns: a pointer to the allocated memory.
|
||||
<!-- # Unused Parameters # -->
|
||||
@size: the number of bytes to allocate.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_realloc ##### -->
|
||||
<para>
|
||||
Reallocates the memory pointed to by @mem, so that it now has space for
|
||||
@size bytes of memory. It returns the new address of the memory, which may
|
||||
@n_bytes bytes of memory. It returns the new address of the memory, which may
|
||||
have been moved. @mem may be %NULL, in which case it's considered to
|
||||
have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
|
||||
</para>
|
||||
|
||||
@mem: the memory to reallocate.
|
||||
@n_bytes: new size of the memory in bytes
|
||||
@n_bytes: new size of the memory in bytes.
|
||||
@Returns: the new address of the allocated memory.
|
||||
<!-- # Unused Parameters # -->
|
||||
@size: the new size of the allocated memory, in bytes.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_try_malloc ##### -->
|
||||
@ -111,8 +96,8 @@ Attempts to allocate @n_bytes, and returns %NULL on failure.
|
||||
Contrast with g_malloc(), which aborts the program on failure.
|
||||
</para>
|
||||
|
||||
@n_bytes: number of bytes to allocate
|
||||
@Returns: the allocated memory, or %NULL
|
||||
@n_bytes: number of bytes to allocate.
|
||||
@Returns: the allocated memory, or %NULL.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_try_realloc ##### -->
|
||||
@ -122,15 +107,15 @@ on failure. Contrast with g_realloc(), which aborts the program
|
||||
on failure. If @mem is %NULL, behaves the same as g_try_malloc().
|
||||
</para>
|
||||
|
||||
@mem: previously-allocated memory, or %NULL
|
||||
@n_bytes: number of bytes to allocate
|
||||
@Returns: the allocated memory, or %NULL
|
||||
@mem: previously-allocated memory, or %NULL.
|
||||
@n_bytes: number of bytes to allocate.
|
||||
@Returns: the allocated memory, or %NULL.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_free ##### -->
|
||||
<para>
|
||||
Frees the memory pointed to by @mem.
|
||||
If @mem is NULL it simply returns.
|
||||
If @mem is %NULL it simply returns.
|
||||
</para>
|
||||
|
||||
@mem: the memory to free.
|
||||
@ -142,7 +127,7 @@ Allocates @size bytes on the stack; these bytes will be freed when the current
|
||||
stack frame is cleaned up.
|
||||
</para>
|
||||
|
||||
@size: number of bytes to allocate
|
||||
@size: number of bytes to allocate.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_memmove ##### -->
|
||||
@ -151,9 +136,9 @@ Copies a block of memory @n bytes long, from @s to @d.
|
||||
The source and destination areas may overlap.
|
||||
</para>
|
||||
<para>
|
||||
In order to use this function, you must include string.h
|
||||
In order to use this function, you must include <filename>string.h</filename>
|
||||
yourself, because this macro will typically simply resolve
|
||||
to memmove() and GLib does not include string.h for you.
|
||||
to <function>memmove()</function> and GLib does not include <filename>string.h</filename> for you.
|
||||
</para>
|
||||
|
||||
@d: the destination address to copy the bytes to.
|
||||
@ -164,36 +149,36 @@ to memmove() and GLib does not include string.h for you.
|
||||
<!-- ##### FUNCTION g_memdup ##### -->
|
||||
<para>
|
||||
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
|
||||
from @mem. If @mem is NULL it returns NULL.
|
||||
from @mem. If @mem is %NULL it returns %NULL.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem
|
||||
is %NULL.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GMemVTable ##### -->
|
||||
<para>
|
||||
A set of functions used to perform memory allocation. The same GMemVTable must
|
||||
A set of functions used to perform memory allocation. The same #GMemVTable must
|
||||
be used for all allocations in the same program; a call to g_mem_set_vtable(),
|
||||
if it exists, should be prior to any use of GLib.
|
||||
</para>
|
||||
|
||||
@malloc: function to use for allocating memory
|
||||
@realloc: function to use for reallocating memory
|
||||
@free: function to use to free memory
|
||||
@calloc: function to use for allocating zero-filled memory
|
||||
@try_malloc: function to use for allocating memory without a default error handler
|
||||
@try_realloc: function to use for reallocating memory without a default error handler
|
||||
@malloc: function to use for allocating memory.
|
||||
@realloc: function to use for reallocating memory.
|
||||
@free: function to use to free memory.
|
||||
@calloc: function to use for allocating zero-filled memory.
|
||||
@try_malloc: function to use for allocating memory without a default error handler.
|
||||
@try_realloc: function to use for reallocating memory without a default error handler.
|
||||
|
||||
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
|
||||
<para>
|
||||
Sets the #GMemVTable to use for memory allocation. You can use this to provide
|
||||
custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
|
||||
OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free
|
||||
functions; GLib can provide default implementations of the others. The malloc
|
||||
and realloc implementations should return %NULL on failure, GLib will handle
|
||||
OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
|
||||
functions; GLib can provide default implementations of the others. The <function>malloc()</function>
|
||||
and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
|
||||
error-checking for you. @vtable is copied, so need not persist after this
|
||||
function has been called.
|
||||
</para>
|
||||
@ -211,15 +196,16 @@ function has been called.
|
||||
|
||||
<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
|
||||
<para>
|
||||
|
||||
A #GMemVTable containing profiling variants of the memory
|
||||
allocation functions. Use them together with g_mem_profile()
|
||||
in order to get information about the memory allocation pattern
|
||||
of your program.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_mem_profile ##### -->
|
||||
<para>
|
||||
Outputs a summary of memory usage.
|
||||
To use this function you must configure glib with the flag
|
||||
'--enable-mem-profile=yes' before compiling.
|
||||
</para>
|
||||
<para>
|
||||
It outputs the frequency of allocations of different sizes,
|
||||
@ -228,6 +214,9 @@ the total number of bytes which have been freed,
|
||||
and the difference between the previous two values, i.e. the number of bytes
|
||||
still in use.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that this function will not output anything unless you have
|
||||
previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
@ -28,8 +28,8 @@ in a pointer value. Naively, you might try this, but it's incorrect:
|
||||
p = (void*) 42;
|
||||
i = (int) p;
|
||||
</programlisting>
|
||||
Again, that example was NOT correct, don't copy it. The problem is
|
||||
that on some systems you need to do this:
|
||||
Again, that example was <emphasis>not</emphasis> correct, don't copy it.
|
||||
The problem is that on some systems you need to do this:
|
||||
<programlisting>
|
||||
gpointer p;
|
||||
int i;
|
||||
@ -66,7 +66,7 @@ storing integers in pointers, and only preserve 32 bits of the
|
||||
integer; values outside the range of a 32-bit integer will be mangled.
|
||||
</para>
|
||||
|
||||
@i: integer to stuff into a pointer
|
||||
@i: integer to stuff into a pointer.
|
||||
|
||||
|
||||
<!-- ##### MACRO GPOINTER_TO_INT ##### -->
|
||||
@ -86,33 +86,35 @@ integer; values outside the range of a 32-bit integer will be mangled.
|
||||
|
||||
<!-- ##### MACRO GUINT_TO_POINTER ##### -->
|
||||
<para>
|
||||
Same as GINT_TO_POINTER(), but for unsigned integers.
|
||||
Stuffs an unsigned integer into a pointer type.
|
||||
</para>
|
||||
|
||||
@u: integer to stuff into the pointer
|
||||
@u: unsigned integer to stuff into the pointer.
|
||||
|
||||
|
||||
<!-- ##### MACRO GPOINTER_TO_UINT ##### -->
|
||||
<para>
|
||||
Same as GPOINTER_TO_INT(), but for unsigned integers.
|
||||
Extracts an unsigned integer from a pointer. The integer must have
|
||||
been stored in the pointer with GUINT_TO_POINTER().
|
||||
</para>
|
||||
|
||||
@p: pointer to extract an integer from
|
||||
@p: pointer to extract an unsigned integer from.
|
||||
|
||||
|
||||
<!-- ##### MACRO GSIZE_TO_POINTER ##### -->
|
||||
<para>
|
||||
|
||||
Stuffs a #gsize into a pointer type.
|
||||
</para>
|
||||
|
||||
@s:
|
||||
@s: #gsize to stuff into the pointer.
|
||||
|
||||
|
||||
<!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
|
||||
<para>
|
||||
|
||||
Extracts a #gsize from a pointer. The #gsize must have
|
||||
been stored in the pointer with GSIZE_TO_POINTER().
|
||||
</para>
|
||||
|
||||
@p:
|
||||
@p: pointer to extract a #gsize from.
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user