GdaDataPivot

## GdaDataPivot GdaDataPivot — A data model for data summarisation |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              GdaDataPivot;
    struct              GdaDataPivotClass;
                        GdaDataPivotPrivate;
    enum                GdaDataPivotError;
    GdaDataModel *      gda_data_pivot_new                  (GdaDataModel *model);
    enum                GdaDataPivotFieldType;
    gboolean            gda_data_pivot_add_field            (GdaDataPivot *pivot,
                                                             GdaDataPivotFieldType field_type,
                                                             const gchar *field,
                                                             const gchar *alias,
                                                             GError **error);
    enum                GdaDataPivotAggregate;
    gboolean            gda_data_pivot_add_data             (GdaDataPivot *pivot,
                                                             GdaDataPivotAggregate aggregate_type,
                                                             const gchar *field,
                                                             const gchar *alias,
                                                             GError **error);
    gboolean            gda_data_pivot_populate             (GdaDataPivot *pivot,
                                                             GError **error);

## Description

The GdaDataPivot data model allows one to do some analysis and summarisation on the contents of a data model.

## Details

### struct GdaDataPivot

    struct GdaDataPivot {
    	GObject                object;
    	GdaDataPivotPrivate   *priv;
    };

### struct GdaDataPivotClass

    struct GdaDataPivotClass {
    	GObjectClass           parent_class;
    };

### GdaDataPivotPrivate

    typedef struct _GdaDataPivotPrivate GdaDataPivotPrivate;

### enum GdaDataPivotError

    typedef enum {
    	GDA_DATA_PIVOT_INTERNAL_ERROR,
    	GDA_DATA_PIVOT_SOURCE_MODEL_ERROR,
            GDA_DATA_PIVOT_FIELD_FORMAT_ERROR,
    	GDA_DATA_PIVOT_USAGE_ERROR,
    	GDA_DATA_PIVOT_OVERFLOW_ERROR
    } GdaDataPivotError;

Possible GdaDataPivot related errors.

`GDA_DATA_PIVOT_INTERNAL_ERROR` |
`GDA_DATA_PIVOT_SOURCE_MODEL_ERROR` |
`GDA_DATA_PIVOT_FIELD_FORMAT_ERROR` |
`GDA_DATA_PIVOT_USAGE_ERROR` |
`GDA_DATA_PIVOT_OVERFLOW_ERROR` |

### gda_data_pivot_new ()

    GdaDataModel *      gda_data_pivot_new                  (GdaDataModel *model);

Creates a new GdaDataModel which will contain analysed data from `model`.

`model` : | a GdaDataModel to analyse data from, or `NULL`. [allow-none]
Returns : | a pointer to the newly created GdaDataModel. [transfer full]

### enum GdaDataPivotFieldType

    typedef enum {
    	GDA_DATA_PIVOT_FIELD_ROW,
    	GDA_DATA_PIVOT_FIELD_COLUMN
    } GdaDataPivotFieldType;

Define types of field to be used when defining a GdaDataPivot analysis.

`GDA_DATA_PIVOT_FIELD_ROW` |
`GDA_DATA_PIVOT_FIELD_COLUMN` |

### gda_data_pivot_add_field ()

    gboolean            gda_data_pivot_add_field            (GdaDataPivot *pivot,
                                                             GdaDataPivotFieldType field_type,
                                                             const gchar *field,
                                                             const gchar *alias,
                                                             GError **error);

Specifies that `field` has to be included in the analysis. `field` is a field specification with the following accepted syntaxes:

- a column name in the source data model (see `gda_data_model_get_column_index()`); or

- an SQL expression involving a column name in the source data model, for example:

      price
      firstname || ' ' || lastname
      nb BETWEEN 5 AND 10

It is also possible to specify several fields to be added, while separating them by a comma (in effect still forming a valid SQL syntax).

`pivot` : | a GdaDataPivot object
`field_type` : | the type of field to add
`field` : | the field description, see below
`alias` : | the field alias, or `NULL`. [allow-none]
`error` : | ta place to store errors, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.0

### enum GdaDataPivotAggregate

    typedef enum {
    	GDA_DATA_PIVOT_AVG,
    	GDA_DATA_PIVOT_COUNT,
    	GDA_DATA_PIVOT_MAX,
    	GDA_DATA_PIVOT_MIN,
    	GDA_DATA_PIVOT_SUM
    } GdaDataPivotAggregate;

Possible operations for the data fields.

`GDA_DATA_PIVOT_AVG` |
`GDA_DATA_PIVOT_COUNT` |
`GDA_DATA_PIVOT_MAX` |
`GDA_DATA_PIVOT_MIN` |
`GDA_DATA_PIVOT_SUM` |

### gda_data_pivot_add_data ()

    gboolean            gda_data_pivot_add_data             (GdaDataPivot *pivot,
                                                             GdaDataPivotAggregate aggregate_type,
                                                             const gchar *field,
                                                             const gchar *alias,
                                                             GError **error);

Specifies that `field` has to be included in the analysis. `field` is a field specification with the following accepted syntaxes:

- a column name in the source data model (see `gda_data_model_get_column_index()`); or

- an SQL expression involving a column name in the source data model, for examples:

      price
      firstname || ' ' || lastname
      nb BETWEEN 5 AND 10

It is also possible to specify several fields to be added, while separating them by a comma (in effect still forming a valid SQL syntax).

`pivot` : | a GdaDataPivot object
`aggregate_type` : | the type of aggregate operation to perform
`field` : | the field description, see below
`alias` : | the field alias, or `NULL`. [allow-none]
`error` : | ta place to store errors, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

Since 5.0

### gda_data_pivot_populate ()

    gboolean            gda_data_pivot_populate             (GdaDataPivot *pivot,
                                                             GError **error);

Acutally populates `pivot` by analysing the data from the provided data model.

`pivot` : | a GdaDataPivot object
`error` : | ta place to store errors, or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred.

Since 5.0