GdaDataHandler

## GdaDataHandler GdaDataHandler — Interface which provides data handling (conversions) capabilities |

## Synopsis

                        GdaDataHandler;
    gchar *             gda_data_handler_get_sql_from_value (GdaDataHandler *dh,
                                                             const GValue *value);
    gchar *             gda_data_handler_get_str_from_value (GdaDataHandler *dh,
                                                             const GValue *value);
    GValue *            gda_data_handler_get_value_from_sql (GdaDataHandler *dh,
                                                             const gchar *sql,
                                                             GType type);
    GValue *            gda_data_handler_get_value_from_str (GdaDataHandler *dh,
                                                             const gchar *str,
                                                             GType type);
    GValue *            gda_data_handler_get_sane_init_value
                                                            (GdaDataHandler *dh,
                                                             GType type);
    gboolean            gda_data_handler_accepts_g_type     (GdaDataHandler *dh,
                                                             GType type);
    const gchar *       gda_data_handler_get_descr          (GdaDataHandler *dh);

## Object Hierarchy

      GInterface
       +----GdaDataHandler

## Prerequisites

GdaDataHandler requires GObject.

## Known Implementations

GdaDataHandler is implemented by GdaHandlerBoolean, GdaHandlerString, GdaHandlerType, GdaHandlerBin, GdaHandlerNumerical and GdaHandlerTime.

## Description

Because data types vary a lot from a DBMS to another, the GdaDataHandler interface helps managing data in its various representations, and converting from one to another:

- as a GValue which is a generic value container for the C language

- as a human readable string

- as an SQL string (a string which can be used in SQL statements)

For each data type, a corresponding GdaDataHandler object can be requested using the `gda_get_default_handler()` function. However, when working with a specific database provider, it's better to use a GdaDataHandler which may be specific to the database provider which will correctly handle each database specificities using `gda_server_provider_get_data_handler_g_type()` or `gda_server_provider_get_data_handler_dbms()`.

## Details

### GdaDataHandler

    typedef struct _GdaDataHandler GdaDataHandler;

### gda_data_handler_get_sql_from_value ()

    gchar *             gda_data_handler_get_sql_from_value (GdaDataHandler *dh,
                                                             const GValue *value);

Creates a new string which is an SQL representation of the given value, the returned string can be used directly in an SQL statement. For example if `value` is a G_TYPE_STRING, then the returned string will be correctly quoted. Note however that it is a better practice to use variables in statements instead of value literals, see the GdaSqlParser for more information.

If the value is NULL or is of type GDA_TYPE_NULL, the returned string is "NULL".

`dh` : | an object which implements the GdaDataHandler interface
`value` : | the value to be converted to a string
Returns : | the new string, or `NULL` if an error occurred

### gda_data_handler_get_str_from_value ()

    gchar *             gda_data_handler_get_str_from_value (GdaDataHandler *dh,
                                                             const GValue *value);

Creates a new string which is a "user friendly" representation of the given value (in the users's locale, specially for the dates). If the value is NULL or is of type GDA_TYPE_NULL, the returned string is a copy of "" (empty string).

`dh` : | an object which implements the GdaDataHandler interface
`value` : | the value to be converted to a string
Returns : | the new string, or `NULL` if an error occurred

### gda_data_handler_get_value_from_sql ()

    GValue *            gda_data_handler_get_value_from_sql (GdaDataHandler *dh,
                                                             const gchar *sql,
                                                             GType type);

Creates a new GValue which represents the SQL value given as argument. This is the opposite of the function `gda_data_handler_get_sql_from_value()`. The type argument is used to determine the real data type requested for the returned value.

If the sql string is NULL, then the returned GValue is of type GDA_TYPE_NULL; if the sql string does not correspond to a valid SQL string for the requested type, then the "NULL" string is returned.

`dh` : | an object which implements the GdaDataHandler interface
`sql` : | an SQL string
`type` : | a GType
Returns : | the new GValue or NULL on error

### gda_data_handler_get_value_from_str ()

    GValue *            gda_data_handler_get_value_from_str (GdaDataHandler *dh,
                                                             const gchar *str,
                                                             GType type);

Creates a new GValue which represents the STR value given as argument. This is the opposite of the function `gda_data_handler_get_str_from_value()`. The type argument is used to determine the real data type requested for the returned value.

If the str string is NULL, then the returned GValue is of type GDA_TYPE_NULL; if the str string does not correspond to a valid STR string for the requested type, then NULL is returned.

`dh` : | an object which implements the GdaDataHandler interface
`str` : | a string
`type` : | a GType
Returns : | the new GValue or NULL on error

### gda_data_handler_get_sane_init_value ()

    GValue *            gda_data_handler_get_sane_init_value
                                                            (GdaDataHandler *dh,
                                                             GType type);

Creates a new GValue which holds a sane initial value to be used if no value is specifically provided. For example for a simple string, this would return a new value containing the "" string.

`dh` : | an object which implements the GdaDataHandler interface
`type` : | a GTYpe
Returns : | the new GValue, or `NULL` if no such value can be created.

### gda_data_handler_accepts_g_type ()

    gboolean            gda_data_handler_accepts_g_type     (GdaDataHandler *dh,
                                                             GType type);

Checks wether the GdaDataHandler is able to handle the gda type given as argument.

`dh` : | an object which implements the GdaDataHandler interface
`type` : | a GType
Returns : | TRUE if the gda type can be handled

### gda_data_handler_get_descr ()

    const gchar *       gda_data_handler_get_descr          (GdaDataHandler *dh);

Get a short description of the GdaDataHandler

`dh` : | an object which implements the GdaDataHandler interface
Returns : | the description