Expressions

## Expressions Expressions — Query language expressions. |

## Synopsis

    typedef             rasqal_expression;
    enum                rasqal_op;
    enum                rasqal_compare_flags;
    enum                rasqal_pattern_flags;
    rasqal_expression*  rasqal_new_0op_expression           (rasqal_world *world,
                                                             rasqal_op op);
    rasqal_expression*  rasqal_new_1op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg);
    rasqal_expression*  rasqal_new_2op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_expression *arg2);
    rasqal_expression*  rasqal_new_3op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_expression *arg2,
                                                             rasqal_expression *arg3);
    rasqal_expression*  rasqal_new_cast_expression          (rasqal_world *world,
                                                             raptor_uri *name,
                                                             rasqal_expression *value);
    rasqal_expression*  rasqal_new_coalesce_expression      (rasqal_world *world,
                                                             raptor_sequence *args);
    rasqal_expression*  rasqal_new_function_expression      (rasqal_world *world,
                                                             raptor_uri *name,
                                                             raptor_sequence *args);
    rasqal_expression*  rasqal_new_literal_expression       (rasqal_world *world,
                                                             rasqal_literal *literal);
    rasqal_expression*  rasqal_new_string_op_expression     (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_literal *literal);
    rasqal_expression*  rasqal_new_expression_from_expression
                                                            (rasqal_expression *e);
    void                rasqal_free_expression              (rasqal_expression *e);
    rasqal_literal*     rasqal_expression_evaluate          (rasqal_world *world,
                                                             raptor_locator *locator,
                                                             rasqal_expression *e,
                                                             int flags);
    int                 rasqal_expression_print             (rasqal_expression *e,
                                                             FILE *fh);
    void                rasqal_expression_print_op          (rasqal_expression *e,
                                                             FILE *fh);
    int                 (*rasqal_expression_visit_fn)       (void *user_data,
                                                             rasqal_expression *e);
    int                 rasqal_expression_visit             (rasqal_expression *e,
                                                             rasqal_expression_visit_fn fn,
                                                             void *user_data);

## Description

Expressions form an expression tree that can be evaluated using `rasqal_expression_evaluate()` over rasqal_op operators, rasqal_literal constants and rasqal_variable values bound in some rasqal_query_result. The result is a rasqal_literal value.

## Details

### rasqal_expression

    typedef struct rasqal_expression_s rasqal_expression;

Expression with arguments

### enum rasqal_op

    typedef enum {
      /* internal */
      RASQAL_EXPR_UNKNOWN,
      RASQAL_EXPR_AND,
      RASQAL_EXPR_OR,
      RASQAL_EXPR_EQ,
      RASQAL_EXPR_NEQ,
      RASQAL_EXPR_LT,
      RASQAL_EXPR_GT,
      RASQAL_EXPR_LE,
      RASQAL_EXPR_GE,
      RASQAL_EXPR_UMINUS,
      RASQAL_EXPR_PLUS,
      RASQAL_EXPR_MINUS,
      RASQAL_EXPR_STAR,
      RASQAL_EXPR_SLASH,
      RASQAL_EXPR_REM,
      RASQAL_EXPR_STR_EQ,
      RASQAL_EXPR_STR_NEQ,
      RASQAL_EXPR_STR_MATCH,
      RASQAL_EXPR_STR_NMATCH,
      RASQAL_EXPR_TILDE,
      RASQAL_EXPR_BANG,
      RASQAL_EXPR_LITERAL,
      RASQAL_EXPR_FUNCTION,
      RASQAL_EXPR_BOUND,
      RASQAL_EXPR_STR,
      RASQAL_EXPR_LANG,
      RASQAL_EXPR_DATATYPE,
      RASQAL_EXPR_ISURI,
      RASQAL_EXPR_ISBLANK,
      RASQAL_EXPR_ISLITERAL,
      RASQAL_EXPR_CAST,
      RASQAL_EXPR_ORDER_COND_ASC,
      RASQAL_EXPR_ORDER_COND_DESC,
      RASQAL_EXPR_LANGMATCHES,
      RASQAL_EXPR_REGEX,
      RASQAL_EXPR_GROUP_COND_ASC,
      RASQAL_EXPR_GROUP_COND_DESC,
      RASQAL_EXPR_COUNT,
      RASQAL_EXPR_VARSTAR,
      RASQAL_EXPR_SAMETERM,
      RASQAL_EXPR_SUM,
      RASQAL_EXPR_AVG,
      RASQAL_EXPR_MIN,
      RASQAL_EXPR_MAX,
      RASQAL_EXPR_COALESCE,
      /* internal */
      RASQAL_EXPR_LAST= RASQAL_EXPR_COALESCE
    } rasqal_op;

Rasqal expression operators. A mixture of unary, binary and tertiary operators (string matches). Also includes casting and two ordering operators from ORDER BY in SPARQL.

`RASQAL_EXPR_UNKNOWN` | Internal
`RASQAL_EXPR_AND` | Expression for AND(A, B)
`RASQAL_EXPR_OR` | Expression for OR(A, B)
`RASQAL_EXPR_EQ` | Expression for A equals B
`RASQAL_EXPR_NEQ` | Expression for A not equals B.
`RASQAL_EXPR_LT` | Expression for A less than B.
`RASQAL_EXPR_GT` | Expression for A greather than B.
`RASQAL_EXPR_LE` | Expression for A less than or equal to B.
`RASQAL_EXPR_GE` | Expression for A greater than or equal to B.
`RASQAL_EXPR_UMINUS` | Expression for -A.
`RASQAL_EXPR_PLUS` | Expression for +A.
`RASQAL_EXPR_MINUS` | Expression for A-B.
`RASQAL_EXPR_STAR` | Expression for A*B.
`RASQAL_EXPR_SLASH` | Expression for A/B.
`RASQAL_EXPR_REM` | Expression for A/B remainder.
`RASQAL_EXPR_STR_EQ` | Expression for A string equals B.
`RASQAL_EXPR_STR_NEQ` | Expression for A string not-equals B.
`RASQAL_EXPR_STR_MATCH` | Expression for string A matches literal regex B with flags.
`RASQAL_EXPR_STR_NMATCH` | Expression for string A not-matches literal regex B with flags.
`RASQAL_EXPR_TILDE` | Expression for binary not A.
`RASQAL_EXPR_BANG` | Expression for logical not A.
`RASQAL_EXPR_LITERAL` | Expression for a rasqal_literal.
`RASQAL_EXPR_FUNCTION` | Expression for a function A with arguments (B...).
`RASQAL_EXPR_BOUND` | Expression for SPARQL ISBOUND(A).
`RASQAL_EXPR_STR` | Expression for SPARQL STR(A).
`RASQAL_EXPR_LANG` | Expression for SPARQL LANG(A).
`RASQAL_EXPR_DATATYPE` | Expression for SPARQL DATATYPE(A).
`RASQAL_EXPR_ISURI` | Expression for SPARQL ISURI(A).
`RASQAL_EXPR_ISBLANK` | Expression for SPARQL ISBLANK(A).
`RASQAL_EXPR_ISLITERAL` | Expression for SPARQL ISLITERAL(A).
`RASQAL_EXPR_CAST` | Expression for cast literal A to type B.
`RASQAL_EXPR_ORDER_COND_ASC` | Expression for SPARQL order condition ascending.
`RASQAL_EXPR_ORDER_COND_DESC` | Expression for SPARQL order condition descending.
`RASQAL_EXPR_LANGMATCHES` | Expression for SPARQL LANGMATCHES(A, B).
`RASQAL_EXPR_REGEX` | Expression for string A matches expression regex B with flags.
`RASQAL_EXPR_GROUP_COND_ASC` | Expression for LAQRS group condition ascending.
`RASQAL_EXPR_GROUP_COND_DESC` | Expression for LAQRS group condition descending.
`RASQAL_EXPR_COUNT` | Expression for LAQRS select `COUNT()`
`RASQAL_EXPR_VARSTAR` | Expression for LAQRS select Variable *
`RASQAL_EXPR_SAMETERM` | Expression for SPARQL sameTerm
`RASQAL_EXPR_SUM` | Expression for LAQRS select `SUM()`
`RASQAL_EXPR_AVG` | Expression for LAQRS select `AVG()`
`RASQAL_EXPR_MIN` | Expression for LAQRS select `MIN()`
`RASQAL_EXPR_MAX` | Expression for LAQRS select `MAX()`
`RASQAL_EXPR_COALESCE` | Expression for LAQRS COALESCE(Expr+)
`RASQAL_EXPR_LAST` | Internal

### enum rasqal_compare_flags

    typedef enum {
      RASQAL_COMPARE_NOCASE = 1,
      RASQAL_COMPARE_XQUERY = 2,
      RASQAL_COMPARE_RDF    = 4,
      RASQAL_COMPARE_URI    = 8,
      RASQAL_COMPARE_SAMETERM = 16
    } rasqal_compare_flags;

Flags for `rasqal_expression_evaluate()`, `rasqal_literal_compare()`, `rasqal_literal_as_string_flags()`, `rasqal_new_literal_from_promotion()`, `rasqal_literal_equals_flags()`.

`RASQAL_COMPARE_NOCASE` | String comparisons are case independent.
`RASQAL_COMPARE_XQUERY` | XQuery comparsion rules apply.
`RASQAL_COMPARE_RDF` | RDF Term comparsion rules apply.
`RASQAL_COMPARE_URI` | Allow comparison of URIs and allow strings to have a boolean value (for RDQL)
`RASQAL_COMPARE_SAMETERM` | SPARQL `sameTerm()` builtin rules apply.

### enum rasqal_pattern_flags

    typedef enum {
      RASQAL_PATTERN_FLAGS_OPTIONAL=1,

      RASQAL_PATTERN_FLAGS_LAST=RASQAL_PATTERN_FLAGS_OPTIONAL
    } rasqal_pattern_flags;

Flags for rasqal_graph_pattern.

`RASQAL_PATTERN_FLAGS_OPTIONAL` | True when the graph pattern is an optional match.
`RASQAL_PATTERN_FLAGS_LAST` | Internal

### rasqal_new_0op_expression ()

    rasqal_expression*  rasqal_new_0op_expression           (rasqal_world *world,
                                                             rasqal_op op);

Constructor - create a new 0-operand (constant) expression.

The operators are: `RASQAL_EXPR_VARSTAR`

The only operator here is the '*' in COUNT(*) as used by LAQRS.

`world` : | rasqal_world object
`op` : | Expression operator
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_1op_expression ()

    rasqal_expression*  rasqal_new_1op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg);

Constructor - create a new 1-operand expression. Takes ownership of the operand expression.

The operators are: `RASQAL_EXPR_TILDE` `RASQAL_EXPR_BANG` `RASQAL_EXPR_UMINUS` `RASQAL_EXPR_BOUND` `RASQAL_EXPR_STR` `RASQAL_EXPR_LANG` `RASQAL_EXPR_LANGMATCHES` `RASQAL_EXPR_DATATYPE` `RASQAL_EXPR_ISURI` `RASQAL_EXPR_ISBLANK` `RASQAL_EXPR_ISLITERAL` `RASQAL_EXPR_ORDER_COND_ASC` `RASQAL_EXPR_ORDER_COND_DESC` `RASQAL_EXPR_GROUP_COND_ASC` `RASQAL_EXPR_GROUP_COND_DESC` `RASQAL_EXPR_COUNT` `RASQAL_EXPR_SUM` `RASQAL_EXPR_AVG` `RASQAL_EXPR_MIN` `RASQAL_EXPR_MAX`

`RASQAL_EXPR_BANG` and `RASQAL_EXPR_UMINUS` are used by RDQL and SPARQL. `RASQAL_EXPR_TILDE` by RDQL only. The rest by SPARQL only.

`world` : | rasqal_world object
`op` : | Expression operator
`arg` : | Operand 1
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_2op_expression ()

    rasqal_expression*  rasqal_new_2op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_expression *arg2);

Constructor - create a new 2-operand expression. Takes ownership of the operand expressions.

The operators are: `RASQAL_EXPR_AND` `RASQAL_EXPR_OR` `RASQAL_EXPR_EQ` `RASQAL_EXPR_NEQ` `RASQAL_EXPR_LT` `RASQAL_EXPR_GT` `RASQAL_EXPR_LE` `RASQAL_EXPR_GE` `RASQAL_EXPR_PLUS` `RASQAL_EXPR_MINUS` `RASQAL_EXPR_STAR` `RASQAL_EXPR_SLASH` `RASQAL_EXPR_REM` `RASQAL_EXPR_STR_EQ` `RASQAL_EXPR_STR_NEQ`

`RASQAL_EXPR_REM` `RASQAL_EXPR_STR_EQ` and `RASQAL_EXPR_STR_NEQ` are not used by SPARQL. `RASQAL_EXPR_REM` is used by RDQL.

`world` : | rasqal_world object
`op` : | Expression operator
`arg1` : | Operand 1
`arg2` : | Operand 2
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_3op_expression ()

    rasqal_expression*  rasqal_new_3op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_expression *arg2,
                                                             rasqal_expression *arg3);

Constructor - create a new 3-operand expression. Takes ownership of the operands.

The only operator is: `RASQAL_EXPR_REGEX`

`world` : | rasqal_world object
`op` : | Expression operator
`arg1` : | Operand 1
`arg2` : | Operand 2
`arg3` : | Operand 3 (may be NULL)
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_cast_expression ()

    rasqal_expression*  rasqal_new_cast_expression          (rasqal_world *world,
                                                             raptor_uri *name,
                                                             rasqal_expression *value);

Constructor - create a new expression for casting and expression to a datatype. Takes ownership of the datatype uri and expression value.

`world` : | rasqal_world object
`name` : | cast datatype URI
`value` : | expression value to cast to `datatype` type
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_coalesce_expression ()

    rasqal_expression*  rasqal_new_coalesce_expression      (rasqal_world *world,
                                                             raptor_sequence *args);

Constructor - create a new `COALESCE()` with expression arguments.

Takes ownership of the `args`

`world` : | rasqal_world object
`args` : | sequence of rasqal_expression coalesce arguments
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_function_expression ()

    rasqal_expression*  rasqal_new_function_expression      (rasqal_world *world,
                                                             raptor_uri *name,
                                                             raptor_sequence *args);

Constructor - create a new expression for a function with expression arguments. Takes ownership of the function uri and arguments.

`world` : | rasqal_world object
`name` : | function name
`args` : | sequence of rasqal_expression function arguments
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_literal_expression ()

    rasqal_expression*  rasqal_new_literal_expression       (rasqal_world *world,
                                                             rasqal_literal *literal);

Constructor - create a new expression for a rasqal_literal Takes ownership of the operand literal.

`world` : | rasqal_world object
`literal` : | Literal operand 1
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_string_op_expression ()

    rasqal_expression*  rasqal_new_string_op_expression     (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_literal *literal);

Constructor - create a new expression with one expression and one string operand. Takes ownership of the operands.

The operators are: `RASQAL_EXPR_STR_MATCH` (RDQL, SPARQL) and `RASQAL_EXPR_STR_NMATCH` (RDQL)

`world` : | rasqal_world object
`op` : | Expression operator
`arg1` : | Operand 1
`literal` : | Literal operand 2
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_expression_from_expression ()

    rasqal_expression*  rasqal_new_expression_from_expression
                                                            (rasqal_expression *e);

Copy Constructor - create a new rasqal_expression object from an existing rasqal_expression object.

`e` : | rasqal_expression object to copy or NULL
Returns : | a new rasqal_expression object or NULL if `e` is NULL

### rasqal_free_expression ()

    void                rasqal_free_expression              (rasqal_expression *e);

Destructor - destroy a rasqal_expression object.

`e` : | rasqal_expression object

### rasqal_expression_evaluate ()

    rasqal_literal*     rasqal_expression_evaluate          (rasqal_world *world,
                                                             raptor_locator *locator,
                                                             rasqal_expression *e,
                                                             int flags);

Evaluate a rasqal_expression tree to give a rasqal_literal result or error.

`world` : | rasqal_world
`locator` : | error locator (or NULL)
`e` : | The expression to evaluate.
`flags` : | Flags for `rasqal_literal_compare()` and RASQAL_COMPARE_NOCASE for string matches.
Returns : | a rasqal_literal value or NULL on failure.

### rasqal_expression_print ()

    int                 rasqal_expression_print             (rasqal_expression *e,
                                                             FILE *fh);

Print a Rasqal expression in a debug format.

The print debug format may change in any release.

`e` : | rasqal_expression object.
`fh` : | The FILE* handle to print to.
Returns : | non-0 on failure

### rasqal_expression_print_op ()

    void                rasqal_expression_print_op          (rasqal_expression *e,
                                                             FILE *fh);

Print a rasqal expression operator in a debug format.

The print debug format may change in any release.

`e` : | the rasqal_expression object
`fh` : | the FILE* handle to print to

### rasqal_expression_visit_fn ()

    int                 (*rasqal_expression_visit_fn)       (void *user_data,
                                                             rasqal_expression *e);

User function to visit an expression and operate on it with `rasqal_expression_visit()`

`user_data` : | user data passed in with `rasqal_expression_visit()`
`e` : | current expression
Returns : | 0 to truncate the visit

### rasqal_expression_visit ()

    int                 rasqal_expression_visit             (rasqal_expression *e,
                                                             rasqal_expression_visit_fn fn,
                                                             void *user_data);

Visit a user function over a rasqal_expression

If the user function `fn` returns 0, the visit is truncated.

`e` : | rasqal_expression to visit
`fn` : | visit function
`user_data` : | user data to pass to visit function
Returns : | 0 if the visit was truncated.