## GdaDataModelIter GdaDataModelIter — Data model iterator |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaDataModelIter;
    const GValue *      gda_data_model_iter_get_value_at    (GdaDataModelIter *iter,
                                                             gint col);
    const GValue *      gda_data_model_iter_get_value_at_e  (GdaDataModelIter *iter,
                                                             gint col,
                                                             GError **error);
    const GValue *      gda_data_model_iter_get_value_for_field
                                                            (GdaDataModelIter *iter,
                                                             const gchar *field_name);
    gboolean            gda_data_model_iter_set_value_at    (GdaDataModelIter *iter,
                                                             gint col,
                                                             const GValue *value,
                                                             GError **error);
    gboolean            gda_data_model_iter_is_valid        (GdaDataModelIter *iter);
    gboolean            gda_data_model_iter_move_to_row     (GdaDataModelIter *iter,
                                                             gint row);
    gboolean            gda_data_model_iter_move_next       (GdaDataModelIter *iter);
    gboolean            gda_data_model_iter_move_prev       (GdaDataModelIter *iter);
    gint                gda_data_model_iter_get_row         (GdaDataModelIter *iter);
    GdaHolder *         gda_data_model_iter_get_holder_for_field
                                                            (GdaDataModelIter *iter,
                                                             gint col);
    void                gda_data_model_iter_invalidate_contents
                                                            (GdaDataModelIter *iter);

## Object Hierarchy

      GObject
       +----GdaSet
             +----GdaDataModelIter

## Properties

      "current-row"              gint                  : Read / Write
      "data-model"               GdaDataModel*         : Read / Write / Construct
      "forced-model"             GdaDataModel*         : Read / Write
      "update-model"             gboolean              : Read / Write

## Signals

      "end-of-data"                                    : Run First
      "row-changed"                                    : Run First

## Description

A GdaDataModelIter object is used to iterate through the rows of a GdaDataModel. If the data model is accessible in a random access way then any number of GdaDataModelIter objects can be created on the same data model, and if the data model only supports a cursor based access then only one GdaDataModelIter can be created. In any case creating a GdaDataModelIter should be done using the `gda_data_model_create_iter()` method. Note that if the data model only supports a cursor based access, then calling this method several times will always return the same GdaDataModelIter, but with its reference count increased by 1 (so you should call `g_object_unref()` when finished with it).

When a GdaDataModelIter is valid (that is when it points to an existing row in the data model it iterates through), the individual values (corresponding to each column of the data model, at the pointer row) can be accessed using the `gda_data_model_iter_get_value_at()` or `gda_data_model_iter_get_value_for_field()` methods (or in the same way GdaSet's values are accessed as GdaDataModelIter inherits the GdaSet).

Right after being created, a GdaDataModelIter is invalid (does not point to any row of its data model). To read the first row of the data model, use the `gda_data_model_iter_move_next()` method. Calling this method several times will move the iterator forward, up to when the data model has no more rows and the GdaDataModelIter will be declared invalid (and `gda_data_model_iter_move_next()` has returned FALSE). Note that at this point, the number of rows in the data model will be known.

If the data model supports it, a GdaDataModelIter can be moved backwards using the `gda_data_model_iter_move_prev()` method. However if the iterator is invalid, moving backwards will not be possible (on the contrary to `gda_data_model_iter_move_next()` which moves to the first row).

The `gda_data_model_iter_move_to_row()` method, if the iterator can be moved both forward and backwards, can move the iterator to a specific row (sometimes faster than moving it forward or backwards a number of times).

The following figure illustrates the GdaDataModelIter usage:

Note: the new GdaDataModelIter does not hold any reference to the data model it iterates through (ie. if this data model is destroyed at some point, the new iterator will become useless but in any case it will not prevent the data model from being destroyed).

Note: when the data model emits the "reset" signal, then:

- the number of columns of the iterator can change to reflect the new data model being itered on. In this case the iterator's position is reset as if it was just created

- some column types which were unknown (i.e. GDA_TYPE_NULL type), can change to their correct type. In this case there is no other iterator change

- some column types which were not GDA_TYPE_NULL can change, and in this case the iterator's position is reset as if it was just created

## Details

### GdaDataModelIter

    typedef struct _GdaDataModelIter GdaDataModelIter;

### gda_data_model_iter_get_value_at ()

    const GValue *      gda_data_model_iter_get_value_at    (GdaDataModelIter *iter,
                                                             gint col);

Get the value stored at the column `col` in `iter`. The returned value must not be modified.

`iter` : | a GdaDataModelIter object
`col` : | the requested column
Returns : | the GValue, or `NULL` if the value could not be fetched. [transfer none]

### gda_data_model_iter_get_value_at_e ()

    const GValue *      gda_data_model_iter_get_value_at_e  (GdaDataModelIter *iter,
                                                             gint col,
                                                             GError **error);

Get the value stored at the column `col` in `iter`. The returned value must not be modified.

`iter` : | a GdaDataModelIter object
`col` : | the requested column
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | the GValue, or `NULL` if the value could not be fetched. [transfer none]

Since 4.2.10

### gda_data_model_iter_get_value_for_field ()

    const GValue *      gda_data_model_iter_get_value_for_field
                                                            (GdaDataModelIter *iter,
                                                             const gchar *field_name);

Get the value stored at the column `field_name` in `iter`

`iter` : | a GdaDataModelIter object
`field_name` : | the requested column name
Returns : | the GValue, or `NULL`. [transfer none]

### gda_data_model_iter_set_value_at ()

    gboolean            gda_data_model_iter_set_value_at    (GdaDataModelIter *iter,
                                                             gint col,
                                                             const GValue *value,
                                                             GError **error);

Sets a value in `iter`, at the column specified by `col`

`iter` : | a GdaDataModelIter object
`col` : | the column number
`value` : | a GValue (not `NULL`)
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_data_model_iter_is_valid ()

    gboolean            gda_data_model_iter_is_valid        (GdaDataModelIter *iter);

Tells if `iter` is a valid iterator (if it actually corresponds to a valid row in the model)

`iter` : | a GdaDataModelIter object
Returns : | TRUE if `iter` is valid

### gda_data_model_iter_move_to_row ()

    gboolean            gda_data_model_iter_move_to_row     (GdaDataModelIter *iter,
                                                             gint row);

Synchronizes the values of the parameters in `iter` with the values at the `row` row.

If `row` is not a valid row, then the returned value is `FALSE`, and the "current-row" property is set to -1 (which means that `gda_data_model_iter_is_valid()` would return `FALSE`), with the exception that if `row` is -1, then the returned value is `TRUE`.

This function can return `FALSE` if it was not allowed to be moved (as it emits the "validate-set" signal before being moved).

When this function returns `TRUE`, then `iter` has actually been moved to the next row, but some values may not have been read correctly in the row, in which case the correcsponding GdaHolder will be left invalid.

`iter` : | a GdaDataModelIter object
`row` : | the row to set `iter` to
Returns : | `TRUE` if no error occurred

### gda_data_model_iter_move_next ()

    gboolean            gda_data_model_iter_move_next       (GdaDataModelIter *iter);

Moves `iter` one row further than where it already is (synchronizes the values of the parameters in `iter` with the values at the new row).

If the iterator was on the data model's last row, then it can't be moved forward anymore, and the returned value is `FALSE`; note also that the "current-row" property is set to -1 (which means that `gda_data_model_iter_is_valid()` would return `FALSE`)

This function can return `FALSE` if it was not allowed to be moved (as it emits the "validate-set" signal before being moved).

When this function returns `TRUE`, then `iter` has actually been moved to the next row, but some values may not have been read correctly in the row, in which case the correcsponding GdaHolder will be left invalid.

`iter` : | a GdaDataModelIter object
Returns : | `TRUE` if the iterator is now at the next row

### gda_data_model_iter_move_prev ()

    gboolean            gda_data_model_iter_move_prev       (GdaDataModelIter *iter);

Moves `iter` one row before where it already is (synchronizes the values of the parameters in `iter` with the values at the new row).

If the iterator was on the data model's first row, then it can't be moved backwards anymore, and the returned value is `FALSE`; note also that the "current-row" property is set to -1 (which means that `gda_data_model_iter_is_valid()` would return `FALSE`).

This function can return `FALSE` if it was not allowed to be moved (as it emits the "validate-set" signal before being moved).

When this function returns `TRUE`, then `iter` has actually been moved to the next row, but some values may not have been read correctly in the row, in which case the correcsponding GdaHolder will be left invalid.

`iter` : | a GdaDataModelIter object
Returns : | `TRUE` if the iterator is now at the previous row

### gda_data_model_iter_get_row ()

    gint                gda_data_model_iter_get_row         (GdaDataModelIter *iter);

Get the row which `iter` represents in the data model

`iter` : | a GdaDataModelIter object
Returns : | the row number, or -1 if `iter` is invalid

### gda_data_model_iter_get_holder_for_field ()

    GdaHolder *         gda_data_model_iter_get_holder_for_field
                                                            (GdaDataModelIter *iter,
                                                             gint col);

Fetch a pointer to the GdaHolder object which is synchronized with data at column `col`

`iter` : | a GdaDataModelIter object
`col` : | the requested column
Returns : | the GdaHolder, or `NULL` if an error occurred. [transfer none]

### gda_data_model_iter_invalidate_contents ()

    void                gda_data_model_iter_invalidate_contents
                                                            (GdaDataModelIter *iter);

Declare all the parameters in `iter` invalid, without modifying the GdaDataModel `iter` is for or changing the row it represents. This method is for internal usage. Note that for `gda_data_model_iter_is_valid()` to return `FALSE`, it is also necessary to set the "current-row" property to -1.

`iter` : | a GdaDataModelIter object

## Property Details

### The `"current-row"` property

      "current-row"              gint                  : Read / Write

Current represented row in the data model.

Allowed values: >= -1

Default value: -1

### The `"data-model"` property

      "data-model"               GdaDataModel*         : Read / Write / Construct

Data model for which the iter is for.

### The `"forced-model"` property

      "forced-model"             GdaDataModel*         : Read / Write

Overrides the data model the iter is attached to (reserved for internal usage).

### The `"update-model"` property

      "update-model"             gboolean              : Read / Write

Default value: TRUE

## Signal Details

### The `"end-of-data"` signal

    void                user_function                      (GdaDataModelIter *iter,
                                                            gpointer          user_data)      : Run First

Gets emitted when `iter` has reached the end of available data (which means the previous row it was on was the last one).

`iter` : | the GdaDataModelIter
`user_data` : | user data set when the signal handler was connected.

### The `"row-changed"` signal

    void                user_function                      (GdaDataModelIter *iter,
                                                            gint              row,
                                                            gpointer          user_data)      : Run First

Gets emitted when the row `iter` is currently pointing has changed

`iter` : | the GdaDataModelIter
`row` : | the new iter's row
`user_data` : | user data set when the signal handler was connected.

## See Also

GdaDataModel