Gda Value

Gda Value — Single value stored in a GdaDataModel

Synopsis




enum        GValueAttribute;
            GdaGeometricPoint;
            GdaNumeric;
            GdaTime;
            GdaTimestamp;
            GdaBinary;
typedef     GdaValueList;
GValue*     gda_value_new                   (GType type);
#define     gda_value_new_null              ()
GValue*     gda_value_new_binary            (guchar *val,
                                             glong size);
GValue*     gda_value_new_timestamp_from_timet
                                            (time_t val);
GValue*     gda_value_new_from_string       (const gchar *as_string,
                                             GType type);
GValue*     gda_value_new_from_xml          (const xmlNodePtr node);
void        gda_value_free                  (GValue *value);
void        gda_value_reset_with_type       (GValue *value,
                                             GType type);
gboolean    gda_value_is_null               (const GValue *value);
gboolean    gda_value_is_number             (const GValue *value);
#define     gda_value_isa                   (value, type)
GValue*     gda_value_copy                  (const GValue *value);
gpointer    gda_binary_copy                 (gpointer boxed);
void        gda_binary_free                 (gpointer boxed);
gpointer    gda_geometricpoint_copy         (gpointer boxed);
void        gda_geometricpoint_free         (gpointer boxed);
gpointer    gda_numeric_copy                (gpointer boxed);
void        gda_numeric_free                (gpointer boxed);
gpointer    gda_time_copy                   (gpointer boxed);
void        gda_time_free                   (gpointer boxed);
gpointer    gda_timestamp_copy              (gpointer boxed);
void        gda_timestamp_free              (gpointer boxed);
const GdaBinary* gda_value_get_binary       (const GValue *value);
void        gda_value_set_binary            (GValue *value,
                                             const GdaBinary *binary);
void        gda_value_take_binary           (GValue *value,
                                             const GdaBinary *binary);
const GdaBlob* gda_value_get_blob           (const GValue *value);
void        gda_value_set_blob              (GValue *value,
                                             const GdaBlob *val);
const GdaGeometricPoint* gda_value_get_geometric_point
                                            (const GValue *value);
void        gda_value_set_geometric_point   (GValue *value,
                                             const GdaGeometricPoint *val);
const GdaValueList* gda_value_get_list      (const GValue *value);
void        gda_value_set_list              (GValue *value,
                                             const GdaValueList *val);
void        gda_value_set_null              (GValue *value);
const GdaNumeric* gda_value_get_numeric     (const GValue *value);
void        gda_value_set_numeric           (GValue *value,
                                             const GdaNumeric *val);
gshort      gda_value_get_short             (const GValue *value);
void        gda_value_set_short             (GValue *value,
                                             const gshort val);
gushort     gda_value_get_ushort            (const GValue *value);
void        gda_value_set_ushort            (GValue *value,
                                             const gushort val);
const GdaTime* gda_value_get_time           (const GValue *value);
void        gda_value_set_time              (GValue *value,
                                             const GdaTime *val);
const GdaTimestamp* gda_value_get_timestamp (const GValue *value);
void        gda_value_set_timestamp         (GValue *value,
                                             const GdaTimestamp *val);
gboolean    gda_value_set_from_string       (GValue *value,
                                             const gchar *as_string,
                                             GType type);
gboolean    gda_value_set_from_value        (GValue *value,
                                             const GValue *from);
gchar*      gda_value_stringify             (const GValue *value);
gint        gda_value_compare               (const GValue *value1,
                                             const GValue *value2);
gint        gda_value_compare_ext           (const GValue *value1,
                                             const GValue *value2);
xmlNodePtr  gda_value_to_xml                (const GValue *value);
gchar*      gda_binary_to_string            (const GdaBinary *bin,
                                             guint maxlen);
gboolean    gda_string_to_binary            (const gchar *str,
                                             GdaBinary *bin);

Description

libgda manages each individual value within an opaque GValue structure. Any GValue type can be used, and libgda adds a few more data types usually found in DBMS such as NUMERIC, TIME, TIMESTAMP, GEOMETRIC POINT and BINARY.

The NULL value is a special case value: it is represented by to a zero-filled (uninitialized) GValue and has a type equal to GDA_TYPE_NULL.

Details

enum GValueAttribute

typedef enum  {
        GDA_VALUE_ATTR_IS_NULL        = 1 << 0,
        GDA_VALUE_ATTR_CAN_BE_NULL    = 1 << 1,
        GDA_VALUE_ATTR_IS_DEFAULT     = 1 << 2,
        GDA_VALUE_ATTR_CAN_BE_DEFAULT = 1 << 3,
        GDA_VALUE_ATTR_IS_UNCHANGED   = 1 << 4,
        GDA_VALUE_ATTR_ACTIONS_SHOWN  = 1 << 5,
        GDA_VALUE_ATTR_DATA_NON_VALID = 1 << 6,
        GDA_VALUE_ATTR_HAS_VALUE_ORIG = 1 << 7,
	GDA_VALUE_ATTR_NO_MODIF       = 1 << 8,
} GValueAttribute;


GdaGeometricPoint

typedef struct {
	gdouble x;
	gdouble y;
} GdaGeometricPoint;


GdaNumeric

typedef struct {
	gchar *number;
	glong precision;
	glong width;
} GdaNumeric;


GdaTime

typedef struct {
	gushort hour;
	gushort minute;
	gushort second;
	gulong fraction;
	glong timezone;	/* # of seconds to the east UTC */
} GdaTime;


GdaTimestamp

typedef struct {
	gshort year;
	gushort month;
	gushort day;
	gushort hour;
	gushort minute;
	gushort second;
	gulong fraction;
	glong timezone;	/* # of seconds to the east UTC */
} GdaTimestamp;


GdaBinary

typedef struct {
	guchar *data;
	glong  binary_length;
} GdaBinary;


GdaValueList

typedef GList GdaValueList;


gda_value_new ()

GValue*     gda_value_new                   (GType type);

Makes a new GValue of type type.

type : the new value type.
Returns : the newly created GValue with the specified type. You need to set the value in the returned GValue.

gda_value_new_null()

#define                           gda_value_new_null() (g_new0 (GValue, 1))

Returns :

gda_value_new_binary ()

GValue*     gda_value_new_binary            (guchar *val,
                                             glong size);

Makes a new GValue of type GDA_TYPE_BINARY with value val.

val : value to set for the new GValue.
size : the size of the memory pool pointer to by val.
Returns : the newly created GValue.

gda_value_new_timestamp_from_timet ()

GValue*     gda_value_new_timestamp_from_timet
                                            (time_t val);

Makes a new GValue of type GDA_TYPE_TIMESTAMP with value val (of type time_t).

val : value to set for the new GValue.
Returns : the newly created GValue.

gda_value_new_from_string ()

GValue*     gda_value_new_from_string       (const gchar *as_string,
                                             GType type);

Makes a new GValue of type type from its string representation.

as_string : stringified representation of the value.
type : the new value type.
Returns : the newly created GValue or NULL if the string representation cannot be converted to the specified type.

gda_value_new_from_xml ()

GValue*     gda_value_new_from_xml          (const xmlNodePtr node);

Creates a GValue from a XML representation of it. That XML node corresponds to the following string representation: <value type="gdatype">value</value>

node : a XML node representing the value.
Returns : the newly created GValue.

gda_value_free ()

void        gda_value_free                  (GValue *value);

Deallocates all memory associated to a GValue.

value : the resource to free.

gda_value_reset_with_type ()

void        gda_value_reset_with_type       (GValue *value,
                                             GType type);

value :
type :

gda_value_is_null ()

gboolean    gda_value_is_null               (const GValue *value);

Tests if a given value is of type GDA_TYPE_NULL.

value : value to test.
Returns : a boolean that says whether or not value is of type GDA_TYPE_NULL.

gda_value_is_number ()

gboolean    gda_value_is_number             (const GValue *value);

Gets whether the value stored in the given GValue is of numeric type or not.

value : a GValue.
Returns : TRUE if a number, FALSE otherwise.

gda_value_isa()

#define gda_value_isa(value, type) (G_VALUE_HOLDS(value, type))

value :
type :

gda_value_copy ()

GValue*     gda_value_copy                  (const GValue *value);

Creates a new GValue from an existing one.

value : value to get a copy from.
Returns : a newly allocated GValue with a copy of the data in value.

gda_binary_copy ()

gpointer    gda_binary_copy                 (gpointer boxed);

Creates a new GdaBinary structure from an existing one.

boxed :
Returns : a newly allocated GdaBinary which contains a copy of information in src.

gda_binary_free ()

void        gda_binary_free                 (gpointer boxed);

Deallocates all memory associated to the given GdaBinary.

boxed : GdaBinary to free.

gda_geometricpoint_copy ()

gpointer    gda_geometricpoint_copy         (gpointer boxed);

boxed :
Returns :

gda_geometricpoint_free ()

void        gda_geometricpoint_free         (gpointer boxed);

boxed :

gda_numeric_copy ()

gpointer    gda_numeric_copy                (gpointer boxed);

Creates a new GdaNumeric structure from an existing one.

boxed :
Returns : a newly allocated GdaNumeric which contains a copy of information in src.

gda_numeric_free ()

void        gda_numeric_free                (gpointer boxed);

Deallocates all memory associated to the given boxed

boxed :

gda_time_copy ()

gpointer    gda_time_copy                   (gpointer boxed);

boxed :
Returns :

gda_time_free ()

void        gda_time_free                   (gpointer boxed);

boxed :

gda_timestamp_copy ()

gpointer    gda_timestamp_copy              (gpointer boxed);

boxed :
Returns :

gda_timestamp_free ()

void        gda_timestamp_free              (gpointer boxed);

boxed :

gda_value_get_binary ()

const GdaBinary* gda_value_get_binary       (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_binary ()

void        gda_value_set_binary            (GValue *value,
                                             const GdaBinary *binary);

Stores val into value.

value : a GValue that will store val.
binary : a GdaBinary structure with the data and its size to be stored in value.

gda_value_take_binary ()

void        gda_value_take_binary           (GValue *value,
                                             const GdaBinary *binary);

Stores val into value, but on the contrary to gda_value_set_binary(), the binary argument is not copied, but used as-is and it should be considered owned by value.

value : a GValue that will store val.
binary : a GdaBinary structure with the data and its size to be stored in value.

gda_value_get_blob ()

const GdaBlob* gda_value_get_blob           (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_blob ()

void        gda_value_set_blob              (GValue *value,
                                             const GdaBlob *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_geometric_point ()

const GdaGeometricPoint* gda_value_get_geometric_point
                                            (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_geometric_point ()

void        gda_value_set_geometric_point   (GValue *value,
                                             const GdaGeometricPoint *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_list ()

const GdaValueList* gda_value_get_list      (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_list ()

void        gda_value_set_list              (GValue *value,
                                             const GdaValueList *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_set_null ()

void        gda_value_set_null              (GValue *value);

Sets the type of value to GDA_TYPE_NULL.

value : a GValue that will store a value of type GDA_TYPE_NULL.

gda_value_get_numeric ()

const GdaNumeric* gda_value_get_numeric     (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_numeric ()

void        gda_value_set_numeric           (GValue *value,
                                             const GdaNumeric *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_short ()

gshort      gda_value_get_short             (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_short ()

void        gda_value_set_short             (GValue *value,
                                             const gshort val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_ushort ()

gushort     gda_value_get_ushort            (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_ushort ()

void        gda_value_set_ushort            (GValue *value,
                                             const gushort val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_time ()

const GdaTime* gda_value_get_time           (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_time ()

void        gda_value_set_time              (GValue *value,
                                             const GdaTime *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_get_timestamp ()

const GdaTimestamp* gda_value_get_timestamp (const GValue *value);

value : a GValue whose value we want to get.
Returns : the value stored in value.

gda_value_set_timestamp ()

void        gda_value_set_timestamp         (GValue *value,
                                             const GdaTimestamp *val);

Stores val into value.

value : a GValue that will store val.
val : value to be stored in value.

gda_value_set_from_string ()

gboolean    gda_value_set_from_string       (GValue *value,
                                             const gchar *as_string,
                                             GType type);

Stores the value data from its string representation as type.

value : a GValue that will store val.
as_string : the stringified representation of the value.
type : the type of the value
Returns : TRUE if the value has been converted to type from its string representation; it not means that the value is converted successfully, just that the transformation is avairable. FALSE otherwise.

gda_value_set_from_value ()

gboolean    gda_value_set_from_value        (GValue *value,
                                             const GValue *from);

Sets the value of a GValue from another GValue. This is different from gda_value_copy, which creates a new GValue. gda_value_set_from_value, on the other hand, copies the contents of copy into value, which must already be allocated.

value : a GValue.
from : the value to copy from.
Returns : TRUE if successful, FALSE otherwise.

gda_value_stringify ()

gchar*      gda_value_stringify             (const GValue *value);

Converts a GValue to its string representation which is a human readable value. Note that the returned string does not take into account the current locale of the user (on the contrary to the GdaDataHandler objects). Using this function should be limited to debugging and values serialization purposes.

Dates are converted in a YYYY-MM-DD format.

value : a GValue.
Returns : a new string, or NULL if the conversion cannot be done. Free the value with a g_free() when you've finished using it.

gda_value_compare ()

gint        gda_value_compare               (const GValue *value1,
                                             const GValue *value2);

Compares two values of the same type.

value1 : a GValue to compare.
value2 : the other GValue to be compared to value1.
Returns : if both values have the same type, returns 0 if both contain the same value, an integer less than 0 if value1 is less than value2 or an integer greater than 0 if value1 is greater than value2.

gda_value_compare_ext ()

gint        gda_value_compare_ext           (const GValue *value1,
                                             const GValue *value2);

Like gda_value_compare(), compares two values of the same type, except that NULL values and values of type GDA_TYPE_NULL are considered equals

value1 : a GValue to compare.
value2 : the other GValue to be compared to value1.
Returns : 0 if both contain the same value, an integer less than 0 if value1 is less than value2 or an integer greater than 0 if value1 is greater than value2.

gda_value_to_xml ()

xmlNodePtr  gda_value_to_xml                (const GValue *value);

Serializes the given GValue to a XML node string.

value : a GValue.
Returns : the XML node. Once not needed anymore, you should free it.

gda_binary_to_string ()

gchar*      gda_binary_to_string            (const GdaBinary *bin,
                                             guint maxlen);

Converts all the non printable characters of bin->data into the \xxx representation where xxx is the octal representation of the byte, and the '\' (backslash) character is converted to "\\".

bin : a correctly filled GdaBinary structure
maxlen : a maximum len used to truncate, or 0 for no maximum length
Returns : a new string from bin

gda_string_to_binary ()

gboolean    gda_string_to_binary            (const gchar *str,
                                             GdaBinary *bin);

Performs the reverse of gda_binary_to_string().

str : a string to convert
bin : a non filled GdaBinary structure
Returns : TRUE if no error were found in str, or FALSE otherwise