DeeModel

## DeeModel DeeModel — A generic table model interface |

## Synopsis

    #include <dee.h>

    gint                (*DeeCompareRowFunc)                (GVariant **row1,
                                                             GVariant **row2,
                                                             gpointer user_data);
    gint                (*DeeCompareRowSizedFunc)           (GVariant **row1,
                                                             guint row1_length,
                                                             GVariant **row2,
                                                             guint row2_length,
                                                             gpointer user_data);
    struct              DeeModelIface;
                        DeeModelIter;
                        DeeModelTag;
    DeeModelIter *      dee_model_append                    (DeeModel *self,
                                                             ...);
    DeeModelIter *      dee_model_append_row                (DeeModel *self,
                                                             GVariant **row_members);
    GVariant **         dee_model_build_row                 (DeeModel *self,
                                                             GVariant **out_row_members,
                                                             ...);
    void                dee_model_clear                     (DeeModel *self);
    void                dee_model_clear_tag                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag);
    DeeModelIter *      dee_model_find_row_sorted           (DeeModel *self,
                                                             GVariant **row_spec,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found);
    DeeModelIter *      dee_model_find_row_sorted_with_sizes
                                                            (DeeModel *self,
                                                             GVariant **row_spec,
                                                             DeeCompareRowSizedFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found);
    DeeModelIter *      dee_model_find_sorted               (DeeModel *self,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found,
                                                             ...);
    void                dee_model_get                       (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);
    gboolean            dee_model_get_bool                  (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    const gchar *       dee_model_get_column_schema         (DeeModel *self,
                                                             guint column);
    gdouble             dee_model_get_double                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    DeeModelIter *      dee_model_get_first_iter            (DeeModel *self);
    gint32              dee_model_get_int32                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    gint64              dee_model_get_int64                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    DeeModelIter *      dee_model_get_iter_at_row           (DeeModel *self,
                                                             guint row);
    DeeModelIter *      dee_model_get_last_iter             (DeeModel *self);
    guint               dee_model_get_n_columns             (DeeModel *self);
    guint               dee_model_get_n_rows                (DeeModel *self);
    guint               dee_model_get_position              (DeeModel *self,
                                                             DeeModelIter *iter);
    GVariant **         dee_model_get_row                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **out_row_members);
    const gchar * const* dee_model_get_schema               (DeeModel *self,
                                                             guint *num_columns);
    const gchar *       dee_model_get_string                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    gpointer            dee_model_get_tag                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag);
    guchar              dee_model_get_uchar                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    guint32             dee_model_get_uint32                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    guint64             dee_model_get_uint64                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    GVariant *          dee_model_get_value                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);
    DeeModelIter *      dee_model_insert                    (DeeModel *self,
                                                             guint pos,
                                                             ...);
    DeeModelIter *      dee_model_insert_before             (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);
    DeeModelIter *      dee_model_insert_row                (DeeModel *self,
                                                             guint pos,
                                                             GVariant **row_members);
    DeeModelIter *      dee_model_insert_row_before         (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **row_members);
    DeeModelIter *      dee_model_insert_row_sorted         (DeeModel *self,
                                                             GVariant **row_members,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data);
    DeeModelIter *      dee_model_insert_row_sorted_with_sizes
                                                            (DeeModel *self,
                                                             GVariant **row_members,
                                                             DeeCompareRowSizedFunc cmp_func,
                                                             gpointer user_data);
    DeeModelIter *      dee_model_insert_sorted             (DeeModel *self,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             ...);
    gboolean            dee_model_is_first                  (DeeModel *self,
                                                             DeeModelIter *iter);
    gboolean            dee_model_is_last                   (DeeModel *self,
                                                             DeeModelIter *iter);
    DeeModelIter *      dee_model_next                      (DeeModel *self,
                                                             DeeModelIter *iter);
    DeeModelIter *      dee_model_prepend                   (DeeModel *self,
                                                             ...);
    DeeModelIter *      dee_model_prepend_row               (DeeModel *self,
                                                             GVariant **row_members);
    DeeModelIter *      dee_model_prev                      (DeeModel *self,
                                                             DeeModelIter *iter);
    DeeModelTag *       dee_model_register_tag              (DeeModel *self,
                                                             GDestroyNotify tag_destroy);
    void                dee_model_remove                    (DeeModel *self,
                                                             DeeModelIter *iter);
    void                dee_model_set                       (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);
    void                dee_model_set_row                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **row_members);
    void                dee_model_set_schema                (DeeModel *self,
                                                             ...);
    void                dee_model_set_schema_full           (DeeModel *self,
                                                             const gchar * const *column_schemas,
                                                             guint num_columns);
    void                dee_model_set_tag                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag,
                                                             gpointer value);
    void                dee_model_set_value                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column,
                                                             GVariant *value);

## Object Hierarchy

      GBoxed
       +----DeeModelIter

## Description

DeeModel is a generic table model that can holds GVariants as column values. Each column is restricted to hold variants with some predefined type signature. This is known as the column schema.

### Indexes - Access by Key or Full Text Analysis

Instead of forcing you to search the rows and columns for given values or patterns DeeModel is integrated with a powerful DeeIndex that allows you to create custom indexes over the model content that are updated automatically as the model changes.

Indexes can be created for integer keys, string keys (fx. URIs), or for full text search into the model contents. The indexing API is flexible and extensible and can provide huge optimizations in terms of access times if you find yourself iterating over the model searching for something.

### Sorting

As a simpler alternative to using indexes you can rely on sorted models. This is done by using the `dee_model_insert_sorted()` and `dee_model_find_sorted()` family of APIs. Some model classes have accelerated implementations of sorted inserts and lookups. Notably DeeSequenceModel.

### Tags - Attach Arbitrary Data to Rows

It's a very common pattern that you want to render a DeeModel into some view in a classinc MVC pattern. If the view needs to reflect changes in the model dynamically you often find yourself creating ad-hoc mappings between the rows of the model and the widgets in your view.

In situations where you need to pair the rows in a model with some external data structure the tags API may come in handy. It consists of the functions `dee_model_register_tag()`, `dee_model_set_tag()`, `dee_model_get_tag()`, and `dee_model_clear_tag()`.

## Details

### DeeCompareRowFunc ()

    gint                (*DeeCompareRowFunc)                (GVariant **row1,
                                                             GVariant **row2,
                                                             gpointer user_data);

Compares `row1` and `row2`. Mainly used with `dee_model_insert_sorted()` and `dee_model_find_sorted()`.

`row1` : | The model being indexed. [array]
`row2` : | The row to extract terms for. [array]
`user_data` : | User data to pass to comparison function. [closure]
Returns : | -1, 0, or 1 if `row1` is respectively less than, equal, or greater than `row2`.

### DeeCompareRowSizedFunc ()

    gint                (*DeeCompareRowSizedFunc)           (GVariant **row1,
                                                             guint row1_length,
                                                             GVariant **row2,
                                                             guint row2_length,
                                                             gpointer user_data);

Compares `row1` and `row2`. Mainly used with `dee_model_insert_row_sorted_with_sizes()` and `dee_model_find_row_sorted_with_sizes()`.

`row1` : | Row data. [array length=row1_length]
`row1_length` : | The number of elements in row1 array
`row2` : | Row data to compare with. [array length=row2_length]
`row2_length` : | The number of elements in row2 array
`user_data` : | User data passed to comparison function. [closure]
Returns : | -1, 0, or 1 if `row1` is respectively less than, equal, or greater than `row2`.

### struct DeeModelIface

    struct DeeModelIface {
      GTypeInterface g_iface;

      /* Signals */
      void           (*row_added)       (DeeModel     *self,
                                         DeeModelIter *iter);

      void           (*row_removed)     (DeeModel     *self,
                                         DeeModelIter *iter);

      void           (*row_changed)     (DeeModel     *self,
                                         DeeModelIter *iter);

      void            (*set_schema_full)    (DeeModel          *self,
                                             const char* const *column_schemas,
                                             guint              num_columns);

      const gchar* const* (*get_schema)     (DeeModel     *self,
                                             guint        *num_columns);

      const gchar*   (*get_column_schema)   (DeeModel     *self,
                                             guint         column);

      guint          (*get_n_columns)   (DeeModel *self);

      guint          (*get_n_rows)      (DeeModel *self);

      DeeModelIter*  (*append_row)    (DeeModel  *self,
                                       GVariant **row_members);

      DeeModelIter*  (*prepend_row)   (DeeModel  *self,
                                       GVariant **row_members);

      DeeModelIter*  (*insert_row)    (DeeModel  *self,
                                       guint      pos,
                                       GVariant **row_members);

      DeeModelIter*  (*insert_row_before) (DeeModel      *self,
                                           DeeModelIter  *iter,
                                           GVariant     **row_members);

      DeeModelIter*  (*insert_row_sorted)  (DeeModel           *self,
                                            GVariant          **row_members,
                                            DeeCompareRowFunc   cmp_func,
                                            gpointer            user_data);

      DeeModelIter*  (*find_row_sorted)    (DeeModel           *self,
                                            GVariant          **row_spec,
                                            DeeCompareRowFunc   cmp_func,
                                            gpointer            user_data,
                                            gboolean           *out_was_found);

      void           (*remove)          (DeeModel     *self,
                                         DeeModelIter *iter);

      void           (*clear)           (DeeModel *self);

      void           (*set_value)       (DeeModel       *self,
                                         DeeModelIter   *iter,
                                         guint           column,
                                         GVariant       *value);

      void           (*set_row)         (DeeModel       *self,
                                         DeeModelIter   *iter,
                                         GVariant      **row_members);

      GVariant*      (*get_value)       (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      DeeModelIter* (*get_first_iter)  (DeeModel     *self);

      DeeModelIter* (*get_last_iter)   (DeeModel     *self);

      DeeModelIter* (*get_iter_at_row) (DeeModel     *self,
                                        guint          row);

      gboolean       (*get_bool)        (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      guchar         (*get_uchar)       (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      gint32         (*get_int32)       (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      guint32        (*get_uint32)      (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      gint64         (*get_int64)       (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      guint64        (*get_uint64)      (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      gdouble        (*get_double)      (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      const gchar*   (*get_string)      (DeeModel     *self,
                                         DeeModelIter *iter,
                                         guint         column);

      DeeModelIter*  (*next)            (DeeModel     *self,
                                         DeeModelIter *iter);

      DeeModelIter*  (*prev)            (DeeModel     *self,
                                         DeeModelIter *iter);

      gboolean       (*is_first)        (DeeModel     *self,
                                         DeeModelIter *iter);

      gboolean       (*is_last)         (DeeModel     *self,
                                         DeeModelIter *iter);

      guint          (*get_position)    (DeeModel     *self,
                                         DeeModelIter *iter);

      DeeModelTag*   (*register_tag)    (DeeModel       *self,
                                         GDestroyNotify  tag_destroy);

      gpointer       (*get_tag)         (DeeModel       *self,
                                         DeeModelIter   *iter,
                                         DeeModelTag    *tag);

      void           (*set_tag)         (DeeModel       *self,
                                         DeeModelIter   *iter,
                                         DeeModelTag    *tag,
                                         gpointer        value);

      GVariant**     (*get_row)         (DeeModel       *self,
                                         DeeModelIter   *iter,
                                         GVariant      **out_row_members);
    };

### DeeModelIter

    typedef struct _DeeModelIter DeeModelIter;

The DeeModelIter structure is private and should only be used with the provided DeeModel API. It is owned by DeeModel and should not be freed.

### DeeModelTag

    typedef struct _DeeModelTag DeeModelTag;

The DeeModelTag structure is private and should only be used with the provided DeeModel API. It is owned by DeeModel and should not be freed.

### dee_model_append ()

    DeeModelIter *      dee_model_append                    (DeeModel *self,
                                                             ...);

Creates and appends a new row to the end of a DeeModel, setting the row values upon creation.

For and example see `dee_model_insert_before()`.

`self` : | a DeeModel
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_append_row ()

    DeeModelIter *      dee_model_append_row                (DeeModel *self,
                                                             GVariant **row_members);

Like `dee_model_append()` but intended for language bindings or situations where you work with models on a meta level and may not have a prior knowledge of the column schemas of the models. See also `dee_model_build_row()`.

`self` : | The model to prepend a row to
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_build_row ()

    GVariant **         dee_model_build_row                 (DeeModel *self,
                                                             GVariant **out_row_members,
                                                             ...);

Build an array of GVariants with values from the variadic argument list according to the model schema for `self`. The caller must call `g_variant_ref_sink()` and `g_variant_unref()` on all the returned variants and `g_free()` the array itself if `NULL` was passed as `out_row_members`.

This is utility function and will not touch or modify `self` in any way.

`self` : | The model to create a row for
`out_row_members` : | An array to write the values to or `NULL` to allocate a new array. If non-`NULL` it must have a length that is longer or equal to the number of columns in `self`
Returns : | If `out_row_members` is `NULL` a newly allocated array of variants will be returned and the array must be freed with `g_free()`. If `out_row_members` is non`NULL` it will be reused, and variants in the array may or may not have floating references, which means the caller must make sure that `g_variant_ref_sink()` and `g_variant_unref()` are called on them.

### dee_model_clear ()

    void                dee_model_clear                     (DeeModel *self);

Removes all rows in the model. Signals are emitted for each row in the model

`self` : | a DeeModel object to clear

### dee_model_clear_tag ()

    void                dee_model_clear_tag                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag);

This method is purely syntactic sugar for calling `dee_model_set_tag()` with a `value` of `NULL`. It's included in order to help developers write more readable code.

`self` : | The model to clear a tag on
`iter` : | The row to clear the tag from
`tag` : | The tag to clear from `iter`

### dee_model_find_row_sorted ()

    DeeModelIter *      dee_model_find_row_sorted           (DeeModel *self,
                                                             GVariant **row_spec,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found);

Finds a row in `self` according to the sorting specified by `cmp_func`. This method will assume that `self` is already sorted by `cmp_func`.

If you use this method for searching you should only use `dee_model_insert_row_sorted()` to insert rows in the model.

`self` : | The model to search
`row_spec` : | An array of GVariants with type signature matching those of the column schemas of `self`. No references will be taken on the variants. [array zero-terminated=1]
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
`out_was_found` : | A place to store a boolean value that will be set when this method returns. If `TRUE` then an exact match was found. If `FALSE` then the returned iter points to a row just after where `row_spec` would have been inserted. Pass `NULL` to ignore. [out]
Returns : | If `out_was_found` is set to `TRUE` then a DeeModelIter pointing to the first matching row. If it is `FALSE` then the iter pointing to the row just after where `row_spec_would` have been inserted. [transfer none][type Dee.ModelIter]

### dee_model_find_row_sorted_with_sizes ()

    DeeModelIter *      dee_model_find_row_sorted_with_sizes
                                                            (DeeModel *self,
                                                             GVariant **row_spec,
                                                             DeeCompareRowSizedFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found);

Like `dee_model_find_row_sorted()`, but uses DeeCompareRowSizedFunc and therefore doesn't cause trouble when used from introspected languages.

Finds a row in `self` according to the sorting specified by `cmp_func`. This method will assume that `self` is already sorted by `cmp_func`.

If you use this method for searching you should only use `dee_model_insert_row_sorted()` (or `dee_model_insert_row_sorted_with_sizes()`) to insert rows in the model.

`self` : | The model to search
`row_spec` : | An array of GVariants with type signature matching those of the column schemas of `self`. No references will be taken on the variants. [array zero-terminated=1]
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
`out_was_found` : | A place to store a boolean value that will be set when this method returns. If `TRUE` then an exact match was found. If `FALSE` then the returned iter points to a row just after where `row_spec` would have been inserted. Pass `NULL` to ignore. [out]
Returns : | If `out_was_found` is set to `TRUE` then a DeeModelIter pointing to the first matching row. If it is `FALSE` then the iter pointing to the row just after where `row_spec_would` have been inserted. [transfer none][type Dee.ModelIter]

### dee_model_find_sorted ()

    DeeModelIter *      dee_model_find_sorted               (DeeModel *self,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             gboolean *out_was_found,
                                                             ...);

Finds a row in `self` according to the sorting specified by `cmp_func`. This method will assume that `self` is already sorted by `cmp_func`.

If you use this method for searching you should only use `dee_model_insert_row_sorted()` to insert rows in the model.

`self` : | The model to search
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
`out_was_found` : | A place to store a boolean value that will be set when this method returns. If `TRUE` then an exact match was found. If `FALSE` then the returned iter points to a row just after where `row_spec` would have been inserted. Pass `NULL` to ignore. [out]
Returns : | If `out_was_found` is set to `TRUE` then a DeeModelIter pointing to the first matching row. If it is `FALSE` then the iter pointing to the row just after where `row_spec_would` have been inserted. [transfer none][type Dee.ModelIter]

### dee_model_get ()

    void                dee_model_get                       (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);

Gets all the values across the entire row referenced by `iter`. The variable argument list should contain pointers to variables that match the column schemas of this model.

For all basic variant types (see `g_variant_type_is_basic()`) this method expects pointers to their native C types while for all other types it expects a pointer to a pointer to a GVariant.

For string values you are passed a constant reference which is owned by the model, but any returned variants must be freed with `g_variant_unref()`.

For example, to get all values a model with signature ("u", "s", "as") you would do:

     guint32      u;
     const gchar *s;
     GVariant    *v;

     dee_model_get (model, iter, &u, &s, &v);

     // do stuff

     g_variant_unref (v);

`self` : | a DeeModel
`iter` : | a DeeModelIter

### dee_model_get_bool ()

    gboolean            dee_model_get_bool                  (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a boolean from
Returns : | if `iter` and `column` are valid, the boolean stored at `column`. Otherwise `FALSE`

### dee_model_get_column_schema ()

    const gchar *       dee_model_get_column_schema         (DeeModel *self,
                                                             guint column);

Get the GVariant signature of a column

`self` : | a DeeModel
`column` : | the column to get retrieve the GVariant type string of
Returns : | the GVariant signature of the column at index `column`

### dee_model_get_double ()

    gdouble             dee_model_get_double                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a double from
Returns : | if `iter` and `column` are valid, the double stored at `column`. Otherwise 0.

### dee_model_get_first_iter ()

    DeeModelIter *      dee_model_get_first_iter            (DeeModel *self);

Retrieves a DeeModelIter representing the first row in `self`.

`self` : | a DeeModel
Returns : | A DeeModelIter (owned by `self`, do not free it). [transfer none]

### dee_model_get_int32 ()

    gint32              dee_model_get_int32                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a int from
Returns : | if `iter` and `column` are valid, the int stored at `column`. Otherwise 0.

### dee_model_get_int64 ()

    gint64              dee_model_get_int64                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a int64 from
Returns : | if `iter` and `column` are valid, the int64 stored at `column`. Otherwise 0.

### dee_model_get_iter_at_row ()

    DeeModelIter *      dee_model_get_iter_at_row           (DeeModel *self,
                                                             guint row);

Retrieves a DeeModelIter representing the row at the given index.

Note that this method does not have any performance guarantees. In particular it is not guaranteed to be O(1).

`self` : | a DeeModel
`row` : | position of the row to retrieve
Returns : | A new DeeModelIter, or `NULL` if `row` was out of bounds. The returned iter is owned by `self`, so do not free it. [transfer none]

### dee_model_get_last_iter ()

    DeeModelIter *      dee_model_get_last_iter             (DeeModel *self);

Retrieves a DeeModelIter pointing right after the last row in `self`. This is refered to also the the end iter.

As with other iters the end iter, in particular, is stable over inserts, changes, or removals.

`self` : | a DeeModel
Returns : | A DeeModelIter (owned by `self`, do not free it). [transfer none]

### dee_model_get_n_columns ()

    guint               dee_model_get_n_columns             (DeeModel *self);

Gets the number of columns in `self`

`self` : | a DeeModel
Returns : | the number of columns per row in `self`

### dee_model_get_n_rows ()

    guint               dee_model_get_n_rows                (DeeModel *self);

Gets the number of rows in `self`

`self` : | a DeeModel
Returns : | the number of rows in `self`

### dee_model_get_position ()

    guint               dee_model_get_position              (DeeModel *self,
                                                             DeeModelIter *iter);

Get the numeric offset of `iter` into `self`. Note that this method is not guaranteed to be O(1).

`self` : | The model to inspect
`iter` : | The iter to get the position of
Returns : | The integer offset of `iter` in `self`

### dee_model_get_row ()

    GVariant **         dee_model_get_row                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **out_row_members);

`self` : | A DeeModel to get a row from
`iter` : | A DeeModelIter pointing to the row to get
`out_row_members` : | An array of variants with a length bigger than or equal to the number of columns in `self`, or `NULL`. If you pass `NULL` here a new array will be allocated for you. The returned variants will have a non-floating reference. [array][out][allow-none][default NULL]
Returns : | `out_row_members` if it was not `NULL` or a newly allocated array otherwise which you must free with `g_free()`. The variants in the array will have a strong reference and needs to be freed with `g_variant_unref()`. [array zero-terminated=1]

### dee_model_get_schema ()

    const gchar * const* dee_model_get_schema               (DeeModel *self,
                                                             guint *num_columns);

Get a `NULL`-terminated array of GVariant type strings that defines the required formats for the columns of `self`.

`self` : | The DeeModel to get the the schema for
`num_columns` : | Address of an integer in which to store the number of columns in `self`. Or `NULL` to ignore the array length. [out][allow-none]
Returns : | A `NULL`-terminated array of GVariant type strings. The length of the returned array is written to `num_columns`. The returned array should not be freed or modified. It is owned by the model. [array length=num_columns][element-type utf8][transfer none]

### dee_model_get_string ()

    const gchar *       dee_model_get_string                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a string from
Returns : | if `iter` and `column` are valid, the string stored at `column`. Otherwise `NULL`.

### dee_model_get_tag ()

    gpointer            dee_model_get_tag                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag);

Look up a tag value for a given row in a model. This method is guaranteed to be O(1).

`self` : | The model to get a tag from
`iter` : | A DeeModelIter pointing to the row to get the tag from
`tag` : | The tag handle to retrieve the tag value for
Returns : | Returns `NULL` if `tag` is unset otherwise the value of the tag as it was set with `dee_model_set_tag()`. [transfer none]

### dee_model_get_uchar ()

    guchar              dee_model_get_uchar                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a uchar from
Returns : | if `iter` and `column` are valid, the uchar stored at `column`. Otherwise 0.

### dee_model_get_uint32 ()

    guint32             dee_model_get_uint32                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a uint from
Returns : | if `iter` and `column` are valid, the uint stored at `column`. Otherwise 0.

### dee_model_get_uint64 ()

    guint64             dee_model_get_uint64                (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | the column to retrieve a uint64 from
Returns : | if `iter` and `column` are valid, the uint64 stored at `column`. Otherwise 0.

### dee_model_get_value ()

    GVariant *          dee_model_get_value                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column);

`self` : | The DeeModel to inspect
`iter` : | a DeeModelIter pointing to the row to inspect
`column` : | column number to retrieve the value from
Returns : | A, guaranteed non-floating, reference to a GVariant containing the row data. Free with `g_variant_unref()`. [transfer full]

### dee_model_insert ()

    DeeModelIter *      dee_model_insert                    (DeeModel *self,
                                                             guint pos,
                                                             ...);

Creates and inserts a new row into a DeeModel, pushing the existing rows down.

For and example see `dee_model_insert_before()`.

`self` : | a DeeModel
`pos` : | The index to insert the row on. The existing row will be pushed down
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_before ()

    DeeModelIter *      dee_model_insert_before             (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);

Creates and inserts a new row into a DeeModel just before the row pointed to by `iter`.

For example, to insert a new row in a model with schema ("u", "s", "as") you would do:

     DeeModelIter    *iter;
     GVariantBuilder  b;

     g_variant_builder_init (&b, "as");
     g_variant_builder_add (&b, "s", "Hello");
     g_variant_builder_add (&b, "s", "World");

     iter = find_my_special_row (model);
     dee_model_insert_before (model, iter,
                              27,
                              "Howdy",
                              g_variant_builder_end (&b));

`self` : | a DeeModel
`iter` : | An iter pointing to the row before which to insert the new one
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_row ()

    DeeModelIter *      dee_model_insert_row                (DeeModel *self,
                                                             guint pos,
                                                             GVariant **row_members);

As `dee_model_insert()`, but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also `dee_model_build_row()`.

`self` : | a DeeModel
`pos` : | The index to insert the row on. The existing row will be pushed down.
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_row_before ()

    DeeModelIter *      dee_model_insert_row_before         (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **row_members);

As `dee_model_insert_before()`, but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also `dee_model_build_row()`.

`self` : | a DeeModel
`iter` : | An iter pointing to the row before which to insert the new one
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_row_sorted ()

    DeeModelIter *      dee_model_insert_row_sorted         (DeeModel *self,
                                                             GVariant **row_members,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data);

Inserts a row in `self` according to the sorting specified by `cmp_func`. If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by `cmp_func`.

`self` : | The model to do a sorted insert on
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_row_sorted_with_sizes ()

    DeeModelIter *      dee_model_insert_row_sorted_with_sizes
                                                            (DeeModel *self,
                                                             GVariant **row_members,
                                                             DeeCompareRowSizedFunc cmp_func,
                                                             gpointer user_data);

Inserts a row in `self` according to the sorting specified by `cmp_func`. If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by `cmp_func`.

`self` : | The model to do a sorted insert on
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_insert_sorted ()

    DeeModelIter *      dee_model_insert_sorted             (DeeModel *self,
                                                             DeeCompareRowFunc cmp_func,
                                                             gpointer user_data,
                                                             ...);

Convenience function for calling `dee_model_insert_row_sorted()`. Inserts a row in `self` according to the sorting specified by `cmp_func`. If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by `cmp_func`.

`self` : | The model to do a sorted insert on
`cmp_func` : | Callback used for comparison or rows. [scope call]
`user_data` : | Arbitrary pointer passed to `cmp_func` during search. [closure]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_is_first ()

    gboolean            dee_model_is_first                  (DeeModel *self,
                                                             DeeModelIter *iter);

Checks if `iter` is the very first iter `self`.

`self` : | a DeeModel
`iter` : | a DeeModelIter
Returns : | TRUE if `iter` is the first iter in the model

### dee_model_is_last ()

    gboolean            dee_model_is_last                   (DeeModel *self,
                                                             DeeModelIter *iter);

Whether `iter` is the end iter of `self`. Note that the end iter points right after the last valid row in `self`.

`self` : | a DeeModel
`iter` : | a DeeModelIter
Returns : | TRUE if `iter` is the last iter in the model

### dee_model_next ()

    DeeModelIter *      dee_model_next                      (DeeModel *self,
                                                             DeeModelIter *iter);

Returns a DeeModelIter that points to the next position in the model.

`self` : | a DeeModel
`iter` : | a DeeModelIter
Returns : | A DeeModelIter, pointing to the next row in the model. The iter is owned by `self`, do not free it. [transfer none]

### dee_model_prepend ()

    DeeModelIter *      dee_model_prepend                   (DeeModel *self,
                                                             ...);

Creates and prepends a new row to the beginning of a DeeModel, setting the row values upon creation.

`self` : | a DeeModel
Returns : | A DeeModelIter pointing to the new row Example:
    DeeModel *model;
    model = ...
    dee_model_set_schema (model, "i", "s", NULL);
    dee_model_prepend (model, 10, "Rooney");
. [transfer none][type Dee.ModelIter]

### dee_model_prepend_row ()

    DeeModelIter *      dee_model_prepend_row               (DeeModel *self,
                                                             GVariant **row_members);

Like `dee_model_prepend()` but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also `dee_model_build_row()`.

`self` : | The model to prepend a row to
`row_members` : | An array of GVariants with type signature matching those of the column schemas of `self`. If any of the variants have floating references they will be consumed. [array zero-terminated=1]
Returns : | A DeeModelIter pointing to the new row. [transfer none][type Dee.ModelIter]

### dee_model_prev ()

    DeeModelIter *      dee_model_prev                      (DeeModel *self,
                                                             DeeModelIter *iter);

Returns a DeeModelIter that points to the previous position in the model.

`self` : | a DeeModel
`iter` : | a DeeModelIter
Returns : | A DeeModelIter, pointing to the previous row in the model. The iter is owned by `self`, do not free it. [transfer none]

### dee_model_register_tag ()

    DeeModelTag *       dee_model_register_tag              (DeeModel *self,
                                                             GDestroyNotify tag_destroy);

Register a new tag on a DeeModel. A tag is an extra value attached to a given row on a model. The tags are invisible to all that doesn't have the tag handle returned by this method. DeeModel implementations must ensure that `dee_model_get_tag()` is an O(1) operation.

Tags can be very useful in associating some extra data to a row in a model and have that automatically synced when the model changes. If you're writing a tiled view for a model you might want to tag each row with the tile widget for that row. That way you have very convenient access to the tile widget given any row in the model.

The private nature of tags and the fact that you can store arbitrary pointers and binary data in them also means that they are not serialized if you utilize a model implementation that exposes the DeeSerializable interface.

`self` : | The model to register a tag on
`tag_destroy` : | Function called when a tagged row is removed from the model. This function will also be called on all tagged rows when the model is finalized.
Returns : | A DeeModelTag handle that you can use to set and get tags with. [transfer none][type Dee.ModelTag]

### dee_model_remove ()

    void                dee_model_remove                    (DeeModel *self,
                                                             DeeModelIter *iter);

Removes the row at the given position from the model.

`self` : | a DeeModel
`iter` : | a DeeModelIter pointing to the row to remove

### dee_model_set ()

    void                dee_model_set                       (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             ...);

Sets all values across the entire row referenced by `iter`. The variable argument list should contain values that match the column schemas for the model. All basic variant type (see `g_variant_type_is_basic()`) are passed in as their raw C type while all other types are passed in boxed in a GVariant. Any floating references on variants passed to this method are consumed.

For example, to set the values for a row on model with the schema ("u", "s", "as"):

      GVariantBuilder b;

      g_variant_builder_init (&b, "as");
      g_variant_builder_add (&b, "Hello");
      g_variant_builder_add (&b, "World");

      dee_model_set (model, iter, 27, "foo", g_variant_builder_end (&b));

`self` : | a DeeModel
`iter` : | a DeeModelIter

### dee_model_set_row ()

    void                dee_model_set_row                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             GVariant **row_members);

Sets all columns in the row `iter` points to, to those found in `row_members`. The variants in `row_members` must match the types defined in the model's schema.

`self` : | a DeeModel
`iter` : | a DeeModelIter
`row_members` : | And array of GVariants with type signature matching those from the model schema. If any of the variants have floating references these will be consumed. [array]

### dee_model_set_schema ()

    void                dee_model_set_schema                (DeeModel *self,
                                                             ...);

Set the GVariant types and the number of columns used by `self`. This method must be called exactly once before using `self`. Note that some constructors will do this for you.

To create a model with three columns; a 32 bit integer, a string, and lastly an array of strings, you would do:

     DeeModel *model;
     model = dee_sequence_model_new ();
     dee_model_set_schema (model, "i", "s", "as", NULL);

`self` : | The DeeModel to set the column layout for

### dee_model_set_schema_full ()

    void                dee_model_set_schema_full           (DeeModel *self,
                                                             const gchar * const *column_schemas,
                                                             guint num_columns);

Set the GVariant types and the number of columns used by `self`. This method must be called exactly once before using `self`. Note that some constructors will do this for you.

`self` : | The DeeModel to set the column layout for
`column_schemas` : | A list of GVariant type strings terminated by a `NULL`. [array length=num_columns zero-terminated=1][element-type utf8][transfer none]
`num_columns` : | an integer specifying the array length for `VarArgs`

### dee_model_set_tag ()

    void                dee_model_set_tag                   (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelTag *tag,
                                                             gpointer value);

Set a tag on a row in a model. This function is guaranteed to be O(1). See also `dee_model_register_tag()`.

If `tag` is already set on this row the existing tag value will be destroyed with the GDestroyNotify passed to the `dee_model_register_tag()`.

`self` : | The model to set a tag on
`iter` : | The row to set the tag on
`tag` : | The tag handle for the tag as obtained from `dee_model_register_tag()`
`value` : | The value to set for `tag`. Note that `NULL` represents an unset tag

### dee_model_set_value ()

    void                dee_model_set_value                 (DeeModel *self,
                                                             DeeModelIter *iter,
                                                             guint column,
                                                             GVariant *value);

Sets the data in `column` for the row `iter` points to, to `value`. The type of `value` must be convertible to the type of the column.

When this method call completes the model will emit ::row-changed. You can edit the model in place without triggering the change signals by calling `dee_model_set_value_silently()`.

`self` : | a DeeModel
`iter` : | a DeeModelIter
`column` : | column number to set the value
`value` : | New value for cell. If `value` is a floating reference the model will assume ownership of the variant