Re: [gnome-db] New Versions of gda-value.c and gda-value.h

["Daniel Espinosa" <esodan gmail com>]

Could you also try to give hints about how to migrate the libgda,
libgnomedb, etc code which uses the current version of the GdaValue
API, if possible using regexp replacements? This will greatly help
porting the code.

Attached you'll find the some documentation of the new API to manage values. I don't know to much about the implementation of the prividers, where I think take more work to port, but I can help any one if the explanetion isn't enough.

-- 
Trabajar, la mejor arma para tu superación
"de grano en grano, se hace la arena" (R) (entrámite, pero para los cuates: LIBRE)
CREATING A NEW VALUE

Use gda_value_new to get a Valid and pre-initated GValue using the GType as argument.

SETTING VALUES A VALUE

Use the g_value_set_* function for all standard GType in GLib (G_TYPE_INT, G_TYPE_BOOLEAN, etc); 
and use the gda_value_set_* for all Types defined in GDA (GDA_TYPE_GEOMETRIC_POINT, GDA_TYPE_TIME, etc).

If you want to use the gda_value_set_from_string, you must take in a count that it internaly use a
g_value_transform function, then, if the source GType has a destination GType transformation function
registered, the source value is modified; otherwise the source value is untouched.

The gda_value_set_from_xml, use the unique registered name of the GType in cuestion, to set the value;
it use the transformation process to convert a string value stored in the XML file.

You can reset a value and set to a new Type, using the gda_value_reset_with_type function; internaly it
use the g_value_reset and g_value_init functions.

The GDate type, used in place of the old GdaDate, can be stored in a GValue using the g_value_set_boxed,
with a GPOINTER to the GDate structure, most GDA types like GdaTimestamp use this mechanish internally in
the gda_value_set_timestamp.

GETTING VALUES

To get a value stored in a GValue, you must use the g_value_get_* function, depending of the value type
stored; to get the values from the GDA Types, you must use gda_value_get_* function.

To get a GDate, you need to use the g_value_get_boxed and cast the returned gpointer to a GDate structure;
to ensure that the GValue holds a GDate, you can use the G_VALUE_HOLDS(value, G_TYPE_DATE).

COPYING VALUES

To copy a value from a source to a destination GValue, use the g_value_copy function. To get a copy from
an other value you can use gda_value_copy.

STRINGIFY VALUES

You can use gda_value_strigify, to get a string representation of a Value. Internaly the API use g_value_transform
to cast a given value to a G_TYPE_STRING type. The GDA library have been registered a function to transform
values defined by itself, for example: GDA_TYPE_GEOMETRIC_POINT, GDA_TYPE_NUMERIC, etc; the other pre-defined
types by GLib has its own transformation function. (SEE TRANSFORM VALUES).

The transformation to one type in other isn't a trivial task, becouse depends on the needs of the developer on
how to show the data, for example: a date in local format, a gdouble precision representation and if it has
an exponation.

Then may be is a good solution to create a user-dined function to cast a value type to another, or get the value
and code for a custome transformation. This is the case of GDate, it doesn't have a G_TYPE_DATE to G_TYPE_STRING
registered function, then you must get the date and transform manualy, may in the locale representation.


TRANSFORM VALUES

As transform, you can understand a cast from a Value type to another.

In the GLib/GValue API, you have the function g_value_transform to cast a value type in other. There must be a
function registered with g_value_type_register_func to use when you try to cast from a source type to a destination
one.

CODING ISSUES

First all, the GdaValue is deprecated, use GValue enstead.

For the providers point of view, they use the old GdaValueType enum to determine the type of the value using a
switch statement, but it doesn't work again, becouse the G_TYPE_*'s isn't an enum; then you need to use the if/else
statements.

The new Value code, use the GValue API defined in GLib, then use it!