* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* as #GList to store elements.
*
* The data contained in each element can be either integer values, by
- * using one of the <link linkend="glib-Type-Conversion-Macros">Type
- * Conversion Macros</link>, or simply pointers to any type of data.
+ * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
+ * or simply pointers to any type of data.
*
* To create a new GQueue, use g_queue_new().
*
* if @queue was created with g_queue_new(). If queue elements contain
* dynamically-allocated memory, they should be freed first.
*
- * <note><para>
- * If queue elements contain dynamically-allocated memory,
- * you should either use g_queue_free_full() or free them manually
- * first.
- * </para></note>
+ * If queue elements contain dynamically-allocated memory, you should
+ * either use g_queue_free_full() or free them manually first.
**/
void
g_queue_free (GQueue *queue)
*
* Returns the number of items in @queue.
*
- * Return value: the number of items in @queue
+ * Returns: the number of items in @queue
*
* Since: 2.4
*/
* queue consist of pointers to data, the pointers are copied, but the
* actual data is not.
*
- * Return value: a copy of @queue
+ * Returns: a copy of @queue
*
* Since: 2.4
*/
*
* Finds the first link in @queue which contains @data.
*
- * Return value: the first link in @queue which contains @data
+ * Returns: the first link in @queue which contains @data
*
* Since: 2.4
*/
* takes two gconstpointer arguments, the #GQueue element's data as the
* first argument and the given user data as the second argument.
*
- * Return value: the found link, or %NULL if it wasn't found
+ * Returns: the found link, or %NULL if it wasn't found
*
* Since: 2.4
*/
/**
* g_queue_push_head_link:
* @queue: a #GQueue
- * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- * more than one element
+ * @link_: a single #GList element, not a list with more than one element
*
* Adds a new element at the head of the queue.
*/
/**
* g_queue_push_tail_link:
* @queue: a #GQueue
- * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- * more than one element
+ * @link_: a single #GList element, not a list with more than one element
*
* Adds a new element at the tail of the queue.
*/
*
* Returns the first link in @queue.
*
- * Return value: the first link in @queue, or %NULL if @queue is empty
+ * Returns: the first link in @queue, or %NULL if @queue is empty
*
* Since: 2.4
*/
*
* Returns the last link in @queue.
*
- * Return value: the last link in @queue, or %NULL if @queue is empty
+ * Returns: the last link in @queue, or %NULL if @queue is empty
*
* Since: 2.4
*/
*
* Removes the @n'th element of @queue and returns its data.
*
- * Return value: the element's data, or %NULL if @n is off the end of @queue
+ * Returns: the element's data, or %NULL if @n is off the end of @queue
*
* Since: 2.4
*/
*
* Removes and returns the link at the given position.
*
- * Return value: the @n'th link, or %NULL if @n is off the end of @queue
+ * Returns: the @n'th link, or %NULL if @n is off the end of @queue
*
* Since: 2.4
*/
*
* Returns the link at the given position
*
- * Return value: the link at the @n'th position, or %NULL
+ * Returns: the link at the @n'th position, or %NULL
* if @n is off the end of the list
*
* Since: 2.4
*
* Returns the position of @link_ in @queue.
*
- * Return value: the position of @link_, or -1 if the link is
+ * Returns: the position of @link_, or -1 if the link is
* not part of @queue
*
* Since: 2.4
/**
* g_queue_unlink:
* @queue: a #GQueue
- * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @link_: a #GList link that must be part of @queue
*
- * Unlinks @link_ so that it will no longer be part of @queue. The link is
- * not freed.
+ * Unlinks @link_ so that it will no longer be part of @queue.
+ * The link is not freed.
*
* @link_ must be part of @queue.
*
/**
* g_queue_delete_link:
* @queue: a #GQueue
- * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @link_: a #GList link that must be part of @queue
*
* Removes @link_ from @queue and frees it.
*
*
* Returns the @n'th element of @queue.
*
- * Return value: the data for the @n'th element of @queue,
+ * Returns: the data for the @n'th element of @queue,
* or %NULL if @n is off the end of @queue
*
* Since: 2.4
*
* Returns the position of the first element in @queue which contains @data.
*
- * Return value: the position of the first element in @queue which
+ * Returns: the position of the first element in @queue which
* contains @data, or -1 if no element in @queue contains @data
*
* Since: 2.4
*
* Removes the first element in @queue that contains @data.
*
- * Return value: %TRUE if @data was found and removed from @queue
+ * Returns: %TRUE if @data was found and removed from @queue
*
* Since: 2.4
*/
*
* Remove all elements whose data equals @data from @queue.
*
- * Return value: the number of elements removed from @queue
+ * Returns: the number of elements removed from @queue
*
* Since: 2.4
*/
/**
* g_queue_insert_before:
* @queue: a #GQueue
- * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the tail of the queue.
* @data: the data to insert
*
* Inserts @data into @queue before @sibling.
*
- * @sibling must be part of @queue.
+ * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+ * data at the tail of the queue.
*
* Since: 2.4
*/
gpointer data)
{
g_return_if_fail (queue != NULL);
- g_return_if_fail (sibling != NULL);
- queue->head = g_list_insert_before (queue->head, sibling, data);
- queue->length++;
+ if (sibling == NULL)
+ {
+ /* We don't use g_list_insert_before() with a NULL sibling because it
+ * would be a O(n) operation and we would need to update manually the tail
+ * pointer.
+ */
+ g_queue_push_tail (queue, data);
+ }
+ else
+ {
+ queue->head = g_list_insert_before (queue->head, sibling, data);
+ queue->length++;
+ }
}
/**
* g_queue_insert_after:
* @queue: a #GQueue
- * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the head of the queue.
* @data: the data to insert
*
- * Inserts @data into @queue after @sibling
+ * Inserts @data into @queue after @sibling.
*
- * @sibling must be part of @queue
+ * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+ * data at the head of the queue.
*
* Since: 2.4
*/
gpointer data)
{
g_return_if_fail (queue != NULL);
- g_return_if_fail (sibling != NULL);
- if (sibling == queue->tail)
- g_queue_push_tail (queue, data);
+ if (sibling == NULL)
+ g_queue_push_head (queue, data);
else
g_queue_insert_before (queue, sibling->next, data);
}
while (list && func (list->data, data, user_data) < 0)
list = list->next;
- if (list)
- g_queue_insert_before (queue, list, data);
- else
- g_queue_push_tail (queue, data);
+ g_queue_insert_before (queue, list, data);
}
projects / platform / upstream / glib.git / blobdiff