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, GdaHandlerType, GdaHandlerBin, GdaHandlerNumerical, GdaHandlerTime and GdaHandlerString.

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 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, 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 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

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