Add G_QUEUE_INIT, g_queue_init(), and g_queue_clear() to better support

2007-03-06  Matthew Barnes  <mbarnes@redhat.com>

	* glib/gqueue.h:
	* glib/gqueue.c: Add G_QUEUE_INIT, g_queue_init(), and
	g_queue_clear() to better support statically allocated
	queues.  (#413244)


svn path=/trunk/; revision=5378

ChangeLog

@@ -1,3 +1,10 @@
+2007-03-06  Matthew Barnes  <mbarnes@redhat.com>
+
+	* glib/gqueue.h:
+	* glib/gqueue.c: Add G_QUEUE_INIT, g_queue_init(), and
+	g_queue_clear() to better support statically allocated
+	queues.  (#413244)
+
 2007-03-06  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gkeyfile.c (g_key_file_parse_value_as_boolean):

docs/reference/glib/glib-sections.txt

@@ -1785,6 +1785,9 @@ g_slist_pop_allocator
 GQueue
 g_queue_new
 g_queue_free
+G_QUEUE_INIT
+g_queue_init
+g_queue_clear
 g_queue_is_empty
 g_queue_get_length
 g_queue_reverse

docs/reference/glib/tmpl/queue.sgml

@@ -20,6 +20,10 @@ or simply pointers to any type of data.
 To create a new #GQueue, use g_queue_new().
 </para>
 <para>
+To initialize a statically-allocated #GQueue, use #G_QUEUE_INIT or
+g_queue_init().
+</para>
+<para>
 To add elements, use g_queue_push_head(), g_queue_push_head_link(), 
 g_queue_push_tail() and g_queue_push_tail_link().
 </para>
@@ -63,6 +67,38 @@ Contains the public fields of a <link linkend="glib-queues">Queue</link>.
 @queue: 
 
 
+<!-- ##### MACRO G_QUEUE_INIT ##### -->
+<para>
+A statically-allocated #GQueue must be initialized with this macro before it
+can be used.  This macro can be used to initialize a variable, but it cannot
+be assigned to a variable.  In that case you have to use g_queue_init().
+</para>
+
+<informalexample>
+<programlisting>
+GQueue my_queue = G_QUEUE_INIT;
+</programlisting>
+</informalexample>
+
+@Since: 2.14
+
+
+<!-- ##### FUNCTION g_queue_init ##### -->
+<para>
+
+</para>
+
+@queue: 
+
+
+<!-- ##### FUNCTION g_queue_clear ##### -->
+<para>
+
+</para>
+
+@queue: 
+
+
 <!-- ##### FUNCTION g_queue_is_empty ##### -->
 <para>
 

glib/glib.symbols

@@ -821,6 +821,7 @@ g_qsort_with_data
 
 #if IN_HEADER(__G_QUEUE_H__)
 #if IN_FILE(__G_QUEUE_C__)
+g_queue_clear
 g_queue_copy
 g_queue_delete_link
 g_queue_find
@@ -829,6 +830,7 @@ g_queue_foreach
 g_queue_free
 g_queue_get_length
 g_queue_index
+g_queue_init
 g_queue_insert_after
 g_queue_insert_before
 g_queue_insert_sorted

glib/gqueue.c

@@ -46,7 +46,9 @@ g_queue_new (void)
  * g_queue_free:
  * @queue: a #GQueue.
  *
- * Frees the memory allocated for the #GQueue.
+ * Frees the memory allocated for the #GQueue. Only call this function if
+ * @queue was created with g_queue_new(). If queue elements contain
+ * dynamically-allocated memory, they should be freed first.
  **/
 void
 g_queue_free (GQueue *queue)
@@ -57,6 +59,44 @@ g_queue_free (GQueue *queue)
   g_slice_free (GQueue, queue);
 }
 
+/**
+ * g_queue_init:
+ * @queue: an uninitialized #GQueue
+ *
+ * A statically-allocated #GQueue must be initialized with this function
+ * before it can be used. Alternatively you can initialize it with
+ * #G_QUEUE_INIT. It is not necessary to initialize queues created with
+ * g_queue_new().
+ *
+ * Since: 2.14
+ **/
+void
+g_queue_init (GQueue *queue)
+{
+  g_return_if_fail (queue != NULL);
+
+  queue->head = queue->tail = NULL;
+  queue->length = 0;
+}
+
+/**
+ * g_queue_clear:
+ * @queue: a #GQueue
+ *
+ * Removes all the elements in @queue. If queue elements contain
+ * dynamically-allocated memory, they should be freed first.
+ *
+ * Since: 2.14
+ */
+void
+g_queue_clear (GQueue *queue)
+{
+  g_return_if_fail (queue != NULL);
+
+  g_list_free (queue->head);
+  g_queue_init (queue);
+}
+
 /**
  * g_queue_is_empty:
  * @queue: a #GQueue.

glib/gqueue.h

@@ -40,10 +40,14 @@ struct _GQueue
   guint  length;
 };
 
+#define G_QUEUE_INIT { NULL, NULL, 0 }
+
 /* Queues
  */
 GQueue*  g_queue_new            (void);
 void     g_queue_free           (GQueue           *queue);
+void     g_queue_init           (GQueue           *queue);
+void     g_queue_clear          (GQueue           *queue);
 gboolean g_queue_is_empty       (GQueue           *queue);
 guint    g_queue_get_length     (GQueue           *queue);
 void     g_queue_reverse        (GQueue           *queue);