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

## Stability Level

Stable, unless otherwise indicated

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

    GdaDataHandler *    gda_data_handler_get_default        (GType for_type);

## Object Hierarchy

      GInterface
       +----GdaDataHandler

## Prerequisites

GdaDataHandler requires GObject.

## Known Implementations

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

## 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_data_handler_get_default()` 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 specifics 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, or is a G_TYPE_STRING and `g_value_get_string()` returns `NULL`, the returned string is "NULL".

`dh` : | an object which implements the GdaDataHandler interface
`value` : | the value to be converted to a string, or `NULL`. [allow-none]
Returns : | the new string, or `NULL` if an error occurred. [transfer full]

### 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 user'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, or `NULL`. [allow-none]
Returns : | the new string, or `NULL` if an error occurred. [transfer full]

### 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` is returned.

`dh` : | an object which implements the GdaDataHandler interface
`sql` : | an SQL string, or `NULL`. [allow-none]
`type` : | a GType
Returns : | the new GValue or `NULL` on error. [transfer full]

### 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 string for the requested type, then `NULL` is returned.

`dh` : | an object which implements the GdaDataHandler interface
`str` : | a string or `NULL`. [allow-none]
`type` : | a GType
Returns : | the new GValue or `NULL` on error. [transfer full]

### 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. [transfer full]

### 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. [transfer none]

### gda_data_handler_get_default ()

    GdaDataHandler *    gda_data_handler_get_default        (GType for_type);

Obtain a pointer to a GdaDataHandler which can manage GValue values of type `for_type`. The returned data handler will be adapted to use the current locale information (for example dates will be formatted taking into account the locale).

The returned pointer is `NULL` if there is no default data handler available for the `for_type` data type

`for_type` : | a GType type
Returns : | a GdaDataHandler which must not be modified or destroyed. [transfer none]

Since 4.2.3