Variables
3
RASQAL Library

# Variables

Variable with names and literal value.

## Synopsis

                        rasqal_variable;
    rasqal_variable*    rasqal_new_variable                 (rasqal_query *rq,
                                                             unsigned char *name,
                                                             rasqal_literal *value);
    rasqal_variable*    rasqal_new_variable_typed           (rasqal_query *rq,
                                                             rasqal_variable_type type,
                                                             unsigned char *name,
                                                             rasqal_literal *value);
    rasqal_variable*    rasqal_new_variable_from_variable   (rasqal_variable *v);
    void                rasqal_free_variable                (rasqal_variable *v);
    void                rasqal_variable_print               (rasqal_variable *v,
                                                             FILE *fh);
    void                rasqal_variable_set_value           (rasqal_variable *v,
                                                             rasqal_literal *l);
    enum                rasqal_variable_type;

## Description

A class to hold a variable with optional name and a rasqal_literal value. The name is not required for SPARQL anonymous variables, when constructed with `rasqal_new_variable_typed()` and type RASQAL_VARIABLE_TYPE_ANONYMOUS.

## Details

### rasqal_variable

    typedef struct {
      const unsigned char *name;
      rasqal_literal* value;
      int offset;
      rasqal_variable_type type;
      struct rasqal_expression_s* expression;
    } rasqal_variable;

Binding between a variable name and a value.

Includes internal field `offset` for recording the offset into the (internal) rasqal_query variables array.

rasqal_literal *value;

  Variable value or NULL if unbound.

int offset;

  Internal.

rasqal_variable_type type;

  Variable type.

struct rasqal_expression_s *expression;

  Expression when the variable is a computed SELECT expression

### rasqal_new_variable ()

    rasqal_variable*    rasqal_new_variable                 (rasqal_query *rq,
                                                             unsigned char *name,
                                                             rasqal_literal *value);

Constructor - Create a new Rasqal normal variable.

The variable must be associated with a query, since variable names are only significant with a single query.

This creates a regular variable that can be returned of type RASQAL_VARIABLE_TYPE_NORMAL. Use rasqal_new_variable_typed to create other variables.

The `name` and `value` become owned by the rasqal_variable structure

`rq` :

  rasqal_query to associate the variable with

`name` :

  variable name

`value` :

  variable rasqal_literal value (or NULL)

Returns :

  a new rasqal_variable or NULL on failure.

### rasqal_new_variable_typed ()

    rasqal_variable*    rasqal_new_variable_typed           (rasqal_query *rq,
                                                             rasqal_variable_type type,
                                                             unsigned char *name,
                                                             rasqal_literal *value);

Constructor - Create a new typed Rasqal variable.

The variable must be associated with a query, since variable names are only significant with a single query.

The `name` and `value` become owned by the rasqal_variable structure

`rq` :

  rasqal_query 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_new_variable_from_variable ()

    rasqal_variable*    rasqal_new_variable_from_variable   (rasqal_variable *v);

Copy Constructor - Create a new Rasqal variable from an existing one

This does a deep copy of all variable fields

`v` :

  rasqal_variable to copy

Returns :

  a new rasqal_variable or NULL on failure.

### rasqal_free_variable ()

    void                rasqal_free_variable                (rasqal_variable *v);

Destructor - Destroy a Rasqal variable object.

`v` :

  rasqal_variable object

### rasqal_variable_print ()

    void                rasqal_variable_print               (rasqal_variable *v,
                                                             FILE *fh);

Print a Rasqal variable in a debug format.

The print debug format may change in any release.

`v` :

  the rasqal_variable object

`fh` :

  the FILE* handle to print to

### rasqal_variable_set_value ()

    void                rasqal_variable_set_value           (rasqal_variable *v,
                                                             rasqal_literal *l);

Set the value of a Rasqal variable.

The variable value is an input parameter and is copied in, not shared. If the variable value is NULL, any existing value is deleted.

`v` :

  the rasqal_variable object

`l` :

  the rasqal_literal value to set (or NULL)

### enum rasqal_variable_type

    typedef enum {
      RASQAL_VARIABLE_TYPE_UNKNOWN   = 0,
      RASQAL_VARIABLE_TYPE_NORMAL    = 1,
      RASQAL_VARIABLE_TYPE_ANONYMOUS = 2
    } rasqal_variable_type;

Rasqal variable types.

ANONYMOUS can be used in queries but cannot be returned in a result.

`RASQAL_VARIABLE_TYPE_UNKNOWN`

  Internal.

`RASQAL_VARIABLE_TYPE_NORMAL`

  The regular variable type.

`RASQAL_VARIABLE_TYPE_ANONYMOUS`

  Anonymous variable type.