GdaDataHandler

GdaDataHandler — Interface which provides data handling (conversions) capabilities

Stability Level

Stable, unless otherwise indicated

Types and Values

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 (in the user defined locale)

  • 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().

Functions

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".

Parameters

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

Note: the returned value will be in the current locale representation.

Parameters

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.

Parameters

dh

an object which implements the GdaDataHandler interface

 

sql

an SQL string, or NULL.

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

Note: the str string must be in the current locale representation

Parameters

dh

an object which implements the GdaDataHandler interface

 

str

a string or NULL.

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

Parameters

dh

an object which implements the GdaDataHandler interface

 

type

a GType

 

Returns

the new GValue, or NULL if no such value can be created.

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

Parameters

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

Parameters

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

Parameters

for_type

a GType type

 

Returns

a GdaDataHandler which must not be modified or destroyed.

[transfer none]

Since 4.2.3

Types and Values

GdaDataHandler

typedef struct _GdaDataHandler GdaDataHandler;