A single Value

## A single Value A single Value — Assorted functions for dealing with GValue values |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    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              (const GdaNumeric *numeric);
    gdouble             gda_numeric_get_double              (const GdaNumeric *numeric);
    glong               gda_numeric_get_precision           (const GdaNumeric *numeric);
    glong               gda_numeric_get_width               (const 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);
    void                gda_time_change_timezone            (GdaTime *time,
                                                             glong ntz);
    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);
    void                gda_timestamp_change_timezone       (GdaTimestamp *ts,
                                                             glong ntz);
    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);

## Object Hierarchy

      GBoxed
       +----GdaBinary

      GBoxed
       +----GdaBlob

      GBoxed
       +----GdaGeometricPoint

      GBoxed
       +----GdaNumeric

      GBoxed
       +----GdaTime

      GBoxed
       +----GdaTimestamp

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

## Details

### enum GdaValueAttribute

    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;

`GDA_VALUE_ATTR_NONE` |
`GDA_VALUE_ATTR_IS_NULL` |
`GDA_VALUE_ATTR_CAN_BE_NULL` |
`GDA_VALUE_ATTR_IS_DEFAULT` |
`GDA_VALUE_ATTR_CAN_BE_DEFAULT` |
`GDA_VALUE_ATTR_IS_UNCHANGED` |
`GDA_VALUE_ATTR_ACTIONS_SHOWN` |
`GDA_VALUE_ATTR_DATA_NON_VALID` |
`GDA_VALUE_ATTR_HAS_VALUE_ORIG` |
`GDA_VALUE_ATTR_NO_MODIF` |
`GDA_VALUE_ATTR_UNUSED` |

### 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. Free-function: gda_value_free. [transfer full]

### GDA_TYPE_NULL

    #define GDA_TYPE_NULL (gda_null_get_type())

### GDA_VALUE_HOLDS_NULL()

    #define GDA_VALUE_HOLDS_NULL(value)            G_VALUE_HOLDS(value, GDA_TYPE_NULL)

### GDA_TYPE_DEFAULT

    #define GDA_TYPE_DEFAULT (gda_default_get_type())

### GDA_VALUE_HOLDS_DEFAULT()

    #define GDA_VALUE_HOLDS_DEFAULT(value)         G_VALUE_HOLDS(value, GDA_TYPE_DEFAULT)

### GDA_TYPE_BINARY

    #define GDA_TYPE_BINARY (gda_binary_get_type())

### GDA_VALUE_HOLDS_BINARY()

    #define GDA_VALUE_HOLDS_BINARY(value)          G_VALUE_HOLDS(value, GDA_TYPE_BINARY)

### GDA_TYPE_BLOB

    #define GDA_TYPE_BLOB (gda_blob_get_type())

### GDA_VALUE_HOLDS_BLOB()

    #define GDA_VALUE_HOLDS_BLOB(value)            G_VALUE_HOLDS(value, GDA_TYPE_BLOB)

### GDA_TYPE_GEOMETRIC_POINT

    #define GDA_TYPE_GEOMETRIC_POINT (gda_geometricpoint_get_type())

### GDA_VALUE_HOLDS_GEOMETRIC_POINT()

    #define GDA_VALUE_HOLDS_GEOMETRIC_POINT(value) G_VALUE_HOLDS(value, GDA_TYPE_GEOMETRIC_POINT)

### GDA_TYPE_NUMERIC

    #define GDA_TYPE_NUMERIC (gda_numeric_get_type())

### GDA_VALUE_HOLDS_NUMERIC()

    #define GDA_VALUE_HOLDS_NUMERIC(value)         G_VALUE_HOLDS(value, GDA_TYPE_NUMERIC)

### GDA_TYPE_SHORT

    #define GDA_TYPE_SHORT (gda_short_get_type())

### GDA_VALUE_HOLDS_SHORT()

    #define GDA_VALUE_HOLDS_SHORT(value)           G_VALUE_HOLDS(value, GDA_TYPE_SHORT)

### GDA_TYPE_USHORT

    #define GDA_TYPE_USHORT (gda_ushort_get_type())

### GDA_VALUE_HOLDS_USHORT()

    #define GDA_VALUE_HOLDS_USHORT(value)          G_VALUE_HOLDS(value, GDA_TYPE_USHORT)

### GDA_TYPE_TIME

    #define GDA_TYPE_TIME (gda_time_get_type())

### GDA_VALUE_HOLDS_TIME()

    #define GDA_VALUE_HOLDS_TIME(value)            G_VALUE_HOLDS(value, GDA_TYPE_TIME)

### GDA_TYPE_TIMESTAMP

    #define GDA_TYPE_TIMESTAMP (gda_timestamp_get_type())

### GDA_VALUE_HOLDS_TIMESTAMP()

    #define GDA_VALUE_HOLDS_TIMESTAMP(value)       G_VALUE_HOLDS(value, GDA_TYPE_TIMESTAMP)

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

Returns : | a new GValue of the type GDA_TYPE_NULL. [transfer full]

### 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_new_default ()

    GValue *            gda_value_new_default               (const gchar *default_val);

Creates a new default value.

`default_val` : | the default value as a string, or `NULL`. [allow-none]
Returns : | a new GValue of the type GDA_TYPE_DEFAULT. [transfer full]

Since 4.2.9

### 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`. Free-function: gda_value_free. [transfer full]

### gda_value_free ()

    void                gda_value_free                      (GValue *value);

Deallocates all memory associated to a GValue.

`value` : | the resource to free (or `NULL`). [transfer full][allow-none]

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

`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`. Free-function: gda_value_free. [transfer full]

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

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

If values are incompatible (see `g_value_type_compatible`) then `value` is set to a GDA_TYPE_NULL, and `FALSE` is returned.

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

Output is in the "C" locale for numbers, and 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. [transfer full]

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

`value1` : | a GValue to compare.
`value2` : | the other GValue to be compared to `value1`.
Returns : | a non 0 value if `value1` and `value2` differ, and 0 if they are equal

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

`value1` : | a GValue to compare (not `NULL`)
`value2` : | 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`.

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

`node` : | an XML node representing the value.
Returns : | the newly created GValue. Free-function: gda_value_free. [transfer full]

### gda_value_to_xml ()

    xmlNodePtr          gda_value_to_xml                    (const GValue *value);

Serializes the given GValue to an XML node string.

`value` : | a GValue.
Returns : | the XML node. Once not needed anymore, you should free it. [transfer full]

### gda_value_reset_with_type ()

    void                gda_value_reset_with_type           (GValue *value,
                                                             GType type);

Resets the GValue and set a new type to GType.

`value` : | the GValue to be reseted
`type` : | the GType to set to

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

### GdaBinary

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

### 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. Free-function: gda_value_free. [transfer full]

### 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`. [transfer none]

### 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,
                                                             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`. [transfer full]

### 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`. Free-function: gda_binary_free. [transfer full]

### gda_binary_free ()

    void                gda_binary_free                     (gpointer boxed);

Deallocates all memory associated to the given GdaBinary.

`boxed` : | GdaBinary to free. [transfer full]

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

`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`. [transfer full]

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

`str` : | a string to convert, or `NULL`. [allow-none]
Returns : | a new GdaBinary if no error were found in `str`, or `NULL` otherwise. [transfer full]

### GdaBlob

    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`; | data buffer, as a GdaBinary
GdaBlobOp *`op`; | a pointer to a GdaBlopOp, or `NULL`. [allow-none]

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

`val` : | value to set for the new GValue.
`size` : | the size of the memory pool pointer to by `val`.
Returns : | the newly created GValue. Free-function: gda_value_free. [transfer full]

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

`filename` : | name of the file to manipulate
Returns : | the newly created GValue. Free-function: gda_value_free. [transfer full]

### 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`. Free-function: gda_blob_free. [transfer full]

### gda_blob_free ()

    void                gda_blob_free                       (gpointer boxed);

Deallocates all memory associated to the given GdaBlob.

`boxed` : | GdaBlob to free. [transfer full]

### 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`. [transfer none]

### 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,
                                                             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`. [transfer full]

### gda_blob_set_op ()

    void                gda_blob_set_op                     (GdaBlob *blob,
                                                             GdaBlobOp *op);

correctly assigns `op` to `blob`

`blob` : | a GdaBlob value
`op` : | a GdaBlobOp object, or `NULL`. [allow-none]

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

`blob` : | a correctly filled `GdaBlob` structure
`maxlen` : | a maximum len used to truncate, or 0 for no maximum length
Returns : | a new string from `blob`. [transfer full]

### GdaGeometricPoint

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

### gda_geometricpoint_copy ()

    gpointer            gda_geometricpoint_copy             (gpointer boxed);

Returns : | . [transfer full]

### gda_geometricpoint_free ()

    void                gda_geometricpoint_free             (gpointer boxed);

### 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`. [transfer none]

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

### struct GdaNumeric

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

### gda_numeric_new ()

    GdaNumeric *        gda_numeric_new                     (void);

Creates a new GdaNumeric with defaults.

Returns : | a new GdaNumeric. [transfer full]

Since 5.0.2

### gda_numeric_copy ()

    GdaNumeric *        gda_numeric_copy                    (GdaNumeric *src);

Creates a new GdaNumeric structure from an existing one.

`src` : | 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]

### gda_numeric_free ()

    void                gda_numeric_free                    (GdaNumeric *numeric);

Deallocates all memory associated to the given `boxed`

`numeric` : | a GdaNumeric pointer. [transfer full]

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

`numeric` : | a GdaNumeric
Returns : | a new string representing the stored valued in `numeric`. [transfer full][allow-none]

Since 5.0.2

### gda_numeric_get_double ()

    gdouble             gda_numeric_get_double              (const GdaNumeric *numeric);

`numeric` : | a GdaNumeric
Returns : | a gdouble representation of `numeric`

Since 5.0.2

### gda_numeric_get_precision ()

    glong               gda_numeric_get_precision           (const GdaNumeric *numeric);

Gets the precision of a GdaNumeric.

`numeric` : | a GdaNumeric
Returns : | an integer with the precision of a GdaNumeric.

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

`numeric` : | a GdaNumeric
Returns : | an integer with the width of a GdaNumeric. (Not jet implemented).

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

`numeric` : | a GdaNumeric
`number` : | a gdouble

Since 5.0.2

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

`numeric` : | a GdaNumeric
`str` : | a string representing a number, in the C locale format

Since 5.0.2

### gda_numeric_set_precision ()

    void                gda_numeric_set_precision           (GdaNumeric *numeric,
                                                             glong precision);

Sets the precision of a GdaNumeric.

`numeric` : | a GdaNumeric
`precision` : | a glong

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

`numeric` : | a GdaNumeric
`width` : | a glong

Since 5.0.2

### 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`. [transfer none]

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

### GdaTime

    typedef struct {
    	gushort hour;
    	gushort minute;
    	gushort second;
    	gulong  fraction;
    	glong   timezone;
    } GdaTime;

Represents a time information.

gushort `hour`; | hour representation of the time, as a number between 0 and 23
gushort `minute`; | minute representation of the time, as a number between 0 and 59
gushort `second`; | second representation of the time, as a number between 0 and 59
gulong `fraction`; | fractionnal part of the seconds, in millionth' of second
glong `timezone`; | number of seconds added to the GMT timezone

### gda_time_copy ()

    gpointer            gda_time_copy                       (gpointer boxed);

Returns : | . [transfer full]

### gda_time_free ()

    void                gda_time_free                       (gpointer boxed);

### gda_time_valid ()

    gboolean            gda_time_valid                      (const GdaTime *time);

`time` : | a GdaTime value to check if it is valid
Returns : | TRUE if GdaTime is valid; `FALSE` otherwise.

Since 4.2

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

`time` : | a valid GdaTime
`ntz` : | a new timezone to use, in seconds added to GMT

Since 5.2

### 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`. [transfer none]

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

### GdaTimestamp

    typedef struct {
    	gshort  year;
    	gushort month;
    	gushort day;
    	gushort hour;
    	gushort minute;
    	gushort second;
    	gulong  fraction;
    	glong   timezone;
    } GdaTimestamp;

Represents an instant (a time stamp)

gshort `year`; | year representation of the time stamp
gushort `month`; | month representation of the time stamp, as a number between 1 and 12
gushort `day`; | day representation of the time stamp, as a number between 1 and 31
gushort `hour`; | hour representation of the time stamp, as a number between 0 and 23
gushort `minute`; | minute representation of the time stamp, as a number between 0 and 59
gushort `second`; | second representation of the time stamp, as a number between 0 and 59
gulong `fraction`; | fractionnal part of the seconds, in millionth' of second
glong `timezone`; | number of seconds added to the GMT timezone

### gda_timestamp_copy ()

    gpointer            gda_timestamp_copy                  (gpointer boxed);

Returns : | . [transfer full]

### gda_timestamp_free ()

    void                gda_timestamp_free                  (gpointer boxed);

### gda_timestamp_valid ()

    gboolean            gda_timestamp_valid                 (const GdaTimestamp *timestamp);

`timestamp` : | a GdaTimestamp value to check if it is valid
Returns : | TRUE if GdaTimestamp is valid; `FALSE` otherwise.

Since 4.2

### gda_timestamp_change_timezone ()

    void                gda_timestamp_change_timezone       (GdaTimestamp *ts,
                                                             glong ntz);

This function is similar to `gda_time_change_timezone()` but operates on time stamps.

Note: the resulting will always be a valid time.

`ts` : | a valid GdaTimestamp
`ntz` : | a new timezone to use, in seconds added to GMT

Since 5.2

### 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`. [transfer none]

### 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_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). 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_timestamp_from_timet (time (NULL));`

`val` : | value to set for the new GValue.
Returns : | the newly created GValue, or `NULL` in case of error Free-function: gda_value_free. [transfer full]

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

## See Also

GValue and GdaBlobOp