Trivial s/foo/foo_/ fixes to make <glib.h> includable with -Wshadow

[platform/upstream/glib.git] / docs / reference / glib / tmpl / arrays.sgml

diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml
index bf1f0d1..6602e13 100644 (file)
--- a/docs/reference/glib/tmpl/arrays.sgml
+++ b/docs/reference/glib/tmpl/arrays.sgml
@@ -31,7 +31,7 @@ To set the size of an array, use g_array_set_size().
 To free an array, use g_array_free().
 </para>
 <example>
-<title>Using a GArray to store gint values.</title>
+<title>Using a <structname>GArray</structname> to store gint values.</title>
 <programlisting>
   GArray *garray;
   gint i;
@@ -39,10 +39,10 @@ To free an array, use g_array_free().
   /* We create a new array to store gint values.
      We don't want it zero-terminated or cleared to 0's. */
   garray = g_array_new (FALSE, FALSE, sizeof (gint));
-  for (i = 0; i < 10000; i++)
+  for (i = 0; i &lt; 10000; i++)
     g_array_append_val (garray, i);
 
-  for (i = 0; i < 10000; i++)
+  for (i = 0; i &lt; 10000; i++)
     if (g_array_index (garray, gint, i) != i)
       g_print ("ERROR: got %d instead of %d\n",
                g_array_index (garray, gint, i), i);
@@ -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.
@@ -79,14 +79,17 @@ when they are allocated.
 
 <!-- ##### FUNCTION g_array_sized_new ##### -->
 <para>
-
+Creates a new #GArray with @reserved_size elements
+preallocated. This avoids frequent reallocation, if you are going to
+add many elements to the array. Note however that the size of the
+array is still 0.
 </para>
 
-@zero_terminated: 
-@clear: 
-@element_size: 
-@reserved_size: 
-@Returns: 
+@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 ##### -->
@@ -179,7 +182,7 @@ Inserts @len elements into a #GArray at the given index.
 </para>
 
 @array: a #GArray.
-@index: the index to place the elements at.
+@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.
@@ -192,7 +195,7 @@ The following elements are moved down one place.
 </para>
 
 @array: a #GArray.
-@index: the index of the element to remove.
+@index_: the index of the element to remove.
 @Returns: the #GArray.
 
 
@@ -205,17 +208,39 @@ g_array_remove_index().
 </para>
 
 @array: a @GArray.
-@index: the index of the element to remove.
+@index_: the index of the element to remove.
 @Returns: the #GArray.
 
 
+<!-- ##### FUNCTION g_array_sort ##### -->
+<para>
+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.
+
+
+<!-- ##### FUNCTION g_array_sort_with_data ##### -->
+<para>
+Like g_array_sort(), but the comparison function receives a user data
+argument.
+</para>
+
+@array: a #GArray.
+@compare_func: comparison function.
+@user_data: data to pass to @compare_func.
+
+
 <!-- ##### MACRO g_array_index ##### -->
 <para>
 Returns the element of a #GArray at the given index.
 The return value is cast to the given type.
 
 <example>
-<title>Getting a pointer to an element in a GArray.</title>
+<title>Getting a pointer to an element in a <structname>GArray</structname>.</title>
 <programlisting>
   EDayViewEvent *event;
 
@@ -235,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.
@@ -246,11 +271,11 @@ 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.
+@free_segment: if %TRUE the actual element data is freed as well.
 @Returns: