GdaDataModel

## GdaDataModel GdaDataModel — Basic data model class |

## Synopsis

                GdaDataModel;
    enum        GdaDataModelAccessFlags;
    enum        GdaDataModelHint;
    enum        GdaDataModelIOFormat;
    void        gda_data_model_changed          (GdaDataModel *model);
    void        gda_data_model_row_inserted     (GdaDataModel *model,
                                                 gint row);
    void        gda_data_model_row_updated      (GdaDataModel *model,
                                                 gint row);
    void        gda_data_model_row_removed      (GdaDataModel *model,
                                                 gint row);
    void        gda_data_model_freeze           (GdaDataModel *model);
    void        gda_data_model_thaw             (GdaDataModel *model);
    guint       gda_data_model_get_access_flags (GdaDataModel *model);
    gint        gda_data_model_get_n_rows       (GdaDataModel *model);
    gint        gda_data_model_get_n_columns    (GdaDataModel *model);
    GdaColumn*  gda_data_model_describe_column  (GdaDataModel *model,
                                                 gint col);
    const gchar* gda_data_model_get_column_title
                                                (GdaDataModel *model,
                                                 gint col);
    void        gda_data_model_set_column_title (GdaDataModel *model,
                                                 gint col,
                                                 const gchar *title);
    const GdaValue* gda_data_model_get_value_at (GdaDataModel *model,
                                                 gint col,
                                                 gint row);
    gboolean    gda_data_model_set_value_at     (GdaDataModel *model,
                                                 gint col,
                                                 gint row,
                                                 const GdaValue *value,
                                                 GError **error);
    GdaDataModelIter* gda_data_model_create_iter
                                                (GdaDataModel *model);
    gboolean    gda_data_model_move_iter_at_row (GdaDataModel *model,
                                                 GdaDataModelIter *iter,
                                                 gint row);
    gboolean    gda_data_model_move_iter_next   (GdaDataModel *model,
                                                 GdaDataModelIter *iter);
    gboolean    gda_data_model_move_iter_prev   (GdaDataModel *model,
                                                 GdaDataModelIter *iter);
    gint        gda_data_model_append_values    (GdaDataModel *model,
                                                 const GList *values,
                                                 GError **error);
    gint        gda_data_model_append_row       (GdaDataModel *model,
                                                 GError **error);
    gboolean    gda_data_model_remove_row       (GdaDataModel *model,
                                                 gint row,
                                                 GError **error);
    gint        gda_data_model_get_row_from_values
                                                (GdaDataModel *model,
                                                 GSList *values,
                                                 gint *cols_index);
    void        gda_data_model_send_hint        (GdaDataModel *model,
                                                 GdaDataModelHint hint,
                                                 const GdaValue *hint_value);
    gchar*      gda_data_model_export_to_string (GdaDataModel *model,
                                                 GdaDataModelIOFormat format,
                                                 const gint *cols,
                                                 gint nb_cols,
                                                 GdaParameterList *options);
    gboolean    gda_data_model_export_to_file   (GdaDataModel *model,
                                                 GdaDataModelIOFormat format,
                                                 const gchar *file,
                                                 const gint *cols,
                                                 gint nb_cols,
                                                 GdaParameterList *options,
                                                 GError **error);
    gboolean    gda_data_model_import_from_model
                                                (GdaDataModel *to,
                                                 GdaDataModel *from,
                                                 GHashTable *cols_trans,
                                                 GError **error);
    gboolean    gda_data_model_import_from_string
                                                (GdaDataModel *model,
                                                 const gchar *string,
                                                 GHashTable *cols_trans,
                                                 GdaParameterList *options,
                                                 GError **error);
    gboolean    gda_data_model_import_from_file (GdaDataModel *model,
                                                 const gchar *file,
                                                 GHashTable *cols_trans,
                                                 GdaParameterList *options,
                                                 GError **error);
    void        gda_data_model_dump             (GdaDataModel *model,
                                                 FILE *to_stream);
    gchar*      gda_data_model_dump_as_string   (GdaDataModel *model);

## Object Hierarchy

      GInterface
       +----GdaDataModel

## Prerequisites

GdaDataModel requires GdaObject.

## Known Implementations

GdaDataModel is implemented by GdaDataModelFilterSQL, GdaDataProxy, GdaDataModelQuery, GdaDataModelRow, GdaDataAccessWrapper, GdaDataModelImport, GdaDataModelArray and GdaDataModelHash.

## Signal Prototypes

    "row-inserted"
                void        user_function      (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);
    "row-removed"
                void        user_function      (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);
    "row-updated"
                void        user_function      (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);

## Description

A GdaDataMode represents an array of values organized in rows and columns. All the data in the same column have the same type, and all the data in each row have the same semantic meaning. The GdaDataModel is actually an interface implemented by other objects to support various kinds of data storage and operations.

Depending on the real implementation, the contents of data models may be modified by the user using functions provided by the model. The actual operations a data model permits can be known using the `gda_data_model_get_access_flags()` method.

Again, depending on the real implementation, data retreiving can be done either accessing direct random values located by their row and column, or using a GdaDataModelIter cursor, or both. Use the `gda_data_model_get_access_flags()` method to know how the data model can be accessed. Note that a GdaDatamodel which can be accessed in a random way can also be accessed using cursors (and several cusrors may be used at the same time), whereas data model which can only be accessed using cursors can only have one cursor for iterating.

Random access data models are easier to use since picking a value is very simple using the `gda_data_model_get_value_at()`, but consume more memory since all the accessible values must generally be present in memory even if they are not used. Thus if a data model must handle large quantities of data, it is generally wiser to use a data model which can be only accessed using a cursor.

As a side note there are also data models which wrap other data models such as:

- The GdaDataProxy data model which stores temporary modifications and shows only some parts of the wrapped data model

- The GdaDataAccessWrapper data model which offers a memory-efficient random access on top of a wrapped cursor based access data model

## Details

### GdaDataModel

    typedef struct _GdaDataModel GdaDataModel;

### enum GdaDataModelAccessFlags

    typedef enum {
    	GDA_DATA_MODEL_ACCESS_RANDOM = 1 << 0,
    	GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD = 1 << 1,
    	GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD = 1 << 2,
    	GDA_DATA_MODEL_ACCESS_INSERT  = 1 << 3,
    	GDA_DATA_MODEL_ACCESS_UPDATE  = 1 << 4,
    	GDA_DATA_MODEL_ACCESS_DELETE  = 1 << 5,
    	GDA_DATA_MODEL_ACCESS_WRITE = GDA_DATA_MODEL_ACCESS_INSERT | GDA_DATA_MODEL_ACCESS_UPDATE |
    	GDA_DATA_MODEL_ACCESS_DELETE,
    } GdaDataModelAccessFlags;

### enum GdaDataModelHint

    typedef enum {
    	GDA_DATA_MODEL_HINT_START_BATCH_UPDATE,
    	GDA_DATA_MODEL_HINT_END_BATCH_UPDATE,
    	GDA_DATA_MODEL_HINT_REFRESH,
    } GdaDataModelHint;

### enum GdaDataModelIOFormat

    typedef enum {
    	GDA_DATA_MODEL_IO_DATA_ARRAY_XML,
    	GDA_DATA_MODEL_IO_TEXT_SEPARATED,
    } GdaDataModelIOFormat;

### gda_data_model_changed ()

    void        gda_data_model_changed          (GdaDataModel *model);

Notifies listeners of the given data model object of changes in the underlying data. Listeners usually will connect themselves to the "changed" signal in the GdaDataModel class, thus being notified of any new data being appended or removed from the data model.

`model` : | a GdaDataModel object.

### gda_data_model_row_inserted ()

    void        gda_data_model_row_inserted     (GdaDataModel *model,
                                                 gint row);

Emits the 'row_inserted' and 'changed' signals on `model`.

`model` : | a GdaDataModel object.
`row` : | row number.

### gda_data_model_row_updated ()

    void        gda_data_model_row_updated      (GdaDataModel *model,
                                                 gint row);

Emits the 'row_updated' and 'changed' signals on `model`.

`model` : | a GdaDataModel object.
`row` : | row number.

### gda_data_model_row_removed ()

    void        gda_data_model_row_removed      (GdaDataModel *model,
                                                 gint row);

Emits the 'row_removed' and 'changed' signal on `model`.

`model` : | a GdaDataModel object.
`row` : | row number.

### gda_data_model_freeze ()

    void        gda_data_model_freeze           (GdaDataModel *model);

Disables notifications of changes on the given data model. To re-enable notifications again, you should call the gda_data_model_thaw function.

`model` : | a GdaDataModel object.

### gda_data_model_thaw ()

    void        gda_data_model_thaw             (GdaDataModel *model);

Re-enables notifications of changes on the given data model.

`model` : | a GdaDataModel object.

### gda_data_model_get_access_flags ()

    guint       gda_data_model_get_access_flags (GdaDataModel *model);

Get the attributes of `model` such as how to access the data it contains if it's modifiable, etc.

`model` : | a GdaDataModel object.
Returns : | an ORed value of GdaDataModelAccessFlags flags

### gda_data_model_get_n_rows ()

    gint        gda_data_model_get_n_rows       (GdaDataModel *model);

`model` : | a GdaDataModel object.
Returns : | the number of rows in the given data model, or -1 if the number of rows is not known

### gda_data_model_get_n_columns ()

    gint        gda_data_model_get_n_columns    (GdaDataModel *model);

`model` : | a GdaDataModel object.
Returns : | the number of columns in the given data model.

### gda_data_model_describe_column ()

    GdaColumn*  gda_data_model_describe_column  (GdaDataModel *model,
                                                 gint col);

Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a GdaColumn structure, which contains all the information about the given column in the data model.

WARNING: the returned GdaColumn object belongs to the `model` model and and should not be destroyed; any modification will impact the whole data model.

`model` : | a GdaDataModel object.
`col` : | column number.
Returns : | the description of the column.

### gda_data_model_get_column_title ()

    const gchar* gda_data_model_get_column_title
                                                (GdaDataModel *model,
                                                 gint col);

`model` : | a GdaDataModel object.
`col` : | column number.
Returns : | the title for the given column in a data model object.

### gda_data_model_set_column_title ()

    void        gda_data_model_set_column_title (GdaDataModel *model,
                                                 gint col,
                                                 const gchar *title);

Sets the `title` of the given `col` in `model`.

`model` : | a GdaDataModel object.
`col` : | column number
`title` : | title for the given column.

### gda_data_model_get_value_at ()

    const GdaValue* gda_data_model_get_value_at (GdaDataModel *model,
                                                 gint col,
                                                 gint row);

Retrieves the data stored in the given position (identified by the `col` and `row` parameters) on a data model.

This is the main function for accessing data in a model.

Note that the returned GdaValue must not be modified directly (unexpected behaviours may occur if you do so). If you want to modify a value stored in a GdaDataModel, use the `gda_data_model_set_value()` method.

`model` : | a GdaDataModel object.
`col` : | a valid column number.
`row` : | a valid row number.
Returns : | a GdaValue containing the value stored in the given position, or `NULL` on error (out-of-bound position, etc).

### gda_data_model_set_value_at ()

    gboolean    gda_data_model_set_value_at     (GdaDataModel *model,
                                                 gint col,
                                                 gint row,
                                                 const GdaValue *value,
                                                 GError **error);

`model` : | a GdaDataModel object.
`col` : | column number.
`row` : | row number.
`value` : | a GdaValue, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the value in the data model has been updated and no error occured

### gda_data_model_create_iter ()

    GdaDataModelIter* gda_data_model_create_iter
                                                (GdaDataModel *model);

Creates a new iterator object GdaDataModelIter object which can be used to iterate through rows in `model`.

The row the returned GdaDataModelIter represents is undefined. For models which can be accessed randomly the correspoding row can be set using `gda_data_model_move_iter_at_row()`, and for models which are accessible sequentially only then the first row will be fetched using `gda_data_model_move_iter_next()`.

`model` : | a GdaDataModel object.
Returns : | a new GdaDataModelIter object, or `NULL` if an error occured

### gda_data_model_move_iter_at_row ()

    gboolean    gda_data_model_move_iter_at_row (GdaDataModel *model,
                                                 GdaDataModelIter *iter,
                                                 gint row);

Sets `iter` to represent the `row` row. `iter` must be a valid iterator object obtained using the `gda_data_model_create_iter()` method.

`model` : | a GdaDataModel object.
`iter` : | a GdaDataModelIter object
`row` : | row number.
Returns : | TRUE if no error occured

### gda_data_model_move_iter_next ()

    gboolean    gda_data_model_move_iter_next   (GdaDataModel *model,
                                                 GdaDataModelIter *iter);

Sets `iter` to the next available row in `model`. `iter` must be a valid iterator object obtained using the `gda_data_model_create_iter()` method.

`model` : | a GdaDataModel object.
`iter` : | a GdaDataModelIter object
Returns : | TRUE if no error occured

### gda_data_model_move_iter_prev ()

    gboolean    gda_data_model_move_iter_prev   (GdaDataModel *model,
                                                 GdaDataModelIter *iter);

Sets `iter` to the previous available row in `model`. `iter` must be a valid iterator object obtained using the `gda_data_model_create_iter()` method.

`model` : | a GdaDataModel object.
`iter` : | a GdaDataModelIter object
Returns : | TRUE if no error occured

### gda_data_model_append_values ()

    gint        gda_data_model_append_values    (GdaDataModel *model,
                                                 const GList *values,
                                                 GError **error);

Appends a row to the given data model.

`model` : | a GdaDataModel object.
`values` : | GList of GdaValue* representing the row to add. The length must match model's column count. These GdaValue are value-copied. The user is still responsible for freeing them.
`error` : | a place to store errors, or `NULL`
Returns : | the number of the added row, or -1 if an error occured

### gda_data_model_append_row ()

    gint        gda_data_model_append_row       (GdaDataModel *model,
                                                 GError **error);

Appends a row to the data model.

`model` : | a GdaDataModel object.
`error` : | a place to store errors, or `NULL`
Returns : | the number of the added row, or -1 if an error occured

### gda_data_model_remove_row ()

    gboolean    gda_data_model_remove_row       (GdaDataModel *model,
                                                 gint row,
                                                 GError **error);

Removes a row from the data model.

`model` : | a GdaDataModel object.
`row` : | the row number to be removed.
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_data_model_get_row_from_values ()

    gint        gda_data_model_get_row_from_values
                                                (GdaDataModel *model,
                                                 GSList *values,
                                                 gint *cols_index);

Returns the first row where all the values in `values` at the columns identified at `cols_index` match. If the row can't be identified, then returns -1;

NOTE: the `cols_index` array MUST contain a column index for each value in `values`

`model` : | a GdaDataModel object.
`values` : | a list of GdaValue values
`cols_index` : | an array of gint containing the column number to match each value of `values`
Returns : | the requested row number, of -1 if not found

### gda_data_model_send_hint ()

    void        gda_data_model_send_hint        (GdaDataModel *model,
                                                 GdaDataModelHint hint,
                                                 const GdaValue *hint_value);

Sends a hint to the data model. The hint may or may not be handled by the data model, depending on its implementation

`model` : | a GdaDataModel
`hint` : | a hint to send to the model
`hint_value` : | an optional value to specify the hint, or `NULL`

### gda_data_model_export_to_string ()

    gchar*      gda_data_model_export_to_string (GdaDataModel *model,
                                                 GdaDataModelIOFormat format,
                                                 const gint *cols,
                                                 gint nb_cols,
                                                 GdaParameterList *options);

Exports data contained in `model` to a string; the format is specified using the `format` argument.

Specifically, the parameters in the `options` list can be:

- "SEPARATOR": a string value of which the first character is used as a separator in case of CSV export

- "NAME": a string value used to name the exported data if the export format is XML

`model` : | a GdaDataModel
`format` : | the format in which to export data
`cols` : | an array containing which columns of `model` will be exported, or `NULL` for all columns
`nb_cols` : | the number of columns in `cols`
`options` : | list of options for the export
Returns : | a new string.

### gda_data_model_export_to_file ()

    gboolean    gda_data_model_export_to_file   (GdaDataModel *model,
                                                 GdaDataModelIOFormat format,
                                                 const gchar *file,
                                                 const gint *cols,
                                                 gint nb_cols,
                                                 GdaParameterList *options,
                                                 GError **error);

Exports data contained in `model` to the `file` file; the format is specified using the `format` argument.

Specifically, the parameters in the `options` list can be:

- "SEPARATOR": a string value of which the first character is used as a separator in case of CSV export

- "NAME": a string value used to name the exported data if the export format is XML

- "OVERWRITE": a boolean value which tells if the file must be over-written if it already exists.

`model` : | a GdaDataModel
`format` : | the format in which to export data
`file` : | the filename to export to
`cols` : | an array containing which columns of `model` will be exported, or `NULL` for all columns
`nb_cols` : | the number of columns in `cols`
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occured

### gda_data_model_import_from_model ()

    gboolean    gda_data_model_import_from_model
                                                (GdaDataModel *to,
                                                 GdaDataModel *from,
                                                 GHashTable *cols_trans,
                                                 GError **error);

Copy the contents of the `from` data model to the `to` data model. The copy stops as soon as an error orrurs.

The `cols_trans` is a hash table for which keys are `to` columns numbers and the values are the corresponding column numbers in the `from` data model. To set the values of a column in `to` to NULL, create an entry in the hash table with a negative value.

`to` : | the destination GdaDataModel
`from` : | the source GdaDataModel
`cols_trans` : | a GHashTable for columns translating, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occured.

### gda_data_model_import_from_string ()

    gboolean    gda_data_model_import_from_string
                                                (GdaDataModel *model,
                                                 const gchar *string,
                                                 GHashTable *cols_trans,
                                                 GdaParameterList *options,
                                                 GError **error);

Loads the data from `string` into `model`.

`model` : | a GdaDataModel
`string` : | the string to import data from
`cols_trans` : | a hash table containing which columns of `model` will be imported, or `NULL` for all columns
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occured.

### gda_data_model_import_from_file ()

    gboolean    gda_data_model_import_from_file (GdaDataModel *model,
                                                 const gchar *file,
                                                 GHashTable *cols_trans,
                                                 GdaParameterList *options,
                                                 GError **error);

Imports data contained in the `file` file into `model`; the format is specified using the `format` argument.

`model` : | a GdaDataModel
`file` : | the filename to export to
`cols_trans` : |
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occured

### gda_data_model_dump ()

    void        gda_data_model_dump             (GdaDataModel *model,
                                                 FILE *to_stream);

Dumps a textual representation of the `model` to the `to_stream` stream

`model` : | a GdaDataModel.
`to_stream` : | where to dump the data model

### gda_data_model_dump_as_string ()

    gchar*      gda_data_model_dump_as_string   (GdaDataModel *model);

Dumps a textual representation of the `model` into a new string

`model` : | a GdaDataModel.
Returns : | a new string.

## Signals

### The "row-inserted" signal

    void        user_function                  (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);

`gdadatamodel` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "row-removed" signal

    void        user_function                  (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);

`gdadatamodel` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "row-updated" signal

    void        user_function                  (GdaDataModel *gdadatamodel,
                                                gint arg1,
                                                gpointer user_data);

`gdadatamodel` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.