mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-09 20:35:49 +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.
|
||||
|
||||
|
||||
|
||||
@ -52,8 +52,8 @@ representation is valid. Sometimes neither is valid. Use the API.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
glib doesn't contain any time-manipulation functions; however, there
|
||||
is a #GTime typedef which is equivalent to time_t, and a #GTimeVal
|
||||
GLib doesn't contain any time-manipulation functions; however, there
|
||||
is a #GTime typedef which is equivalent to <type>time_t</type>, and a #GTimeVal
|
||||
struct which represents a more precise time (with microseconds). You
|
||||
can request the current time as a #GTimeVal with g_get_current_time().
|
||||
</para>
|
||||
@ -78,8 +78,8 @@ Represents a precise time, with seconds and microseconds. Same as the
|
||||
<function>gettimeofday()</function> UNIX call.
|
||||
</para>
|
||||
|
||||
@tv_sec:
|
||||
@tv_usec:
|
||||
@tv_sec: seconds.
|
||||
@tv_usec: microseconds.
|
||||
|
||||
<!-- ##### FUNCTION g_get_current_time ##### -->
|
||||
<para>
|
||||
@ -98,7 +98,7 @@ may have limited precision, depending on hardware and operating system; don't
|
||||
rely on the exact length of the sleep.
|
||||
</para>
|
||||
|
||||
@microseconds: number of microseconds to pause
|
||||
@microseconds: number of microseconds to pause.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_time_val_add ##### -->
|
||||
@ -132,7 +132,7 @@ month, and year.
|
||||
|
||||
<!-- ##### TYPEDEF GTime ##### -->
|
||||
<para>
|
||||
Simply a replacement for time_t. Unrelated to GTimer.
|
||||
Simply a replacement for <type>time_t</type>. Unrelated to #GTimer.
|
||||
</para>
|
||||
|
||||
|
||||
@ -156,22 +156,22 @@ Integer representing a day of the month; between 1 and
|
||||
<!-- ##### ENUM GDateMonth ##### -->
|
||||
<para>
|
||||
Enumeration representing a month; values are #G_DATE_JANUARY,
|
||||
#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value.
|
||||
#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
|
||||
</para>
|
||||
|
||||
@G_DATE_BAD_MONTH:
|
||||
@G_DATE_JANUARY:
|
||||
@G_DATE_FEBRUARY:
|
||||
@G_DATE_MARCH:
|
||||
@G_DATE_APRIL:
|
||||
@G_DATE_MAY:
|
||||
@G_DATE_JUNE:
|
||||
@G_DATE_JULY:
|
||||
@G_DATE_AUGUST:
|
||||
@G_DATE_SEPTEMBER:
|
||||
@G_DATE_OCTOBER:
|
||||
@G_DATE_NOVEMBER:
|
||||
@G_DATE_DECEMBER:
|
||||
@G_DATE_BAD_MONTH: invalid value.
|
||||
@G_DATE_JANUARY: January.
|
||||
@G_DATE_FEBRUARY: February.
|
||||
@G_DATE_MARCH: March.
|
||||
@G_DATE_APRIL: April.
|
||||
@G_DATE_MAY: May.
|
||||
@G_DATE_JUNE: June.
|
||||
@G_DATE_JULY: July.
|
||||
@G_DATE_AUGUST: August.
|
||||
@G_DATE_SEPTEMBER: September.
|
||||
@G_DATE_OCTOBER: October.
|
||||
@G_DATE_NOVEMBER: November.
|
||||
@G_DATE_DECEMBER: December.
|
||||
|
||||
<!-- ##### TYPEDEF GDateYear ##### -->
|
||||
<para>
|
||||
@ -187,14 +187,14 @@ Enumeration representing a day of the week; #G_DATE_MONDAY,
|
||||
#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
|
||||
</para>
|
||||
|
||||
@G_DATE_BAD_WEEKDAY:
|
||||
@G_DATE_MONDAY:
|
||||
@G_DATE_TUESDAY:
|
||||
@G_DATE_WEDNESDAY:
|
||||
@G_DATE_THURSDAY:
|
||||
@G_DATE_FRIDAY:
|
||||
@G_DATE_SATURDAY:
|
||||
@G_DATE_SUNDAY:
|
||||
@G_DATE_BAD_WEEKDAY: invalid value.
|
||||
@G_DATE_MONDAY: Monday.
|
||||
@G_DATE_TUESDAY: Tuesday.
|
||||
@G_DATE_WEDNESDAY: Wednesday.
|
||||
@G_DATE_THURSDAY: Thursday.
|
||||
@G_DATE_FRIDAY: Friday.
|
||||
@G_DATE_SATURDAY: Saturday.
|
||||
@G_DATE_SUNDAY: Sunday.
|
||||
|
||||
<!-- ##### MACRO G_DATE_BAD_DAY ##### -->
|
||||
<para>
|
||||
@ -219,12 +219,12 @@ Represents an invalid year.
|
||||
|
||||
<!-- ##### FUNCTION g_date_new ##### -->
|
||||
<para>
|
||||
Allocate a #GDate and initialize it to a sane state. The new date will
|
||||
Allocates a #GDate and initializes it to a sane state. The new date will
|
||||
be cleared (as if you'd called g_date_clear()) but invalid (it won't
|
||||
represent an existing day). Free the return value with g_date_free().
|
||||
</para>
|
||||
|
||||
@Returns: The newly-allocated #GDate
|
||||
@Returns: a newly-allocated #GDate.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_new_dmy ##### -->
|
||||
@ -234,10 +234,10 @@ day/month/year triplet you pass in represents an existing day, the
|
||||
returned date will be valid.
|
||||
</para>
|
||||
|
||||
@day: Day of the month
|
||||
@month: Month of the year
|
||||
@year: Year
|
||||
@Returns: Allocated date initialized with @day, @month, and @year
|
||||
@day: day of the month.
|
||||
@month: month of the year.
|
||||
@year: year
|
||||
@Returns: a newly-allocated #GDate initialized with @day, @month, and @year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_new_julian ##### -->
|
||||
@ -247,98 +247,98 @@ Julian day number you pass in is valid (greater than 0, less than an
|
||||
unreasonably large number), the returned date will be valid.
|
||||
</para>
|
||||
|
||||
@julian_day: Days since January 1, Year 1
|
||||
@Returns: Allocated date initialized with @julian_day
|
||||
@julian_day: days since January 1, Year 1.
|
||||
@Returns: a newly-allocated #GDate initialized with @julian_day.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_clear ##### -->
|
||||
<para>
|
||||
Initialize one or more #GDate structs to a sane but invalid
|
||||
Initializes one or more #GDate structs to a sane but invalid
|
||||
state. The cleared dates will not represent an existing date, but will
|
||||
not contain garbage. Useful to init a date declared on the stack.
|
||||
Validity can be tested with g_date_valid().
|
||||
</para>
|
||||
|
||||
@date: Pointer to one or more dates to clear
|
||||
@n_dates: Number of dates to clear
|
||||
@date: pointer to one or more dates to clear.
|
||||
@n_dates: number of dates to clear.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_free ##### -->
|
||||
<para>
|
||||
Free a #GDate returned from g_date_new()
|
||||
Frees a #GDate returned from g_date_new().
|
||||
</para>
|
||||
|
||||
@date: Date to free
|
||||
@date: a #GDate.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_day ##### -->
|
||||
<para>
|
||||
Set the day of the month for a #GDate. If the resulting day-month-year
|
||||
Sets the day of the month for a #GDate. If the resulting day-month-year
|
||||
triplet is invalid, the date will be invalid.
|
||||
</para>
|
||||
|
||||
@date: Date to set the day for
|
||||
@day: Day to set
|
||||
@date: a #GDate.
|
||||
@day: day to set.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_month ##### -->
|
||||
<para>
|
||||
Set the month of the year for a #GDate. If the resulting
|
||||
day-month-year triplet is invalid, the date will be invalid.
|
||||
Sets the month of the year for a #GDate. If the resulting
|
||||
day-month-year triplet is invalid, the date will be invalid.
|
||||
</para>
|
||||
|
||||
@date: Date
|
||||
@month: Month to set
|
||||
@date: a #GDate.
|
||||
@month: month to set.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_year ##### -->
|
||||
<para>
|
||||
Set the year for a #GDate. If the resulting day-month-year triplet is
|
||||
invalid, the date will be invalid.
|
||||
Sets the year for a #GDate. If the resulting day-month-year triplet is
|
||||
invalid, the date will be invalid.
|
||||
</para>
|
||||
|
||||
@date: Date
|
||||
@year: Year to set
|
||||
@date: a #GDate.
|
||||
@year: year to set.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_dmy ##### -->
|
||||
<para>
|
||||
Set the value of a #GDate from a day, month, and year. The DMY triplet
|
||||
must be valid; if you aren't sure it is, call g_date_valid_dmy() to
|
||||
Sets the value of a #GDate from a day, month, and year. The day-month-year
|
||||
triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to
|
||||
check before you set it.
|
||||
</para>
|
||||
|
||||
@date: Date to set the value of
|
||||
@day: Day
|
||||
@month: Month
|
||||
@y: Year
|
||||
@date: a #GDate.
|
||||
@day: day.
|
||||
@month: month.
|
||||
@y: year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_julian ##### -->
|
||||
<para>
|
||||
Set the value of a #GDate from a Julian day number.
|
||||
Sets the value of a #GDate from a Julian day number.
|
||||
</para>
|
||||
|
||||
@date: Date to set
|
||||
@julian_date: Julian day number (days since January 1, Year 1)
|
||||
@date: a #GDate.
|
||||
@julian_date: Julian day number (days since January 1, Year 1).
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_time ##### -->
|
||||
<para>
|
||||
Set the value of a date from a #GTime (time_t) value. To set the value
|
||||
of a date to the current day, you could write:
|
||||
Sets the value of a date from a #GTime (<type>time_t</type>) value.
|
||||
To set the value of a date to the current day, you could write:
|
||||
<informalexample><programlisting>
|
||||
g_date_set_time(date, time(NULL));
|
||||
g_date_set_time(date, time(NULL));
|
||||
</programlisting></informalexample>
|
||||
</para>
|
||||
|
||||
@date: Date to update
|
||||
@time: #GTime value to set
|
||||
@date: a #GDate.
|
||||
@time: #GTime value to set.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_set_parse ##### -->
|
||||
<para>
|
||||
Parse a user-inputted string @str, and try to figure out what date it
|
||||
Parses 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
|
||||
@ -353,86 +353,86 @@ user means by a given string (and it does work pretty well in that
|
||||
capacity).
|
||||
</para>
|
||||
|
||||
@date: Date to fill in
|
||||
@str: String to parse
|
||||
@date: a #GDate to fill in.
|
||||
@str: string to parse.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_add_days ##### -->
|
||||
<para>
|
||||
Increment a date some number of days. To move forward by weeks, add
|
||||
Increments a date some number of days. To move forward by weeks, add
|
||||
weeks*7 days. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: The date to increment
|
||||
@n_days: Number of days to move the date forward
|
||||
@date: a #GDate to increment.
|
||||
@n_days: number of days to move the date forward.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_subtract_days ##### -->
|
||||
<para>
|
||||
Move a date some number of days into the past. To move by weeks, just
|
||||
move by weeks*7 days. Date must be valid.
|
||||
Moves a date some number of days into the past. To move by weeks, just
|
||||
move by weeks*7 days. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to decrement
|
||||
@n_days: Number of days to move
|
||||
@date: a #GDate to decrement.
|
||||
@n_days: number of days to move.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_add_months ##### -->
|
||||
<para>
|
||||
Increment a date by some number of months. If the day of the month is
|
||||
Increments a date by some number of months. If the day of the month is
|
||||
greater than 28, this routine may change the day of the month (because
|
||||
the destination month may not have the current day in it). The date
|
||||
must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to increment
|
||||
@n_months: Number of months to move forward
|
||||
@date: a #GDate to increment.
|
||||
@n_months: number of months to move forward.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_subtract_months ##### -->
|
||||
<para>
|
||||
Move a date some number of months into the past. If the current day of
|
||||
Moves 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.
|
||||
may change. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to decrement
|
||||
@n_months: Number of months to move
|
||||
@date: a #GDate to decrement.
|
||||
@n_months: number of months to move.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_add_years ##### -->
|
||||
<para>
|
||||
Increment a date by some number of years. If the date is February 29,
|
||||
Increments a date by some number of years. If the date is February 29,
|
||||
and the destination year is not a leap year, the date will be changed
|
||||
to February 28. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to increment
|
||||
@n_years: Number of years to move forward
|
||||
@date: a #GDate to increment.
|
||||
@n_years: number of years to move forward.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_subtract_years ##### -->
|
||||
<para>
|
||||
Move a date some number of years into the past. If the current day
|
||||
Moves 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
|
||||
move to a non-leap-year) then the day is changed to February 29. The date
|
||||
must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to decrement
|
||||
@n_years: Number of years to move
|
||||
@date: a #GDate to decrement.
|
||||
@n_years: number of years to move.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_days_between ##### -->
|
||||
<para>
|
||||
Compute the number of days between two dates.
|
||||
Computes the number of days between two dates.
|
||||
If @date2 is prior to @date1, the returned value is negative.
|
||||
Both dates must be valid.
|
||||
</para>
|
||||
|
||||
@date1: The first date
|
||||
@date2: The second date
|
||||
@Returns: The number of days between @date1 and @date2
|
||||
@date1: the first date.
|
||||
@date2: the second date.
|
||||
@Returns: the number of days between @date1 and @date2.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_compare ##### -->
|
||||
@ -441,72 +441,72 @@ Both dates must be valid.
|
||||
dates must be valid.
|
||||
</para>
|
||||
|
||||
@lhs: First date to compare
|
||||
@rhs: Second date to compare
|
||||
@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
|
||||
greater than zero if @lhs is greater than @rhs.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_clamp ##### -->
|
||||
<para>
|
||||
If @date is prior to @min_date, set @date equal to @min_date.
|
||||
If @date falls after @max_date, set @date equal to @max_date.
|
||||
If @date is prior to @min_date, sets @date equal to @min_date.
|
||||
If @date falls after @max_date, sets @date equal to @max_date.
|
||||
Either @min_date and @max_date may be %NULL. All non-%NULL dates
|
||||
must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to clamp
|
||||
@min_date: Minimum accepted value for @date
|
||||
@max_date: Maximum accepted value for @date
|
||||
@date: a #GDate to clamp.
|
||||
@min_date: minimum accepted value for @date.
|
||||
@max_date: maximum accepted value for @date.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_order ##### -->
|
||||
<para>
|
||||
Check if @date1 is less than or equal to @date2,
|
||||
Checks if @date1 is less than or equal to @date2,
|
||||
and swap the values if this is not the case.
|
||||
</para>
|
||||
|
||||
@date1: The first date
|
||||
@date2: The second date
|
||||
@date1: the first date.
|
||||
@date2: the second date.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_day ##### -->
|
||||
<para>
|
||||
Return the day of the month; the #GDate must be valid.
|
||||
Returns the day of the month. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to extract the day of the month from
|
||||
@Returns: Day of the month
|
||||
@date: a #GDate to extract the day of the month from.
|
||||
@Returns: day of the month.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_month ##### -->
|
||||
<para>
|
||||
Accessor for the month of the year. Date must be valid.
|
||||
Returns the month of the year. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to get the month from
|
||||
@Returns: A #GDateMonth
|
||||
@date: a #GDate to get the month from.
|
||||
@Returns: month of the year as a #GDateMonth.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_year ##### -->
|
||||
<para>
|
||||
Accessor; returns the year of a #GDate. The date must be valid.
|
||||
Returns the year of a #GDate. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date
|
||||
@Returns: Year in which the date falls
|
||||
@date: a #GDate.
|
||||
@Returns: year in which the date falls.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_julian ##### -->
|
||||
<para>
|
||||
Accessor, returns the Julian day or "serial number" of the #GDate. The
|
||||
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.
|
||||
etc. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to extract the Julian day from
|
||||
@Returns: Julian day
|
||||
@date: a #GDate to extract the Julian day from.
|
||||
@Returns: Julian day.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_weekday ##### -->
|
||||
@ -514,120 +514,121 @@ etc. Date must be valid.
|
||||
Returns the day of the week for a #GDate. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date
|
||||
@Returns: Day of the week as a #GDateWeekday
|
||||
@date: a #GDate.
|
||||
@Returns: day of the week as a #GDateWeekday.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_day_of_year ##### -->
|
||||
<para>
|
||||
Return the day of the year, where Jan 1 is the first day of the
|
||||
year. Date must be valid.
|
||||
Returns the day of the year, where Jan 1 is the first day of the
|
||||
year. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to extract day of year from
|
||||
@Returns: Day of the year
|
||||
@date: a #GDate to extract day of year from.
|
||||
@Returns: day of the year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_days_in_month ##### -->
|
||||
<para>
|
||||
Return the number of days in a month, taking leap years into account.
|
||||
Returns the number of days in a month, taking leap years into account.
|
||||
</para>
|
||||
|
||||
@month: Month
|
||||
@year: Year
|
||||
@Returns: Number of days in @month during the year @year.
|
||||
@month: month.
|
||||
@year: year.
|
||||
@Returns: number of days in @month during the @year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
|
||||
<para>
|
||||
Returns TRUE if the date is on the first of a month. Date must be valid.
|
||||
Returns %TRUE if the date is on the first of a month. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to check
|
||||
@Returns: Boolean, if the date is the first of the month
|
||||
@date: a #GDate to check.
|
||||
@Returns: %TRUE if the date is the first of the month.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
|
||||
<para>
|
||||
Returns TRUE if the date is the last day of the month. Date must be valid.
|
||||
Returns %TRUE if the date is the last day of the month. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to check
|
||||
@Returns: Boolean, if the date is the last day of the month
|
||||
@date: a #GDate to check.
|
||||
@Returns: %TRUE if the date is the last day of the month.
|
||||
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_is_leap_year ##### -->
|
||||
<para>
|
||||
Returns TRUE if the year is a leap year
|
||||
Returns %TRUE if the year is a leap year.
|
||||
</para>
|
||||
|
||||
@year: Year to check
|
||||
@Returns: Boolean, if the year is a leap year
|
||||
@year: year to check.
|
||||
@Returns: %TRUE if the year is a leap year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_monday_week_of_year ##### -->
|
||||
<para>
|
||||
Return the week of the year, where weeks are understood to start on
|
||||
Returns 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.
|
||||
0. The date must be valid.
|
||||
</para>
|
||||
|
||||
@date: Date to use
|
||||
@Returns: Week of the year
|
||||
@date: a #GDate.
|
||||
@Returns: week of the year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_monday_weeks_in_year ##### -->
|
||||
<para>
|
||||
Return the number of weeks in the year, where weeks are taken to start
|
||||
on Monday. Will be 52 or 53. Date must be valid. (Years always have 52
|
||||
Returns the number of weeks in the year, where weeks are taken to start
|
||||
on Monday. Will be 52 or 53. The date must be valid. (Years always have 52
|
||||
7-day periods, plus 1 or 2 extra days depending on whether it's a leap
|
||||
year. This function is basically telling you how many Mondays are in
|
||||
the year, i.e. there are 53 Mondays if one of the extra days happens
|
||||
to be a Monday.)
|
||||
</para>
|
||||
|
||||
@year: Year
|
||||
@Returns: Number of Mondays in the year
|
||||
@year: a year.
|
||||
@Returns: number of Mondays in the year.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_sunday_week_of_year ##### -->
|
||||
<para>
|
||||
Week of the year during which this date falls, if weeks are understood
|
||||
to being on Sunday. Date must be valid. Can return 0 if the day is
|
||||
before the first Sunday of the year.
|
||||
Returns the week of the year during which this date falls, if weeks
|
||||
are understood to being on Sunday. The date must be valid. Can return 0 if
|
||||
the day is before the first Sunday of the year.
|
||||
</para>
|
||||
|
||||
@date: Date
|
||||
@Returns: Week number
|
||||
@date: a #GDate.
|
||||
@Returns: week number.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_get_sunday_weeks_in_year ##### -->
|
||||
<para>
|
||||
Return the number of weeks in the year, where weeks are taken to start
|
||||
on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52
|
||||
Returns the number of weeks in the year, where weeks are taken to start
|
||||
on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52
|
||||
7-day periods, plus 1 or 2 extra days depending on whether it's a leap
|
||||
year. This function is basically telling you how many Sundays are in
|
||||
the year, i.e. there are 53 Sundays if one of the extra days happens
|
||||
to be a Sunday.)
|
||||
</para>
|
||||
|
||||
@year: Year to count weeks in
|
||||
@Returns: Number of weeks
|
||||
@year: year to count weeks in.
|
||||
@Returns: number of weeks.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_strftime ##### -->
|
||||
<para>
|
||||
Generate a printed representation of the date, in a locale-specific
|
||||
Generates a printed representation of the date, in a locale-specific
|
||||
way. Works just like the standard C <function>strftime()</function>
|
||||
function, but only accepts date-related formats; time-related formats
|
||||
give undefined results. Date must be valid.
|
||||
</para>
|
||||
|
||||
@s: 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
|
||||
@s: destination buffer.
|
||||
@slen: buffer size.
|
||||
@format: format string.
|
||||
@date: valid #GDate.
|
||||
@Returns: number of characters written to the buffer, or 0 the buffer was too small.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
|
||||
@ -637,81 +638,81 @@ using the @date value. Initializes the non-date parts with something
|
||||
sane but meaningless.
|
||||
</para>
|
||||
|
||||
@date: Date to set the <structname>struct tm</structname> from
|
||||
@tm: <structname>struct tm</structname> to fill
|
||||
@date: a #GDate to set the <structname>struct tm</structname> from.
|
||||
@tm: <structname>struct tm</structname> to fill.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid ##### -->
|
||||
<para>
|
||||
Returns TRUE if the #GDate represents an existing day. #GDate must not
|
||||
Returns %TRUE if the #GDate represents an existing day. The date must not
|
||||
contain garbage; it should have been initialized with g_date_clear()
|
||||
if it wasn't allocated by one of the g_date_new() variants.
|
||||
</para>
|
||||
|
||||
@date: Date to check
|
||||
@date: a #GDate to check.
|
||||
@Returns: Whether the date is valid.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_day ##### -->
|
||||
<para>
|
||||
Returns TRUE if the day of the month is valid (a day is valid if it's
|
||||
Returns %TRUE if the day of the month is valid (a day is valid if it's
|
||||
between 1 and 31 inclusive).
|
||||
</para>
|
||||
|
||||
@day: Day to check.
|
||||
@Returns: Boolean, whether the day is valid.
|
||||
@day: day to check.
|
||||
@Returns: %TRUE if the day is valid.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_month ##### -->
|
||||
<para>
|
||||
Returns TRUE if the month value is valid. The 12 #GDateMonth
|
||||
Returns %TRUE if the month value is valid. The 12 #GDateMonth
|
||||
enumeration values are the only valid months.
|
||||
</para>
|
||||
|
||||
@month: Month
|
||||
@Returns: Boolean, whether the month is valid
|
||||
@month: month.
|
||||
@Returns: %TRUE if the month is valid.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_year ##### -->
|
||||
<para>
|
||||
Returns TRUE if the year is valid. Any year greater than 0 is valid,
|
||||
though there is a 16-bit limit to what GDate will understand.
|
||||
Returns %TRUE if the year is valid. Any year greater than 0 is valid,
|
||||
though there is a 16-bit limit to what #GDate will understand.
|
||||
</para>
|
||||
|
||||
@year: Year
|
||||
@Returns: Boolean, whether the year is valid.
|
||||
@year: year.
|
||||
@Returns: %TRUE if the year is valid.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
|
||||
<para>
|
||||
Returns TRUE if the day/month/year triplet forms a valid, existing day
|
||||
in the range of days GDate understands (Year 1 or later, no more than
|
||||
Returns %TRUE if the day/month/year triplet forms a valid, existing day
|
||||
in the range of days #GDate understands (Year 1 or later, no more than
|
||||
a few thousand years in the future).
|
||||
</para>
|
||||
|
||||
@day: Day
|
||||
@month: Month
|
||||
@year: Year
|
||||
@Returns: Boolean, whether the date is a valid one
|
||||
@day: day.
|
||||
@month: month.
|
||||
@year: year.
|
||||
@Returns: %TRUE if the date is a valid one.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_julian ##### -->
|
||||
<para>
|
||||
Returns TRUE if the Julian day is valid. Anything greater than zero is basically a
|
||||
Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a
|
||||
valid Julian, though there is a 32-bit limit.
|
||||
</para>
|
||||
|
||||
@julian_date: Julian day to check
|
||||
@Returns: Boolean, whether the Julian day is valid.
|
||||
@julian_date: Julian day to check.
|
||||
@Returns: %TRUE if the Julian day is valid.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_date_valid_weekday ##### -->
|
||||
<para>
|
||||
Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
|
||||
Returns %TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
|
||||
values are the only valid weekdays.
|
||||
</para>
|
||||
|
||||
@weekday: Weekday
|
||||
@Returns: Boolean, whether the weekday is valid.
|
||||
@weekday: weekday.
|
||||
@Returns: %TRUE if the weekday is valid.
|
||||
|
||||
|
||||
|
||||
@ -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…
x
Reference in New Issue
Block a user