![]() |
![]() |
![]() |
GNOME Data Access 5 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
enum GdaValueAttribute; GValue * gda_value_new (GType type
); #define GDA_TYPE_NULL #define GDA_VALUE_HOLDS_NULL (value) #define GDA_TYPE_DEFAULT #define GDA_VALUE_HOLDS_DEFAULT (value) #define GDA_TYPE_BINARY #define GDA_VALUE_HOLDS_BINARY (value) #define GDA_TYPE_BLOB #define GDA_VALUE_HOLDS_BLOB (value) #define GDA_TYPE_GEOMETRIC_POINT #define GDA_VALUE_HOLDS_GEOMETRIC_POINT (value) #define GDA_TYPE_NUMERIC #define GDA_VALUE_HOLDS_NUMERIC (value) #define GDA_TYPE_SHORT #define GDA_VALUE_HOLDS_SHORT (value) #define GDA_TYPE_USHORT #define GDA_VALUE_HOLDS_USHORT (value) #define GDA_TYPE_TIME #define GDA_VALUE_HOLDS_TIME (value) #define GDA_TYPE_TIMESTAMP #define GDA_VALUE_HOLDS_TIMESTAMP (value) GValue * gda_value_new_null (void
); void gda_value_set_null (GValue *value
); GValue * gda_value_new_default (const gchar *default_val
); 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
); 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
); struct GdaNumeric; GdaNumeric * gda_numeric_new (void
); GdaNumeric * gda_numeric_copy (GdaNumeric *src
); void gda_numeric_free (GdaNumeric *numeric
); gchar * gda_numeric_get_string (GdaNumeric *numeric
); gdouble gda_numeric_get_double (GdaNumeric *numeric
); glong gda_numeric_get_precision (GdaNumeric *numeric
); glong gda_numeric_get_width (GdaNumeric *numeric
); void gda_numeric_set_double (GdaNumeric *numeric
,gdouble number
); void gda_numeric_set_from_string (GdaNumeric *numeric
,const gchar *str
); void gda_numeric_set_precision (GdaNumeric *numeric
,glong precision
); void gda_numeric_set_width (GdaNumeric *numeric
,glong width
); 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
); gboolean gda_time_valid (const GdaTime *time
); 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
); gboolean gda_timestamp_valid (const GdaTimestamp *timestamp
); 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
);
GBoxed +----GdaBinary
GBoxed +----GdaBlob
GBoxed +----GdaGeometricPoint
GBoxed +----GdaNumeric
GBoxed +----GdaTime
GBoxed +----GdaTimestamp
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.
There are two special value types which are:
the GDA_TYPE_NULL value which never changes and acutally represents an SQL NULL value
the GDA_TYPE_DEFAULT value which represents a default value which Libgda does not interpret (such as when a table column's default value is a function call)
typedef enum { GDA_VALUE_ATTR_NONE = 0, 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, GDA_VALUE_ATTR_UNUSED = 1 << 9 } GdaValueAttribute;
#define GDA_VALUE_HOLDS_DEFAULT(value) G_VALUE_HOLDS(value, GDA_TYPE_DEFAULT)
#define GDA_VALUE_HOLDS_BINARY(value) G_VALUE_HOLDS(value, GDA_TYPE_BINARY)
#define GDA_VALUE_HOLDS_GEOMETRIC_POINT(value) G_VALUE_HOLDS(value, GDA_TYPE_GEOMETRIC_POINT)
#define GDA_VALUE_HOLDS_NUMERIC(value) G_VALUE_HOLDS(value, GDA_TYPE_NUMERIC)
#define GDA_VALUE_HOLDS_USHORT(value) G_VALUE_HOLDS(value, GDA_TYPE_USHORT)
#define GDA_VALUE_HOLDS_TIMESTAMP(value) G_VALUE_HOLDS(value, GDA_TYPE_TIMESTAMP)
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
);
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 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. [transfer full]
|
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
|
a GValue to compare. |
|
the other GValue to be compared to value1 . |
Returns : |
a non 0 value if value1 and value2 differ, and 0 if they are equal |
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
|
a GValue to compare (not NULL ) |
|
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 . |
xmlNodePtr gda_value_to_xml (const GValue *value
);
Serializes the given GValue to an XML node string.
|
a GValue. |
Returns : |
the XML node. Once not needed anymore, you should free it. [transfer full] |
gpointer gda_binary_copy (gpointer boxed
);
Creates a new GdaBinary structure from an existing one.
|
source to get a copy from. |
Returns : |
a newly allocated GdaBinary which contains a copy of information in boxed .
Free-function: gda_binary_free. [transfer full]
|
void gda_binary_free (gpointer boxed
);
Deallocates all memory associated to the given GdaBinary.
|
GdaBinary to free. [transfer full] |
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 "\\". Printable characters (defined by g_ascii_isprint()
) as well as newline
character are not converted.
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()
.
|
a correctly filled GdaBinary structure |
|
a maximum len used to truncate, or 0 for no maximum length |
Returns : |
a new string from bin . [transfer full]
|
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).
I str
is NULL
, then an empty (i.e. where the data
part is NULL
) GdaBinary is created and returned.
|
a string to convert, or NULL . [allow-none]
|
Returns : |
a new GdaBinary if no error were found in str , or NULL otherwise. [transfer full]
|
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 buffer, as a GdaBinary |
GdaBlobOp * |
a pointer to a GdaBlopOp, or NULL . [allow-none]
|
gpointer gda_blob_copy (gpointer boxed
);
Creates a new GdaBlob structure from an existing one.
|
source to get a copy from. |
Returns : |
a newly allocated GdaBlob which contains a copy of information in boxed .
Free-function: gda_blob_free. [transfer full]
|
void gda_blob_free (gpointer boxed
);
Deallocates all memory associated to the given GdaBlob.
|
GdaBlob to free. [transfer full] |
void gda_blob_set_op (GdaBlob *blob
,GdaBlobOp *op
);
correctly assigns op
to blob
|
a GdaBlob value |
|
a GdaBlobOp object, or NULL . [allow-none]
|
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 "\\".
|
a correctly filled GdaBlob structure |
|
a maximum len used to truncate, or 0 for no maximum length |
Returns : |
a new string from blob . [transfer full]
|
gpointer gda_geometricpoint_copy (gpointer boxed
);
Returns : |
. [transfer full] |
const GdaGeometricPoint * gda_value_get_geometric_point (const GValue *value
);
void gda_value_set_geometric_point (GValue *value
,const GdaGeometricPoint *val
);
struct GdaNumeric { gchar* GSEAL(number); glong GSEAL(precision); glong GSEAL(width); };
Holds numbers represented as strings.
This struct must be considered as opaque. Any access to its members must use its accessors added since version 5.0.2.
Set value func: gda_value_set_numeric Get value func: gda_value_get_numeric
GdaNumeric * gda_numeric_new (void
);
Creates a new GdaNumeric with defaults.
Returns : |
a new GdaNumeric. [transfer full] |
Since 5.0.2
GdaNumeric * gda_numeric_copy (GdaNumeric *src
);
Creates a new GdaNumeric structure from an existing one.
|
source to get a copy from. |
Returns : |
a newly allocated GdaNumeric which contains a copy of information in boxed .
Free-function: gda_numeric_free. [transfer full]
|
void gda_numeric_free (GdaNumeric *numeric
);
Deallocates all memory associated to the given boxed
|
a GdaNumeric pointer. [transfer full] |
gchar * gda_numeric_get_string (GdaNumeric *numeric
);
Get the string representation of numeric
.
|
a GdaNumeric |
Returns : |
a new string representing the stored valued in numeric . [transfer full][allow-none]
|
Since 5.0.2
gdouble gda_numeric_get_double (GdaNumeric *numeric
);
|
a GdaNumeric |
Returns : |
a gdouble representation of numeric
|
Since 5.0.2
glong gda_numeric_get_precision (GdaNumeric *numeric
);
Gets the precision of a GdaNumeric.
|
a GdaNumeric |
Returns : |
an integer with the precision of a GdaNumeric. |
Since 5.0.2
glong gda_numeric_get_width (GdaNumeric *numeric
);
Gets the width of a GdaNumeric. (Not yet implemented).
|
a GdaNumeric |
Returns : |
an integer with the width of a GdaNumeric. (Not jet implemented). |
Since 5.0.2
void gda_numeric_set_double (GdaNumeric *numeric
,gdouble number
);
Sets numeric
using a gdouble represented by number
.
|
a GdaNumeric |
|
a gdouble |
Since 5.0.2
void gda_numeric_set_from_string (GdaNumeric *numeric
,const gchar *str
);
Sets numeric
with a number represented by str
. By default converts str
to
gdouble.
* Since: 5.0.2
|
a GdaNumeric |
|
a string representing a number |
void gda_numeric_set_precision (GdaNumeric *numeric
,glong precision
);
Sets the precision of a GdaNumeric.
|
a GdaNumeric |
|
a glong |
Since 5.0.2
void gda_numeric_set_width (GdaNumeric *numeric
,glong width
);
Sets the width of a GdaNumeric. (Not yet implemented).
|
a GdaNumeric |
|
a glong |
Since 5.0.2
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;
gboolean gda_timestamp_valid (const GdaTimestamp *timestamp
);
|
a GdaTimestamp value to check if it is valid |
Returns : |
TRUE if GdaTimestamp is valid; FALSE otherwise. |
Since 4.2