+2000-04-16 Damon Chaplin <damon@helixcode.com>
+
+ * tmpl/linked_lists_single.sgml:
+ * tmpl/linked_lists_double.sgml:
+ * tmpl/trees-nary.sgml: updated.
+
+ * tmpl/modules.sgml: described g_module_build_path().
+
+ * tmpl/date.sgml: made short description lower case and end in a '.'.
+
+ * glib-sections.txt: rearranged GDate section.
+
+ * tmpl/arrays.sgml:
+ * tmpl/arrays_byte.sgml:
+ * tmpl/arrays_pointer.sgml: updated.
+
2000-02-21 Damon Chaplin <damon@helixcode.com>
* tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions
g_get_current_time
<SUBSECTION>
-GTime
GDate
+GTime
GDateDMY
GDateDay
GDateMonth
-GDateWeekday
GDateYear
+GDateWeekday
+
+<SUBSECTION>
G_DATE_BAD_DAY
G_DATE_BAD_JULIAN
G_DATE_BAD_YEAR
+
+<SUBSECTION>
+g_date_new
+g_date_new_dmy
+g_date_new_julian
+g_date_clear
+g_date_free
+
+<SUBSECTION>
+g_date_set_day
+g_date_set_month
+g_date_set_year
+g_date_set_dmy
+g_date_set_julian
+g_date_set_time
+g_date_set_parse
+
+<SUBSECTION>
g_date_add_days
+g_date_subtract_days
g_date_add_months
+g_date_subtract_months
g_date_add_years
-g_date_clear
+g_date_subtract_years
g_date_compare
+
+<SUBSECTION>
g_date_day
+g_date_month
+g_date_year
+g_date_julian
+g_date_weekday
g_date_day_of_year
+
+<SUBSECTION>
g_date_days_in_month
-g_date_free
g_date_is_first_of_month
g_date_is_last_of_month
g_date_is_leap_year
-g_date_julian
g_date_monday_week_of_year
g_date_monday_weeks_in_year
-g_date_month
-g_date_new
-g_date_new_dmy
-g_date_new_julian
-g_date_set_day
-g_date_set_dmy
-g_date_set_julian
-g_date_set_month
-g_date_set_parse
-g_date_set_time
-g_date_set_year
-g_date_strftime
-g_date_subtract_days
-g_date_subtract_months
-g_date_subtract_years
g_date_sunday_week_of_year
g_date_sunday_weeks_in_year
+
+<SUBSECTION>
+g_date_strftime
g_date_to_struct_tm
+
+<SUBSECTION>
g_date_valid
g_date_valid_day
+g_date_valid_month
+g_date_valid_year
g_date_valid_dmy
g_date_valid_julian
-g_date_valid_month
g_date_valid_weekday
-g_date_valid_year
-g_date_weekday
-g_date_year
</SECTION>
<SECTION>
g_list_index
<SUBSECTION>
-g_list_pop_allocator
g_list_push_allocator
+g_list_pop_allocator
</SECTION>
<SECTION>
g_slist_index
<SUBSECTION>
-g_slist_pop_allocator
g_slist_push_allocator
+g_slist_pop_allocator
</SECTION>
<SECTION>
g_node_destroy
<SUBSECTION>
-g_node_pop_allocator
g_node_push_allocator
+g_node_pop_allocator
</SECTION>
+2000-04-16 Damon Chaplin <damon@helixcode.com>
+
+ * tmpl/linked_lists_single.sgml:
+ * tmpl/linked_lists_double.sgml:
+ * tmpl/trees-nary.sgml: updated.
+
+ * tmpl/modules.sgml: described g_module_build_path().
+
+ * tmpl/date.sgml: made short description lower case and end in a '.'.
+
+ * glib-sections.txt: rearranged GDate section.
+
+ * tmpl/arrays.sgml:
+ * tmpl/arrays_byte.sgml:
+ * tmpl/arrays_pointer.sgml: updated.
+
2000-02-21 Damon Chaplin <damon@helixcode.com>
* tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions
<!-- ##### STRUCT GArray ##### -->
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
-The <structfield>data</structfield> field points to the element data.
-It may change as elements are added to the array.
-The <structfield>len</structfield> field contains the number of elements
-in the array.
</para>
-@data:
-@len:
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GArray.
+@len: the number of elements in the #GArray.
<!-- ##### FUNCTION g_array_new ##### -->
<para>
<!-- ##### MACRO g_array_insert_val ##### -->
<para>
-
+Inserts an element into an array at the given index.
+</para>
+<note>
+<para>
+g_array_insert_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
</para>
+</note>
-@a:
-@i:
-@v:
+@a: a #GArray.
+@i: the index to place the element at.
+@v: the value to insert into the array.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_insert_vals ##### -->
<para>
-
+Inserts @len elements into a #GArray at the given index.
</para>
-@array:
-@index:
-@data:
-@len:
-@Returns:
+@array: a #GArray.
+@index: the index to place the elements at.
+@data: a pointer to the elements to insert.
+@len: the number of elements to insert.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index ##### -->
<para>
-
+Removes the element at the given index from a #GArray.
+The following elements are moved down one place.
</para>
-@array:
-@index:
-@Returns:
+@array: a #GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index_fast ##### -->
<para>
-
+Removes the element at the given index from a #GArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GArray. But it is faster than
+g_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a @GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
<!-- ##### MACRO g_array_index ##### -->
<para>
Returns the element of a #GArray at the given index.
The return value is cast to the given type.
-FIXME: need more info on how it works with structures.
+
+<example>
+<title>Getting a pointer to an element in a GArray.</title>
+<programlisting>
+ EDayViewEvent *event;
+
+ /* This gets a pointer to the 3rd element in the array of EDayViewEvent
+ structs. */
+ event = &g_array_index (events, EDayViewEvent, 3);
+</programlisting>
+</example>
</para>
@a: a #GArray.
<!-- ##### STRUCT GByteArray ##### -->
<para>
-The GByteArray struct allows access to the public fields of a GByteArray.
-The <structfield>data</structfield> field points to the element data.
-It may change as elements are added to the array.
-The <structfield>len</structfield> field contains the number of elements
-in the array.
+The #GByteArray struct allows access to the public fields of a #GByteArray.
</para>
-@data:
-@len:
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GByteArray.
+@len: the number of elements in the #GByteArray.
<!-- ##### FUNCTION g_byte_array_new ##### -->
<para>
<!-- ##### FUNCTION g_byte_array_remove_index ##### -->
<para>
-
+Removes the byte at the given index from a #GByteArray.
+The following bytes are moved down one place.
</para>
-@array:
-@index:
-@Returns:
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
<para>
-
+Removes the byte at the given index from a #GByteArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GByteArray. But it is faster than
+g_byte_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
To add elements to a pointer array, use g_ptr_array_add().
</para>
<para>
-To remove elements from a pointer array, use g_ptr_array_remove(), and
-g_ptr_array_remove_index().
+To remove elements from a pointer array, use g_ptr_array_remove(),
+g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
</para>
<para>
To access an element of a pointer array, use g_ptr_array_index().
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
<para>
-Removes the first occurrence of given pointer from the pointer array.
-It returns TRUE if the pointer was removed, or FALSE if the pointer
-was not found.
+Removes the first occurrence of the given pointer from the pointer array.
+The following elements are moved down one place.
</para>
-<note>
<para>
-If you remove elements from the array, elements at the end of the array
-are moved into the space previously occupied by the removed element.
-This means that you should not rely on the index of particular elements
-remaining the same. You should also be careful when deleting elements while
-iterating over the array.
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
</para>
-</note>
@array: a #GPtrArray.
@data: the pointer to remove.
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
<para>
Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place.
</para>
-<note>
-<para>
-If you remove elements from the array, elements at the end of the array
-are moved into the space previously occupied by the removed element.
-This means that you should not rely on the index of particular elements
-remaining the same. You should also be careful when deleting elements while
-iterating over the array.
-</para>
-</note>
@array: a #GPtrArray.
@index: the index of the pointer to remove.
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
<para>
-
+Removes the first occurrence of the given pointer from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove().
+</para>
+<para>
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
</para>
-@array:
-@data:
-@Returns:
+@array: a #GPtrArray.
+@data: the pointer to remove.
+@Returns: TRUE if the pointer was found in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
<para>
-
+Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a #GPtrArray.
+@index: the index of the pointer to remove.
+@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
Date and Time Functions\r
\r
<!-- ##### SECTION Short_Description ##### -->\r
-\r
-Calendrical Calculations and Miscellaneous Time Stuff\r
+calendrical calculations and miscellaneous time stuff.\r
\r
<!-- ##### SECTION Long_Description ##### -->\r
<para>\r
<!-- ##### FUNCTION g_list_copy ##### -->
<para>
-
+Copies a #GList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: a copy of @list.
<!-- ##### FUNCTION g_list_reverse ##### -->
<!-- ##### FUNCTION g_list_sort ##### -->
<para>
-
+Sorts a #GList using the given comparison function.
</para>
-@list:
-@compare_func:
-@Returns:
+@list: a #GList.
+@compare_func: the comparison function used to sort the #GList. This function
+is passed 2 elements of the #GList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_list_concat ##### -->
<!-- ##### FUNCTION g_list_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GList elements.
</para>
<!-- ##### FUNCTION g_list_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GList elements.
+Use g_list_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GList elements.
<!-- ##### FUNCTION g_slist_copy ##### -->
<para>
-
+Copies a #GSList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
</para>
-@list:
-@Returns:
+@list: a #GSList.
+@Returns: a copy of @list.
<!-- ##### FUNCTION g_slist_reverse ##### -->
<!-- ##### FUNCTION g_slist_sort ##### -->
<para>
-
+Sorts a #GSList using the given comparison function.
</para>
-@list:
-@compare_func:
-@Returns:
+@list: a #GSList.
+@compare_func: the comparison function used to sort the #GSList. This function
+is passed 2 elements of the #GSList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_slist_concat ##### -->
<!-- ##### FUNCTION g_slist_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GSList elements.
</para>
-
<!-- ##### FUNCTION g_slist_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GSList elements.
+Use g_slist_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GSList elements.
<!-- ##### FUNCTION g_module_build_path ##### -->
<para>
-
+A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result is
+added to the directory, using the correct separator character.
+</para>
+<para>
+The directory should specify the directory where the module can be found.
+It can be NULL or an empty string to indicate that the module is in a standard
+operating-system specific directory, though this is not recommended since the
+wrong module may be found.
+</para>
+<para>
+For example, calling g_module_build_path() on a Linux system with a directory
+of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
+On a Windows system, using "\Windows" as the directory it will return
+"\Windows\mylibrary.dll".
</para>
-@directory:
-@module_name:
-@Returns:
+@directory: the directory where the module is. This can be NULL or the empty
+string to indicate that the standard operating system-specific directories
+will be used, though that is not recommended.
+@module_name: the name of the module.
+@Returns: the complete path of the module, including the standard library
+prefix and suffix. This should be freed when no longer needed.
<!-- ##### FUNCTION g_module_open ##### -->
<!-- ##### FUNCTION g_node_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GNode elements.
</para>
<!-- ##### FUNCTION g_node_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GNode elements.
+Use g_node_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GNode elements.
projects / platform / upstream / glib.git / commitdiff