Gda Value

Gda Value — Single value stored in a GdaDataModel

Functions

GValue * gda_value_new ()
#define gda_value_new_null
GValue * gda_value_new_binary ()
GValue * gda_value_new_blob ()
GValue * gda_value_new_timestamp_from_timet ()
GValue * gda_value_new_from_string ()
GValue * gda_value_new_from_xml ()
void gda_value_free ()
void gda_value_reset_with_type ()
gboolean gda_value_is_null ()
gboolean gda_value_is_number ()
#define gda_value_isa()
GValue * gda_value_copy ()
gpointer gda_binary_copy ()
void gda_binary_free ()
gpointer gda_blob_copy ()
void gda_blob_free ()
gpointer gda_geometricpoint_copy ()
void gda_geometricpoint_free ()
gpointer gda_numeric_copy ()
void gda_numeric_free ()
gpointer gda_time_copy ()
void gda_time_free ()
gpointer gda_timestamp_copy ()
void gda_timestamp_free ()
const GdaBinary * gda_value_get_binary ()
void gda_value_set_binary ()
void gda_value_take_binary ()
const GdaBlob * gda_value_get_blob ()
void gda_value_set_blob ()
void gda_value_take_blob ()
const GdaGeometricPoint * gda_value_get_geometric_point ()
void gda_value_set_geometric_point ()
const GdaValueList * gda_value_get_list ()
void gda_value_set_list ()
void gda_value_set_null ()
const GdaNumeric * gda_value_get_numeric ()
void gda_value_set_numeric ()
gshort gda_value_get_short ()
void gda_value_set_short ()
gushort gda_value_get_ushort ()
void gda_value_set_ushort ()
const GdaTime * gda_value_get_time ()
void gda_value_set_time ()
const GdaTimestamp * gda_value_get_timestamp ()
void gda_value_set_timestamp ()
gboolean gda_value_set_from_string ()
gboolean gda_value_set_from_value ()
gchar * gda_value_stringify ()
gint gda_value_compare ()
gint gda_value_compare_ext ()
xmlNodePtr gda_value_to_xml ()
gchar * gda_binary_to_string ()
gboolean gda_string_to_binary ()

Types and Values

Object Hierarchy

    GBoxed
    ├── GdaBinary
    ├── GdaGeometricPoint
    ├── GdaNumeric
    ├── GdaTime
    ├── GdaTimestamp
    ╰── GdaValueList

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, BINARY and BLOB.

Libgda makes a distinction between binary and blob types

  • binary data can be inserted into an SQL statement using a (DBMS dependant) syntax, such as "X'ABCD'" syntax for SQLite or the binary strings syntax for PostgreSQL. Binary data is manipulated using a GdaBinary structure (which is basically a bytes buffer and a length attribute).

  • blob data are a special feature that some DBMS have which requires some non SQL code to manipulate them. Usually only a reference is stored in each table containing a blob, and the actual blob data resides somewhere on the disk (while still being managed transparently by the database). For example PotsgreSQL stores blobs as files on the disk and references them using object identifiers (Oid). Blob data is manipulated using a GdaBlob structure which encapsulates a GdaBinary structure and adds a reference to a GdaBlobOp object used to read and write data from and to the blob.

Please note that is distinction between binary data and blobs is Libgda only and does not reflect the DBMS's documentations; for instance MySQL has several BLOB types but Libgda interprets them as binary types.

Each provider or connection can be queried about its blob support using the gda_server_provider_supports_feature() or gda_connection_supports_feature() methods.

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.

Functions

gda_value_new ()

GValue *
gda_value_new (GType type);

Makes a new GValue of type type .

Parameters

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 (const guchar *val,
                      glong size);

Makes a new GValue of type GDA_TYPE_BINARY with value val .

Parameters

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_blob ()

GValue *
gda_value_new_blob (const guchar *val,
                    glong size);

Makes a new GValue of type GDA_TYPE_BLOB with value val .

Parameters

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

Parameters

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.

Parameters

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 an XML representation of it. That XML node corresponds to the following string representation: <value type="gdatype">value</value>

Parameters

node

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

Parameters

value

the resource to free.

 

gda_value_reset_with_type ()

void
gda_value_reset_with_type (GValue *value,
                           GType type);


gda_value_is_null ()

gboolean
gda_value_is_null (const GValue *value);

Tests if a given value is of type GDA_TYPE_NULL.

Parameters

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.

Parameters

value

a GValue.

 

Returns

TRUE if a number, FALSE otherwise.


gda_value_isa()

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


gda_value_copy ()

GValue *
gda_value_copy (const GValue *value);

Creates a new GValue from an existing one.

Parameters

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.

Parameters

boxed

source to get a copy from.

 

Returns

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


gda_binary_free ()

void
gda_binary_free (gpointer boxed);

Deallocates all memory associated to the given GdaBinary.

Parameters

boxed

GdaBinary to free.

 

gda_blob_copy ()

gpointer
gda_blob_copy (gpointer boxed);

Creates a new GdaBlob structure from an existing one.

Parameters

boxed

source to get a copy from.

 

Returns

a newly allocated GdaBlob which contains a copy of information in boxed .


gda_blob_free ()

void
gda_blob_free (gpointer boxed);

Deallocates all memory associated to the given GdaBlob.

Parameters

boxed

GdaBlob to free.

 

gda_geometricpoint_copy ()

gpointer
gda_geometricpoint_copy (gpointer boxed);

Returns


gda_geometricpoint_free ()

void
gda_geometricpoint_free (gpointer boxed);


gda_numeric_copy ()

gpointer
gda_numeric_copy (gpointer boxed);

Creates a new GdaNumeric structure from an existing one.

Parameters

boxed

source to get a copy from.

 

Returns

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


gda_numeric_free ()

void
gda_numeric_free (gpointer boxed);

Deallocates all memory associated to the given boxed


gda_time_copy ()

gpointer
gda_time_copy (gpointer boxed);

Returns


gda_time_free ()

void
gda_time_free (gpointer boxed);


gda_timestamp_copy ()

gpointer
gda_timestamp_copy (gpointer boxed);

Returns


gda_timestamp_free ()

void
gda_timestamp_free (gpointer boxed);


gda_value_get_binary ()

const GdaBinary *
gda_value_get_binary (const GValue *value);

Parameters

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 .

Parameters

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 .

Parameters

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

Parameters

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

Stores val into value .

Parameters

value

a GValue that will store val .

 

blob

a GdaBlob structure with the data and its size to be stored in value .

 

gda_value_take_blob ()

void
gda_value_take_blob (GValue *value,
                     const GdaBlob *blob);

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

Parameters

value

a GValue that will store val .

 

blob

a GdaBlob structure with the data and its size to be stored in value .

 

gda_value_get_geometric_point ()

const GdaGeometricPoint *
gda_value_get_geometric_point (const GValue *value);

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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.

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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 an XML node string.

Parameters

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

Parameters

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

Parameters

str

a string to convert

 

bin

a non filled GdaBinary structure

 

Returns

TRUE if no error were found in str , or FALSE otherwise

Types and Values

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;


GdaBlob

typedef struct {
	GdaBinary  data;
	GdaBlobOp *op; /* set up by providers if the GdaBlob is linked to something actually existing in the database, 
			  useable by anyone */
} GdaBlob;


GdaValueList

typedef GList GdaValueList;

See Also

The GdaBlobOp object which operates on blobs