Variables Table

## Variables Table Variables Table — A table of variables with optional bound literal values. |

## Synopsis

    typedef             rasqal_variables_table;
    rasqal_variables_table * rasqal_new_variables_table     (rasqal_world *world);
    void                rasqal_free_variables_table         (rasqal_variables_table *vt);
    rasqal_variable *   rasqal_variables_table_add          (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name,
                                                             rasqal_literal *value);
    rasqal_variable *   rasqal_variables_table_add2         (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name,
                                                             size_t name_len,
                                                             rasqal_literal *value);
    int                 rasqal_variables_table_add_variable (rasqal_variables_table *vt,
                                                             rasqal_variable *variable);
    rasqal_variable *   rasqal_variables_table_get_by_name  (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name);
    int                 rasqal_variables_table_contains     (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name);

## Description

A table of rasqal_variable usually associated with a rasqal_query query or rasqal_query_results query result set. The order of the variables in the table may be significant, such as for a standalone query result set in which case it might define the order of variables in resulting rows.

## Details

### rasqal_variables_table

    typedef struct rasqal_variables_table_s rasqal_variables_table;

Internal - for now

### rasqal_new_variables_table ()

    rasqal_variables_table * rasqal_new_variables_table     (rasqal_world *world);

Constructor - create a new variables table

`world` : | rasqal world
Returns : | new variables table or NULL On failure

### rasqal_free_variables_table ()

    void                rasqal_free_variables_table         (rasqal_variables_table *vt);

Destructor - destroy a new variables table

`vt` : | rasqal variables table

### rasqal_variables_table_add ()

    rasqal_variable *   rasqal_variables_table_add          (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name,
                                                             rasqal_literal *value);

Constructor - Create a new variable and add it to the variables table

`Deprecated`: for `rasqal_variables_table_add2()` which copies the `name` and `value`

The `name` and `value` become owned by the rasqal_variable structure. If a variable with the name already exists, that is returned and the new `value` is ignored.

`vt` : | rasqal_variables_table to associate the variable with
`type` : | variable type defined by enumeration rasqal_variable_type
`name` : | variable name
`value` : | variable rasqal_literal value (or NULL)
Returns : | a new rasqal_variable or NULL on failure.

### rasqal_variables_table_add2 ()

    rasqal_variable *   rasqal_variables_table_add2         (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name,
                                                             size_t name_len,
                                                             rasqal_literal *value);

Constructor - Create a new variable and add it to the variables table

The `name` and `value` fields are copied. If a variable with the name already exists, that is returned and the new `value` is ignored.

`vt` : | rasqal_variables_table to associate the variable with
`type` : | variable type defined by enumeration rasqal_variable_type
`name` : | variable name
`name_len` : | length of `name` (or 0)
`value` : | variable rasqal_literal value (or NULL)
Returns : | a new rasqal_variable or NULL on failure.

### rasqal_variables_table_add_variable ()

    int                 rasqal_variables_table_add_variable (rasqal_variables_table *vt,
                                                             rasqal_variable *variable);

Constructor - Add an existing variable to the variables table

The variables table `vt` takes a reference to `variable`. This function will fail if the variable is already in the table. Use `rasqal_variables_table_contains()` to check before calling.

`vt` : | rasqal_variables_table to associate the variable with
`variable` : | existing variable to add
Returns : | non-0 on failure (such as name already exists)

### rasqal_variables_table_get_by_name ()

    rasqal_variable *   rasqal_variables_table_get_by_name  (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name);

Lookup a variable by type and name in the variables table.

Note that looking up for any type RASQAL_VARIABLE_TYPE_UNKNOWN may a name match but for any type so in cases where the query has both a named and anonymous (extensional) variable, an arbitrary one will be returned.

`vt` : | the variables table
`type` : | the variable type to match or RASQAL_VARIABLE_TYPE_UNKNOWN for any.
`name` : | the variable type
Returns : | a shared pointer to the rasqal_variable or NULL if not found

### rasqal_variables_table_contains ()

    int                 rasqal_variables_table_contains     (rasqal_variables_table *vt,
                                                             rasqal_variable_type type,
                                                             const char *name);

Check if there is a variable with the given type and name in the variables table

`vt` : | rasqal_variables_table to lookup
`type` : | variable type
`name` : | variable name
Returns : | non-0 if the variable is present