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

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