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

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