GdaValue: libgda Reference Manual

## GdaValue GdaValue — Assorted functions for dealing with single GValue values |

## Stability Level

Stable, unless otherwise indicated

## Functions

GValue * | gda_value_new ()
#define | GDA_VALUE_HOLDS_NULL()
#define | GDA_VALUE_HOLDS_DEFAULT()
#define | GDA_VALUE_HOLDS_BINARY()
#define | GDA_VALUE_HOLDS_BLOB()
#define | GDA_VALUE_HOLDS_GEOMETRIC_POINT()
#define | GDA_VALUE_HOLDS_NUMERIC()
#define | GDA_VALUE_HOLDS_SHORT()
#define | GDA_VALUE_HOLDS_USHORT()
#define | GDA_VALUE_HOLDS_TIME()
GValue * | gda_value_new_null ()
void | gda_value_set_null ()
GValue * | gda_value_new_default ()
GValue * | gda_value_copy ()
void | gda_value_free ()
#define | GDA_VALUE_HOLDS_TEXT()
GValue * | gda_value_new_from_string ()
gboolean | gda_value_set_from_string ()
gboolean | gda_value_set_from_value ()
gchar * | gda_value_stringify ()
gint | gda_value_differ ()
gint | gda_value_compare ()
GValue * | gda_value_new_from_xml ()
xmlNodePtr | gda_value_to_xml ()
void | gda_value_reset_with_type ()
gboolean | gda_value_is_null ()
gboolean | gda_value_is_number ()
#define | gda_value_isa()
GValue * | gda_value_new_binary ()
void | gda_value_set_binary ()
void | gda_value_take_binary ()
GdaBinary * | gda_value_get_binary ()
GType | gda_binary_get_type ()
GdaBinary * | gda_binary_new ()
void | gda_binary_set_data ()
void | gda_binary_reset_data ()
gpointer | gda_binary_get_data ()
glong | gda_binary_get_size ()
GdaBinary * | gda_binary_copy ()
void | gda_binary_free ()
gchar * | gda_binary_to_string ()
GdaBinary * | gda_string_to_binary ()
GType | gda_blob_get_type ()
GdaBlob * | gda_blob_new ()
GdaBinary * | gda_blob_get_binary ()
GdaBlobOp * | gda_blob_get_op ()
void | gda_blob_set_op ()
GdaBlob * | gda_blob_copy ()
void | gda_blob_free ()
GValue * | gda_value_new_blob ()
GValue * | gda_value_new_blob_from_file ()
void | gda_value_set_blob ()
void | gda_value_take_blob ()
const GdaBlob * | gda_value_get_blob ()
gchar * | gda_blob_to_string ()
GdaBlob * | gda_string_to_blob ()
GdaGeometricPoint * | gda_geometric_point_copy ()
void | gda_geometric_point_free ()
gdouble | gda_geometric_point_get_x ()
void | gda_geometric_point_set_x ()
gdouble | gda_geometric_point_get_y ()
void | gda_geometric_point_set_y ()
const GdaGeometricPoint * | gda_value_get_geometric_point ()
void | gda_value_set_geometric_point ()
GdaNumeric * | gda_numeric_new ()
GdaNumeric * | gda_numeric_copy ()
void | gda_numeric_free ()
gchar * | gda_numeric_get_string ()
gdouble | gda_numeric_get_double ()
glong | gda_numeric_get_precision ()
glong | gda_numeric_get_width ()
void | gda_numeric_set_double ()
void | gda_numeric_set_from_string ()
void | gda_numeric_set_precision ()
void | gda_numeric_set_width ()
const GdaNumeric * | gda_value_get_numeric ()
void | gda_value_set_numeric ()
GdaTime * | gda_time_copy ()
void | gda_time_free ()
gboolean | gda_time_valid ()
GdaTime * | gda_time_new ()
GdaTime * | gda_time_new_from_date_time ()
GdaTime * | gda_time_new_from_values ()
gulong | gda_time_get_fraction ()
gushort | gda_time_get_hour ()
gushort | gda_time_get_minute ()
gushort | gda_time_get_second ()
GTimeZone * | gda_time_get_tz ()
glong | gda_time_get_timezone ()
void | gda_time_set_fraction ()
void | gda_time_set_hour ()
void | gda_time_set_minute ()
void | gda_time_set_second ()
void | gda_time_set_timezone ()
gchar * | gda_time_to_string ()
gchar * | gda_time_to_string_local ()
gchar * | gda_time_to_string_utc ()
GdaTime * | gda_time_to_timezone ()
GdaTime * | gda_time_to_utc ()
const GdaTime * | gda_value_get_time ()
void | gda_value_set_time ()
GValue * | gda_value_new_time_from_timet ()
GValue * | gda_value_new_date_time_from_timet ()
gshort | gda_value_get_short ()
void | gda_value_set_short ()
gushort | gda_value_get_ushort ()
void | gda_value_set_ushort ()

## Types and Values

enum | GdaValueAttribute
#define | GDA_TYPE_NULL
#define | GDA_TYPE_DEFAULT
#define | GDA_TYPE_BINARY
#define | GDA_TYPE_BLOB
#define | GDA_TYPE_GEOMETRIC_POINT
#define | GDA_TYPE_NUMERIC
#define | GDA_TYPE_SHORT
#define | GDA_TYPE_USHORT
#define | GDA_TYPE_TIME
| GdaBinary
| GdaBlob
| GdaGeometricPoint
| GdaNumeric
typedef | GdaTime

## Object Hierarchy

        GBoxed
        ├── GdaBinary
        ├── GdaBlob
        ├── GdaGeometricPoint
        ├── GdaNumeric
        ╰── GdaTime
        GFlags
        ╰── GdaValueAttribute

## Includes

    #include <libgda/gda-blob-op.h>

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

## Functions

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

#### Parameters

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

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

### GDA_VALUE_HOLDS_DEFAULT()

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

### GDA_VALUE_HOLDS_BINARY()

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

### GDA_VALUE_HOLDS_BLOB()

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

### GDA_VALUE_HOLDS_GEOMETRIC_POINT()

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

### GDA_VALUE_HOLDS_NUMERIC()

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

### GDA_VALUE_HOLDS_SHORT()

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

### GDA_VALUE_HOLDS_USHORT()

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

### GDA_VALUE_HOLDS_TIME()

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

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

#### Parameters

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.

#### Parameters

default_val | the default value as a string, or `NULL`. | [nullable]

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

#### Parameters

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.

#### Parameters

value | the resource to free (or `NULL`). | [transfer full][nullable]

### GDA_VALUE_HOLDS_TEXT()

    #define GDA_VALUE_HOLDS_TEXT(value)            G_VALUE_HOLDS(value, GDA_TYPE_TEXT)

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

[skip]

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

value | a GValue. |

#### Returns

`TRUE` if a number, `FALSE` otherwise.

### gda_value_isa()

    #define gda_value_isa(value, type) (G_VALUE_HOLDS(value, type))

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

#### Returns

the newly created GValue.

Free-function: gda_value_free.

[transfer full]

### gda_value_set_binary ()

    void
    gda_value_set_binary (GValue *value,
                          GdaBinary *binary);

Stores `val` into `value` .

#### Parameters

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

#### Parameters

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

    GdaBinary *
    gda_value_get_binary (const GValue *value);

#### Parameters

value | a GValue whose value we want to get. |

#### Returns

the value stored in `value` .

[transfer none]

### gda_binary_get_type ()

    GType
    gda_binary_get_type (void);

### gda_binary_new ()

    GdaBinary *
    gda_binary_new (void);

Creates a new GdaBinary coping data.

#### Returns

the newly created GdaBinary.

[transfer full]

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.

#### Parameters

binary | a GdaBinary pointer |
val | value to be copied by GdaBinary. | [array length=size][element-type guint8]
size | the size of the memory pool pointer to by `val` . |

Since: 6.0

### gda_binary_reset_data ()

    void
    gda_binary_reset_data (GdaBinary *binary);

Frees data referenced by GdaBinary

#### Parameters

binary | a GdaBinary pointer |

Since: 6.0

### gda_binary_get_data ()

    gpointer
    gda_binary_get_data (GdaBinary *binary);

#### Parameters

binary | a GdaBinary pointer |

#### Returns

associated data to GdaBinary.

[transfer none]

Since: 6.0

### gda_binary_get_size ()

    glong
    gda_binary_get_size (const GdaBinary *binary);

#### Returns

size of associated data to GdaBinary or -1 in case of error.

Since: 6.0

### gda_binary_copy ()

    GdaBinary *
    gda_binary_copy (GdaBinary *src);

Creates a new GdaBinary structure from an existing one.

#### Parameters

src | source to get a copy from. |

#### Returns

a newly allocated GdaBinary which contains a copy of information in `boxed` .

[transfer full]

### gda_binary_free ()

    void
    gda_binary_free (GdaBinary *binary);

Deallocates all memory associated to the given GdaBinary.

#### Parameters

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

#### Parameters

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.

#### Parameters

str | a string to convert, or `NULL`. | [nullable]

#### Returns

a new GdaBinary if no error were found in `str` , or `NULL` otherwise.

[transfer full]

### gda_blob_get_type ()

    GType
    gda_blob_get_type (void);

### gda_blob_new ()

    GdaBlob *
    gda_blob_new (void);

Creates a new GdaBlob.

#### Returns

a newly allocated GdaBlob.

[transfer full]

Since: 6.0

### gda_blob_get_binary ()

    GdaBinary *
    gda_blob_get_binary (GdaBlob *blob);

#### Parameters

blob | a GdaBlob pointer |

#### Returns

associated GdaBinary.

[transfer none]

Since: 6.0

### gda_blob_get_op ()

    GdaBlobOp *
    gda_blob_get_op (GdaBlob *blob);

#### Parameters

blob | a GdaBlob pointer |

#### Returns

associated GdaBlobOp.

[transfer none]

Since: 6.0

### gda_blob_set_op ()

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

Correctly assigns `op` to `blob` (increases `op` 's reference count)

#### Parameters

blob | a GdaBlob value |
op | a GdaBlobOp object, or `NULL`. | [nullable]

### gda_blob_copy ()

    GdaBlob *
    gda_blob_copy (GdaBlob *src);

Creates a new GdaBlob structure from an existing one.

#### Parameters

src | source to get a copy from. |

#### Returns

a newly allocated GdaBlob which contains a copy of information in `boxed` .

[transfer full]

### gda_blob_free ()

    void
    gda_blob_free (GdaBlob *blob);

Deallocates all memory associated to the given GdaBlob.

#### Parameters

blob | GdaBlob to free. | [transfer full]

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

#### Parameters

filename | name of the file to manipulate |

#### Returns

the newly created GValue.

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

#### Parameters

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

#### Parameters

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

    const GdaBlob *
    gda_value_get_blob (const GValue *value);

#### Parameters

value | a GValue whose value we want to get. |

#### Returns

the value stored in `value` .

[transfer 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 "\".

#### Parameters

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]

### gda_string_to_blob ()

    GdaBlob *
    gda_string_to_blob (const gchar *str);

Performs the reverse of `gda_blob_to_string()`.

#### Parameters

str | a string to convert |

#### Returns

a new gdaBlob if no error were found in `str` , or NULL otherwise.

[transfer full]

### gda_geometric_point_copy ()

    GdaGeometricPoint *
    gda_geometric_point_copy (GdaGeometricPoint *gp);

#### Returns

.

[transfer full]

### gda_geometric_point_free ()

    void
    gda_geometric_point_free (GdaGeometricPoint *gp);

### gda_geometric_point_get_x ()

    gdouble
    gda_geometric_point_get_x (GdaGeometricPoint *gp);

### gda_geometric_point_set_x ()

    void
    gda_geometric_point_set_x (GdaGeometricPoint *gp,
                               double x);

### gda_geometric_point_get_y ()

    gdouble
    gda_geometric_point_get_y (GdaGeometricPoint *gp);

### gda_geometric_point_set_y ()

    void
    gda_geometric_point_set_y (GdaGeometricPoint *gp,
                               double y);

### gda_value_get_geometric_point ()

    const GdaGeometricPoint *
    gda_value_get_geometric_point (const GValue *value);

#### Parameters

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

#### Parameters

value | a GValue that will store `val` . |
val | value to be stored in `value` . |

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

#### Parameters

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`

#### Parameters

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

#### Parameters

numeric | a GdaNumeric |

#### Returns

a new string representing the stored valued in `numeric` .

[transfer full][nullable]

Since: 5.0.2

### gda_numeric_get_double ()

    gdouble
    gda_numeric_get_double (const GdaNumeric *numeric);

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

numeric | a GdaNumeric |
width | a glong |

Since: 5.0.2

### gda_value_get_numeric ()

    const GdaNumeric *
    gda_value_get_numeric (const GValue *value);

#### Parameters

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

#### Parameters

value | a GValue that will store `val` . |
val | value to be stored in `value` . |

### gda_time_copy ()

    GdaTime *
    gda_time_copy (const GdaTime *time);

Create a copy of GdaTime

#### Parameters

time | an instance of GdaTime to copy |

#### Returns

a pointer to a new GdaTime struct.

[transfer full]

### gda_time_free ()

    void
    gda_time_free (GdaTime *time);

Free resources holded by the GdaTime instance

#### Parameters

time | a GdaTime to free |

Since: 6.0

### gda_time_valid ()

    gboolean
    gda_time_valid (const GdaTime *time);

`gda_time_valid` has been deprecated since version 6.0 and should not be used in newly-written code.

A time is always valid, so this method has been deprecated.

#### Parameters

time | a GdaTime value to check if it is valid |

#### Returns

TRUE if GdaTime is valid; `FALSE` otherwise.

Since: 4.2

### gda_time_new ()

    GdaTime *
    gda_time_new (void);

Creates a new GdaTime with time now local.

#### Returns

a new GdaTime structure.

[transfer full]

### gda_time_new_from_date_time ()

    GdaTime *
    gda_time_new_from_date_time (GDateTime *dt);

Creates new instcne of GdaTime from GDateTime.

#### Parameters

dt | a GDateTime to get time from |

#### Returns

the a new value storing a time.

[transfer full]

Since: 6.0

### gda_time_new_from_values ()

    GdaTime *
    gda_time_new_from_values (gushort hour,
                              gushort minute,
                              gushort second,
                              gulong fraction,
                              glong timezone);

Create new instance of GdaTime from the provided values.

#### Parameters

hour | hours |
minute | minutes |
second | seconds |
fraction | fraction of seconds |
timezone | timezone in seconds added to UTC |

#### Returns

the a new value storing a time.

[transfer full]

### gda_time_get_fraction ()

    gulong
    gda_time_get_fraction (const GdaTime *time);

Extract fraction of seconds from the instance of GdaTime

#### Parameters

time | a GdaTime value to get fraction of seconds from |

#### Returns

fraction of seconds

Since: 6.0

### gda_time_get_hour ()

    gushort
    gda_time_get_hour (const GdaTime *time);

Get hours from the GdaTime instance

#### Parameters

time | a GdaTime value to get hours from |

Since: 6.0

### gda_time_get_minute ()

    gushort
    gda_time_get_minute (const GdaTime *time);

Get minutes from the GdaTime instance

#### Parameters

time | a GdaTime value to get minutes from |

Since: 6.0

### gda_time_get_second ()

    gushort
    gda_time_get_second (const GdaTime *time);

Get second component from GdaTime

#### Parameters

time | a GdaTime value to get seconds from |

Since: 6.0

### gda_time_get_tz ()

    GTimeZone *
    gda_time_get_tz (const GdaTime *time);

Returns a GTimeZone in use in this `time` .

#### Parameters

time | a GdaTime value to get time zone from |

Since: 6.0

### gda_time_get_timezone ()

    glong
    gda_time_get_timezone (const GdaTime *time);

Returns number of seconds to be added to UTC time.

#### Parameters

time | a GdaTime value to get time zone from |

Since: 6.0

### gda_time_set_fraction ()

    void
    gda_time_set_fraction (GdaTime *time,
                           gulong fraction);

Set new value for the second fraction

#### Parameters

time | a GdaTime value to set hours to |
fraction | new second fraction to set to. |

Since: 6.0

### gda_time_set_hour ()

    void
    gda_time_set_hour (GdaTime *time,
                       gushort hour);

Set hour component to the GdaTime instance.

#### Parameters

time | a GdaTime value to set hours to |
hour | new hours to set to |

Since: 6.0

### gda_time_set_minute ()

    void
    gda_time_set_minute (GdaTime *time,
                         gushort minute);

Set minutes to the GdaTime instance

#### Parameters

time | a GdaTime value to set hours to |
minute | new minutes to set to |

Since: 6.0

### gda_time_set_second ()

    void
    gda_time_set_second (GdaTime *time,
                         gushort second);

Set second component

#### Parameters

time | a GdaTime value to set hours to |
second | new seconds to set to |

Since: 6.0

### gda_time_set_timezone ()

    void
    gda_time_set_timezone (GdaTime *time,
                           glong timezone);

Set timezone component for the instance of GdaTime

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

    gchar *
    gda_time_to_string (GdaTime *time);

Creates a string representation of a GdaTime in local time with the timezone designation.

#### Parameters

time | GdaTime instance to convert to string |

#### Returns

a new string.

[transfer full]

Since: 6.0

### gda_time_to_string_local ()

    gchar *
    gda_time_to_string_local (GdaTime *time);

Creates a string representation of a GdaTime in local time without timezone designation.

#### Parameters

time | GdaTime instance to convert to string |

#### Returns

a new string.

[transfer full]

Since: 6.0

### gda_time_to_string_utc ()

    gchar *
    gda_time_to_string_utc (GdaTime *time);

Creates a string representation of a GdaTime in UTC time with time zone indication.

#### Parameters

time | GdaTime instance to convert to string |

#### Returns

a new string.

[transfer full]

Since: 6.0

### gda_time_to_timezone ()

    GdaTime *
    gda_time_to_timezone (GdaTime *time,
                          GTimeZone *ntz);

Translate `time` 's to give timezone

#### Parameters

time | a valid GdaTime |
ntz | a new GTimeZone to use |

Since: 6.0

### gda_time_to_utc ()

    GdaTime *
    gda_time_to_utc (GdaTime *time);

Change time zone to UTC.

#### Parameters

time | a GdaTime |

### gda_value_get_time ()

    const GdaTime *
    gda_value_get_time (const GValue *value);

#### Parameters

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

#### Parameters

value | a GValue that will store `val` . |
val | value to be stored in `value` . |

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

#### Parameters

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]

Since: 6.0

### gda_value_new_date_time_from_timet ()

    GValue *
    gda_value_new_date_time_from_timet (time_t val);

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

value | a GValue that will store `val` . |
val | value to be stored in `value` . |

## Types and Values

### enum GdaValueAttribute

Attributes of a value, used internally by Libgda in different contexts. Values can be OR'ed.

#### Members

GDA_VALUE_ATTR_NONE | no specific attribute |
GDA_VALUE_ATTR_IS_NULL | value is NULL (in the SQL sense) |
GDA_VALUE_ATTR_CAN_BE_NULL | value can be set to NULL (in the SQL sense) |
GDA_VALUE_ATTR_IS_DEFAULT | value is defined as the default value (the value itself is not specified) |
GDA_VALUE_ATTR_CAN_BE_DEFAULT | a default value (not specified) exists for the value |
GDA_VALUE_ATTR_IS_UNCHANGED | the value has not been changed (in the context of the attribute usage) |
GDA_VALUE_ATTR_DATA_NON_VALID | the value is not valid (with regards to the context) |
GDA_VALUE_ATTR_HAS_VALUE_ORIG | the value can be resetted to its "original" value (i.e. before it was modified) |
GDA_VALUE_ATTR_NO_MODIF |  |
GDA_VALUE_ATTR_READ_ONLY | the value can't be modified |

### GDA_TYPE_NULL

    #define GDA_TYPE_NULL (gda_null_get_type())

### GDA_TYPE_DEFAULT

    #define GDA_TYPE_DEFAULT (gda_default_get_type())

### GDA_TYPE_BINARY

    #define GDA_TYPE_BINARY (gda_binary_get_type ())

### GDA_TYPE_BLOB

    #define GDA_TYPE_BLOB (gda_blob_get_type())

### GDA_TYPE_GEOMETRIC_POINT

    #define GDA_TYPE_GEOMETRIC_POINT (gda_geometric_point_get_type())

### GDA_TYPE_NUMERIC

    #define GDA_TYPE_NUMERIC (gda_numeric_get_type())

### GDA_TYPE_SHORT

    #define GDA_TYPE_SHORT (gda_short_get_type())

### GDA_TYPE_USHORT

    #define GDA_TYPE_USHORT (gda_ushort_get_type())

### GDA_TYPE_TIME

    #define GDA_TYPE_TIME (gda_time_get_type())

### GdaBinary

    typedef struct _GdaBinary GdaBinary;

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

#### Members

### GdaGeometricPoint

    typedef struct _GdaGeometricPoint GdaGeometricPoint;

### GdaNumeric

    typedef struct _GdaNumeric GdaNumeric;

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.

#### Members

### GdaTime

    typedef struct _GDateTime GdaTime;

Represents a time information.

## See Also

GValue and GdaBlobOp