![]() |
![]() |
![]() |
GNOME Data Access manual | ![]() |
---|---|---|---|---|
Gda ValueGda Value — Single value stored in a GdaDataModel |
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);
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.
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;
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;
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.
|
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. |
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. |
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 .
|
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. |
void gda_value_free (GValue *value);
Deallocates all memory associated to a GValue.
value : |
the resource to free. |
void gda_value_reset_with_type (GValue *value, GType type);
value : |
|
type : |
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.
|
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.
|
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 .
|
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 .
|
void gda_binary_free (gpointer boxed);
Deallocates all memory associated to the given GdaBinary.
boxed : |
GdaBinary to free. |
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 .
|
void gda_numeric_free (gpointer boxed);
Deallocates all memory associated to the given boxed
boxed : |
const GdaBinary* gda_value_get_binary (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
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 .
|
const GdaBlob* gda_value_get_blob (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
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 .
|
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 .
|
const GdaValueList* gda_value_get_list (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
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. |
const GdaNumeric* gda_value_get_numeric (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
gshort gda_value_get_short (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
gushort gda_value_get_ushort (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
const GdaTime* gda_value_get_time (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
const GdaTimestamp* gda_value_get_timestamp (const GValue *value);
value : |
a GValue whose value we want to get. |
Returns : | the value stored in value .
|
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 .
|
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.
|
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.
|
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.
|
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 .
|
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 .
|
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. |
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
|
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
|