GdaDataModelIter

GdaDataModelIter — Data model iterator

Stability Level

Stable, unless otherwise indicated

Functions

const GValue * gda_data_model_iter_get_value_at ()
const GValue * gda_data_model_iter_get_value_at_e ()
const GValue * gda_data_model_iter_get_value_for_field ()
gboolean gda_data_model_iter_set_value_at ()
gboolean gda_data_model_iter_is_valid ()
gboolean gda_data_model_iter_move_to_row ()
gboolean gda_data_model_iter_move_next ()
gboolean gda_data_model_iter_move_prev ()
gint gda_data_model_iter_get_row ()
GdaHolder * gda_data_model_iter_get_holder_for_field ()
void gda_data_model_iter_invalidate_contents ()

Properties

int current-row Read / Write
GdaDataModel * data-model Read / Write / Construct
GdaDataModel * forced-model Read / Write
gboolean update-model Read / Write

Signals

void end-of-data Run First
void row-changed Run First

Types and Values

  GdaDataModelIter

Object Hierarchy

    GObject
    ╰── GdaSet
        ╰── GdaDataModelIter

Includes

#include <virtual/gda-ldap-connection.h>

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:

GdaDataModelIter's 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

Functions

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.

Parameters

iter

a GdaDataModelIter object

  

col

the requested column

  

Returns

the GValue, or NULL if the value could not be fetched.

[allow-none][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.

Parameters

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.

[allow-none][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

Parameters

iter

a GdaDataModelIter object

  

field_name

the requested column name

  

Returns

the GValue, or NULL.

[allow-none][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

Parameters

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)

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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.

Parameters

iter

a GdaDataModelIter object

  

Types and Values

GdaDataModelIter

typedef struct _GdaDataModelIter GdaDataModelIter;

Property Details

The “current-row” property

  “current-row”              int

Current represented row in the data model.

Owner: GdaDataModelIter

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The “data-model” property

  “data-model”               GdaDataModel *

Data model for which the iter is for.

Owner: GdaDataModelIter

Flags: Read / Write / Construct

The “forced-model” property

  “forced-model”             GdaDataModel *

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

Owner: GdaDataModelIter

Flags: Read / Write

The “update-model” property

  “update-model”             gboolean

Owner: GdaDataModelIter

Flags: Read / Write

Default value: TRUE

Signal Details

The “end-of-data” signal

void
user_function (GdaDataModelIter *iter,
               gpointer          user_data)

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

Parameters

iter

the GdaDataModelIter

  

user_data

user data set when the signal handler was connected.

  

Flags: Run First

The “row-changed” signal

void
user_function (GdaDataModelIter *iter,
               int               row,
               gpointer          user_data)

Gets emitted when the row iter is currently pointing has changed

Parameters

iter

the GdaDataModelIter

  

row

the new iter's row

  

user_data

user data set when the signal handler was connected.

  

Flags: Run First

See Also

GdaDataModel

Generated by GTK-Doc V1.33.1