Top |
A single ValueA single Value — Assorted functions for dealing with GValue values |
Functions
Description
manages each individual value within an opaque GValue structure. Any GValue type can be used, and 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 does not interpret (such as when a table column's default value is a function call)
Functions
gda_numeric_new ()
GdaNumeric *
gda_numeric_new (void
);
Creates a new GdaNumeric with defaults.
Since: 5.0.2
gda_numeric_copy ()
GdaNumeric *
gda_numeric_copy (GdaNumeric *src
);
Creates a new GdaNumeric structure from an existing one.
Returns
a newly allocated GdaNumeric which contains a copy of information in boxed
.
Free-function: gda_numeric_free.
[transfer full]
gda_numeric_set_from_string ()
void gda_numeric_set_from_string (GdaNumeric *numeric
,const gchar *str
);
Sets numeric
with a number represented by str
, in the C locale format (dot as a fraction separator).
Since: 5.0.2
gda_numeric_set_double ()
void gda_numeric_set_double (GdaNumeric *numeric
,gdouble number
);
Sets numeric
using a gdouble represented by number
.
Since: 5.0.2
gda_numeric_set_precision ()
void gda_numeric_set_precision (GdaNumeric *numeric
,glong precision
);
Sets the precision of a GdaNumeric.
Since: 5.0.2
gda_numeric_get_precision ()
glong
gda_numeric_get_precision (const GdaNumeric *numeric
);
Gets the precision of a GdaNumeric.
Since: 5.0.2
gda_numeric_set_width ()
void gda_numeric_set_width (GdaNumeric *numeric
,glong width
);
Sets the width of a GdaNumeric. (Not yet implemented).
Since: 5.0.2
gda_numeric_get_width ()
glong
gda_numeric_get_width (const GdaNumeric *numeric
);
Gets the width of a GdaNumeric. (Not yet implemented).
Since: 5.0.2
gda_numeric_get_string ()
gchar *
gda_numeric_get_string (const GdaNumeric *numeric
);
Get the string representation of numeric
, in the C locale format (dot as a fraction separator).
Since: 5.0.2
gda_numeric_free ()
void
gda_numeric_free (GdaNumeric *numeric
);
Deallocates all memory associated to the given boxed
gda_time_new_from_values ()
GdaTime * gda_time_new_from_values (gushort hour
,gushort minute
,gushort second
,gulong fraction
,glong timezone
);
gda_time_get_timezone ()
glong
gda_time_get_timezone (const GdaTime *time
);
Returns number of seconds to be added to UTC time.
Since: 6.0
gda_time_set_timezone ()
void gda_time_set_timezone (GdaTime *time
,glong timezone
);
Parameters
time |
a GdaTime value to set time zone to |
|
timezone |
new time zone to set to. See gda_time_change_timezone |
Since: 6.0
gda_time_change_timezone ()
void gda_time_change_timezone (GdaTime *time
,glong ntz
);
Changes time
's timezone (for example to convert from GMT to another time zone).
If time
's current timezone is unset (i.e. equal to GDA_TIMEZONE_INVALID
), then this function simply sets
time
's timezone attribute; Otherwise, it adds or removes hours, minutes or seconds to reflect the time in the new timezone.
Note: the resulting will always be a valid time.
Since: 5.2
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. |
[transfer full] |
size |
the size of the memory pool pointer to by |
gda_value_set_binary ()
void gda_value_set_binary (GValue *value
,GdaBinary *binary
);
Stores val
into 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
.
gda_binary_new ()
GdaBinary *
gda_binary_new (void
);
Creates a new GdaBinary coping data.
Since: 6.0
gda_binary_reset_data ()
void
gda_binary_reset_data (GdaBinary *binary
);
Frees data referenced by GdaBinary
Since: 6.0
gda_binary_set_data ()
void gda_binary_set_data (GdaBinary *binary
,const guchar *val
,glong size
);
Set binary data to a GdaBinary, holding a copy of the data.
Since: 6.0
gda_binary_take_data ()
void gda_binary_take_data (GdaBinary *binary
,guchar *val
,glong size
);
Set binary data to a GdaBinary, directly holding val
(no copy made).
Parameters
val |
value to be taken by GdaBinary. |
[array length=size][element-type guint8] |
size |
the size of the memory pool pointer to by |
gda_binary_copy ()
GdaBinary *
gda_binary_copy (GdaBinary *src
);
Creates a new GdaBinary structure from an existing one.
gda_binary_free ()
void
gda_binary_free (GdaBinary *binary
);
Deallocates all memory associated to the given GdaBinary.
gda_blob_copy ()
GdaBlob *
gda_blob_copy (GdaBlob *src
);
Creates a new GdaBlob structure from an existing one.
gda_blob_free ()
void
gda_blob_free (GdaBlob *blob
);
Deallocates all memory associated to the given GdaBlob.
gda_blob_set_op ()
void gda_blob_set_op (GdaBlob *blob
,GdaBlobOp *op
);
Correctly assigns op
to blob
(increases op
's reference count)
gda_value_new ()
GValue *
gda_value_new (GType type
);
Creates a new GValue of type type
, left in the same state as when g_value_init()
is called.
Returns
the newly created GValue with the specified type
. You need to set the value in the returned GValue.
Free-function: gda_value_free.
[transfer full]
gda_value_new_null ()
GValue *
gda_value_new_null (void
);
Creates a new GValue initiated to a GdaNull structure with a GDA_TYPE_NULL, to represent a NULL in the database.
gda_value_new_default ()
GValue *
gda_value_new_default (const gchar *default_val
);
Creates a new default value.
Since: 4.2.9
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
.
Parameters
val |
value to set for the new GValue. |
|
size |
the size of the memory pool pointer to by |
gda_value_new_blob_from_file ()
GValue *
gda_value_new_blob_from_file (const gchar *filename
);
Makes a new GValue of type GDA_TYPE_BLOB interfacing with the contents of the file
named filename
gda_value_new_time_from_timet ()
GValue *
gda_value_new_time_from_timet (time_t val
);
Makes a new GValue of type GDA_TYPE_TIME with value val
(of type time_t). The returned times's value is relative to the current
timezone (i.e. is localtime).
For example, to get a time representing the current time, use:
ts = gda_value_new_time_from_timet (time (NULL));
Returns
the newly created GValue, or NULL
in case of error
Free-function: gda_value_free.
[transfer full]
Since: 6.0
gda_value_new_date_time_from_timet ()
GValue *
gda_value_new_date_time_from_timet (time_t val
);
gda_value_new_date_time_from_timet
has been deprecated since version 6.0 and should not be used in newly-written code.
Use gda_value_new_date_time_from_timet()
instead
Makes a new GValue of type G_TYPE_DATE_TIME with value val
(of type time_t). The returned timestamp's value is relative to the current
timezone (i.e. is localtime).
For example, to get a time stamp representing the current date and time, use:
ts = gda_value_new_date_time_from_timet (time (NULL));
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.
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.
gda_value_free ()
void
gda_value_free (GValue *value
);
Deallocates all memory associated to a GValue.
gda_value_is_null ()
gboolean
gda_value_is_null (const GValue *value
);
Tests if a given 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.
gda_value_copy ()
GValue *
gda_value_copy (const GValue *value
);
Creates a new GValue from an existing one.
Returns
a newly allocated GValue with a copy of the data in value
.
Free-function: gda_value_free.
[transfer full]
gda_value_set_blob ()
void gda_value_set_blob (GValue *value
,const GdaBlob *blob
);
Stores val
into 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
.
gda_value_get_geometric_point ()
const GdaGeometricPoint *
gda_value_get_geometric_point (const GValue *value
);
gda_value_set_geometric_point ()
void gda_value_set_geometric_point (GValue *value
,const GdaGeometricPoint *val
);
Stores val
into value
.
gda_value_set_null ()
void
gda_value_set_null (GValue *value
);
Sets the type of value
to GDA_TYPE_NULL.
gda_value_set_numeric ()
void gda_value_set_numeric (GValue *value
,const GdaNumeric *val
);
Stores val
into value
.
gda_value_set_short ()
void gda_value_set_short (GValue *value
,const gshort val
);
Stores val
into value
.
gda_value_set_ushort ()
void gda_value_set_ushort (GValue *value
,const gushort val
);
Stores val
into value
.
gda_value_set_time ()
void gda_value_set_time (GValue *value
,const GdaTime *val
);
Stores val
into 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
.
The accepted formats are:
G_TYPE_BOOLEAN: a caseless comparison is made with "true" or "false"
numerical types: C locale format (dot as a fraction separator)
G_TYPE_DATE: see
gda_parse_iso8601_date()
GDA_TYPE_TIME: see
gda_parse_iso8601_time()
GDA_TYPE_TIMESTAMP: see
gda_parse_iso8601_timestamp()
This function is typically used when reading configuration files or other non-user input that should be locale independent.
Parameters
value |
a GValue that will store |
|
as_string |
the stringified representation of the value. |
|
type |
the type of the value |
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.
If values are incompatible (see g_value_type_compatible
) then value
is set to a
GDA_TYPE_NULL, and FALSE
is returned.
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
andvalue2
are both GDA_TYPE_NULL values then the returned value is 0if
value1
is a GDA_TYPE_NULL value andvalue2
is of another type then the returned value is 1if
value1
is of another type andvalue2
is a GDA_TYPE_NULL value then the returned value is 1in all other cases,
value1
andvalue2
must be of the same type and their values are compared
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
andvalue2
are both GDA_TYPE_NULL values then the returned value is 0if
value1
is a GDA_TYPE_NULL value andvalue2
is of another type then the returned value is -1if
value1
is of another type andvalue2
is a GDA_TYPE_NULL value then the returned value is 1in all other cases,
value1
andvalue2
must be of the same type and their values are compared
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.
Output is in the "C" locale for numbers, and dates are converted in a YYYY-MM-DD format.
gda_value_to_xml ()
xmlNodePtr
gda_value_to_xml (const GValue *value
);
Serializes the given GValue to an XML node string.
[skip]
gda_value_to_xml_string ()
gchar *
gda_value_to_xml_string (const GValue *value
);
This methods creates an XML string representation of a GValue
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 "\". 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()
.
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).
I str
is NULL
, then an empty (i.e. where the data
part is NULL
) GdaBinary is created and returned.
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 "\".
gda_string_to_blob ()
GdaBlob *
gda_string_to_blob (const gchar *str
);
Performs the reverse of gda_blob_to_string()
.
Types and Values
GdaBlob
typedef struct _GdaBlob 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()
.