Expressions

## Expressions Expressions — Query language expressions. |

## Synopsis

    typedef             rasqal_expression;
    enum                rasqal_expression_flags;
                        rasqal_evaluation_context;
    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_4op_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             rasqal_expression *arg2,
                                                             rasqal_expression *arg3,
                                                             rasqal_expression *arg4);
    rasqal_expression * rasqal_new_aggregate_function_expression
                                                            (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             raptor_sequence *params,
                                                             unsigned int flags);
    rasqal_expression * rasqal_new_cast_expression          (rasqal_world *world,
                                                             raptor_uri *name,
                                                             rasqal_expression *value);
    rasqal_expression * rasqal_new_function_expression      (rasqal_world *world,
                                                             raptor_uri *name,
                                                             raptor_sequence *args,
                                                             raptor_sequence *params,
                                                             unsigned int flags);
    rasqal_expression * rasqal_new_group_concat_expression  (rasqal_world *world,
                                                             unsigned int flags,
                                                             raptor_sequence *args,
                                                             rasqal_literal *separator);
    rasqal_expression * rasqal_new_literal_expression       (rasqal_world *world,
                                                             rasqal_literal *literal);
    rasqal_expression * rasqal_new_set_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             raptor_sequence *args);
    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);
    rasqal_expression * rasqal_new_expr_seq_expression      (rasqal_world *world,
                                                             rasqal_op op,
                                                             raptor_sequence *args);
    void                rasqal_free_expression              (rasqal_expression *e);
    int                 rasqal_expression_compare           (rasqal_expression *e1,
                                                             rasqal_expression *e2,
                                                             int flags,
                                                             int *error_p);
    rasqal_literal *    rasqal_expression_evaluate          (rasqal_world *world,
                                                             raptor_locator *locator,
                                                             rasqal_expression *e,
                                                             int flags);
    rasqal_literal *    rasqal_expression_evaluate2         (rasqal_expression *e,
                                                             rasqal_evaluation_context *eval_context,
                                                             int *error_p);
    const char *        rasqal_expression_op_label          (rasqal_op op);
    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);
    rasqal_evaluation_context * rasqal_new_evaluation_context
                                                            (rasqal_world *world,
                                                             raptor_locator *locator,
                                                             int flags);
    void                rasqal_free_evaluation_context      (rasqal_evaluation_context *eval_context);
    int                 rasqal_evaluation_context_set_base_uri
                                                            (rasqal_evaluation_context *eval_context,
                                                             raptor_uri *base_uri);
    int                 rasqal_evaluation_context_set_rand_seed
                                                            (rasqal_evaluation_context *eval_context,
                                                             unsigned int seed);

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

    typedef enum {
      RASQAL_EXPR_FLAG_DISTINCT = 1,
      RASQAL_EXPR_FLAG_AGGREGATE = 2
    } rasqal_expression_flags;

Flags for expressions.

`RASQAL_EXPR_FLAG_DISTINCT` | Distinct
`RASQAL_EXPR_FLAG_AGGREGATE` | Aggregate function expression

### rasqal_evaluation_context

    typedef struct {
      rasqal_world *world;
      raptor_uri* base_uri;
      raptor_locator *locator;
      int flags;
      unsigned int seed;
      rasqal_random* random;
    } rasqal_evaluation_context;

A context for evaluating an expression such as with `rasqal_expression_evaluate2()`

rasqal_world *`world`; | rasqal world
raptor_uri *`base_uri`; | base URI of expression context (or NULL)
raptor_locator *`locator`; | locator or NULL
int `flags`; | expression comparison flags
unsigned int `seed`; | random seeed
rasqal_random *`random`; | random number generator object

### 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,
      RASQAL_EXPR_IF,
      RASQAL_EXPR_URI,
      RASQAL_EXPR_IRI,
      RASQAL_EXPR_STRLANG,
      RASQAL_EXPR_STRDT,
      RASQAL_EXPR_BNODE,
      RASQAL_EXPR_GROUP_CONCAT,
      RASQAL_EXPR_SAMPLE,
      RASQAL_EXPR_IN,
      RASQAL_EXPR_NOT_IN,
      RASQAL_EXPR_ISNUMERIC,
      RASQAL_EXPR_YEAR,
      RASQAL_EXPR_MONTH,
      RASQAL_EXPR_DAY,
      RASQAL_EXPR_HOURS,
      RASQAL_EXPR_MINUTES,
      RASQAL_EXPR_SECONDS,
      RASQAL_EXPR_TIMEZONE,
      RASQAL_EXPR_CURRENT_DATETIME,
      RASQAL_EXPR_NOW,
      RASQAL_EXPR_FROM_UNIXTIME,
      RASQAL_EXPR_TO_UNIXTIME,
      RASQAL_EXPR_CONCAT,
      RASQAL_EXPR_STRLEN,
      RASQAL_EXPR_SUBSTR,
      RASQAL_EXPR_UCASE,
      RASQAL_EXPR_LCASE,
      RASQAL_EXPR_STRSTARTS,
      RASQAL_EXPR_STRENDS,
      RASQAL_EXPR_CONTAINS,
      RASQAL_EXPR_ENCODE_FOR_URI,
      RASQAL_EXPR_TZ,
      RASQAL_EXPR_RAND,
      RASQAL_EXPR_ABS,
      RASQAL_EXPR_ROUND,
      RASQAL_EXPR_CEIL,
      RASQAL_EXPR_FLOOR,
      RASQAL_EXPR_MD5,
      RASQAL_EXPR_SHA1,
      RASQAL_EXPR_SHA224,
      RASQAL_EXPR_SHA256,
      RASQAL_EXPR_SHA384,
      RASQAL_EXPR_SHA512,
      RASQAL_EXPR_STRBEFORE,
      RASQAL_EXPR_STRAFTER,
      RASQAL_EXPR_REPLACE,
      RASQAL_EXPR_UUID,
      RASQAL_EXPR_STRUUID,
      /* internal */
      RASQAL_EXPR_LAST = RASQAL_EXPR_STRUUID
    } 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` | Obsolete - not used
`RASQAL_EXPR_GROUP_COND_DESC` | Obsolete - not used
`RASQAL_EXPR_COUNT` | Expression for LAQRS select `COUNT()` aggregate function
`RASQAL_EXPR_VARSTAR` | Expression for LAQRS select Variable *
`RASQAL_EXPR_SAMETERM` | Expression for SPARQL sameTerm
`RASQAL_EXPR_SUM` | Expression for LAQRS select `SUM()` aggregate function
`RASQAL_EXPR_AVG` | Expression for LAQRS select `AVG()` aggregate function
`RASQAL_EXPR_MIN` | Expression for LAQRS select `MIN()` aggregate function
`RASQAL_EXPR_MAX` | Expression for LAQRS select `MAX()` aggregate function
`RASQAL_EXPR_COALESCE` | Expression for LAQRS COALESCE(Expr+)
`RASQAL_EXPR_IF` | Expression for LAQRS IF(expr, expr, expr)
`RASQAL_EXPR_URI` | Expression for LAQRS URI(expr)
`RASQAL_EXPR_IRI` | Expression for LAQRS IRI(expr)
`RASQAL_EXPR_STRLANG` | Expression for LAQRS STRLANG(expr, expr)
`RASQAL_EXPR_STRDT` | Expression for LAQRS STRDT(expr, expr)
`RASQAL_EXPR_BNODE` | Expression for LAQRS `BNODE()` and BNODE(expr)
`RASQAL_EXPR_GROUP_CONCAT` | Expression for LAQRS GROUP_CONCAT(arglist) aggregate function
`RASQAL_EXPR_SAMPLE` | Expression for LAQRS SAMPLE(expr) aggregate function
`RASQAL_EXPR_IN` | Expression for LAQRS expr IN ( list of expr )
`RASQAL_EXPR_NOT_IN` | Expression for LAQRS expr NOT IN ( list of expr )
`RASQAL_EXPR_ISNUMERIC` | Expression for SPARQL 1.1 isNUMERIC(expr)
`RASQAL_EXPR_YEAR` | Expression for SPARQL 1.1 YEAR(datetime)
`RASQAL_EXPR_MONTH` | Expression for SPARQL 1.1 MONTH(datetime)
`RASQAL_EXPR_DAY` | Expression for SPARQL 1.1 DAY(datetime)
`RASQAL_EXPR_HOURS` | Expression for SPARQL 1.1 HOURS(datetime)
`RASQAL_EXPR_MINUTES` | Expression for SPARQL 1.1 MINUTES(datetime)
`RASQAL_EXPR_SECONDS` | Expression for SPARQL 1.1 SECONDS(datetime)
`RASQAL_EXPR_TIMEZONE` | Expression for SPARQL 1.1 TIMEZONE(datetime)
`RASQAL_EXPR_CURRENT_DATETIME` | Expression for LAQRS CURRENT_DATETIME( void )
`RASQAL_EXPR_NOW` | Expression for LAQRS NOW( void )
`RASQAL_EXPR_FROM_UNIXTIME` | Expression for LAQRS FROM_UNIXTIME(int)
`RASQAL_EXPR_TO_UNIXTIME` | Expression for LAQRS TO_UNIXTIME(datetime)
`RASQAL_EXPR_CONCAT` | Expression for SPARQL 1.1 CONCAT(strings)
`RASQAL_EXPR_STRLEN` | Expression for SPARQL 1.1 STRLEN(str)
`RASQAL_EXPR_SUBSTR` | Expression for SPARQL 1.1 SUBSTR(str, start[,offset])
`RASQAL_EXPR_UCASE` | Expression for SPARQL 1.1 UCASE(str)
`RASQAL_EXPR_LCASE` | Expression for SPARQL 1.1 LCASE(str)
`RASQAL_EXPR_STRSTARTS` | Expression for SPARQL 1.1 STRSTARTS(str, str)
`RASQAL_EXPR_STRENDS` | Expression for SPARQL 1.1 STRENDS(str, str)
`RASQAL_EXPR_CONTAINS` | Expression for SPARQL 1.1 CONTAINS(str, str)
`RASQAL_EXPR_ENCODE_FOR_URI` | Expression for SPARQL 1.1 ENCODE_FOR_URI(str)
`RASQAL_EXPR_TZ` | Expression for SPARQL 1.1 `TZ()`
`RASQAL_EXPR_RAND` | Expression for SPARQL 1.1 `RAND()`
`RASQAL_EXPR_ABS` | Expression for SPARQL 1.1 `ABS()`
`RASQAL_EXPR_ROUND` | Expression for SPARQL 1.1 `ROUND()`
`RASQAL_EXPR_CEIL` | Expression for SPARQL 1.1 `CEIL()`
`RASQAL_EXPR_FLOOR` | Expression for SPARQL 1.1 `FLOOR()`
`RASQAL_EXPR_MD5` | Expression for SPARQL 1.1 `MD5()`
`RASQAL_EXPR_SHA1` | Expression for SPARQL 1.1 `SHA1()`
`RASQAL_EXPR_SHA224` | Expression for SPARQL 1.1 `SHA224()`
`RASQAL_EXPR_SHA256` | Expression for SPARQL 1.1 `SHA256()`
`RASQAL_EXPR_SHA384` | Expression for SPARQL 1.1 `SHA384()`
`RASQAL_EXPR_SHA512` | Expression for SPARQL 1.1 `SHA512()`
`RASQAL_EXPR_STRBEFORE` | Expression for SPARQL 1.1 `STRBEFORE()`
`RASQAL_EXPR_STRAFTER` | Expression for SPARQL 1.1 `STRAFTER()`
`RASQAL_EXPR_REPLACE` | Expression for SPARQL 1.1 `REPLACE()`
`RASQAL_EXPR_UUID` | Expression for SPARQL 1.1 `UUID()`
`RASQAL_EXPR_STRUUID` | Expression for SPARQL 1.1 `STRUUID()`
`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()` or `rasqal_literal_as_string_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 (unused; was 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_COUNT` `RASQAL_EXPR_SUM` `RASQAL_EXPR_AVG` `RASQAL_EXPR_MIN` `RASQAL_EXPR_MAX`

The operator `RASQAL_EXPR_TILDE` is not used by SPARQL (formerly RDQL).

`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`, `RASQAL_EXPR_STR_NEQ` and `RASQAL_EXPR_REM` are unused (formerly 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 operators are: RASQAL_EXPR_REGEX RASQAL_EXPR_IF RASQAL_EXPR_SUBSTR

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

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

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

The operators are: RASQAL_EXPR_REPLACE

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

### rasqal_new_aggregate_function_expression ()

    rasqal_expression * rasqal_new_aggregate_function_expression
                                                            (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             raptor_sequence *params,
                                                             unsigned int flags);

Constructor - create a new 1-arg aggregate function expression for a builtin aggregate function

Takes ownership of the `args` and `params`

`world` : | rasqal_world object
`op` : | built-in aggregate function expression operator
`arg1` : | rasqal_expression argument to aggregate function
`params` : | sequence of rasqal_expression function parameters (or NULL)
`flags` : | extension function bitflags
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_function_expression ()

    rasqal_expression * rasqal_new_function_expression      (rasqal_world *world,
                                                             raptor_uri *name,
                                                             raptor_sequence *args,
                                                             raptor_sequence *params,
                                                             unsigned int flags);

Constructor - create a new expression for a URI-named function with arguments and optional parameters.

Takes ownership of the `name`, `args` and `params` arguments.

`world` : | rasqal_world object
`name` : | function name
`args` : | sequence of rasqal_expression function arguments
`params` : | sequence of rasqal_expression function parameters (or NULL)
`flags` : | extension function bitflags
Returns : | a new rasqal_expression object or NULL on failure

### rasqal_new_group_concat_expression ()

    rasqal_expression * rasqal_new_group_concat_expression  (rasqal_world *world,
                                                             unsigned int flags,
                                                             raptor_sequence *args,
                                                             rasqal_literal *separator);

Constructor - create a new SPARQL group concat expression

Takes an optional distinct flag, a list of expressions and an optional separator string.

Takes ownership of the `args` and `separator`

`world` : | rasqal_world object
`flags` : | bitset of flags. Only RASQAL_EXPR_FLAG_DISTINCT is defined
`args` : | sequence of rasqal_expression list arguments
`separator` : | SEPARATOR string literal or NULL
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_set_expression ()

    rasqal_expression * rasqal_new_set_expression           (rasqal_world *world,
                                                             rasqal_op op,
                                                             rasqal_expression *arg1,
                                                             raptor_sequence *args);

Constructor - create a new set IN/NOT IN operation with expression arguments.

Takes ownership of the `arg1` and `args`

`world` : | rasqal_world object
`op` : | list operation
`arg1` : | expression to look for in list
`args` : | sequence of rasqal_expression list arguments
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` and `RASQAL_EXPR_STR_NMATCH` (unused: formerly for 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_new_expr_seq_expression ()

    rasqal_expression * rasqal_new_expr_seq_expression      (rasqal_world *world,
                                                             rasqal_op op,
                                                             raptor_sequence *args);

Constructor - create a new expression with a sequence of expression arguments.

Takes ownership of the `args`

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

### rasqal_free_expression ()

    void                rasqal_free_expression              (rasqal_expression *e);

Destructor - destroy a rasqal_expression object.

`e` : | rasqal_expression object

### rasqal_expression_compare ()

    int                 rasqal_expression_compare           (rasqal_expression *e1,
                                                             rasqal_expression *e2,
                                                             int flags,
                                                             int *error_p);

Compare two expressions

The two literals are compared. The comparison returned is as for strcmp, first before second returns <0. equal returns 0, and first after second returns >0. For URIs, the string value is used for the comparsion.

See `rasqal_literal_compare()` for comparison flags.

If `error` is not NULL, *error is set to non-0 on error

`e1` : | rasqal_expression first expression
`e2` : | rasqal_expression second expression
`flags` : | comparison flags: see `rasqal_literal_compare()`
`error_p` : | pointer to error
Returns : | <0, 0, or >0 as described above.

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

`Deprecated`: use `rasqal_expression_evaluate2()` using a rasqal_evaluation_context

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

    rasqal_literal *    rasqal_expression_evaluate2         (rasqal_expression *e,
                                                             rasqal_evaluation_context *eval_context,
                                                             int *error_p);

Evaluate a rasqal_expression tree in the context of a rasqal_evaluation_context to give a rasqal_literal result or error.

`e` : | The expression to evaluate.
`eval_context` : | expression context
`error_p` : | pointer to error return flag
Returns : | a rasqal_literal value or NULL (a valid value). `error_p` is set to non-0 on failure.

### rasqal_expression_op_label ()

    const char *        rasqal_expression_op_label          (rasqal_op op);

Get a label for the rasqal expression operator

`op` : | the rasqal_expression_op object
Returns : | the label (shared string) or NULL if op is out of range or unknown

### 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 : | non-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 non-0, the visit is truncated and the value is returned.

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

### rasqal_new_evaluation_context ()

    rasqal_evaluation_context * rasqal_new_evaluation_context
                                                            (rasqal_world *world,
                                                             raptor_locator *locator,
                                                             int flags);

Constructor - create a rasqal_evaluation_context for use with `rasqal_expression_evaluate2()`

`world` : | rasqal world
`locator` : | locator or NULL
`flags` : | expression comparison flags
Returns : | non-0 on failure

### rasqal_free_evaluation_context ()

    void                rasqal_free_evaluation_context      (rasqal_evaluation_context *eval_context);

Destructor - destroy a rasqal_evaluation_context object.

`eval_context` : | rasqal_evaluation_context object

### rasqal_evaluation_context_set_base_uri ()

    int                 rasqal_evaluation_context_set_base_uri
                                                            (rasqal_evaluation_context *eval_context,
                                                             raptor_uri *base_uri);

Set the URI for a rasqal_evaluation_context

`eval_context` : | rasqal_evaluation_context object
`base_uri` : | base URI
Returns : | non-0 on failure

### rasqal_evaluation_context_set_rand_seed ()

    int                 rasqal_evaluation_context_set_rand_seed
                                                            (rasqal_evaluation_context *eval_context,
                                                             unsigned int seed);

Set the random seed for a rasqal_evaluation_context

`eval_context` : | rasqal_evaluation_context object
`seed` : | random seed
Returns : | non-0 on failure