GdaDataComparator

## GdaDataComparator GdaDataComparator — Simple data model's contents comparison |

## Synopsis

                        GdaDataComparator;
                        GdaDataComparatorClass;
                        GdaDataComparatorPrivate;
    GObject *           gda_data_comparator_new             (GdaDataModel *old_model,
                                                             GdaDataModel *new_model);
    void                gda_data_comparator_set_key_columns (GdaDataComparator *comp,
                                                             const gint *col_numbers,
                                                             gint nb_cols);
                        GdaDiff;
    enum                GdaDiffType;
    gboolean            gda_data_comparator_compute_diff    (GdaDataComparator *comp,
                                                             GError **error);
    gint                gda_data_comparator_get_n_diffs     (GdaDataComparator *comp);
    const GdaDiff *     gda_data_comparator_get_diff        (GdaDataComparator *comp,
                                                             gint pos);

## Description

The GdaDataComparator is a simple object which takes two GdaDataModel objects and compare them. Actual comparison is performed when the `gda_data_comparator_compute_diff()` is called; for each difference found, the diff-computed signal is emitted (any user installed signal handler which returns FALSE stops the computing process).

After the differences have been computed, they can each be accessed using `gda_data_comparator_get_diff()`, the number of differences found being returned by `gda_data_comparator_get_n_diffs()`.

There are some limitations to this object:

- The data models compared must have the same number and type of columns

- The comparison is done column-for-column: one cannot omit columns in the comparison, nor compare columns with different positions

## Details

### GdaDataComparator

    typedef struct {
    	GObject                   object;
    	GdaDataComparatorPrivate *priv;
    } GdaDataComparator;

### GdaDataComparatorClass

    typedef struct {
    	GObjectClass              parent_class;
    	gboolean               (* diff_computed)  (GdaDataComparator *comp, GdaDiff *diff);

    	/* Padding for future expansion */
    	void (*_gda_reserved1) (void);
    	void (*_gda_reserved2) (void);
    	void (*_gda_reserved3) (void);
    	void (*_gda_reserved4) (void);
    } GdaDataComparatorClass;

### GdaDataComparatorPrivate

    typedef struct _GdaDataComparatorPrivate GdaDataComparatorPrivate;

### gda_data_comparator_new ()

    GObject *           gda_data_comparator_new             (GdaDataModel *old_model,
                                                             GdaDataModel *new_model);

Creates a new comparator to compute the differences from `old_model` to `new_model`: if one applies all the computed differences (as GdaDiff structures) to `old_model`, the resulting data model should have the same contents as `new_model`.

`old_model` : | Data model to which the modifications should be applied
`new_model` : | Target data model.
Returns : | a new GdaDataComparator object

### gda_data_comparator_set_key_columns ()

    void                gda_data_comparator_set_key_columns (GdaDataComparator *comp,
                                                             const gint *col_numbers,
                                                             gint nb_cols);

Defines the columns which will be used as a key when searching data. This is not mandatory but will speed things up as less data will be processed.

`comp` : | a GdaDataComparator object
`col_numbers` : | a array of `nb_cols` values
`nb_cols` : | the size of the `col_numbers` array

### GdaDiff

    typedef struct {
    	GdaDiffType  type;
    	gint         old_row;
    	gint         new_row;
    	GHashTable  *values; /* key = ('+' or '-') and a column position starting at 0 (string)
    			      * value = a GValue pointer */
    } GdaDiff;

### enum GdaDiffType

    typedef enum {
    	GDA_DIFF_ADD_ROW,
    	GDA_DIFF_REMOVE_ROW,
    	GDA_DIFF_MODIFY_ROW
    } GdaDiffType;

### gda_data_comparator_compute_diff ()

    gboolean            gda_data_comparator_compute_diff    (GdaDataComparator *comp,
                                                             GError **error);

Actually computes the differences bewteen the data models for which `comp` is defined.

For each difference computed, stored in a GdaDiff structure, the "diff-computed" signal is emitted. If one connects to this signal and returns FALSE in the signal handler, then computing differences will be stopped and an error will be returned.

`comp` : | a GdaDataComparator object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if all the differences have been sucessfully computed, and FALSE if an error occurred

### gda_data_comparator_get_n_diffs ()

    gint                gda_data_comparator_get_n_diffs     (GdaDataComparator *comp);

Get the number of differences as computed by the last time `gda_data_comparator_compute_diff()` was called.

`comp` : | a GdaDataComparator object
Returns : | the number of computed differences

### gda_data_comparator_get_diff ()

    const GdaDiff *     gda_data_comparator_get_diff        (GdaDataComparator *comp,
                                                             gint pos);

Get a pointer to the GdaDiff structure representing the difference which number is `pos`

`comp` : | a GdaDataComparator object
`pos` : | the requested difference number (starting at 0)
Returns : | a pointer to a GdaDiff, or `NULL` if `pos` is invalid