Filters

## Filters Filters — A suite of simple DeeFilters for use with DeeFilterModels |

## Synopsis

    #include <dee.h>

                        DeeFilter;
    void                (*DeeFilterMapFunc)                 (DeeModel *orig_model,
                                                             DeeFilterModel *filter_model,
                                                             gpointer user_data);
    gboolean            (*DeeFilterMapNotify)               (DeeModel *orig_model,
                                                             DeeModelIter *orig_iter,
                                                             DeeFilterModel *filter_model,
                                                             gpointer user_data);
    void                dee_filter_destroy                  (DeeFilter *filter);
    void                dee_filter_map                      (DeeFilter *filter,
                                                             DeeModel *orig_model,
                                                             DeeFilterModel *filter_model);
    void                dee_filter_new                      (DeeFilterMapFunc map_func,
                                                             DeeFilterMapNotify map_notify,
                                                             gpointer userdata,
                                                             GDestroyNotify destroy,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_collator             (guint column,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_collator_desc        (guint column,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_for_any_column       (guint column,
                                                             GVariant *value,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_for_key_column       (guint column,
                                                             const gchar *key,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_regex                (guint column,
                                                             GRegex *regex,
                                                             DeeFilter *out_filter);
    void                dee_filter_new_sort                 (DeeCompareRowFunc cmp_row,
                                                             gpointer cmp_user_data,
                                                             GDestroyNotify cmp_destroy,
                                                             DeeFilter *out_filter);
    gboolean            dee_filter_notify                   (DeeFilter *filter,
                                                             DeeModelIter *orig_iter,
                                                             DeeModel *orig_model,
                                                             DeeFilterModel *filter_model);

## Description

DeeFilters are used together with DeeFilterModels to build "views" of some original DeeModel. An example could be to build a view of a model that exposes the rows of the original model sorted by a given column (leaving the original model unaltered):

      DeeModel  *model, *view;
      DeeFilter *collator;

      // Create and populate a model with some unsorted rows
      model = dee_sequence_model_new ();
      dee_model_set_schema (model, "i", "s", NULL);
      dee_model_append (model, 27, "Foo");
      dee_model_append (model, 68, "Bar");

      // Create a collator for column 1
      collator = dee_filter_new_collator (1);

      // Create the sorted view
      view = dee_filter_model_new (collator, model);
      g_free (collator);

      // When accessing the view the row with 'Bar' will be first

## Details

### DeeFilter

    typedef struct {
      DeeFilterMapFunc   map_func;
      DeeFilterMapNotify map_notify;
      GDestroyNotify     destroy;
      gpointer           userdata;
    } DeeFilter;

Structure encapsulating the mapping logic used to construct a DeeFilterModel

DeeFilterMapFunc `map_func`; | The DeeModelMapFunc used to construct the initial contents of a DeeFilterModel. [scope notified]
DeeFilterMapNotify `map_notify`; | Callback invoked when the original model changes. [scope notified]
GDestroyNotify `destroy`; | Callback for freeing the `user_data` `userdata` (closure): Free form user data associated with the filter. This pointer will be passed to `map_func` and `map_notify`
gpointer `userdata`; |

### DeeFilterMapFunc ()

    void                (*DeeFilterMapFunc)                 (DeeModel *orig_model,
                                                             DeeFilterModel *filter_model,
                                                             gpointer user_data);

Function used to collect the rows from a model that should be included in a DeeFilterModel. To add rows to `filter_model` use the methods `dee_filter_model_append_iter()`, `dee_filter_model_prepend_iter()`, `dee_filter_model_insert_iter()`, and `dee_filter_model_insert_iter_before()`.

The iteration over the original model is purposely left to the map func in order to allow optimized iterations if the the caller has a priori knowledge of the sorting and grouping of the data in the original model.

`orig_model` : | The model containing the original data to filter
`filter_model` : | The model that will contain the filtered results. The filter func must iterate over `orig_model` and add all relevant rows to `filter_model`. This model is guaranteed to be empty when the filter func is invoked
`user_data` : | User data passed together with the filter func. [closure]

### DeeFilterMapNotify ()

    gboolean            (*DeeFilterMapNotify)               (DeeModel *orig_model,
                                                             DeeModelIter *orig_iter,
                                                             DeeFilterModel *filter_model,
                                                             gpointer user_data);

Callback invoked when a row is added to `orig_model`. To add rows to `filter_model` use the methods `dee_filter_model_append_iter()`, `dee_filter_model_prepend_iter()`, `dee_filter_model_insert_iter()`, and `dee_filter_model_insert_iter_before()`.

`orig_model` : | The model containing the added row
`orig_iter` : | A DeeModelIter pointing to the new row in `orig_model`
`filter_model` : | The model that was also passed to the DeeModelMapFunc of the DeeFilter this functions is a part of
`user_data` : | User data for the DeeFilter. [closure]
Returns : | `TRUE` if `orig_iter` was added to `filter_model`

### dee_filter_destroy ()

    void                dee_filter_destroy                  (DeeFilter *filter);

Call the GDestroyNotify function on the userdata pointer of a DeeFilter (if the destroy member is set, that is).

When using a DeeFilterModel you should not call this method yourself.

This method will not free the memory allocated for `filter`.

`filter` : | The filter to destroy

### dee_filter_map ()

    void                dee_filter_map                      (DeeFilter *filter,
                                                             DeeModel *orig_model,
                                                             DeeFilterModel *filter_model);

Call the DeeFilterMapFunc function of a DeeFilter. When using a DeeFilterModel you should not call this method yourself.

`filter` : | The filter to apply
`orig_model` : | The model that is being filtered
`filter_model` : | The DeeFilterModel that holds the filtered subset of `orig_model`

### dee_filter_new ()

    void                dee_filter_new                      (DeeFilterMapFunc map_func,
                                                             DeeFilterMapNotify map_notify,
                                                             gpointer userdata,
                                                             GDestroyNotify destroy,
                                                             DeeFilter *out_filter);

Create a new DeeFilter with the given parameters. This call will zero the `out_filter` struct.

`map_func` : | The DeeFilterMapFunc to use for the filter. [scope notified]
`map_notify` : | The DeeFilterMapNotify to use for the filter. [scope notified]
`userdata` : | The user data to pass to `map_func` and `map_notify`. [closure]
`destroy` : | The GDestroyNotify to call on `userdata` when disposing of the filter. [allow-none]
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_collator ()

    void                dee_filter_new_collator             (guint column,
                                                             DeeFilter *out_filter);

Create a DeeFilter that takes string values from a column in the model and builds a DeeFilterModel with the rows sorted according to the collation rules of the current locale.

`column` : | The index of a column containing the strings to sort after
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_collator_desc ()

    void                dee_filter_new_collator_desc        (guint column,
                                                             DeeFilter *out_filter);

Create a DeeFilter that takes string values from a column in the model and builds a DeeFilterModel with the rows sorted descending according to the collation rules of the current locale.

`column` : | The index of a column containing the strings to sort after
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_for_any_column ()

    void                dee_filter_new_for_any_column       (guint column,
                                                             GVariant *value,
                                                             DeeFilter *out_filter);

Create a DeeFilter that only includes rows from the original model which match a variant value in a given column. A DeeFilterModel created with this filter will be ordered in accordance with its parent model.

This method will work on any column, disregarding its schema, since the value comparison is done using `g_variant_equal()`. This means you can use this filter as a convenient fallback when there is no predefined filter for your column type if raw performance is not paramount.

`column` : | The index of a column containing the string to match
`value` : | A GVariant value columns must match exactly. The matching semantics are those of `g_variant_equal()`. If `value` is floating the ownership will be transfered to the filter. [transfer none]
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_for_key_column ()

    void                dee_filter_new_for_key_column       (guint column,
                                                             const gchar *key,
                                                             DeeFilter *out_filter);

Create a DeeFilter that only includes rows from the original model which has an exact match on some string column. A DeeFilterModel created with this filter will be ordered in accordance with its parent model.

`column` : | The index of a column containing the string key to match
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_regex ()

    void                dee_filter_new_regex                (guint column,
                                                             GRegex *regex,
                                                             DeeFilter *out_filter);

Create a DeeFilter that only includes rows from the original model which match a regular expression on some string column. A DeeFilterModel created with this filter will be ordered in accordance with its parent model.

`column` : | The index of a column containing the string to match
`regex` : | The regular expression `column` must match. [transfer none]
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_new_sort ()

    void                dee_filter_new_sort                 (DeeCompareRowFunc cmp_row,
                                                             gpointer cmp_user_data,
                                                             GDestroyNotify cmp_destroy,
                                                             DeeFilter *out_filter);

Create a new DeeFilter sorting a model according to a DeeCompareRowFunc.

`cmp_row` : | A DeeCompareRowFunc to use for sorting. [scope notified]
`cmp_user_data` : | User data passed to `cmp_row`. [closure]
`cmp_destroy` : | The GDestroyNotify to call on `cmp_user_data` when disposing of the filter. [allow-none]
`out_filter` : | A pointer to an uninitialized DeeFilter struct. This struct will zeroed and configured with the filter parameters. [out]

### dee_filter_notify ()

    gboolean            dee_filter_notify                   (DeeFilter *filter,
                                                             DeeModelIter *orig_iter,
                                                             DeeModel *orig_model,
                                                             DeeFilterModel *filter_model);

Call the DeeFilterMapNotify function of a DeeFilter. When using a DeeFilterModel you should not call this method yourself.

`filter` : | The filter to apply
`orig_iter` : | The DeeModelIter added to `orig_model`
`orig_model` : | The model that is being filtered
`filter_model` : | The DeeFilterModel that holds the filtered subset of `orig_model`
Returns : | The return value from the DeeFilterMapNotify. That is; `TRUE` if `orig_iter` was added to `filter_model`