Top | ![]() |
![]() |
![]() |
![]() |
Gda ValueGda Value — Single value stored in a GdaDataModel |
GBoxed ├── GdaBinary ├── GdaGeometricPoint ├── GdaNumeric ├── GdaTime ├── GdaTimestamp ╰── GdaValueList
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.
GValue * gda_value_new_binary (const guchar *val
,glong size
);
Makes a new GValue of type GDA_TYPE_BINARY with value val
.
GValue * gda_value_new_blob (const guchar *val
,glong size
);
Makes a new GValue of type GDA_TYPE_BLOB with value val
.
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).
GValue * gda_value_new_from_string (const gchar *as_string
,GType type
);
Makes a new GValue of type type
from its string representation.
the newly created GValue or NULL
if the string representation
cannot be converted to the specified type
.
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>
void
gda_value_free (GValue *value
);
Deallocates all memory associated to a GValue.
gboolean
gda_value_is_null (const GValue *value
);
Tests if a given value
is of type GDA_TYPE_NULL.
gboolean
gda_value_is_number (const GValue *value
);
Gets whether the value stored in the given GValue is of numeric type or not.
GValue *
gda_value_copy (const GValue *value
);
Creates a new GValue from an existing one.
gpointer
gda_binary_copy (gpointer boxed
);
Creates a new GdaBinary structure from an existing one.
void
gda_binary_free (gpointer boxed
);
Deallocates all memory associated to the given GdaBinary.
gpointer
gda_blob_copy (gpointer boxed
);
Creates a new GdaBlob structure from an existing one.
void
gda_blob_free (gpointer boxed
);
Deallocates all memory associated to the given GdaBlob.
gpointer
gda_numeric_copy (gpointer boxed
);
Creates a new GdaNumeric structure from an existing one.
void
gda_numeric_free (gpointer boxed
);
Deallocates all memory associated to the given boxed
void gda_value_set_binary (GValue *value
,const GdaBinary *binary
);
Stores val
into value
.
value |
a GValue that will store |
|
binary |
a GdaBinary structure with the data and its size to be stored in |
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 |
|
binary |
a GdaBinary structure with the data and its size to be stored in |
void gda_value_set_blob (GValue *value
,const GdaBlob *blob
);
Stores val
into value
.
value |
a GValue that will store |
|
blob |
a GdaBlob structure with the data and its size to be stored in |
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
.
value |
a GValue that will store |
|
blob |
a GdaBlob structure with the data and its size to be stored in |
const GdaGeometricPoint *
gda_value_get_geometric_point (const GValue *value
);
void gda_value_set_geometric_point (GValue *value
,const GdaGeometricPoint *val
);
Stores val
into value
.
void gda_value_set_list (GValue *value
,const GdaValueList *val
);
Stores val
into value
.
void
gda_value_set_null (GValue *value
);
Sets the type of value
to GDA_TYPE_NULL.
void gda_value_set_numeric (GValue *value
,const GdaNumeric *val
);
Stores val
into value
.
void gda_value_set_short (GValue *value
,const gshort val
);
Stores val
into value
.
void gda_value_set_ushort (GValue *value
,const gushort val
);
Stores val
into value
.
void gda_value_set_time (GValue *value
,const GdaTime *val
);
Stores val
into value
.
void gda_value_set_timestamp (GValue *value
,const GdaTimestamp *val
);
Stores val
into value
.
gboolean gda_value_set_from_string (GValue *value
,const gchar *as_string
,GType type
);
Stores the value data from its string representation as type
.
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.
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.
a new string, or NULL
if the conversion cannot be done. Free the value with a g_free()
when you've finished
using it.
gint gda_value_compare (const GValue *value1
,const GValue *value2
);
Compares two values of the same type.
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
xmlNodePtr
gda_value_to_xml (const GValue *value
);
Serializes the given GValue to an XML node 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 "\".
gboolean gda_string_to_binary (const gchar *str
,GdaBinary *bin
);
Performs the reverse of gda_binary_to_string()
.
typedef struct { gushort hour; gushort minute; gushort second; gulong fraction; glong timezone; /* # of seconds to the east UTC */ } GdaTime;
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;
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;