## GstFilter

GstFilter — A utility function to filter GLists.

## Synopsis

    #include <gst/gst.h>

    gboolean            (*GstFilterFunc)                    (gpointer obj,
                                                             gpointer user_data);
    GList*              gst_filter_run                      (const GList *list,
                                                             GstFilterFunc func,
                                                             gboolean first,
                                                             gpointer user_data);

## Description

Example 12. Filtering a list

    1
    2
    3
    4
    5
    6
    7
    8
    9

    GList *node;
    GstObject *result = NULL;

    node = gst_filter_run (list, (GstFilterFunc) my_filter, TRUE, NULL);
    if (node) {
      result = GST_OBJECT (node->data);
      gst_object_ref (result);
      g_list_free (node);
    }

## Details

### GstFilterFunc ()

    gboolean            (*GstFilterFunc)                    (gpointer obj,
                                                             gpointer user_data);

Function prototype for a filter callback taht can be use in `gst_filter_run()`. The function should apply its filtering to `obj`. Additional data passed to `gst_filter_run()` are in `data`.

`obj` : | the object
`user_data` : | filter data
Returns : | `TRUE` for success.

### gst_filter_run ()

    GList*              gst_filter_run                      (const GList *list,
                                                             GstFilterFunc func,
                                                             gboolean first,
                                                             gpointer user_data);

Iterates over the elements in `list`, calling `func` with the list item data for each item. If `func` returns TRUE, `data` is prepended to the list of results returned. If `first` is true, the search is halted after the first result is found.

Since `gst_filter_run()` knows nothing about the type of `data`, no reference will be taken (if `data` refers to an object) and no copy of `data` wil be made in any other way when prepending `data` to the list of results.

`list` : | a linked list
`func` : | the function to execute for each item
`first` : | flag to stop execution after a successful item
`user_data` : | user data
Returns : | the list of results. Free with `g_list_free()` when no longer needed (the data contained in the list is a flat copy and does need to be unreferenced or freed).