## Gda Value

Gda Value — Single value stored in a GdaDataModel

## Synopsis

                        GdaGeometricPoint;
                        GdaNumeric;
                        GdaTime;
                        GdaTimestamp;
                        GdaBinary;
                        GdaBlob;
    typedef             GdaValueList;
    GValue*             gda_value_new                       (GType type);
    #define             gda_value_new_null                  ()
    GValue*             gda_value_new_binary                (const guchar *val,
                                                             glong size);
    GValue*             gda_value_new_blob                  (const 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_blob_copy                       (gpointer boxed);
    void                gda_blob_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 *blob);
    void                gda_value_take_blob                 (GValue *value,
                                                             const GdaBlob *blob);
    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);

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

## Details

### GdaGeometricPoint

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

### GdaNumeric

    typedef struct {
    	gchar *number;
    	glong precision;
    	glong width;
    } GdaNumeric;

### GdaTime

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

### 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;

### GdaBinary

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

### GdaBlob

    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;

### GdaValueList

    typedef GList GdaValueList;

### 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_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_new_blob ()

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

Makes a new GValue of type GDA_TYPE_BLOB 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_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_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.

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

    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.

### gda_value_free ()

    void                gda_value_free                      (GValue *value);

Deallocates all memory associated to a GValue.

`value` : | the resource to free.

### 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` : |

### 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_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_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_geometricpoint_copy ()

    gpointer            gda_geometricpoint_copy             (gpointer boxed);

`boxed` : |
Returns : |

### gda_geometricpoint_free ()

    void                gda_geometricpoint_free             (gpointer boxed);

`boxed` : |

### 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` : |

### gda_time_copy ()

    gpointer            gda_time_copy                       (gpointer boxed);

`boxed` : |
Returns : |

### gda_time_free ()

    void                gda_time_free                       (gpointer boxed);

`boxed` : |

### gda_timestamp_copy ()

    gpointer            gda_timestamp_copy                  (gpointer boxed);

`boxed` : |
Returns : |

### gda_timestamp_free ()

    void                gda_timestamp_free                  (gpointer boxed);

`boxed` : |

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

### 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,
                                                             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 `val`.
`blob` : | a GdaBlob structure with the data and its size to be stored in `value`.

### 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`.

### 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`.

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

### 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`.

### 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`.

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

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

### 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_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_compare ()

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

### gda_value_compare_ext ()

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

### gda_value_to_xml ()

    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.

### 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 \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`

### gda_string_to_binary ()

    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

## See Also

The GdaBlobOp object which operates on blobs