gst/gstfilter.c

   1 /* GStreamer
   2  * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /**
  21  * SECTION:gstfilter
  22  * @short_description: A utility function to filter GLists.
  23  *
  24  * <example>
  25  * <title>Filtering a list</title>
  26  *   <programlisting>
  27  *     GList *node;
  28  *     GstObject *result = NULL;
  29  *
  30  *     node = gst_filter_run (list, (GstFilterFunc) my_filter, TRUE, NULL);
  31  *     if (node) {
  32  *       result = GST_OBJECT (node->data);
  33  *       gst_object_ref (result);
  34  *       g_list_free (node);
  35  *     }
  36  *   </programlisting>
  37  * </example>
  38  */
  39 #include "gst_private.h"
  40 #include <gst/gstfilter.h>
  41
  42 /**
  43  * gst_filter_run:
  44  * @list: a linked list
  45  * @func: (scope call): the function to execute for each item
  46  * @first: flag to stop execution after a successful item
  47  * @user_data: (closure): user data
  48  *
  49  * Iterates over the elements in @list, calling @func with the
  50  * list item data for each item.  If @func returns TRUE, @data is
  51  * prepended to the list of results returned.  If @first is true,
  52  * the search is halted after the first result is found.
  53  *
  54  * Since gst_filter_run() knows nothing about the type of @data, no
  55  * reference will be taken (if @data refers to an object) and no copy of
  56  * @data wil be made in any other way when prepending @data to the list of
  57  * results.
  58  *
  59  * Returns: (transfer container): the list of results. Free with g_list_free()
  60  *     when no longer needed (the data contained in the list is a flat copy
  61  *     and does need to be unreferenced or freed).
  62  */
  63 GList *
  64 gst_filter_run (const GList * list, GstFilterFunc func, gboolean first,
  65     gpointer user_data)
  66 {
  67   const GList *walk = list;
  68   GList *result = NULL;
  69
  70   while (walk) {
  71     gboolean res = TRUE;
  72     gpointer data = walk->data;
  73
  74     walk = g_list_next (walk);
  75
  76     if (func)
  77       res = func (data, user_data);
  78
  79     if (res) {
  80       result = g_list_prepend (result, data);
  81
  82       if (first)
  83         break;
  84     }
  85   }
  86
  87   return result;
  88 }