GdaDataModelImport

## GdaDataModelImport GdaDataModelImport — Importing data from a string or a file |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              GdaDataModelImport;
    struct              GdaDataModelImportClass;
                        GdaDataModelImportPrivate;
    GdaDataModel *      gda_data_model_import_new_file      (const gchar *filename,
                                                             gboolean random_access,
                                                             GdaSet *options);
    GdaDataModel *      gda_data_model_import_new_mem       (const gchar *data,
                                                             gboolean random_access,
                                                             GdaSet *options);
    GdaDataModel *      gda_data_model_import_new_xml_node  (xmlNodePtr node);
    GSList *            gda_data_model_import_get_errors    (GdaDataModelImport *model);
    void                gda_data_model_import_clean_errors  (GdaDataModelImport *model);

## Object Hierarchy

      GObject
       +----GdaDataModelImport

## Implemented Interfaces

GdaDataModelImport implements GdaDataModel.

## Properties

      "data-string"              gchar*                : Read / Write / Construct Only
      "filename"                 gchar*                : Read / Write / Construct Only
      "options"                  GdaSet*               : Read / Write / Construct Only
      "random-access"            gboolean              : Read / Write / Construct Only
      "strict"                   gboolean              : Read / Write / Construct
      "xml-node"                 gpointer              : Read / Write / Construct Only

## Description

The GdaDataModelImport data model imports data from a string or a file. The data can either be in a CSV (comma separated values) format or in an XML format as described by the libgda-array.dtd DTD (as a side way it is also possible to import data from an already-build XML tree validated against that DTD).

The caller must decide, upon construction, if the new GdaDataModelImport must support random access or simply a cursor based access. Random access makes it easier to use the resulting data model but consumes more memory as all the data is copied in memory, and is thus not suitable for large data sets. Note that importing from an already-build XML tree will always result in a random access data model.

Various import options can be specified using parameters in a GdaSet object. The available options depend on the format of the imported data listed here:

- "SEPARATOR" (string, CVS import only): specifies the separator to consider

- "ESCAPE_CHAR" (string, CVS import only): specifies the character used to "escape" the strings contained between two separators

- "ENCODING" (string, CVS import only): specifies the character set used in the imported data

- "TITLE_AS_FIRST_LINE" (boolean, CVS import only): TRUE to specify that the first line of the imported data contains the column names

- "G_TYPE_<col number>" (GType, CVS import only): specifies the requested GType type for the column numbered "col number"

## Details

### struct GdaDataModelImport

    struct GdaDataModelImport;

### struct GdaDataModelImportClass

    struct GdaDataModelImportClass {
    	GObjectClass               parent_class;
    };

### GdaDataModelImportPrivate

    typedef struct _GdaDataModelImportPrivate GdaDataModelImportPrivate;

### gda_data_model_import_new_file ()

    GdaDataModel *      gda_data_model_import_new_file      (const gchar *filename,
                                                             gboolean random_access,
                                                             GdaSet *options);

Creates a new GdaDataModel object which contains the data stored within the `filename` file.

The options are the following ones:

- For the CSV format:

  - ENCODING (string): specifies the encoding of the data in the file

  - SEPARATOR (string): specifies the CSV separator (comma as default)

  - QUOTE (string): specifies the character used as quote (double quote as default)

  - NAMES_ON_FIRST_LINE (boolean): consider that the first line of the file contains columns' titles (note that the TITLE_AS_FIRST_LINE option is also accepted as a synonym)

  - G_TYPE_<column number> (GType): specifies the type of value expected in column <column number>

- Other formats: no option

Note: after the creation, please use `gda_data_model_import_get_errors()` to check any error.

`filename` : | the file to import data from
`random_access` : | TRUE if random access will be required
`options` : | importing options. [transfer none][allow-none]
Returns : | a pointer to the newly created GdaDataModel. [transfer full]

### gda_data_model_import_new_mem ()

    GdaDataModel *      gda_data_model_import_new_mem       (const gchar *data,
                                                             gboolean random_access,
                                                             GdaSet *options);

Creates a new GdaDataModel object which contains the data stored in the `data` string.

Important note: the `data` string is not copied for memory efficiency reasons and should not therefore be altered in any way as long as the returned data model exists.

`data` : | a string containing the data to import
`random_access` : | TRUE if random access will be required
`options` : | importing options, see `gda_data_model_import_new_file()` for more information. [transfer none][allow-none]
Returns : | a pointer to the newly created GdaDataModel. [transfer full]

### gda_data_model_import_new_xml_node ()

    GdaDataModel *      gda_data_model_import_new_xml_node  (xmlNodePtr node);

Creates a new GdaDataModel and loads the data in `node`. The resulting data model can be accessed in a random way.

`node` : | an XML node corresponding to a <data-array> tag. [transfer none]
Returns : | a pointer to the newly created GdaDataModel. [transfer full]

### gda_data_model_import_get_errors ()

    GSList *            gda_data_model_import_get_errors    (GdaDataModelImport *model);

Get the list of errors which `model` has to report. The returned list is a list of GError structures, and must not be modified

`model` : | a GdaDataModelImport object
Returns : | the list of errors (which must not be modified), or `NULL`. [transfer none][element-type GLib.Error]

### gda_data_model_import_clean_errors ()

    void                gda_data_model_import_clean_errors  (GdaDataModelImport *model);

Clears the history of errors `model` has to report

`model` : | a GdaDataModelImport object

## Property Details

### The `"data-string"` property

      "data-string"              gchar*                : Read / Write / Construct Only

Data to import, as a string.

Default value: NULL

### The `"filename"` property

      "filename"                 gchar*                : Read / Write / Construct Only

Name of the file to import.

Default value: NULL

### The `"options"` property

      "options"                  GdaSet*               : Read / Write / Construct Only

Data model options.

### The `"random-access"` property

      "random-access"            gboolean              : Read / Write / Construct Only

Defines if the data model will be accessed randomly or through a cursor. If set to `FALSE`, access will have to be done using a cursor.

Default value: FALSE

### The `"strict"` property

      "strict"                   gboolean              : Read / Write / Construct

Defines the behaviour in case the imported data contains recoverable errors (usually too many or too few data per row). If set to `TRUE`, an error will be reported and the import will stop, and if set to `FALSE`, then the error will be reported but the import will not stop.

Default value: FALSE

Since 4.2.1

### The `"xml-node"` property

      "xml-node"                 gpointer              : Read / Write / Construct Only

Data to import, as a pointer to an XML node (a xmlNodePtr).

## See Also

GdaDataModel