diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index fe546374d..2cf0ed214 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,19 @@ +2000-04-16 Damon Chaplin + + * 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 * tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 63b1bcdbd..e48890e01 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -569,58 +569,74 @@ GTimeVal g_get_current_time -GTime GDate +GTime GDateDMY GDateDay GDateMonth -GDateWeekday GDateYear +GDateWeekday + + G_DATE_BAD_DAY G_DATE_BAD_JULIAN G_DATE_BAD_YEAR -g_date_add_days -g_date_add_months -g_date_add_years -g_date_clear -g_date_compare -g_date_day -g_date_day_of_year -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_clear +g_date_free + + g_date_set_day +g_date_set_month +g_date_set_year 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_set_parse + + +g_date_add_days g_date_subtract_days +g_date_add_months g_date_subtract_months +g_date_add_years g_date_subtract_years +g_date_compare + + +g_date_day +g_date_month +g_date_year +g_date_julian +g_date_weekday +g_date_day_of_year + + +g_date_days_in_month +g_date_is_first_of_month +g_date_is_last_of_month +g_date_is_leap_year +g_date_monday_week_of_year +g_date_monday_weeks_in_year g_date_sunday_week_of_year g_date_sunday_weeks_in_year + + +g_date_strftime g_date_to_struct_tm + + 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
@@ -924,8 +940,8 @@ g_list_position g_list_index -g_list_pop_allocator g_list_push_allocator +g_list_pop_allocator
@@ -965,8 +981,8 @@ g_slist_position g_slist_index -g_slist_pop_allocator g_slist_push_allocator +g_slist_pop_allocator
@@ -1155,8 +1171,8 @@ g_node_unlink g_node_destroy -g_node_pop_allocator g_node_push_allocator +g_node_pop_allocator
diff --git a/docs/reference/glib/glib/ChangeLog b/docs/reference/glib/glib/ChangeLog index fe546374d..2cf0ed214 100644 --- a/docs/reference/glib/glib/ChangeLog +++ b/docs/reference/glib/glib/ChangeLog @@ -1,3 +1,19 @@ +2000-04-16 Damon Chaplin + + * 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 * tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index d05a1de81..d985d4e3b 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -58,14 +58,11 @@ To free an array, use g_array_free(). Contains the public fields of an Array. -The data field points to the element data. -It may change as elements are added to the array. -The len field contains the number of elements -in the array. -@data: -@len: +@data: a pointer to the element data. The data may be moved as elements are +added to the #GArray. +@len: the number of elements in the #GArray. @@ -148,51 +145,73 @@ in the array have to be moved to make space for the new elements. - +Inserts an element into an array at the given index. + + +g_array_insert_val() is a macro which uses a reference to the value +parameter @v. This means that you cannot use it with literal values +such as "27". You must use variables. + + -@a: -@i: -@v: +@a: a #GArray. +@i: the index to place the element at. +@v: the value to insert into the array. +@Returns: the #GArray. - +Inserts @len elements into a #GArray at the given index. -@array: -@index: -@data: -@len: -@Returns: +@array: a #GArray. +@index: the index to place the elements at. +@data: a pointer to the elements to insert. +@len: the number of elements to insert. +@Returns: the #GArray. - +Removes the element at the given index from a #GArray. +The following elements are moved down one place. -@array: -@index: -@Returns: +@array: a #GArray. +@index: the index of the element to remove. +@Returns: the #GArray. - +Removes the element at the given index from a #GArray. +The last element in the array is used to fill in the space, so this function +does not preserve the order of the #GArray. But it is faster than +g_array_remove_index(). -@array: -@index: -@Returns: +@array: a @GArray. +@index: the index of the element to remove. +@Returns: the #GArray. Returns the element of a #GArray at the given index. The return value is cast to the given type. -FIXME: need more info on how it works with structures. + + +Getting a pointer to an element in a GArray. + + EDayViewEvent *event; + + /* This gets a pointer to the 3rd element in the array of EDayViewEvent + structs. */ + event = &g_array_index (events, EDayViewEvent, 3); + + @a: a #GArray. diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index cba774b85..17c1a8d96 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -51,15 +51,12 @@ To free a GByteArray, use g_byte_array_free(). -The GByteArray struct allows access to the public fields of a GByteArray. -The data field points to the element data. -It may change as elements are added to the array. -The len field contains the number of elements -in the array. +The #GByteArray struct allows access to the public fields of a #GByteArray. -@data: -@len: +@data: a pointer to the element data. The data may be moved as elements are +added to the #GByteArray. +@len: the number of elements in the #GByteArray. @@ -95,22 +92,26 @@ The array will grow in size automatically if necessary. - +Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. -@array: -@index: -@Returns: +@array: a #GByteArray. +@index: the index of the byte to remove. +@Returns: the #GByteArray. - +Removes the byte at the given index from a #GByteArray. +The last element in the array is used to fill in the space, so this function +does not preserve the order of the #GByteArray. But it is faster than +g_byte_array_remove_index(). -@array: -@index: -@Returns: +@array: a #GByteArray. +@index: the index of the byte to remove. +@Returns: the #GByteArray. diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index 59e1b44b2..cc8595c80 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -25,8 +25,8 @@ To create a pointer array, use g_ptr_array_new(). To add elements to a pointer array, use g_ptr_array_add(). -To remove elements from a pointer array, use g_ptr_array_remove(), 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(). To access an element of a pointer array, use g_ptr_array_index(). @@ -92,19 +92,13 @@ The array will grow in size automatically if necessary. -Removes the first occurrence of given pointer from the pointer array. +Removes the first occurrence of the given pointer from the pointer array. +The following elements are moved down one place. + + It returns TRUE if the pointer was removed, or FALSE if the pointer was not found. - - -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. - - @array: a #GPtrArray. @data: the pointer to remove. @@ -115,16 +109,8 @@ in the array. Removes the pointer at the given index from the pointer array. +The following elements are moved down one place. - - -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. - - @array: a #GPtrArray. @index: the index of the pointer to remove. @@ -133,22 +119,32 @@ iterating over the array. - +Removes the first occurrence of the given pointer from the pointer array. +The last element in the array is used to fill in the space, so this function +does not preserve the order of the array. But it is faster than +g_ptr_array_remove(). + + +It returns TRUE if the pointer was removed, or FALSE if the pointer +was not found. -@array: -@data: -@Returns: +@array: a #GPtrArray. +@data: the pointer to remove. +@Returns: TRUE if the pointer was found in the array. - +Removes the pointer at the given index from the pointer array. +The last element in the array is used to fill in the space, so this function +does not preserve the order of the array. But it is faster than +g_ptr_array_remove_index(). -@array: -@index: -@Returns: +@array: a #GPtrArray. +@index: the index of the pointer to remove. +@Returns: the pointer which was removed. diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 7350193b3..cfced74dc 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -2,8 +2,7 @@ Date and Time Functions - -Calendrical Calculations and Miscellaneous Time Stuff +calendrical calculations and miscellaneous time stuff. diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index 7add0adbd..995379c8c 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -224,11 +224,15 @@ Gets the number of elements in a #GList. - +Copies a #GList. + + +Note that this is a "shallow" copy. If the list elements consist of pointers +to data, the pointers are copied but the actual data isn't. -@list: -@Returns: +@list: a #GList. +@Returns: a copy of @list. @@ -243,12 +247,15 @@ It simply switches the next and prev pointers of each element. - +Sorts a #GList using the given comparison function. -@list: -@compare_func: -@Returns: +@list: a #GList. +@compare_func: the comparison function used to sort the #GList. This function +is passed 2 elements of the #GList and should return 0 if they are equal, +a negative value if the first element comes before the second, or a positive +value if the first element comes after the second. +@Returns: the start of the sorted #GList. @@ -392,16 +399,17 @@ is not found. - +Restores the previous #GAllocator, used when allocating #GList elements. - +Sets the allocator to use to allocate #GList elements. +Use g_list_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GList elements. diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index 95dc4df99..61f9bb9e4 100644 --- a/docs/reference/glib/tmpl/linked_lists_single.sgml +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -217,11 +217,15 @@ Gets the number of elements in a #GSList. - +Copies a #GSList. + + +Note that this is a "shallow" copy. If the list elements consist of pointers +to data, the pointers are copied but the actual data isn't. -@list: -@Returns: +@list: a #GSList. +@Returns: a copy of @list. @@ -235,12 +239,15 @@ Reverses a #GSList. - +Sorts a #GSList using the given comparison function. -@list: -@compare_func: -@Returns: +@list: a #GSList. +@compare_func: the comparison function used to sort the #GSList. This function +is passed 2 elements of the #GSList and should return 0 if they are equal, +a negative value if the first element comes before the second, or a positive +value if the first element comes after the second. +@Returns: the start of the sorted #GList. @@ -356,16 +363,16 @@ is not found. - +Restores the previous #GAllocator, used when allocating #GSList elements. - - +Sets the allocator to use to allocate #GSList elements. +Use g_slist_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GSList elements. diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index 24c1a4ba9..f3d0ba83e 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -58,12 +58,29 @@ Checks if modules are supported on the current platform. - +A portable way to build the filename of a module. The platform-specific +prefix and suffix are added to the filename, if needed, and the result is +added to the directory, using the correct separator character. + + +The directory should specify the directory where the module can be found. +It can be NULL or an empty string to indicate that the module is in a standard +operating-system specific directory, though this is not recommended since the +wrong module may be found. + + +For example, calling g_module_build_path() on a Linux system with a directory +of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so". +On a Windows system, using "\Windows" as the directory it will return +"\Windows\mylibrary.dll". -@directory: -@module_name: -@Returns: +@directory: the directory where the module is. This can be NULL or the empty +string to indicate that the standard operating system-specific directories +will be used, though that is not recommended. +@module_name: the name of the module. +@Returns: the complete path of the module, including the standard library +prefix and suffix. This should be freed when no longer needed. diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index d45683127..7a8aca2e8 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -478,16 +478,17 @@ allocated. - +Restores the previous #GAllocator, used when allocating #GNode elements. - +Sets the allocator to use to allocate #GNode elements. +Use g_node_pop_allocator() to restore the previous allocator. -@allocator: +@allocator: the #GAllocator to use when allocating #GNode elements.