GdaDataModel

## GdaDataModel GdaDataModel — Data model interface |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaDataModel;
    enum                GdaDataModelError;
    gint                gda_data_model_get_n_rows           (GdaDataModel *model);
    gint                gda_data_model_get_n_columns        (GdaDataModel *model);
    GError **           gda_data_model_get_exceptions       (GdaDataModel *model);
    GdaColumn *         gda_data_model_describe_column      (GdaDataModel *model,
                                                             gint col);
    gint                gda_data_model_get_column_index     (GdaDataModel *model,
                                                             const gchar *name);
    const gchar *       gda_data_model_get_column_name      (GdaDataModel *model,
                                                             gint col);
    const gchar *       gda_data_model_get_column_title     (GdaDataModel *model,
                                                             gint col);

    enum                GdaDataModelAccessFlags;
    GdaDataModelAccessFlags gda_data_model_get_access_flags (GdaDataModel *model);
    GdaDataModelIter *  gda_data_model_create_iter          (GdaDataModel *model);
    const GValue *      gda_data_model_get_value_at         (GdaDataModel *model,
                                                             gint col,
                                                             gint row,
                                                             GError **error);
    const GValue *      gda_data_model_get_typed_value_at   (GdaDataModel *model,
                                                             gint col,
                                                             gint row,
                                                             GType expected_type,
                                                             gboolean nullok,
                                                             GError **error);
    gboolean            gda_data_model_set_value_at         (GdaDataModel *model,
                                                             gint col,
                                                             gint row,
                                                             const GValue *value,
                                                             GError **error);
    gboolean            gda_data_model_set_values           (GdaDataModel *model,
                                                             gint row,
                                                             GList *values,
                                                             GError **error);
    GdaValueAttribute   gda_data_model_get_attributes_at    (GdaDataModel *model,
                                                             gint col,
                                                             gint row);
    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);

    enum                GdaDataModelHint;
    void                gda_data_model_send_hint            (GdaDataModel *model,
                                                             GdaDataModelHint hint,
                                                             const GValue *hint_value);
    enum                GdaDataModelIOFormat;
    gchar *             gda_data_model_export_to_string     (GdaDataModel *model,
                                                             GdaDataModelIOFormat format,
                                                             const gint *cols,
                                                             gint nb_cols,
                                                             const gint *rows,
                                                             gint nb_rows,
                                                             GdaSet *options);
    gboolean            gda_data_model_export_to_file       (GdaDataModel *model,
                                                             GdaDataModelIOFormat format,
                                                             const gchar *file,
                                                             const gint *cols,
                                                             gint nb_cols,
                                                             const gint *rows,
                                                             gint nb_rows,
                                                             GdaSet *options,
                                                             GError **error);
    gboolean            gda_data_model_add_data_from_xml_node
                                                            (GdaDataModel *model,
                                                             xmlNodePtr node,
                                                             GError **error);
    gboolean            gda_data_model_import_from_model    (GdaDataModel *to,
                                                             GdaDataModel *from,
                                                             gboolean overwrite,
                                                             GHashTable *cols_trans,
                                                             GError **error);
    gboolean            gda_data_model_import_from_string   (GdaDataModel *model,
                                                             const gchar *string,
                                                             GHashTable *cols_trans,
                                                             GdaSet *options,
                                                             GError **error);
    gboolean            gda_data_model_import_from_file     (GdaDataModel *model,
                                                             const gchar *file,
                                                             GHashTable *cols_trans,
                                                             GdaSet *options,
                                                             GError **error);
    void                gda_data_model_dump                 (GdaDataModel *model,
                                                             FILE *to_stream);
    gchar *             gda_data_model_dump_as_string       (GdaDataModel *model);

    void                gda_data_model_set_column_name      (GdaDataModel *model,
                                                             gint col,
                                                             const gchar *name);
    void                gda_data_model_set_column_title     (GdaDataModel *model,
                                                             gint col,
                                                             const gchar *title);
    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_reset                (GdaDataModel *model);
    void                gda_data_model_freeze               (GdaDataModel *model);
    void                gda_data_model_thaw                 (GdaDataModel *model);

## Object Hierarchy

      GInterface
       +----GdaDataModel

## Prerequisites

GdaDataModel requires GObject.

## Known Implementations

GdaDataModel is implemented by GdaDataAccessWrapper, GdaDataModelArray, GdaDataModelBdb, GdaDataModelDir, GdaDataModelImport, GdaDataModelLdap, GdaDataProxy and GdaDataSelect.

## Signals

      "access-changed"                                 : Run Last
      "changed"                                        : Run Last
      "reset"                                          : Run Last
      "row-inserted"                                   : Run Last
      "row-removed"                                    : Run Last
      "row-updated"                                    : Run Last

## Description

A GdaDataModel 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.

When a SELECT statement is executed using an opened GdaConnection, the returned value (if no error occurred) is a GdaDataSelect object which implements the GdaDataModel interface. Please see the GdaDataSelect's documentation for more information.

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 retrieving can be done either accessing direct random values located by their row and column, or using a cursor, or both. Use the `gda_data_model_get_access_flags()` method to know how the data model can be accessed.

- Random access to a data model's contents is done using `gda_data_model_get_value_at()`, or using one or more GdaDataModelIter object(s);

- Cursor access to a data model's contents is done using a GdaDataModelIter object. If this mode is the only supported, then only one GdaDataModelIter object can be created and it is not possible to use `gda_data_model_get_value_at()` in this case.

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

Also see the section about writing your own GdaDataModel

## Details

### GdaDataModel

    typedef struct _GdaDataModel GdaDataModel;

### enum GdaDataModelError

    typedef enum {
    	GDA_DATA_MODEL_ROW_OUT_OF_RANGE_ERROR,
    	GDA_DATA_MODEL_COLUMN_OUT_OF_RANGE_ERROR,
    	GDA_DATA_MODEL_VALUES_LIST_ERROR,
    	GDA_DATA_MODEL_VALUE_TYPE_ERROR,
    	GDA_DATA_MODEL_ROW_NOT_FOUND_ERROR,
    	GDA_DATA_MODEL_ACCESS_ERROR,
    	GDA_DATA_MODEL_FEATURE_NON_SUPPORTED_ERROR,
    	GDA_DATA_MODEL_FILE_EXIST_ERROR,
    	GDA_DATA_MODEL_XML_FORMAT_ERROR,

    	GDA_DATA_MODEL_TRUNCATED_ERROR,
    	GDA_DATA_MODEL_OTHER_ERROR
    } GdaDataModelError;

### 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 Virtual: i_get_n_rows

### 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, or -1 if unknown. Virtual: i_get_n_columns

### gda_data_model_get_exceptions ()

    GError **           gda_data_model_get_exceptions       (GdaDataModel *model);

Get the global data model exception(s) that occurred when using `model`. This is useful for example for the LDAP related data models where some rows may be missing because the LDAP search has reached a limit imposed by the LDAP server.

`model` : | a GdaDataModel
Returns : | a pointer to a `NULL` terminated array of GError, or `NULL`. [transfer none][element-type GError][array zero-terminated=1]

Since 4.2.6

### 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 affect the whole data model.

`model` : | a GdaDataModel object.
`col` : | column number.
Returns : | the description of the column. Virtual: i_describe_column. [transfer none][allow-none]

### gda_data_model_get_column_index ()

    gint                gda_data_model_get_column_index     (GdaDataModel *model,
                                                             const gchar *name);

Get the index of the first column named `name` in `model`.

`model` : | a GdaDataModel object.
`name` : | a column name
Returns : | the column index, or -1 if no column named `name` was found

### gda_data_model_get_column_name ()

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

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

Since 3.2

### 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.

### 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_CURSOR = GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD | GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD,
    	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;

### gda_data_model_get_access_flags ()

    GdaDataModelAccessFlags 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 Virtual: i_get_access_flags. [transfer none]

### 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 new GdaDataModelIter does not hold any reference to `model` (ie. if `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).

Depending on the data model's implementation, a new GdaDataModelIter object may be created, or a reference to an already existing GdaDataModelIter may be returned. For example if `model` only supports being accessed using a forward moving cursor (say a the result of a SELECT executed by SQLite with a cursor access mode specified), then this method will always return the same iterator.

If a new GdaDataModelIter is created, then the row it represents is undefined.

For models which can be accessed randomly, any row can be set using `gda_data_model_iter_move_to_row()`, and for models which are accessible sequentially only then use `gda_data_model_iter_move_next()` (and `gda_data_model_iter_move_prev()` if supported).

Note: for the GdaDataProxy data model (which proxies any GdaDataModel for modifications and has twice the number of columns of the proxied data model), this method will create an iterator in which only the columns of the proxied data model appear. If you need to have a GdaDataModelIter in which all the proxy's columns appear, create it using:

    iter = g_object_new (GDA_TYPE_DATA_MODEL_ITER, "data-model", proxy, NULL);

`model` : | a GdaDataModel object.
Returns : | a GdaDataModelIter object, or `NULL` if an error occurred Virtual: i_create_iter. [transfer full]

### gda_data_model_get_value_at ()

    const GValue *      gda_data_model_get_value_at         (GdaDataModel *model,
                                                             gint col,
                                                             gint row,
                                                             GError **error);

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

Upon errors `NULL` will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

This is the main function for accessing data in a model which allows random access to its data. To access data in a data model using a cursor, use a GdaDataModelIter object, obtained using `gda_data_model_create_iter()`.

Note1: the returned GValue must not be modified directly (unexpected behaviours may occur if you do so).

Note2: the returned value may become invalid as soon as any Libgda part is executed again, which means if you want to keep the value, a copy must be made, however it will remain valid as long as the only Libgda usage is calling `gda_data_model_get_value_at()` for different values of the same row.

If you want to modify a value stored in a GdaDataModel, use the `gda_data_model_set_value_at()` or `gda_data_model_set_values()` methods.

Upon errors `NULL` will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel object.
`col` : | a valid column number.
`row` : | a valid row number.
`error` : | a place to store errors, or `NULL`.
Returns : | a GValue containing the value stored in the given position, or `NULL` on error (out-of-bound position, etc). Virtual: i_get_value_at. [allow-none][transfer none]

### gda_data_model_get_typed_value_at ()

    const GValue *      gda_data_model_get_typed_value_at   (GdaDataModel *model,
                                                             gint col,
                                                             gint row,
                                                             GType expected_type,
                                                             gboolean nullok,
                                                             GError **error);

Upon errors `NULL` will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

This method is similar to `gda_data_model_get_value_at()`, except that it also allows one to specify the expected GType of the value to get: if the data model returned a GValue of a type different than the expected one, then this method returns `NULL` and an error code.

Note: the same limitations and usage instructions apply as for `gda_data_model_get_value_at()`.

Upon errors `NULL` will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel object.
`col` : | a valid column number.
`row` : | a valid row number.
`expected_type` : | the expected data type of the returned value
`nullok` : | if TRUE, then NULL values (value of type `GDA_TYPE_NULL`) will not generate any error
`error` : | a place to store errors, or `NULL`
Returns : | a GValue containing the value stored in the given position, or `NULL` on error (out-of-bound position, wrong data type, etc).

### gda_data_model_set_value_at ()

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

Modifies a value in `model`, at (`col`, `row`).

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel object.
`col` : | column number.
`row` : | row number.
`value` : | a GValue (not `NULL`)
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the value in the data model has been updated and no error occurred Virtual: i_set_value_at

### gda_data_model_set_values ()

    gboolean            gda_data_model_set_values           (GdaDataModel *model,
                                                             gint row,
                                                             GList *values,
                                                             GError **error);

In a similar way to `gda_data_model_set_value_at()`, this method modifies a data model's contents by setting several values at once.

If any value in `values` is actually `NULL`, then the value in the corresponding column is left unchanged. Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel object.
`row` : | row number.
`values` : | a list of GValue (or `NULL`), one for at most the number of columns of `model`. [element-type GLib.Value][transfer none][allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if the value in the data model has been updated and no error occurred Virtual: i_set_values

### gda_data_model_get_attributes_at ()

    GdaValueAttribute   gda_data_model_get_attributes_at    (GdaDataModel *model,
                                                             gint col,
                                                             gint row);

Get the attributes of the value stored at (row, col) in `model`, which is an ORed value of GdaValueAttribute flags. As a special case, if `row` is -1, then the attributes returned correspond to a "would be" value if a row was added to `model`.

`model` : | a GdaDataModel object
`col` : | a valid column number
`row` : | a valid row number, or -1
Returns : | the attributes as an ORed value of GdaValueAttribute Virtual: i_get_attributes_at. [transfer none]

### 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. If any value in `values` is actually `NULL`, then it is considered as a default value. If `values` is `NULL` then all values are set to their default value.

Upon errors -1 will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel object.
`values` : | GList of GValue* representing the row to add. The length must match model's column count. These GValue are value-copied (the user is still responsible for freeing them). [element-type GLib.Value][allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | the number of the added row, or -1 if an error occurred Virtual: i_append_values

### gda_data_model_append_row ()

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

Appends a row to the data model (the new row will possibly have NULL values for all columns, or some other values depending on the data model implementation)

Upon errors -1 will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

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

### gda_data_model_remove_row ()

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

Removes a row from the data model.

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`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. Virtual: i_remove_row

### 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 GValue values (no `NULL` is allowed). [element-type GLib.Value]
`cols_index` : | an array of gint containing the column number to match each value of `values`. [array]
Returns : | the requested row number, of -1 if not found Virtual: i_find_row

### enum GdaDataModelHint

    typedef enum {
    	GDA_DATA_MODEL_HINT_START_BATCH_UPDATE,
    	GDA_DATA_MODEL_HINT_END_BATCH_UPDATE,
    	GDA_DATA_MODEL_HINT_REFRESH
    } GdaDataModelHint;

### gda_data_model_send_hint ()

    void                gda_data_model_send_hint            (GdaDataModel *model,
                                                             GdaDataModelHint hint,
                                                             const GValue *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

Virtual: i_send_hint

`model` : | a GdaDataModel
`hint` : | a hint to send to the model. [transfer none]
`hint_value` : | an optional value to specify the hint, or `NULL`. [allow-none]

### enum GdaDataModelIOFormat

    typedef enum {
    	GDA_DATA_MODEL_IO_DATA_ARRAY_XML,
    	GDA_DATA_MODEL_IO_TEXT_SEPARATED,
    	GDA_DATA_MODEL_IO_TEXT_TABLE
    } GdaDataModelIOFormat;

Format to use when exporting a data model, see `gda_data_model_export_to_string()` and `gda_data_model_export_to_file()`

`GDA_DATA_MODEL_IO_DATA_ARRAY_XML` | data is exported as an XML structure
`GDA_DATA_MODEL_IO_TEXT_SEPARATED` | data is exported as CSV
`GDA_DATA_MODEL_IO_TEXT_TABLE` | data is exported as a human readable table

### gda_data_model_export_to_string ()

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

Exports data contained in `model` to a string; the format is specified using the `format` argument, see the `gda_data_model_export_to_file()` documentation for more information about the `options` argument (except for the "OVERWRITE" option).

Warning: this function uses a GdaDataModelIter iterator, and if `model` does not offer a random access (check using `gda_data_model_get_access_flags()`), the iterator will be the same as normally used to access data in `model` previously to calling this method, and this iterator will be moved (point to another row).

See also `gda_data_model_dump_as_string()`;

`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. [array length=nb_cols][allow-none]
`nb_cols` : | the number of columns in `cols`
`rows` : | an array containing which rows of `model` will be exported, or `NULL` for all rows. [array length=nb_rows][allow-none]
`nb_rows` : | the number of rows in `rows`
`options` : | list of options for the export
Returns : | a new string, use `g_free()` when no longer needed. [transfer full]

### 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,
                                                             const gint *rows,
                                                             gint nb_rows,
                                                             GdaSet *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

- "QUOTE": a string value of which the first character is used as a quote character in case of CSV export. The default if not specified is the double quote character

- "FIELD_QUOTE": a boolean value which can be set to FALSE if no quote around the individual fields is requeted, in case of CSV export

- "NAMES_ON_FIRST_LINE": a boolean value which, if set to `TRUE` and in case of a CSV or `GDA_DATA_MODEL_IO_TEXT_TABLE` export, will add a first line with the name each exported field (note that "FIELDS_NAME" is also accepted as a synonym)

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

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

- "NULL_AS_EMPTY": a boolean value which, if set to `TRUE` and in case of a CSV or `GDA_DATA_MODEL_IO_TEXT_TABLE` export, will render and NULL value as the empty string (instead of the 'NULL' string)

- "INVALID_AS_NULL": a boolean value which, if set to `TRUE`, considers any invalid data (for example for the date related values) as NULL

- "COLUMN_SEPARATORS": a boolean value which, if set to `TRUE`, adds a separators lines between each column, if the export format is `GDA_DATA_MODEL_IO_TEXT_TABLE`

- "SEPARATOR_LINE": a boolean value which, if set to `TRUE`, adds an horizontal line between column titles and values, if the export format is `GDA_DATA_MODEL_IO_TEXT_TABLE`

- "ROW_NUMBERS": a boolean value which, if set to `TRUE`, prepends a column with row numbers, if the export format is `GDA_DATA_MODEL_IO_TEXT_TABLE`

- "MAX_WIDTH": an integer value which, if greater than 0, makes all the lines truncated to have at most that number of characters, if the export format is `GDA_DATA_MODEL_IO_TEXT_TABLE`

Warning: this function uses a GdaDataModelIter iterator, and if `model` does not offer a random access (check using `gda_data_model_get_access_flags()`), the iterator will be the same as normally used to access data in `model` previously to calling this method, and this iterator will be moved (point to another row).

Upon errors `FALSE` will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`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. [array length=nb_cols][allow-none]
`nb_cols` : | the number of columns in `cols`
`rows` : | an array containing which rows of `model` will be exported, or `NULL` for all rows. [array length=nb_rows][allow-none]
`nb_rows` : | the number of rows in `rows`
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_data_model_add_data_from_xml_node ()

    gboolean            gda_data_model_add_data_from_xml_node
                                                            (GdaDataModel *model,
                                                             xmlNodePtr node,
                                                             GError **error);

Adds the data from an XML node to the given data model (see the DTD for that node in the $prefix/share/libgda/dtd/libgda-array.dtd file).

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel.
`node` : | an XML node representing a <gda_array_data> XML node.
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if successful, `FALSE` otherwise.

### gda_data_model_import_from_model ()

    gboolean            gda_data_model_import_from_model    (GdaDataModel *to,
                                                             GdaDataModel *from,
                                                             gboolean overwrite,
                                                             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. For example:

    GHashTable *hash;
    gint *ptr;
    hash = g_hash_table_new_full (g_int_hash, g_int_equal, g_free, NULL);
    ptr = g_new (gint, 1);
    *ptr = 2;
    g_hash_table_insert (hash, ptr, GINT_TO_POINTER (3));
    gda_data_model_import_from_model (...);
    g_hash_table_free (hash);

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`to` : | the destination GdaDataModel
`from` : | the source GdaDataModel
`overwrite` : | TRUE if `to` is completely overwritten by `from`'s data, and FALSE if `from`'s data is appended to `to`
`cols_trans` : | a GHashTable for columns translating, or `NULL`. [element-type gint gint][allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_data_model_import_from_string ()

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

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

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`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, see `gda_data_model_import_from_model()`. [element-type gint gint][allow-none]
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_data_model_import_from_file ()

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

Imports data contained in the `file` file into `model`; the format is detected.

Upon errors FALSE will be returned and `error` will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

`model` : | a GdaDataModel
`file` : | the filename to import from
`cols_trans` : | a GHashTable for columns translating, or `NULL`, see `gda_data_model_import_from_model()`. [element-type gint gint][allow-none]
`options` : | list of options for the export
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### 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

The following environment variables can affect the resulting output:

- GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers

- GDA_DATA_MODEL_DUMP_ATTRIBUTES: if set, also dump the data model's columns' types and value's attributes

- GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model's title

- GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values

- GDA_DATA_MODEL_DUMP_TRUNCATE: if set to a numeric value, truncates the output to the width specified by the value. If the value is -1 then the actual terminal size (if it can be determined) is used

`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. The main differences with `gda_data_model_export_to_string()` are that the formatting options are passed using environment variables, and that the data is dumped regardless of the user locale (e.g. dates are not formatted according to the locale).

The following environment variables can affect the resulting output:

- GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers

- GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model's title

- GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values

- GDA_DATA_MODEL_DUMP_TRUNCATE: if set to a numeric value, truncates the output to the width specified by the value. If the value is -1 then the actual terminal size (if it can be determined) is used

`model` : | a GdaDataModel.
Returns : | a new string. [transfer full]

### gda_data_model_set_column_name ()

    void                gda_data_model_set_column_name      (GdaDataModel *model,
                                                             gint col,
                                                             const gchar *name);

Sets the `name` of the given `col` in `model`, and if its title is not set, also sets the title to `name`.

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

Since 3.2

### 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_row_inserted ()

    void                gda_data_model_row_inserted         (GdaDataModel *model,
                                                             gint row);

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

This method should only be used by GdaDataModel implementations to signal that a row has been inserted.

`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`.

This method should only be used by GdaDataModel implementations to signal that a row has been updated.

`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`.

This method should only be used by GdaDataModel implementations to signal that a row has been removed

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

### gda_data_model_reset ()

    void                gda_data_model_reset                (GdaDataModel *model);

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

`model` : | a GdaDataModel object.

### 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.

## Signal Details

### The `"access-changed"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gpointer      user_data)      : Run Last

Gets emitted when `model`'s access flags have changed. Use `gda_data_model_get_access_flags()` to get the access flags.

`model` : | the GdaDataModel
`user_data` : | user data set when the signal handler was connected.

### The `"changed"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gpointer      user_data)      : Run Last

Gets emitted when any value in `model` has been changed

`model` : | the GdaDataModel
`user_data` : | user data set when the signal handler was connected.

### The `"reset"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gpointer      user_data)      : Run Last

Gets emitted when `model`'s contents has been completely reset (the number and type of columns may also have changed)

`model` : | the GdaDataModel
`user_data` : | user data set when the signal handler was connected.

### The `"row-inserted"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gint          row,
                                                            gpointer      user_data)      : Run Last

Gets emitted when a row has been inserted in `model`

`model` : | the GdaDataModel
`row` : | the row number
`user_data` : | user data set when the signal handler was connected.

### The `"row-removed"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gint          row,
                                                            gpointer      user_data)      : Run Last

Gets emitted when a row has been removed from `model`

`model` : | the GdaDataModel
`row` : | the row number
`user_data` : | user data set when the signal handler was connected.

### The `"row-updated"` signal

    void                user_function                      (GdaDataModel *model,
                                                            gint          row,
                                                            gpointer      user_data)      : Run Last

Gets emitted when a row has been modified in `model`

`model` : | the GdaDataModel
`row` : | the row number
`user_data` : | user data set when the signal handler was connected.

## See Also

GdaDataModelIter