A single Value

A single Value — Assorted functions for dealing with GValue values.

Synopsis

GValue *            gda_value_new                       (GType type);
#define             gda_value_new_null                  ()
GValue *            gda_value_copy                      (const GValue *value);
void                gda_value_free                      (GValue *value);
GValue *            gda_value_new_from_string           (const gchar *as_string,
                                                         GType type);
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);
void                gda_value_set_null                  (GValue *value);
gchar *             gda_value_stringify                 (const GValue *value);
gint                gda_value_differ                    (const GValue *value1,
                                                         const GValue *value2);
gint                gda_value_compare                   (const GValue *value1,
                                                         const GValue *value2);
GValue *            gda_value_new_from_xml              (const xmlNodePtr node);
xmlNodePtr          gda_value_to_xml                    (const 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)

                    GdaBinary;
GValue *            gda_value_new_binary                (const guchar *val,
                                                         glong size);
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,
                                                         GdaBinary *binary);
gpointer            gda_binary_copy                     (gpointer boxed);
void                gda_binary_free                     (gpointer boxed);
gchar *             gda_binary_to_string                (const GdaBinary *bin,
                                                         guint maxlen);
GdaBinary *         gda_string_to_binary                (const gchar *str);

                    GdaBlob;
GValue *            gda_value_new_blob                  (const guchar *val,
                                                         glong size);
GValue *            gda_value_new_blob_from_file        (const gchar *filename);
gpointer            gda_blob_copy                       (gpointer boxed);
void                gda_blob_free                       (gpointer boxed);
const GdaBlob *     gda_value_get_blob                  (const GValue *value);
void                gda_value_set_blob                  (GValue *value,
                                                         const GdaBlob *blob);
void                gda_value_take_blob                 (GValue *value,
                                                         GdaBlob *blob);
void                gda_blob_set_op                     (GdaBlob *blob,
                                                         GdaBlobOp *op);
gchar *             gda_blob_to_string                  (GdaBlob *blob,
                                                         guint maxlen);

                    GdaGeometricPoint;
gpointer            gda_geometricpoint_copy             (gpointer boxed);
void                gda_geometricpoint_free             (gpointer boxed);
const GdaGeometricPoint * gda_value_get_geometric_point (const GValue *value);
void                gda_value_set_geometric_point       (GValue *value,
                                                         const GdaGeometricPoint *val);

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

                    GdaNumeric;
gpointer            gda_numeric_copy                    (gpointer boxed);
void                gda_numeric_free                    (gpointer boxed);
const GdaNumeric *  gda_value_get_numeric               (const GValue *value);
void                gda_value_set_numeric               (GValue *value,
                                                         const GdaNumeric *val);

                    GdaTime;
gpointer            gda_time_copy                       (gpointer boxed);
void                gda_time_free                       (gpointer boxed);
const GdaTime *     gda_value_get_time                  (const GValue *value);
void                gda_value_set_time                  (GValue *value,
                                                         const GdaTime *val);

                    GdaTimestamp;
gpointer            gda_timestamp_copy                  (gpointer boxed);
void                gda_timestamp_free                  (gpointer boxed);
const GdaTimestamp * gda_value_get_timestamp            (const GValue *value);
void                gda_value_set_timestamp             (GValue *value,
                                                         const GdaTimestamp *val);
GValue *            gda_value_new_timestamp_from_timet  (time_t 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);

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

Details

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_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_value_free ()

void                gda_value_free                      (GValue *value);

Deallocates all memory associated to a GValue.

value :

the resource to free.

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.

For more information about the string format, see the gda_value_set_from_string() function. This function is typically used when reading configuration files or other non-user input that should be locale independent.

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

The accepted formats are:

This function is typically used when reading configuration files or other non-user input that should be locale independent.

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 available. 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_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_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_differ ()

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

Tells if two values are equal or not, by comparing memory representations. Unlike gda_value_compare(), the returned value is boolean, and gives no idea about ordering.

The two values must be of the same type, with the exception that a value of any type can be compared to a GDA_TYPE_NULL value, specifically:

  • if value1 and value2 are both GDA_TYPE_NULL values then the returned value is 0

  • if value1 is a GDA_TYPE_NULL value and value2 is of another type then the returned value is 1

  • if value1 is of another type and value2 is a GDA_TYPE_NULL value then the returned value is 1

  • in all other cases, value1 and value2 must be of the same type and their values are compared

value1 :

a GValue to compare.

value2 :

the other GValue to be compared to value1.

Returns :

a non 0 value if value1 and value2 differ, and 0 if they are equal

gda_value_compare ()

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

Compares two values of the same type, with the exception that a value of any type can be compared to a GDA_TYPE_NULL value, specifically:

  • if value1 and value2 are both GDA_TYPE_NULL values then the returned value is 0

  • if value1 is a GDA_TYPE_NULL value and value2 is of another type then the returned value is -1

  • if value1 is of another type and value2 is a GDA_TYPE_NULL value then the returned value is 1

  • in all other cases, value1 and value2 must be of the same type and their values are compared

value1 :

a GValue to compare (not NULL)

value2 :

the other GValue to be compared to value1 (not NULL)

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_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>

For more information about the string format, see the gda_value_set_from_string() function. This function is typically used when reading configuration files or other non-user input that should be locale independent.

node :

an XML node representing the value.

Returns :

the newly created GValue.

gda_value_to_xml ()

xmlNodePtr          gda_value_to_xml                    (const GValue *value);

Serializes the given GValue to an XML node string.

value :

a GValue.

Returns :

the XML node. Once not needed anymore, you should free it.

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 :


GdaBinary

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


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.

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_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,
                                                         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_binary_copy ()

gpointer            gda_binary_copy                     (gpointer boxed);

Creates a new GdaBinary structure from an existing one.

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.

boxed :

GdaBinary to free.

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 "\xyz" representation where "xyz" is the octal representation of the byte, and the '\' (backslash) character is converted to "\\".

Note that the backslash and newline characters are considered as printable characters and will not be represented by the "\xyz" representation.

Use this function to get a representation as much readable by humans as possible of a binary chunk. Note that this function is internally called when transforming a binary value to a string for example when using g_value_transform() or gda_value_stringify().

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

GdaBinary *         gda_string_to_binary                (const gchar *str);

Performs the reverse of gda_binary_to_string() (note that for any "\xyz" succession of 4 characters where "xyz" represents a valid octal value, the resulting read value will be modulo 256)

str :

a string to convert

Returns :

a new GdaBinary if no error were found in str, or NULL otherwise

GdaBlob

typedef struct {
	GdaBinary  data;
	GdaBlobOp *op;
} GdaBlob;

Represents some binary data, accessed through a GdaBlobOp object. op is generally set up by database providers when giving access to an existing BLOB in a database, but can be modified if needed using gda_blob_set_op().

GdaBinary data;

data buffer, as a GdaBinary

GdaBlobOp *op;

a pointer to a GdaBlopOp, or NULL

gda_value_new_blob ()

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

Makes a new GValue of type GDA_TYPE_BLOB with the data contained by 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_blob_from_file ()

GValue *            gda_value_new_blob_from_file        (const gchar *filename);

filename :

Returns :


gda_blob_copy ()

gpointer            gda_blob_copy                       (gpointer boxed);

Creates a new GdaBlob structure from an existing one.

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.

boxed :

GdaBlob to free.

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

Stores val into value.

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

value :

a GValue that will store val.

blob :

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

gda_blob_set_op ()

void                gda_blob_set_op                     (GdaBlob *blob,
                                                         GdaBlobOp *op);

correctly assigns op to blob

blob :

a GdaBlob value

op :

a GdaBlobOp object, or NULL

gda_blob_to_string ()

gchar *             gda_blob_to_string                  (GdaBlob *blob,
                                                         guint maxlen);

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

blob :

a correctly filled GdaBlob structure

maxlen :

a maximum len used to truncate, or 0 for no maximum length

Returns :

a new string from blob

GdaGeometricPoint

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


gda_geometricpoint_copy ()

gpointer            gda_geometricpoint_copy             (gpointer boxed);

boxed :

Returns :


gda_geometricpoint_free ()

void                gda_geometricpoint_free             (gpointer boxed);

boxed :


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.

GdaValueList

typedef GList GdaValueList;


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.

GdaNumeric

typedef struct {
	gchar   *number;
	glong    precision;
	glong    width;
	gpointer reserved; /* reserved for future usage with GMP (http://gmplib.org/) */
} GdaNumeric;


gda_numeric_copy ()

gpointer            gda_numeric_copy                    (gpointer boxed);

Creates a new GdaNumeric structure from an existing one.

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

boxed :

a GdaNumeric pointer

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.

GdaTime

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


gda_time_copy ()

gpointer            gda_time_copy                       (gpointer boxed);

boxed :

Returns :


gda_time_free ()

void                gda_time_free                       (gpointer boxed);

boxed :


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.

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;

gshort year;

representation of the date

gushort month;

month representation of the date, as a number between 1 and 12

gushort day;

day representation of the date, as a number between 1 and 31

gushort hour;

gushort minute;

gushort second;

gulong fraction;

glong timezone;


gda_timestamp_copy ()

gpointer            gda_timestamp_copy                  (gpointer boxed);

boxed :

Returns :


gda_timestamp_free ()

void                gda_timestamp_free                  (gpointer boxed);

boxed :


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

See Also

The GdaBlobOp object which operates on blobs