GdaDataModel: GNOME Data Access 5 manual

## GdaDataModel GdaDataModel — Data model interface |

## Stability Level

Stable, unless otherwise indicated

## Functions

gint | gda_data_model_get_n_rows ()
gint | gda_data_model_get_n_columns ()
GError ** | gda_data_model_get_exceptions ()
GdaColumn * | gda_data_model_describe_column ()
gint | gda_data_model_get_column_index ()
const gchar * | gda_data_model_get_column_name ()
const gchar * | gda_data_model_get_column_title ()
GdaDataModelAccessFlags | gda_data_model_get_access_flags ()
GdaDataModelIter * | gda_data_model_create_iter ()
const GValue * | gda_data_model_get_value_at ()
const GValue * | gda_data_model_get_typed_value_at ()
gboolean | gda_data_model_set_value_at ()
gboolean | gda_data_model_set_values ()
GdaValueAttribute | gda_data_model_get_attributes_at ()
gint | gda_data_model_append_values ()
gint | gda_data_model_append_row ()
gboolean | gda_data_model_remove_row ()
gint | gda_data_model_get_row_from_values ()
void | gda_data_model_send_hint ()
gchar * | gda_data_model_export_to_string ()
gboolean | gda_data_model_export_to_file ()
gboolean | gda_data_model_add_data_from_xml_node ()
gboolean | gda_data_model_import_from_model ()
gboolean | gda_data_model_import_from_string ()
gboolean | gda_data_model_import_from_file ()
void | gda_data_model_dump ()
gchar * | gda_data_model_dump_as_string ()
void | gda_data_model_set_column_name ()
void | gda_data_model_set_column_title ()
void | gda_data_model_row_inserted ()
void | gda_data_model_row_updated ()
void | gda_data_model_row_removed ()
void | gda_data_model_reset ()
void | gda_data_model_freeze ()
void | gda_data_model_thaw ()

## Signals

void | access-changed | Run Last
void | changed | Run Last
void | reset | Run Last
void | row-inserted | Run Last
void | row-removed | Run Last
void | row-updated | Run Last

## Types and Values

| GdaDataModel
enum | GdaDataModelError
enum | GdaDataModelAccessFlags
enum | GdaDataModelHint
enum | GdaDataModelIOFormat

## Object Hierarchy

        GInterface
        ╰── GdaDataModel

## Prerequisites

GdaDataModel requires GObject.

## Known Implementations

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

## Includes

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

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

## Functions

### gda_data_model_get_n_rows ()

    gint
    gda_data_model_get_n_rows (GdaDataModel *model);

[virtual i_get_n_rows]

#### Parameters

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);

[virtual i_get_n_columns]

#### Parameters

model | a GdaDataModel object. |

#### Returns

the number of columns in the given data model, or -1 if unknown.

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

[virtual i_get_exceptions]

#### Parameters

model | a GdaDataModel |

#### Returns

a pointer to a `NULL` terminated array of GError, or `NULL`.

[transfer none][element-type GLib.Error][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.

[virtual i_describe_column]

#### Parameters

model | a GdaDataModel object. |
col | column number. |

#### Returns

the description of the column.

[transfer none][nullable]

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

#### Parameters

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);

#### Parameters

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);

#### Parameters

model | a GdaDataModel object. |
col | column number. |

#### Returns

the title for the given column in a data model object.

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

[virtual i_get_access_flags]

#### Parameters

model | a GdaDataModel object. |

#### Returns

an ORed value of GdaDataModelAccessFlags 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);

[virtual i_create_iter]

#### Parameters

model | a GdaDataModel object. |

#### Returns

a GdaDataModelIter object, or `NULL` if an error occurred.

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

[virtual i_get_value_at]

#### Parameters

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

[nullable][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.

#### Parameters

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

[nullable][transfer none]

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

[virtual i_set_value_at]

#### Parameters

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

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

[virtual i_set_values]

#### Parameters

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 GObject.Value][transfer none][nullable]
error | a place to store errors, or `NULL` |

#### Returns

`TRUE` if the value in the data model has been updated and no error occurred

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

[virtual i_get_attributes_at]

#### Parameters

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.

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

[virtual i_append_values]

#### Parameters

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 GObject.Value][nullable]
error | a place to store errors, or `NULL` |

#### Returns

the number of the added row, or -1 if an error occurred

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

[virtual i_append_row]

#### Parameters

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

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

[virtual i_remove_row]

#### Parameters

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`

[virtual i_find_row]

#### Parameters

model | a GdaDataModel object. |
values | a list of GValue values (no `NULL` is allowed). | [element-type GObject.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

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

#### Parameters

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

### 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()`;

#### Parameters

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][nullable]
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][nullable]
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. Note that the date format used is the one used by the connection from which the data model has been made (as the result of a SELECT statement), or, for other kinds of data models, the default format (refer to `gda_data_handler_get_default()`) unless the "cnc" property has been set and points to a GdaConnection to use that connection's date format.

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.

#### Parameters

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][nullable]
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][nullable]
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.

#### Parameters

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.

#### Parameters

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][nullable]
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.

#### Parameters

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][nullable]
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.

#### Parameters

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][nullable]
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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

model | a GdaDataModel object. |

## Types and Values

### GdaDataModel

    typedef struct _GdaDataModel GdaDataModel;

### enum GdaDataModelError

#### Members

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

### enum GdaDataModelAccessFlags

#### Members

GDA_DATA_MODEL_ACCESS_RANDOM |  |
GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD |  |
GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD |  |
GDA_DATA_MODEL_ACCESS_CURSOR |  |
GDA_DATA_MODEL_ACCESS_INSERT |  |
GDA_DATA_MODEL_ACCESS_UPDATE |  |
GDA_DATA_MODEL_ACCESS_DELETE |  |
GDA_DATA_MODEL_ACCESS_WRITE |  |

### enum GdaDataModelHint

#### Members

GDA_DATA_MODEL_HINT_START_BATCH_UPDATE |  |
GDA_DATA_MODEL_HINT_END_BATCH_UPDATE |  |
GDA_DATA_MODEL_HINT_REFRESH |  |

### enum GdaDataModelIOFormat

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

#### Members

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 |

## Signal Details

### The `“access-changed”` signal

    void
    user_function (GdaDataModel *model,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

### The `“changed”` signal

    void
    user_function (GdaDataModel *model,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

### The `“reset”` signal

    void
    user_function (GdaDataModel *model,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

### The `“row-inserted”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“row-removed”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“row-updated”` signal

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

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

#### Parameters

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

Flags: Run Last

## See Also

GdaDataModelIter