Main Page Modules

Typedefs | Enumerations | Functions
CODA Expression

## Typedefs
typedef struct coda_expression_struct | coda_expression
typedef enum coda_expression_type_enum | coda_expression_type

## Enumerations
enum | coda_expression_type_enum

## Functions
int | coda_expression_print (const coda_expression *expr, int(*print)(const char *,...))
const char * | coda_expression_get_type_name (coda_expression_type type)
void | coda_expression_delete (coda_expression *expr)
int | coda_expression_is_constant (const coda_expression *expr)
int | coda_expression_is_equal (const coda_expression *expr1, const coda_expression *expr2)
int | coda_expression_get_type (const coda_expression *expr, coda_expression_type *type)
int | coda_expression_eval_bool (const coda_expression *expr, const coda_cursor *cursor, int *value)
int | coda_expression_eval_integer (const coda_expression *expr, const coda_cursor *cursor, int64_t *value)
int | coda_expression_eval_float (const coda_expression *expr, const coda_cursor *cursor, double *value)
int | coda_expression_eval_string (const coda_expression *expr, const coda_cursor *cursor, char **value, long *length)
int | coda_expression_eval_node (const coda_expression *expr, coda_cursor *cursor)
int | coda_expression_from_string (const char *exprstring, coda_expression **expr)

## Detailed Description

CODA comes with a powerful expression language that can be used to perform calculations based on product data. This expression system is used internally with the product format definition (codadef) files that CODA uses to interpret products, but it can also be used by you as a user for your own purposes. More information on the CODA expression language and its ascii syntax can be found in the CODA documentation.

The example below shows how to evaluate a simple integer expression that does not make use of any product data:

const char *equation = "1+2";
coda_expression *expr;
long result;
coda_expression_from_string(equation, &expr);
coda_expression_eval_integer(expr, NULL, &result);
coda_expression_delete(expr);
printf("%d\n", result);

However, in most cases you will want to run an expression on actual product data. In the example below the expression expects a cursor that points to a record which has two fields, 'numerator' and 'denominator', and it will return a floating point value with the division of those two field values.

const char *equation = "float(./numerator)/float(./denominator)";
coda_cursor cursor;
coda_expression *expr;
double result;
coda_expression_from_string(equation, &expr);
... loop over all cursors for which you want to calculate the division ....
coda_expression_eval_integer(expr, &cursor, &result);
printf("%f\n", result);
... end of loop ...
coda_expression_delete(expr);

Note that, unlike most other CODA functions, the coda_expression_from_string() and coda_expression_delete() functions do not require that CODA is initialised with coda_init(). This also holds for the coda_expression_eval functions if no cursor is provided as parameter (i.e. when a static evaluation of the expression is performed).

## Typedef Documentation

coda_expression

CODA Expression

coda_expression_type

Result types of CODA expressions.

## Enumeration Type Documentation

enum coda_expression_type_enum

Result types of CODA expressions.

## Function Documentation

void coda_expression_delete | ( | coda_expression * | expr | ) |

Delete the CODA expression object.

Parameters

  expr | A CODA expression object

int coda_expression_eval_bool | ( | const coda_expression * | expr,
|  | const coda_cursor * | cursor,
|  | int * | value
| ) |  |

Evaluate a boolean expression. The expression object should be a coda_expression_bool expression. The function will evaluate the expression at the given cursor position and return the resulting boolean value (which will be 0 for False and 1 for True).

Parameters

  expr | A boolean expression object
  cursor | Cursor pointing to a location in the product where the boolean expression should be evaluated (can be NULL for constant expressions).
  value | Pointer to the variable where the resulting boolean value will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_eval_float | ( | const coda_expression * | expr,
|  | const coda_cursor * | cursor,
|  | double * | value
| ) |  |

Evaluate a floating point expression. The function will evaluate the expression at the given cursor position and return the resulting floating point value. The expression object should be a coda_expression_float expression.

Parameters

  expr | A floating point expression object
  cursor | Cursor pointing to a location in the product where the floating point expression should be evaluated (can be NULL for constant expressions).
  value | Pointer to the variable where the resulting floating point value will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_eval_integer | ( | const coda_expression * | expr,
|  | const coda_cursor * | cursor,
|  | int64_t * | value
| ) |  |

Evaluate an integer expression. The expression object should be a coda_expression_integer expression. The function will evaluate the expression at the given cursor position and return the resulting integer value.

Parameters

  expr | An integer expression object
  cursor | Cursor pointing to a location in the product where the integer expression should be evaluated (can be NULL for constant expressions).
  value | Pointer to the variable where the resulting integer value will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_eval_node | ( | const coda_expression * | expr,
|  | coda_cursor * | cursor
| ) |  |

Evaluate a node expression. The function will moves the cursor to a different position in a product based on the node expression. The expression object should be a coda_expression_node expression.

Parameters

  expr | A node expression object
  cursor | Cursor pointing to a location in the product where the node expression should be evaluated.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_eval_string | ( | const coda_expression * | expr,
|  | const coda_cursor * | cursor,
|  | char ** | value,
|  | long * | length
| ) |  |

Evaluate a string expression. The function will evaluate the expression at the given cursor position (if provided) and return the resulting string and length. If length is 0 then no string will be returned and `value` will be set to NULL. If a string is returned then it will be zero terminated. However, in the case where the string itself also contains zero characters, strlen() can not be used and the `length` parameter will give the actual string length of `value`. The expression object should be a coda_expression_string expression.

Note
  The caller of this function is responsible for freeing the memory of the result that is stored in `value`. It is recommended to do this with coda_free().

Parameters

  expr | A string expression object
  cursor | Cursor pointing to a location in the product where the string expression should be evaluated (can be NULL for constant expressions).
  value | Pointer to the variable where the result string will be stored (will be NULL if length == 0).
  length | Pointer to the variable where the length of the result string will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_from_string | ( | const char * | exprstring,
|  | coda_expression ** | expr
| ) |  |

Create a new CODA expression object by parsing a string containing a CODA expression. The string should contain a valid CODA expression. The returned expression object should be cleaned up using coda_expression_delete() after it has been used.

Parameters

  exprstring | A string containing the string representation of the CODA expression
  expr | Pointer to the variable where the expression object will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_get_type | ( | const coda_expression * | expr,
|  | coda_expression_type * | type
| ) |  |

Retrieve the result type of a CODA expression.

Parameters

  expr | A CODA expression object
  type | Pointer to the variable where the result type of the CODA expression will be stored.

Returns
  - `0`, Success.
  - `-1`, Error occurred (check coda_errno).

const char* coda_expression_get_type_name | ( | coda_expression_type | type | ) |

Returns the name of an expression type.

Parameters

  type | CODA expression type

Returns
  if the type is known a string containing the name of the type, otherwise the string "unknown".

int coda_expression_is_constant | ( | const coda_expression * | expr | ) |

Return whether an expression is constant or not. An expression is constant if it does not depend on the contents of a product and if the expression evaluation function can be called with cursor=NULL.

Parameters

  expr | A CODA expression object

Returns
  - `0`, Expression will depend on the contents of a product.
  - `1`, Expression is constant.
  - `-1`, Error occurred (check coda_errno).

int coda_expression_is_equal | ( | const coda_expression * | expr1,
|  | const coda_expression * | expr2
| ) |  |

Determines whether two expressions are equal or not This function will return 1 if both expressions are equal, and 0 if they are not.

The comparison will not be on the evaluated result of the expressions but on the operators and operands of the expressions themselves. For two expressions to be equal, all operands to an operation need to be equal and operands need to be provided in the same order. So the expression '1!=2' will not be considered equal to the expression '2!=1'.

Providing two NULL pointers will be considered as a case of equal expressions.

Parameters

  expr1 | A CODA expression object
  expr2 | A CODA expression object

Returns
  - `0`, expr1 and expr2 consist of the exact same sequence of operators and operands.
  - `1`, expr1 and expr2 differ in terms of operators and operands.

int coda_expression_print | ( | const coda_expression * | expr,
|  | int(*)(const char *,...) | print
| ) |  |

Write the full expression using a printf compatible function. This function will produce a string representation of the expression itself (it won't evaluate the expression, nor write its result). The print function parameter should be a function that resembles printf(). The printed string representation is something that can be passed to coda_expression_from_string() again to reproduce the expression object.

Parameters

  expr | Pointer to the expression object.
  print | Reference to a printf compatible function.

Returns
  - `0`, Succes.
  - `-1`, Error occurred (check coda_errno).