GdaDataModel

GdaDataModel — Basic data model class

Functions

Signals

void reset Run Last
void row-inserted Run Last
void row-removed Run Last
void row-updated Run Last

Types and Values

Object Hierarchy

    GInterface
    ╰── GdaDataModel

Prerequisites

GdaDataModel requires GdaObject.

Known Implementations

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

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

Functions

gda_data_model_row_inserted ()

void
gda_data_model_row_inserted (GdaDataModel *model,
                             gint row);

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

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 .

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 .

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.

 

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.

Parameters

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

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

Parameters

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

Parameters

model

a GdaDataModel object.

 

col

column number.

 

Returns

the description of the column.


gda_data_model_get_column_index_by_name ()

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

Get the index of the 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_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_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_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_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 .

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


gda_data_model_get_value_at ()

const GValue *
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 which allow 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().

Note that the returned GValue 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.

Parameters

model

a GdaDataModel object.

 

col

a valid column number.

 

row

a valid row number.

 

Returns

a GValue containing the value stored in the given position, or NULL on error (out-of-bound position, etc).


gda_data_model_get_value_at_col_name ()

const GValue *
gda_data_model_get_value_at_col_name (GdaDataModel *model,
                                      const gchar *column_name,
                                      gint row);

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

See also gda_data_model_get_value_at().

Parameters

model

a GdaDataModel object.

 

column_name

a valid column name.

 

row

a valid row number.

 

Returns

a GValue 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 GValue *value,
                             GError **error);

Parameters

model

a GdaDataModel object.

 

col

column number.

 

row

row number.

 

value

a GValue, 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 occurred


gda_data_model_set_values ()

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

If any value in values is actually NULL, then it is considered as a default value.

Parameters

model

a GdaDataModel object.

 

row

row number.

 

values

a list of GValue, one for each n (<nb_cols) columns of model

 

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

Parameters

model

a GdaDataModel object.

 

Returns

a new GdaDataModelIter object, or NULL if an error occurred


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.

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

 

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.

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.

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

Parameters

model

a GdaDataModel object.

 

values

a list of GValue 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 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

Parameters

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,
                                 const gint *rows,
                                 gint nb_rows,
                                 GdaParameterList *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).

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

 

nb_cols

the number of columns in cols

 

rows

an array containing which rows of model will be exported, or NULL for all rows

 

nb_rows

the number of rows in rows

 

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

  • "QUOTE": a string value of which the first character is used as a quote character in case of CSV export

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

  • "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.

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

 

nb_cols

the number of columns in cols

 

rows

an array containing which rows of model will be exported, or NULL for all rows

 

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 a XML node to the given data model (see the DTD for that node in the $prefix/share/libgda/dtd/libgda-array.dtd file).

Parameters

model

a GdaDataModel.

 

node

a XML node representing a <gda_array_data> XML node.

 

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.

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

 

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,
                                   GdaParameterList *options,
                                   GError **error);

Loads the data from string into model .

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

 

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,
                                 GdaParameterList *options,
                                 GError **error);

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

Parameters

model

a GdaDataModel

 

file

the filename to import from

 

cols_trans

a GHashTable for columns translating, or NULL

 

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 coulumn 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_DUMP_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values

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 following environment variables can affect the resulting output:

  • GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first coulumn of the output will contain row numbers

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

  • GDA_DATA_MODEL_DUMP_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values

Parameters

model

a GdaDataModel.

 

Returns

a new string.

Types and Values

GdaDataModel

typedef struct _GdaDataModel GdaDataModel;


enum GdaDataModelAccessFlags

Members

GDA_DATA_MODEL_ACCESS_RANDOM

   

GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD

   

GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD

   

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

Members

GDA_DATA_MODEL_IO_DATA_ARRAY_XML

   

GDA_DATA_MODEL_IO_TEXT_SEPARATED

   

Signal Details

The “reset” signal

void
user_function (GdaDataModel *gdadatamodel,
               gpointer      user_data)

This signal is emitted when either the columns of the data model have changed (the number or columns and/or tier types), or when the data model has changed in a way where it has not been possible to follow the changes using the "row-inserted", "row-updated" or "row-removed" signals.

Parameters

gdadatamodel

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-inserted” signal

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

This signal is emitted when a row has been inserted in the data model (the new row is readily accessible at the provided row). All the row numbers of the row after the inserted row have been increased by one.

Parameters

gdadatamodel

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-removed” signal

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

This signal is emitted when a row has been removed from the data model (the new row is no longer accessible at the provided row). All the row numbers of the row after the removed row have been decreased by one.

Parameters

gdadatamodel

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-updated” signal

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

This signal is emitted when a row has been updated from the data model (the updated values are accessible at the provided row).

Parameters

gdadatamodel

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last